thread-master/docs/product/scout-topic-quality/tasks/T051-worker-run-lifecycle.md

T051 — Worker guarded 生命週期

Status: done Milestone: M5 Est. change: ~190 lines

Goal

完成後，worker 驗證 run context，guarded 推進 run/job 並回報搜尋階段與 eligible/target 進度。

Depends on

• T050

Inputs

• 讀取 / 依賴：
  • 檔案：apps/backend/cmd/worker/main.go、job/scout usecase
  • 既有能力 / API：MarkRunningProgress、SucceedJob、FailJob、RunScan pipeline
  • Spec 段落：§3.1、§5.3

Outputs

程式變更（預期路徑）

路徑	動作	說明
apps/backend/cmd/worker/main.go	edit	驗證 RefID/payload/owner，推進 run，傳遞階段 progress，成功發佈。
apps/backend/internal/module/scout/usecase/run_progress.go	add	封裝 guarded running/succeeded/failed/cancelled 與安全摘要。
apps/backend/internal/module/scout/usecase/run_progress_test.go	add	驗證合法／非法 transition 與終態不倒退。

行為變更

• queued→running→terminal；summary 顯示 stage 及 eligible/target，不含 token。

API / 契約（若有）

• Job guarded 更新沿用既有規則，Redis lock value 保持 workerID。

Out of scope

• 不修改其他 job template，不更換 lock 實作。

Acceptance

• payload/ref mismatch 在搜尋前失敗，終態 run 不被 retry 改回 running。
• 指令：

cd apps/backend && go test ./cmd/worker ./internal/module/scout/... ./internal/module/job/... -count=1

驗收結果：worker 驗證 payload.run_id／job.RefID／owner／job binding，guarded queued→running→succeeded/failed，搜尋結果先 stage 再 PublishRun；StartRun retry 與終態防倒退測試通過。

Notes

worker orchestration 只協調，不複製 candidate/pipeline 邏輯。