網址只是來源，檔案才是真相

📑 本頁是 v1.0（定稿）。 實作中有設計異動，見 設計 v1.1（補開 E-1、A-2，H-1 挪批 5、Z-1 挪批 6，工具代號更正）。本頁內容保留定稿原樣，不回頭改。

整案一句話：主系統登記「外部連結」型的檢測 Profile 時，背景下載解析完順手把那份壓縮檔存起來，這一版從此是檔案型；既有的「只同步檔案型給 Agent」機制不用改，Agent 主控台下拉自然就有東西；網址留著當「來源網址」做新鮮度檢查。

依賴一句：E-0 → P-1 → （P-2、F-1、A-1）→ （E-1 環境對齊 FR-171、A-2 Agent 快取路徑）→ H-1 → Z-1。你第一個看得到畫面的是批 5 的 H-1。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
  autonumber
  participant U as 管理者（主系統 Profile 頁）
  participant S as 主系統（jedi-detection）
  participant F as upload_files／儲存
  participant A as Agent
  U->>S: 新增 Profile，來源＝外部連結 https://…
  S->>S: 建版 v1：source_type=url、file_id=NULL、status=pending
  S->>S: 背景 worker：下載（60 秒內、50 MB 內、SSRF 五道防護）
  S->>S: cinc-auditor 解析（28～117 秒）
  rect rgb(226,240,241)
    Note over S,F: 本案新增：解析成功 → 存檔 → 轉型（同一 transaction）
    S->>F: 壓縮檔 bytes 存成 upload_files（save_dir=detection-profiles，sha256 回填）
    S->>S: 寫控制項；source_type=file、file_id=新列、url 保留、sha256＝bytes 雜湊、ETag
  end
  A->>S: 心跳（FR-171 B 之後改 GET /agents/config）
  S-->>A: 現行 file 型清單（含這一版：uid、version、sha256、file_uid、tool、name）
  A->>S: GET /agents/files/<file_uid>
  S-->>A: 壓縮檔
  A->>A: 對帳 sha256 → 解壓進 cache → 主控台下拉出現
  U->>S: 開控制項頁
  S->>S: HEAD 來源網址比 ETag；變了 → 同版重抽、換檔（D5）

被拔掉的舊路：派工 _profile payload 帶 {source_type:url, url} → Agent 把網址原樣丟給 cinc-auditor exec。本案後派工只會有 file 形狀；Agent 收到 url 形狀一律報「派工資料錯誤」。

3.1 存檔與轉型

• 新檔 jedi_detection/common/profile_snapshot.py：store_snapshot(file_upload_service, upload_file_domain_service, raw: bytes, file_name: str, scope: str, login_name: str) -> UploadFileEntity。內部把 bytes 包成 werkzeug FileStorage，走 與 DetectionProfileService._store_file 完全相同的分流（SYSTEM 走 upload_system_file、TENANT 走 upload_files，save_dir="detection-profiles"），再 _backfill_sha256。_store_file 本身改成呼叫這支（1,146 行的檔只准一行呼叫，不複製）。
• DetectionProfileExtractionService._extract_in_thread：下載成功、解析成功後，在 _persist 的 session 內呼叫 store_snapshot，把回來的 file_id 交給 _persist。順序：先 store_snapshot（檔進儲存）→ replace_for_version（控制項）→ 改版本列。存檔在 session 內是可以的：它是本機／物件儲存寫入，不是外部網站。
• _persist(…, file_id=None)：file_id 有值時 version.source_type = "file"、version.file_id = file_id；url、source_etag、source_last_modified、sha256 照舊寫。
• 重抽換檔（D5）：_persist 發現版本已有 file_id 且本次又存了新檔 → 舊 file_id 收進一個清單，commit 後 file_upload_service.delete_file(old_uid)（失敗只 log，不回滾——孤兒檔比壞版本便宜）。
• 檔名：沿用 _download() 從網址推得的 name；推不出時用 <profile uid>-v<version>.tar.gz。

3.2 守門與派工

