# 交付內容型別

交付／交接工作包開工時，先跟使用者確認這份交付要產出什麼內容。預設選項固定兩個，其餘由使用者輸入。

| 選項 | 內容 |
| --- | --- |
| 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（本次變更）
```
````

新端點不需要狀態欄與差異區塊，但要註明「本次新增端點」。