jiantw83andClaude Opus 5
62fd2a6022
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 交付內容型別
|
|
|
|
交付／交接工作包開工時，先跟使用者確認這份交付要產出什麼內容。預設選項固定兩個，其餘由使用者輸入。
|
|
|
|
| 選項 | 內容 |
|
|
| --- | --- |
|
|
| 1. API 文件 | 端點路徑、輸入參數（**全部**）、輸出參數（**全部**）；見下節 |
|
|
| 2. 由使用者輸入 | 使用者自己講要什麼內容；照使用者說的做，不套 API 文件格式 |
|
|
|
|
選項一律依 `jsc-ask:ask` 規則呈現，並標明影響範圍。**不得自行預設，也不得跳過詢問。**
|
|
|
|
## API 文件
|
|
|
|
### 必備欄位
|
|
|
|
| 區塊 | 要求 |
|
|
| --- | --- |
|
|
| 端點路徑 | 方法與完整路徑（例 `GET /v1/members/{id}`），含版本前綴 |
|
|
| 輸入參數 | **列出全部**——路徑、查詢字串、標頭、請求主體逐層列，不可只列「主要的幾個」 |
|
|
| 輸出參數 | **列出全部**——回應主體逐層列，含錯誤回應的結構與狀態碼 |
|
|
|
|
每個參數都要有：名稱、型別、必填與否、範例、資料來源、新舊狀態。
|
|
|
|
### 參數範例：真實資料優先
|
|
|
|
1. 先找真實來源：資料庫欄位與實際資料列、實際 API 回應、既有設定檔或 fixture、日誌。標成 `真實：{來源}`。
|
|
2. 找不到來源才由邏輯推理，標成 `推論：無來源`，讓接手者知道那個值還沒被驗證。
|
|
3. **不得**編一個看起來合理的值當成真實資料。
|
|
4. 範例只保留**結構與格式**。個資一律遮蔽或改寫成格式描述，不把真實個資寫進交付文件。
|
|
|
|
### 既有端點：新舊參數必須明顯區分
|
|
|
|
改的是既有端點時，接手者最需要知道「哪些是這次動到的」。用兩種標示，兩者都要：
|
|
|
|
**一、參數表加狀態欄**
|
|
|
|
| 狀態 | 標示 | 意義 |
|
|
| --- | --- | --- |
|
|
| 新增 | 🆕 **新增** | 這次新增的參數 |
|
|
| 變更 | ⚠️ **變更** | 既有參數改了型別、必填性、預設值或語意 |
|
|
| 既有 | （留空） | 這次沒動 |
|
|
| 移除 | ❌ **移除** | 這次移除，含淘汰時程 |
|
|
|
|
**二、差異區塊用 `diff` 語法標色**
|
|
|
|
Gitea 與 GitHub 的 markdown 都會替 `diff` 程式碼區塊上色，`+` 綠、`-` 紅，是最可靠的「顏色」做法（HTML 的 `style` 屬性會被 wiki 過濾掉，不要用）：
|
|
|
|
````markdown
|
|
```diff
|
|
GET /v1/members/{id}
|
|
id string 必填
|
|
+ include_tags boolean 選填 預設 false（本次新增）
|
|
- legacy_flag boolean 選填 （本次移除，2026-12-31 前相容）
|
|
! status string 必填 列舉值新增 suspended（本次變更）
|
|
```
|
|
````
|
|
|
|
新端點不需要狀態欄與差異區塊，但要註明「本次新增端點」。
|