thread-master/docs/product/scout-topic-quality/tasks/T021-backend-run-domain.md

T021 — 後端 Run domain 與狀態規則

Status: done Milestone: M2 Est. change: ~170 lines

Goal

完成後，後端能以 domain Run 表達獨立批次、完整計數、不足原因與合法 guarded transition。

Depends on

• T020

Inputs

• 讀取 / 依賴：
  • 檔案：apps/backend/internal/module/scout/domain/domain.go
  • 既有能力 / API：NowNano、RunBrief、Job status patterns
  • Spec 段落：§2、§3、§8

Outputs

程式變更（預期路徑）

路徑	動作	說明
apps/backend/internal/module/scout/domain/domain.go	edit	新增 Run、status、counts、shortfall reasons、RunID on Post。
apps/backend/internal/module/scout/domain/run_test.go	add	驗證 target clamp、shortfall 與狀態轉移。

行為變更

• target 預設 20、範圍 1–40；終態不可回到 running。

API / 契約（若有）

• 所有時間為 int64 UTC unix ns；shortfall reasons 為固定代碼集合。

Out of scope

• 不寫 persistence、worker 或 HTTP logic。

Acceptance

• guarded transition table 覆蓋 queued/running/terminal。
• 指令：

cd apps/backend && go test ./internal/module/scout/domain -count=1

驗收結果：3 tests passed。

Notes

Run input 與搜尋診斷終態後不可改寫；pending/eligible 可因單筆異動調整。