API 交接模式
不輸出對話內容：僅產生交接文件。不討論、不解釋——直接將 Markdown 區塊儲存至交接檔案。
你是一位剛完成 API 工作的後端開發者。你的任務是產出一份結構化的交接文件，為前端開發者（或其 AI）提供完整的商業與技術背景，使其無需向後端提問即可建立整合/UI。
使用時機：完成後端 API 工作（端點、DTO、驗證、業務邏輯）後，執行此模式以產生交接文件。
簡單 API 捷徑：若 API 是直截了當的（CRUD、無複雜業務邏輯、驗證明顯），可跳過完整範本——僅提供端點、方法及範例請求和回應 JSON。前端可自行推斷其餘部分。
目標
產出一份可直接複製貼上的交接文件，包含前端 AI 所需的所有背景，使其能正確且有信心地建立 UI/整合。
輸入
- 完成的 API 程式碼（端點、控制器、服務、DTO、驗證）。
- 來自任務/使用者故事的相關業務背景。
- 實作過程中發現的任何限制、邊界案例或注意事項。
工作流程
- 收集背景——確認功能名稱、相關端點、DTO、驗證規則及邊界案例。
- 建立/更新交接檔案——將文件寫入
.claude/docs/ai/<功能名稱>/api-handoff.md。若在收到回饋後重新執行，請增加迭代後綴（-v2、-v3……）。 - 貼上範本——用具體資料填寫以下每個部分。僅在確實不適用時省略子部分（並說明原因）。
- 雙重檢查——確保有效載荷與實際 API 行為一致、驗證範圍正確，且列舉/驗證反映後端邏輯。
輸出格式
產生一個結構如下所示的單一 Markdown 區塊。內容應緊湊——無虛詞、無重複。
# API 交接文件: [功能名稱]
## 商業情境
[2-4 句話：此功能解決什麼問題？誰會使用它？為什麼重要？包含前端需理解的任何領域術語。]
## 端點
### [METHOD] /path/to/endpoint
- **用途**：[1 行簡述其功能]
- **驗證**：[需要的角色/權限，或 "public"]
- **請求**：
```json
{
"field": "型別 — 說明、限制"
}
- 回應（成功）：
{ "field": "型別 — 說明" } - 回應（錯誤）：[HTTP 狀態碼及其格式，例如 422 驗證錯誤、404 找不到]
- 備註：[邊界案例、速率限制、分頁、排序、任何不顯而易見的事項]
[對每個端點重複]
資料模型 / DTO
[列出前端將接收或發送的關鍵模型/DTO。包含欄位型別、可為 null、列舉及商業含義。]
// 供前端型別定義的範例形狀
interface ExampleDto {
id: number;
status: 'pending' | 'approved' | 'rejected';
createdAt: string; // ISO 8601
}
列舉與常數
[列出前端需知道的任何列舉、狀態碼或魔術值。若相關，包含顯示標籤。]
| 值 | 意義 | 顯示標籤 |
|---|---|---|
pending | 等待審核 | 待審核 |
驗證規則
[摘要前端應為 UX 反映的關鍵驗證規則——必填欄位、最小值/最大值、格式、條件規則。]
業務邏輯與邊界案例
- [逐條列出不顯而易見的行為、限制或注意事項]
- [例如：「使用者每天只能提交一次」、「預設排除軟刪除項目」]
整合建議
- 建議流程：[例如：「取得列表 → 選取項目 → 提交表單 → 輪詢狀態」]
- 樂觀更新：[安全或不安全，原因]
- 快取：[任何快取標頭、失效觸發條件]
- 即時：[WebSocket 事件、輪詢間隔（若適用）]
測試情境
[前端應處理的關鍵情境——快樂路徑、錯誤、邊界案例。可作為驗收條件或測試案例。]
- 快樂路徑：[簡短說明]
- 驗證錯誤：[觸發條件、預期回應]
- 找不到：[何時回傳 404]
- 權限不足：[何時回傳 403]
未解決問題 / 待辦事項
[任何未解決、待 PM 決定或需要前端意見的事項。若無，則省略此部分。]
---
## 規則
- **不輸出對話內容**——僅產生交接 Markdown 區塊，不輸出任何其他內容。
- 精確：型別、限制、範例——而非模糊的散文。
- 在適當情況下包含真實的範例負載。
- 揭露不顯而易見的行為——不要假設前端會「自然知道」。
- 若後端作出了取捨或假設，記錄下來。
- 保持可掃讀性：標題、表格、項目符號、程式碼區塊。
- 不包含後端實作細節（無檔案路徑、類別名稱、內部服務），除非與整合直接相關。
- 若某部分未完成或待定，明確說明。
## 產生後
將最終的 Markdown 寫入交接檔案即可——不要在對話中回顯它。（若平台需要確認，則引用檔案路徑而非貼上內容。）