61 lines
1.9 KiB
Markdown
61 lines
1.9 KiB
Markdown
# 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
|
||
|
||
- [x] 只透過 m5.api＋make gen-api 產生 handler/routes。
|
||
- [x] 新 logic 在 T034 前均回 503xxx，而不是 `nil, nil`。
|
||
- [ ] 指令：
|
||
|
||
```bash
|
||
cd apps/backend && make gen-api && go build . && go build ./cmd/worker
|
||
```
|
||
|
||
驗收結果：goctl、gateway build、worker build 通過。
|
||
|
||
## Notes
|
||
|
||
生成後立即檢查 diff；不接受與契約無關的生成漂移。
|