掃描設定檔管理（Scan Profile Management）

功能群：系統管理｜共用權限模型先讀 功能群總覽

事實基準：2026-08-01 從 FE src/views/detection-profile/DetectionProfileManageView.vue（1,239 行）+ BE api/detection_tools/routes/detection_tool_profile_route.py / app/detection_tools/service/detection_tool_profile_service.py 全鏈 + DEV config.detection_tool_profiles 實查掃出（FR-059 檢測工具 Profile / Content 庫 T-1.1~T-4.2）

變更紀錄

1. 功能描述

掃描設定檔管理是檢測工具（CINC Auditor / GCB）掃描設定檔（profile / content）的後台管理頁：把「一支掃描要套用哪套檢測基準」的內容檔收進平台庫，取代原本「進版控 → 人工投放到 Agent 主機 → 改資料庫選項」的維運鏈。上傳或登記後，任務配置頁的 profile 下拉立即列出庫內項目（不經任何部署動作），Agent 執行時透過平台通道取檔——封閉網路（Agent 無外網）環境也能使用檔案型設定檔。

資料模型是公用版 / 租戶自有雙軌（與流程範本管理同一模式）：scope='SYSTEM' 公用版由平台（root 租戶）管理員維護、全租戶可見可用但唯讀；scope='TENANT' 自有版各租戶自行上傳維護、他租戶不可見。非 root 使用者對公用版可「複製為自有」（fork）後自行編輯。設定檔按 detection_tool_id 分池：上傳時必選所屬工具，GCB 任務抽屜只見 gcb 池、CINC Auditor 只見 inspec 池；同一份內容兩工具都要用，走「複製到其他工具」各登記一筆。

來源型態雙軌：檔案型（source_type='file'）上傳打包檔存平台儲存，Agent 走 mTLS 通道拉檔＋本機 cache；連結型（source_type='url'）只登記 URL 字串，Agent 原樣交給檢測引擎自行下載，平台不驗證可達性、不代管憑證（打不打得通是使用端網路與授權問題，設計界線非缺陷）。

主要使用者：持有 detection-profile.* capability 的角色（角色權限矩陣「掃描設定檔管理」列；比照流程範本管理授予各租戶系統管理員角色）；tenant 管理員與 root 用同一頁，能力差異由 BE 回的 can_edit 與三層守門決定。

角色速覽：

1.1 功能總覽（本頁全部功能）

UC（§2）展開具後端寫入的核心路徑：新增 / 登記（6，UC-DPM-01）、版更（7，UC-DPM-02）、fork（8，UC-DPM-03）、停用（10，UC-DPM-04）。複製到其他工具（9）與 fork 同構（INSERT 新列），於 §6.4 說明；純顯示 / 篩選類（1~5、11、12）於 §5 / §6.2 說明。

2. Use Case

角色速覽：見 §1。

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-DPM-01 上傳 / 登記掃描設定檔

流程：按「新增設定檔」開 Dialog → 選所屬工具（必選）＋來源類型＋名稱 → 檔案型選擇打包檔（FE accept=".zip,.tar,.tar.gz,.tgz"、maxFileSize=52428800）走 multipart 送出；連結型填 URL 走 JSON 送出（同一 endpoint 依 content-type 分流，_payload()）→ BE capability 檢查 → 同工具同租戶同名檢查（DETECTION_TOOLS_409006）→ 檔案型跑驗證管線（四格式偵測 / 50MB / 安全 / 結構，四種失敗各自獨立 error code，見 §6.3）→ 計算 sha256 → 存平台儲存 → INSERT。連結型只驗 URL 形狀（須 http(s):// 開頭，否則 DETECTION_TOOLS_400012），不驗可達性。

建立公用版（scope='SYSTEM'）目前無 FE 入口：新增 Dialog 的 scope 固定送 TENANT（DetectionProfileManageView.vue::openCreate:188-202），API 雖收 scope 欄位且 service 有對應守門，公用版新增現況走 seed script（見 §11）。詳見 §12 坑 1。

UC-DPM-02 版更

流程：按「版更」開 Dialog（顯示「為『{name}』建立新版本（目前 v{n}）」）→ 檔案型換新檔 / 連結型換新連結（名稱與所屬工具沿用舊版不可改——版更的定義是「同一支 profile 的新內容」）→ BE guard（SYSTEM 列非平台管理員 → DETECTION_TOOLS_403001）→ 帶了新來源就重跑驗證管線；未帶新來源（只改描述 / 適用平台）也算一次版更，沿用舊版的檔案與 sha256，讓每一列自身資訊完整 → 先 demote_current（舊版降 FALSE）再 INSERT——順序不可顛倒，uq_dtp_current_name 唯一索引擋兩筆 current。

