thread-master/docs/product/scout-topic-quality/tasks/T020-scout-run-api-goctl.md

T020 — Run API 契約與 goctl 生成

Status: done Milestone: M2 Est. change: ~180 authored lines + generated output

Goal

完成後，go-zero 暴露已批准的 run list、run posts page、run delete 與 scan run response 型別；尚未接 persistence 的新端點會明確回 503。

Depends on

• T015

Inputs

• 讀取 / 依賴：
  • 檔案：apps/backend/generate/api/m5.api、common.api、gateway.api
  • 既有能力 / API：Pagination、ScoutPostPublic、ScoutScanJobData
  • Spec 段落：§5.1、§5.3

Outputs

程式變更（預期路徑）

路徑	動作	說明
apps/backend/generate/api/m5.api	edit	定義 ScoutRunPublic、list requests/data、run_id 與新端點。
apps/backend/internal/types/types.go	generate	由 goctl 更新型別。
apps/backend/internal/handler/scout/**	generate	由 goctl 生成 handler／route，禁止手寫。
apps/backend/internal/logic/scout/*run*_logic.go	generate/edit	由 goctl 建立骨架，隨即以明確 503 取代 nil 成功，待 T034 接真 usecase。
apps/backend/internal/logic/scout/run_contract_guard_test.go	add	驗證未接 persistence 時不會成功空資料。

行為變更

• HTTP contract 可編譯；舊 posts/theme 端點仍存在；新增端點不會假成功。

API / 契約（若有）

• GET runs 與 run posts 使用 page/pageSize → list+pagination；POST scan 回 job+run。

Out of scope

• 不在此 task 實作 repository；只允許明確 503，不允許成功空資料。

Acceptance

• 只透過 m5.api＋make gen-api 產生 handler/routes。
• 新 logic 在 T034 前均回 503xxx，而不是 nil, nil。
• 指令：

cd apps/backend && make gen-api && go build . && go build ./cmd/worker

驗收結果：goctl、gateway build、worker build 通過。

Notes

生成後立即檢查 diff；不接受與契約無關的生成漂移。