thread-master/docs/product/scout-topic-quality/tasks/T010-web-run-contracts.md

T010 — 前端 Run 與分頁契約

Status: done Milestone: M1 Est. change: ~140 lines

Goal

完成後，前端以明確型別表達 Scout Run、完整計數、不足原因與伺服器分頁。

Depends on

• T001、T002

Inputs

• 讀取 / 依賴：
  • 檔案：apps/web/src/domain/types.ts、apps/web/src/data/repos.ts
  • 既有能力 / API：ScoutPost、ScoutRunBrief、既有 pagination patterns
  • Spec 段落：§2、§5.1、§5.2

Outputs

程式變更（預期路徑）

路徑	動作	說明
apps/web/src/domain/types.ts	edit	新增 ScoutRun、status、shortfall reason、pagination；ScoutPost 加 run_id。
apps/web/src/data/repos.ts	edit	新增 listRuns、listRunPosts、removeRun 契約，scan response 加 run，保留 listPosts。

行為變更

• 所有新列表呼叫回傳 list 與完整 pagination，不回傳裸陣列。
• runScanFromBrief 回傳同一次建立的 job 與 run。

API / 契約（若有）

• page/pageSize 最大值由 server 正規化；時間仍為 UTC unix ns。

Out of scope

• 不實作 live HTTP，不改頁面。

Acceptance

• TypeScript 能阻止把 theme_key 當 run ID 或把 page response 當陣列。
• 指令：

cd apps/web && npm run build

驗收結果：npm run build、npm test -- src/pages/ScoutPage.test.tsx 通過。

Notes

通用 Page 型別若已有等價定義應重用，不再創造相同形狀。