UC-DPM-03 複製為自有（fork 公用版）

流程：按「複製為自有」→ Dialog 預填來源名稱（可改）→ 送出 → BE 檢查本租戶同工具同名（DETECTION_TOOLS_409006）→ INSERT——scope / tenant_id 由 BE 硬寫成 TENANT / 本租戶，不沿用來源列（沿用會讓副本仍是公用版，等於任何人 fork 一次就多一份全站可見資料；detection_tool_profile_service.py::fork_profile:256-294）。

UC-DPM-04 停用

流程：按「停用」→ confirm（「停用後任務下拉不再出現此設定檔，既有的執行紀錄不受影響」）→ PUT /<uid>/deactivate → guard → 更新兩旗標。

3. 權限矩陣

三層防禦分工（capability 管「能不能碰這個功能」、service guard 管「能不能碰公用版」、RLS 兜底）：四個 capability 全部 is_platform=false——租戶管理員必須能建自己的 TENANT 設定檔與 fork 公用版，這正是雙軌功能的核心；公用版保護不在 capability 層鎖。與檢測工具管理（純平台目錄頁）的守門模型刻意不同。

⚠️ detection-profile.update capability 已 seed 且掛在路由節點，但目前沒有任何端點使用（見 §12 坑 2）。

4. 狀態機與前置條件

本頁無輪次 / 階段狀態機，僅有每列自身的 is_active × is_current 二旗標，FE 呈現為三態：

頁面 gate 表：

5. UI 設計

版面骨架（篩選列 + DataTable + 四組 Dialog）：

📸 實機截圖待補：列表（公用版 10 筆排前 + 自有列、三態狀態 Tag、公用版鎖 icon）、新增 Dialog（file / url 兩型態各一張）、版更 Dialog、複製為自有 Dialog、詳細資料 Dialog（sha256 等寬字）、任務抽屜 profile 下拉動態選項（GCB 池）。

狀態呈現：來源欄 Tag——公用版（info）/ 自有（success）；類型欄 icon＋文字——上傳檔案（pi-file）/ 外部連結（pi-link）；狀態欄三態 Tag（見 §4）。名稱 cell 可點開詳細資料 Dialog（hover 底線）；描述截兩行顯示於名稱下方。互動模式沿用流程範本管理頁（segmented pill 篩選、DataTable lazy 分頁、confirm 停用），不另發明。無 socket；各寫入動作成功後重打 fetchProfiles()（新增另重置回第 1 頁）。首次載入以 LoadingState 蓋住整個表格區。錯誤呈現：具體驗證錯誤（格式 / 大小 / 安全 / 結構）由 axios interceptor 依 error code 出 toast（error-code.json 已補 DETECTION_TOOLS_4000xx 對應文案），Dialog 端 catch 留空不重複出錯。

6. API 規格

Envelope：成功 {"code": 1, "data": …}、失敗 {"code": 0, "msg": "…"}（return_response）。route 註冊：api/detection_tools/__init__.py:48-68（掛 /detection-tool-profiles，不掛工具目錄底下——設定檔是獨立資源家族）。

6.1 總清單（本頁呼叫的全部 endpoint）

6.2 列表 / 下拉 menu

[POST] /detection-tool-profiles/list

Request（RequestMetaSchema 分頁慣例）：

{
  "pager": {"page": 1, "page_size": 10, "with_total": true},
  "sort": [],
  "filters": {
    "detection_tool_uid": "<uid>",
    "source_type": "file",
    "scope": "SYSTEM",
    "name": "TWGCB",
    "is_active": true,
    "current_only": true
  }
}

Response data[]（DetectionToolProfileResponseSchema）：

排序固定：scope asc, name asc——'SYSTEM' < 'TENANT' 字典序，公用版天然排前（detection_tool_profile_repo_impl.py:89-92），FE 不另排序。

可見範圍是業務語意不是只靠 RLS：root 租戶的 allowed_tenant_paths 前綴涵蓋所有子租戶，只靠 RLS 的話平台管理員會看到全站每個租戶的私有設定檔；repo 顯式收斂 or_(scope=='SYSTEM', tenant_id==ctx.tenant_id)（:45-56），RLS 只是兜底。

出處：route detection_tool_profile_route.py:54-77、schema api/detection_tools/serializers/detection_tool_profile.py:13-61、service detection_tool_profile_service.py::list_profiles:84-112。

