sdlc/references/deliver-formats.md

交付內容型別

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

選項	內容
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 過濾掉，不要用）：

```diff
  GET /v1/members/{id}
    id            string   必填
+   include_tags  boolean  選填  預設 false（本次新增）
-   legacy_flag   boolean  選填  （本次移除，2026-12-31 前相容）
!   status        string   必填  列舉值新增 suspended（本次變更）
```

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