• common/detection_profile_ref.build_payload：刪 url 分支；source_type != "file" 直接 raise ValueError（派工層包成 DETECTION_PROFILE_NOT_DISPATCHABLE）。
• detection_orchestration_service._load_profile 之後一律 _load_profile_file，不再依 source_type 分流。url 型且 failed 的版本本來就被 assert_profile_dispatchable 擋；url 型且 pending／running 的版本（還在抽）由 build_payload 擋，錯誤訊息「此版本尚未解析完成，無法派工」。
• _check_source_freshness：條件從「source_type == url」改成「url 非空 且 status == succeeded 且有驗證器」。_read_controls 已把 _source_url 帶出來，不用改。
• list_current_files_visible_to、current_profiles_for_heartbeat、record_agent_states：不動。

3.3 資料庫（migration 014）

-- jedi-detection 014：外部連結型 Profile 解析成功後存成檔案（FR-174 D1／D2）
-- Date: 2026-11-0X
-- 🔴 套件只提供、不執行；冪等。
ALTER TABLE config.detection_profile_versions DROP CONSTRAINT IF EXISTS chk_dpv_source_exclusive;
ALTER TABLE config.detection_profile_versions ADD CONSTRAINT chk_dpv_source_exclusive CHECK (
    (source_type = 'file' AND file_id IS NOT NULL)
 OR (source_type = 'url'  AND url IS NOT NULL AND file_id IS NULL)
);
COMMENT ON COLUMN config.detection_profile_versions.source_type IS 'file＝有檔（上傳或由來源網址解析後存下）／url＝只登記網址、尚未解析成功';
COMMENT ON COLUMN config.detection_profile_versions.url IS '來源網址；file 型有值代表這份檔是從該網址解析存下的，開頁時拿它比 ETag';

主專案側由 flatten_pkg_migrations.sh 攤平到 scripts/sql/packages/jedi_detection/014-…，DEV 手套並登記 schema_migrations（登記名 packages/jedi_detection/014-fr174-url-profile-snapshot.sql）。

3.4 要改寫的註解與文件

detection_profile_extraction_service.py 檔頭「url 型：平台代為下載，但只在記憶體」整段、_download() docstring 紅字、detection_profile_version.py 兩個欄位 comment=、detection_profile_ref.build_payload docstring 的兩形狀表。改成描述新規則與陷阱（「解析失敗不轉型，否則 Agent 會拉到空」「重抽換檔要清舊檔」），不留「原本／改判」字樣。

底表 handoff/cards.py（兩個斷言已過：依賴都在更早的批、同批同 repo 不改同一既有檔）。

共 9 張、6 批；BE 3、jedi 套件 3、evidence-agent 2、FE 1。

1. DEV 主系統 Profile 頁：dev-sec Linux 版本列顯示來源「上傳檔案」圖示、檔名 linux-baseline-master.tar.gz（或推得的檔名）與來源網址；明細有「來源網址」列。
2. 本機 Agent 主控台 → 掃描 → CINC Auditor → Profile 下拉有「dev-sec Linux 基準」「dev-sec Windows 基準」，選一支對本機目標跑完有報告。
3. 主系統檢測任務綁 dev-sec Linux 派給本機 Agent，Agent log 顯示走 cache 路徑（不是網址）。
4. 控制項頁對 dev-sec 版本：改 DB 的 source_etag 成假值再開頁 → 出現「有更新版本，正在重新解析」→ 抽完 file_id 換成新列、舊 upload_files 列消失、Agent 下次同步重拉（sha256 變了）。
5. 新增一支壞網址的外部連結 Profile → failed、仍是 url 型、file_id 空、派工被擋 412。
6. 乾淨庫跑 001～014＋主專案 seed（補兩列 upload_files）→ dev-sec 兩版是 file 型。
7. grep -rn "source_type == \"url\"\|SOURCE_TYPE_URL" 在主系統 core/／app/ 與 Agent guidant_agent/ 為 0。

• 不加新欄、不加新表、不加新端點。
• 不做回填 migration、不做舊 Agent 相容。
• 不改 FR-171 設定通道、不改心跳。
• 不處理 189 POC（屬上版動作；升級後由決策者按兩次「重新解析」）。
• 不重產出貨基線（Z-1 回報清單，決策者裁示後另做）。