[GET] /detection-tool-profiles/menu?detection_tool_uid=

detection_tool_uid 必帶（P7 分池：GCB 抽屜只該見 gcb 池，未帶回 400 DETECTION_TOOLS_400007）。只回 is_current=TRUE AND is_active=TRUE 的列（公用版＋本租戶自有）。Response data[]（DetectionToolProfileMenuResponseSchema）：

出處：route :80-97、service list_menu:114-125、repo list_menu:114-123。

6.3 新增 / 登記

[POST] /detection-tool-profiles

同一 endpoint 收兩種 content-type（route _payload():43-51 判 multipart/form-data 取 request.form，否則取 JSON）：檔案型走 multipart（檔案在 file 欄位、其餘欄位在 form；FE 送 FormData 時不手動設 Content-Type，讓 axios 自帶 boundary）；連結型走 JSON。

檔案型驗證管線（common/util/detection_profile_archive.py::ProfileArchiveValidator，streaming 全程不落地解壓——只讀 entry metadata、不呼叫任何 extract）：

tar 系與 zip 的安全檢查共用同一套 entry 檢查器（僅迭代介面不同）——「按格式分支處理」正是 zip 路徑漏防的典型成因。source_type 與來源欄位互斥（file 無檔 / url 無字串 / 未知型態）→ 400 DETECTION_TOOLS_400012（DB chk_dtp_source_exclusive CHECK 是兜底，業務層先擋讓錯誤可讀）。

出處：route :100-125、service create_profile:133-194 / _resolve_source:404-432 / _store_file:434-458。

6.4 版更 / fork / 複製到其他工具 / 停用

[POST] /detection-tool-profiles/{uid}/new-version

Request（全部選填；multipart / JSON 同 §6.3 分流）：source_type / file / url / description / platform_hint。名稱與所屬工具不收（沿用舊版）。來源型態允許換（file → url 或反向）；帶了新來源重跑驗證管線；全部未帶＝只改 metadata 也算一次版更，沿用舊版 file_id / sha256 / url——讓「這一版對應哪個檔」在每一列上都是完整的（Agent 拿 payload 不必回溯前版）。寫入順序固定：先 demote_current 再 INSERT version+1（uq_dtp_current_name 擋兩筆 current，順序是必要條件不是風格）。出處：service create_new_version:196-254。

[POST] /detection-tool-profiles/{uid}/fork

Request：{"name": "<新名稱>"}（未帶沿用來源名）。scope='TENANT' / tenant_id=本租戶 硬寫；file_id / url / sha256 沿用來源列（共用同一 upload_files 實體——profile 檔不可變、版更＝新列新檔，複製 binary 只會同內容存兩次）。同名檢查對本租戶池。出處：service fork_profile:256-294。

[POST] /detection-tool-profiles/{uid}/copy-to-tool

Request：{"detection_tool_uid": "<目標工具>", "name": "<名稱>"}。目標工具＝來源工具 → 400（FE 下拉已排除來源工具，copyToolOptions:387-389）。scope 沿用來源——把公用版複製到另一工具，結果仍是公用版（受眾沒變，只是換池），故此路徑走 _guard_system_writable（與 fork 的語意差異正在於此）。同名檢查對來源列的 tenant_id＋目標工具池。出處：service copy_to_tool:296-343。

[PUT] /detection-tool-profiles/{uid}/deactivate

無 body。is_active=FALSE 且 is_current=FALSE（後者讓同名後繼者建得起來——留著 current 會撞 uq_dtp_current_name；deactivate_profile:345-360）。

Error code 一覽（本頁新增，common/code/detection_tools_error_code.py:56-90）

FE error-code.json（zh-tw / en）已補齊上列八碼文案，上傳失敗由 axios interceptor 統一出 toast。

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：route 不碰 session、app service 全數 @transaction、repo 繼承 BaseRepositoryImpl；寫入守門 route 層 capability decorator（主體域）＋service 層 scope guard（資源域）雙軌，符合 FR-048 規範。

9. DB

9.1 資料表總清單（本頁讀寫的全部表）

9.2 ER 圖

9.3 核心表欄位（2026-08-01 DEV 實查）

config.detection_tool_profiles — 掃描設定檔庫

唯一索引三組（皆含 version 或以 is_current 收斂——版更後同名多列並存是常態，全域唯一會在第一次版更撞索引）：

