FR-059 檢測工具 Profile / Content 庫（掃描設定檔後台管理）（母案）

本卡為母案，統整目標、決策定案（P1–P7 + D1–D10 共 17 項）、四子需求索引。四個子需求（FR-059.1~.4）各有獨立卡片，關聯回本卡。FR-058 檢測工具擴充續作。

關聯：

CM-992 — FR-058 後續：GCB content 產製（Windows GPO 解析器）+ 後台 content 管理機制（本案承接其範圍③「後台 content 管理機制」——封閉網路 profile 遞送＋私有版本庫憑證兩限制的解法）
FR-058 母案 — FR-058 檢測工具擴充（四工具接入）（母案）（母脈絡：檢測工具擴充）
FR-058.7 母卡 — FR-058.7 SonarQube 上傳檔案掃描（scan 模式取源擴充）（agent 取檔通道依賴，該案先行；D6 resolver 可插拔介面須在其 T-7.1 談定）

設計文件：docs/features/FR-059-2608-detection-profile-library/design.md（BE repo）——§3 決策定案 / §5 詳細設計 / §6 拆分 / §7 驗收

討論稿（含流程圖）：同資料夾 discussion.html

任務摘要

現況一支新 profile 要走四步人工維運鏈（進 BE repo 版控 → 人工 rsync 到每台 agent 主機 → 寫 migration 加 param_schema options → 三環境套用），沒有任何一步是一線工程師或客戶端管理員做得到的；8 支 TWGCB profile 只投放 DEV agent，STG / POC 的 agent 根本沒有檔案（選了下拉也掃不動）。CM-992 另記錄兩個限制：封閉網路客戶無法投放 profile、私有版本庫無憑證路徑。

目標：agent 只升級一次（學會「拉檔＋cache」），之後 content 的新增 / 改版 / 停用全部在後台完成——不再重建 agent image、不再人工 rsync、不再為選項寫 migration。公用版由 root 租戶維護全租戶可見，各租戶也能上傳自己的 profile，雙軌模式與流程管理（flow_templates）完全一致。

端到端流程

管理者在「掃描設定檔管理」頁上傳 profile（zip/tar/tar.gz/tgz 或登記 URL）
  → BE 驗證（格式/大小/結構含 inspec.yml/防 slip・bomb）→ 計算 sha256 → 存平台儲存 + 落 config.detection_tool_profiles
  → 任務抽屜 profile 下拉動態列出庫內項目（按 detection_tool_id 過濾）
  → 使用者選庫內 profile 發起執行（params.profile = "profile:<uid>"）
  → 派工 _collect_pending_tasks() 偵測前綴、展開 _profile 內部 payload
  → agent 心跳領工 → 查本機 cache /data/content/cache/<uid>/v<version>/
      命中 → 直接用；miss → GET /api/1.0/agents/files/<uid>（FR-058.7 通道）拉檔
      → 重算 sha256 對帳（不符即 fail）→ 安全解壓進 cache 目錄
  → 把解壓後「目錄」餵給 cinc-auditor（四格式一條路徑，D4）→ 掃描 → 報告走既有 blob 回收鏈

決策一覽（P1–P7 + D1–D10，共 17 項全數拍板）

完整版（含被排除方案與理由）見 design.md §3，此表為一句話濃縮：

#	主題	定案一句話
P1	範圍	第一期只做形態 A（agent 本機讀取型），涵蓋 inspec＋gcb 兩工具；資料模型帶 detection_tool_id 保持 tool-agnostic（OpenSCAP / ZAP 排除）
P2	取檔通道	復用 FR-058.7 的 `GET /api/1.0/agents/files/<uid>`（純 mTLS＋任務綁定＋串流不落地），不重建；本案增量＝`profile_ref` resolver（見 D6）
P3	存量搬遷	既有 8 支 TWGCB 搬入庫成 SYSTEM 公用版 seed——上線第一天下拉零回歸；搬完退役舊路（時程見 D5）
P4	版本模型	照抄 detection_tool_param_schemas：`version`＋`is_current` 單現行版；版更＝INSERT 新版＋舊版 is_current=FALSE，不原地 UPDATE
P5	型態雙軌	`source_type = file
P6	手填保留	欄位維持 `select_or_text`，取值三層並存：庫內 file / 庫內 url / 現場手填——既有手填值升級後照常可用（相容性零破壞）
P7	工具隔離	CINC 與 GCB 的 profile 池分開，按 detection_tool_id 綁定與過濾；同檔兩工具用就各登記一筆，提供「複製到另一工具」動作
D1	表落點	`config.detection_tool_profiles`；事實修正：config schema 已有 RLS 前例（tdtc_tenant_isolation），本表帶 RLS 並非首例
D2	庫參照格式	`profile:<uid>` 顯式前綴字串存 `params.profile`，派工時展開——與手填值零歧義、單欄位不動 FE 主參數顯示
D3	FE 入口	系統管理下獨立新頁「掃描設定檔管理」——tenant 管理員與 root 同一頁，靠 scope 區分能力（公版對非 root 唯讀）
D4	上傳格式（決策者修訂）	收 zip / tar / tar.gz / tgz 四格式、上限 50MB；agent 端交付統一化——一律安全解壓到 cache、把目錄餵 cinc-auditor（四格式一條路徑）
D5	舊路退役	過渡一版——驗收通過後下一版拿掉 agent bind mount 與 param_schema 靜態 options；手填容器路徑能力因 P6 永遠保留
D6	058.7 通道增量	端點共用、授權 resolver 按檔案用途分流（source_file / profile_ref 各自驗證）；🔴 058.7 須把授權驗證做成可插拔 resolver 介面（寫進其 T-7.1 規格）
D7	URL 型公版搬遷	dev-sec linux-baseline / windows-baseline 兩條公開 tarball URL 搬成 SYSTEM url 型公版，與 P3 同批 seed——CINC 下拉零回歸＋url 型首批示範資料
D8	上傳驗證深度	只驗「結構＋檔案安全」（inspec.yml / slip / bomb / 大小）；profile 正確性由掃描執行結果反映（界線明寫），BE 裝 CINC pre-check 列未來
D9	agent cache 管理	第一期無上限＋手動清理指引；cache key 含 version 版更自然失效；重啟不清；LRU 上限列 follow-up
D10	三環境節奏（提醒）	DEV 先行驗收，STG / POC 一律等決策者明示放行才套 migration 與 seed（環境異動鐵律）；放行後 STG/POC agent 第一次有可用 GCB 掃描能力

依賴鏈

flowchart LR
    A[FR-059.1 BE 地基] --> B[FR-059.2 下發整合]
    A --> D[FR-059.4 FE]
    B --> C[FR-059.3 Agent 端]
    E[FR-058.7 取檔通道] -.硬依賴.-> C
    E -.resolver 介面談定 D6.-> B