| name | aibdd-form-api-spec |
| description | 從推理包翻譯為 OpenAPI。負責 OpenAPI 語法規章 + 歸檔。 切檔策略（單檔 / per-resource / per-module / per-boundary）由 Planner 透過 DELEGATE 參數指定， 本 skill 不自決。不做跨 boundary 決策。
|
| user-invocable | false |
§1 角色
Formulation skill。綁定 DSL = OpenAPI 3.x。被 aibdd-service-contract-analysis 與 /aibdd-plan（透過 boundary operation contract specifier）DELEGATE。
§2 入口契約
接收推理包：
| 項目 | 內容 |
|---|
| M/D/C 變更集 | EndpointGroup / InteractionMode / ModuleSlice 的增刪改 |
| Axis 單位對應 | 推理包中每個 endpoint → OpenAPI path/method 的具體對應 |
| 退出狀態 | Reason 步是否完整通過 |
slice_list | Planner 指定的切檔清單：每個 slice 的 target_path + scope（包含哪些 endpoint groups）。target_path 為 caller 提供之相對於 ${CONTRACTS_DIR} 的檔案路徑。target_path 內不得含 <<NN-functional-module>> 借位子層；${CONTRACTS_DIR} 在 SSOT 已是 flat directory（見 aibdd-core::ssot/spec-package-paths.md），functional module 借位只允許出現在 ${TRUTH_BOUNDARY_PACKAGES_DIR} 子樹。type 亦不出現於 path — 由 ${BOUNDARY_YML} type 欄位 SSOT。 |
缺項：推理包不完整或 slice_list 未指定 → 回退呼叫 Planner 補齊（白話文回報「推理包不完整」）。
§3 Formulate SOP
- 讀取 format reference：
references/format-reference.md（OpenAPI 3.x 語法合法範例、狀態碼、型別）
- 讀取行為 / 封裝規約：
references/patterns/command-resource.md（狀態遷移、命令封裝、讀模型、後端裁定邊界）
- 讀取反模式：
references/patterns/anti-patterns.md（對照自查）
- 依 slice_list 展開：每個 slice 產出一個 OpenAPI 文件；共用 schema 放
common.api.yml
- 填入 path + method：從推理包的 endpoint → RESTful path + HTTP method 映射（命名細節見
patterns/rest-naming.md）
- 錯誤與切檔：
patterns/error-schema.md、patterns/modular-layout.md
- $ref 跨檔引用：依切檔策略寫入正確的
$ref 引用
- 寫檔前 ASSERT：每個 slice 的
target_path 不得含 <<NN-functional-module>> 借位子層；任一違反 → STOP 並回退 Planner 補正（白話文回報「target_path 違反 ${CONTRACTS_DIR} flat 規約」）。
- 寫檔：依 slice 的
target_path 逐一寫出（落點＝${CONTRACTS_DIR} ⊕ target_path）。
§4 DSL 最佳實踐
領域與狀態（優先於「路徑長相」）
- 禁止將核心狀態遷移或規則裁定下放給客戶端 request body，除非推理包明示為測試／示意且與正式 API 分離（見
command-resource.md）。
- 避免僅切狀態的 endpoint；偏誤：同一使用者意圖合併為單一命令，並以 snapshot／GET 滿足讀模型（細節見
command-resource.md、anti-patterns.md）。
REST 命名
- path: 名詞複數或從屬資源（見
patterns/rest-naming.md）
- method: CRUD 與命令型
POST（見 command-resource.md）
- operationId:
<verb><Resource> camelCase（createOrder）；path 仍保持名詞導向
- tag: 等於 EndpointGroup.group_id
Error schema
- 統一使用
ErrorResponse { message, code }（見 patterns/error-schema.md）
- 放在
common.api.yml#/components/schemas/ErrorResponse
模組化 layout
- 切檔策略由 Planner 決定；本 skill 配合落地（見
patterns/modular-layout.md）
$ref 引用語法嚴格遵循 OpenAPI 3.x 規範- 每個 slice 的
info.title 反映 scope
§5 匯報
以白話文 1–3 句匯報（依 aibdd-core::planner-contract.md §REPORT 匯報；不輸出 JSON / YAML）：
Form API Spec 完成。產出 N 個 OpenAPI 檔案。
§6 參考
- references/format-reference.md：合法
responses 形狀、狀態碼對照、型別推斷
- references/patterns/command-resource.md：狀態遷移、業務封裝、讀模型、命令型 POST 資源化
- references/patterns/anti-patterns.md：RPC 氣味、純狀態 API、204+無讀模型、誤放後端裁量欄
- references/patterns/rest-naming.md：path / method / operationId
- references/patterns/error-schema.md：
ErrorResponse 與 4xx 分工
- references/patterns/modular-layout.md：common.api.yml、相對
$ref、slice info