1. uq_dtp_tool_tenant_name_version (detection_tool_id, tenant_id, name, version)
2. uq_dtp_system_tool_name_version (detection_tool_id, name, version) WHERE scope='SYSTEM' AND is_active（公用版跨租戶防撞名的防禦性第二道）
3. uq_dtp_current_name (detection_tool_id, tenant_id, name) WHERE is_current AND is_active——「同名只有一個現行版」的真正保證

查詢索引：idx_dtp_tool_current_active（menu）、idx_dtp_tenant_scope（列表）。

RLS 四段 policy（detection_tool_profiles_select / insert / update / delete）：SELECT 公用版分支放最前（人人可讀）＋super_admin＋自己子樹；INSERT WITH CHECK 堵 SYSTEM 偽造；UPDATE USING＋WITH CHECK 兩段都有（缺 WITH CHECK 的話租戶可把自己的列 UPDATE 成 scope='SYSTEM' 升格公用版）；DELETE 非 super 不能刪 SYSTEM。app_tenant_allowed_for_session() 只接 integer，呼叫處對 bigint tenant_id 顯式 ::integer cast。

建表 migration：scripts/sql/2026-08-01-fr059-1-detection-tool-profiles.sql（含 GRANT cm_app＋sequence）；capability seed：2026-08-01-fr059-2-detection-profile-capability.sql；選單路由：2026-08-01-fr059-3-detection-profile-menu-route.sql。三支皆只套 DEV，STG / POC 依環境異動鐵律等放行（§12 坑 12）。

10. 頁面邏輯與資料對應

載入時序：onMounted 先 fetchTools()（工具目錄——所屬工具欄顯示名與新增下拉的來源；拿不到不擋列表，只是工具欄退成 code、新增下拉為空）→ fetchProfiles()。搜尋 300ms debounce 重查並跳回第 1 頁；scope / 工具 / 歷史開關任一變動同樣重查跳頁。

關鍵欄位對應（畫面 ↔︎ API）：

儲存流程：新增依 source_type 分流——file 組 FormData（欄位逐一 append、空值不帶）、url 組 JSON（空值帶 null）→ createProfile() → 成功 toast＋關 Dialog＋清 FileUpload＋跳回第 1 頁重查。版更 / fork / 複製 / 停用成功後重查當前頁。

