thread-master/docs/product/scout-topic-quality/tasks/T050-scan-run-job-link.md

T050 — Scan、Run 與 Job 一對一

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

Goal

完成後，每次 POST scan 先建立唯一 run，再以同一 run ID 排程 job 並一起回傳。

Depends on

• T034、T045

Inputs

• 讀取 / 依賴：
  • 檔案：apps/backend/internal/logic/scout/run_scan_logic.go、job usecase、Run usecase
  • 既有能力 / API：ScheduleScoutScan、immutable RunBrief、UUID、guarded run status
  • Spec 段落：§4 流程 A、§5.1、§5.3

Outputs

程式變更（預期路徑）

路徑	動作	說明
apps/backend/internal/module/scout/usecase/runs.go	edit	建立 queued run，正規化 target 與不可變 input。
apps/backend/internal/module/job/usecase/service.go	edit	ScheduleScoutScan 的 RefID/payload 改綁 run ID。
apps/backend/internal/logic/scout/run_scan_logic.go	edit	create run → schedule job → bind job → 回 job+run；排程失敗收斂 run。
apps/backend/internal/logic/scout/run_scan_logic_test.go	add	驗證每次新 ID、payload 一致與失敗收斂。

行為變更

• 相同 theme 每次 scan 都是新 run；排程失敗不留下 queued run。

API / 契約（若有）

• member JWT owner 寫入 run/job；provider token 不進 payload。

Out of scope

• 不執行 worker 或改 job claim lock。

Acceptance

• response.job.ref_id、response.run.id 與 payload.run_id 一致。
• 指令：

cd apps/backend && go test ./internal/logic/scout ./internal/module/job/... -run 'RunScan|ScoutScan' -count=1

驗收結果：scan 先建立獨立 queued run，再以 run_id 作 job RefID 與 flat immutable payload 欄位；bind／排程失敗會 guarded 收斂 failed，不回部分成功。RunScan logic 測試通過。

Notes

若 bind job 失敗，使用 guarded failed + safe error，不回部分成功。