子需求：FR-058.7 SonarQube 上傳檔案掃描（scan 模式取源擴充）

任務摘要

FR-058.7 的 BE 側全部工作。包含：① param_schema 升 v3 migration（INSERT 新版＋v2 is_current=FALSE，僅 scan_mode options 加 upload）；② execute 端點改造：POST /detection-tools/jobs/<uid>/execute 改可收 body {"source_file": {"uid": "..."}}——帶 uid 覆寫綁定 sticky 參照、不帶沿用現值、首次無檔 400；③ 新開 agent 專用 mTLS 檔案下載端點 GET /api/1.0/agents/files/<uid>＋任務綁定驗證＋串流轉發不落地；④ 心跳下發注入 _source_file（含 size / sha256 / limits）；⑤ 限額 config（config class 屬性＋環境變數覆寫）；⑥ 新 upload_type 分類 DETECTION_SOURCE。

關鍵約束

• migration 依環境異動鐵律只套 DEV，STG / POC 不動
• 下載端點認證比照 tasks ack / result 的「純 mTLS 不掛 jwt」形狀（api/remote_agent/__init__.py:34-38 先例）；授權驗證 uid 屬於該 agent 名下 pending / running 任務的 source_file，錯誤一律 404 不區分情況
• 🔴 跨案要求（FR-059 D6，2026-08-01 補）：授權驗證做成可插拔 resolver 介面，不可硬編 source_file 查詢——按檔案用途分流 claim，本案實作第一種 source_file resolver；後續 FR-059（Profile / Content 庫，CM-1007 起）會在同一端點掛第二種 profile_ref resolver（驗證語意＝uid 是該 agent 名下 pending / running 任務 params 中引用的 profile 檔）。介面形狀：resolver 依檔案用途註冊、各自實作「此 agent 可否取此 uid」判定，端點本體只負責 mTLS 驗證＋分派＋串流。FR-059 設計見 docs/features/FR-059-2608-detection-profile-library/design.md §5.4／D6
• 檔案 metadata（file_name / size / sha256）從 upload_files 表權威取回，不信 FE（D31）；BE 驗證：uid 屬本 tenant、副檔名在允許清單、大小在限額內
• 限額預設：上傳 100MB / 解壓後 500MB / 50,000 檔 / 磁碟係數 ×12＋1GB，比照 DRIVE_FILE_SIZE_LIMIT_MB pattern（D27）；隨 payload 下發、單一真相在 BE
• 與 T-7.2 並行前先凍結 key 契約：source_file / _source_file 形狀、下載端點路徑、sha256 header 名（§4.8「執行時輸入與 params 形狀」）

design.md 座標

詳細設計見 §4.8（端點契約草案 A/B、params 形狀）；決策理由見 §2 D25、D26、D27、D31；驗收條件見 §5.12 T-7.1。

驗收條件摘要

• DEV SELECT 確認 v3 為 is_current、v2 保留
• execute 帶 uid 覆寫 / 不帶沿用 / 首次 400 三路徑正確
• 下載端點對非本 agent 任務的 uid 回 404
• 不帶 body 的既有呼叫（pull / scan）行為完全不變

已完成修正（2026-08-01）

做了什麼