錯誤對應：BE error envelope → axios interceptor 依 error code 查 error-code.json 出 toast（八碼文案見 §6.4）；Dialog 的 catch 留空不重複出錯。列表載入失敗另有本地 toast（toast_load_failed）並清空列表。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 公用版新增無 FE 入口（現況）：新增 Dialog 的 scope 寫死 TENANT——API 與 service guard 都支援 scope='SYSTEM'（平台管理員），但 FE 沒有渲染 scope 選擇欄位（i18n 已備 field_scope / hint_scope_system key 未使用）。公用版建立現況走 seed script；root 對既有公用版的版更 / 複製 / 停用則正常可用（can_edit=true）。要補公用版新增 UI 時 i18n 與 BE 都是現成的。
2. detection-profile.update capability 是預留孤兒：四能力點全數 seed 且掛路由節點（read=ALL、寫入三個=ANY），但版更 / fork / 複製全是 INSERT 對 create、停用對 delete——沒有任何端點消費 update。日後若出現原地編輯類端點（如改描述不升版）再啟用；在那之前對角色勾 update 沒有實際效果。
3. 讀端點僅 JWT 無 capability 守門：列表 / menu / 詳細只 @jwt_required()——menu 是任務抽屜全員要用的（刻意開放），列表與詳細跟著同粒度。可見範圍靠查詢收斂＋RLS，不靠 capability；與寫入端點的守門粒度不一致，改動時勿混為一談（同 檢測工具管理 §12 坑 2 模式）。
4. 停用同時降 is_current，FE 歷史開關必須一起放兩個條件：deactivate_profile 把 is_active 與 is_current 一起降 FALSE（留著 current 會讓同名後繼者撞 uq_dtp_current_name 建不起來）。因此 FE「顯示已停用與舊版」開關必須同時放掉 is_active 與 current_only——只放前者的話停用列仍被 current 條件濾掉、開關等於沒作用。代價是版更後的舊版一起現身，狀態欄因此做三態（啟用中 / 舊版 / 已停用）不把舊版誤標成啟用中。
5. fork 與複製到其他工具共用檔案實體不複製 binary：file_id / sha256 沿用來源列——profile 檔不可變（版更＝新列新檔），同內容存兩次沒有意義。含意：來源公用版停用不影響 fork 列（upload_files 實體仍在）；反向也一樣。
6. fork 不走 SYSTEM guard、複製到其他工具走：fork 寫的是新租戶列（scope 硬寫 TENANT）；複製沿用來源 scope——公用版複製到另一池結果仍是公用版，故需平台管理員。兩者語意差異就在這裡，改動守門時別對齊成同一套。
7. 派工不檢查 is_current 只檢查 is_active：任務綁定存的是使用者當初選的那一版 uid，版更後舊版仍是合法歷史版本，掃描照使用者所選執行（要換版是使用者自己回任務改選，不是 BE 偷偷跳版）；停用才是「不該再被使用」的管理決策。參照失效（查無 / 停用）→ 派工當下 400 明確報錯，不原樣下發（agent 會拿到無法解析的 profile:<uid> 變成 agent 端神祕失敗）、不默默拿掉（使用者以為在掃 A 基準實際參數沒了）。
8. profile: 前綴契約單點：menu 的 value 已是 BE 組好的 profile:<uid>，FE 不自己拼前綴；BE 端前綴判斷只有 common/util/detection_profile_ref.py 一份，派工展開不可自己寫 startswith。手填值不可能以 profile: 開頭——這是三種取值來源（庫內 / 手填 / 舊靜態選項值）零歧義共存的基礎。
9. _profile.uid 對 file 型是 upload_files 的 uid 不是 profile 列的 uid：agent 拿它直接打取檔端點（該端點認的就是 upload_files uid）；url 型無檔案實體，uid 才是 profile 列自己的。讀 payload 時別搞混兩種 uid。
10. 上傳驗證是第一道不是唯一一道：bomb 檢查靠 entry 自報的宣告 size（header 值理論上可偽造）——偽造後 agent 端真解壓時與宣告不符會失敗，且 agent 端另有一套同等的 slip / bomb 防護（BE 驗過不代表可信任傳輸後內容）。本驗證器是全 repo 第一個壓縮檔安全實作，之後任何要收壓縮檔的功能應來 common/util/detection_profile_archive.py 復用，不要各自再寫一套。
11. url 型平台不驗證可達性、不代管憑證：登記時只驗 http(s):// 形狀。連結打不打得通、要不要憑證，是使用端網路與授權問題——此界線在設計即明寫（含 FE hint 文案），別當缺陷回報；需求出現再立案。
12. ⚠️ 本功能現況只在 DEV：表 / capability / 選單路由 / param_schema 升版 / 搬遷 seed 全數只套 DEV（環境異動鐵律）。param_schema 升版 migration 尤其不可單獨誤套 STG / POC——它拿掉靜態 options，而該兩環境沒有搬遷 seed 資料，套下去任務抽屜下拉會直接空掉；必須整批依序等決策者放行。
13. 同名檢查是業務層前置、唯一索引是兜底：find_by_exact_name 查同租戶同工具現行名稱；公用版與某租戶自有版可以同名（不同 tenant_id 池）——fork 預設沿用原名能成立正是因為這點。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟
• 測試帳號：dev 環境持 detection-profile.create / delete capability 的帳號（比照流程範本管理授予的租戶系統管理員角色；公用版維護需 root 租戶平台管理員），密碼見 .env / 部署文件
• 導航路徑：登入 → 合規稽核 → 「掃描設定檔管理」（/plugin/detection-profile-manage，選單掛在檢測工具管理與流程範本管理之間）
• 前置資料：config.detection_tools 已 seed（工具下拉來源）；公用版 10 筆由 scripts/seed_2026-08-01_fr059_detection_profiles.py 落庫（需 BE 環境可連 DB 執行）；上傳測試可用 content/detection-profiles/ 下任一 TWGCB 目錄自行打包 tar.gz
• 驗證要點：上傳四格式正常樣本全過、惡意樣本（假副檔名 / 超大小 / traversal / 無 inspec.yml）各回獨立 error code；版更後 menu 指新版且舊版留存；fork 後副本可編輯；非 root 對公用版寫入 403；租戶 A 看不到租戶 B 自有列（RLS）；任務抽屜 GCB 池只見 gcb、CINC 只見 inspec
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 detection-profile / 掃描設定檔 搜尋
• 相關文件：需求討論稿（決策脈絡與 mermaid 流程圖）docs/features/FR-059-2608-detection-profile-library/discussion.html；設計決策全文（P1–P7 + D1–D10）同資料夾 design.md；下拉動態化與三層取值來源見 任務配置；執行紀錄的 profile 標籤對照見 我的任務 §11.1；工具目錄與 param_schema 兩層 schema 關係見 檢測工具管理；使用手冊 docs/user-manual/scan-profile-guide.md