# 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；不接受與契約無關的生成漂移。