FR-060 檢測基準內容管理 — 設計文件

功能編號：FR-060｜名稱：檢測基準內容管理（Detection Profile Content Management） 狀態：設計定案，待實作（D1–D19 全數拍板）｜建立日期：2026-08-03 前作：FR-059 掃描設定檔庫（Profile 庫）／FR-058 檢測工具整合平台｜後續：FR-061 選用範圍・豁免・人工判定・自訂項 工作 branch：feature/e2e-env-build 討論稿（含四張流程圖與五支探脈實測）：discussion.md

1.1 使用者現在看到的只有一個名字

FR-059 解決了「profile 怎麼進系統」——把掃描設定檔打包收進平台庫、由 agent 拉檔執行。但平台把 profile 當成不透明的二進位檔，完全不理解它的內容：使用者在管理頁與任務下拉看到的只有一個名稱（例如「TWGCB-01-014 Ubuntu 22.04 LTS」），不知道它會驗什麼、驗幾項、哪些項目其實跑不出結果。

決策者原話（2026-08-03）：

目前只有項目，user 完全不知道這個東西會驗證什麼，我怎麼知道我要選什麼？哪些基準可以參考，我可以先請負責人去判斷、提前先處理，而不是等報告出來才去處理。

1.2 一組實測數字說明急迫性

拿系統內最常被選用的 TWGCB-01-014（Ubuntu 22.04 政府組態基準）在 DEV agent 主機（192.168.50.123，CINC Auditor 7.1.7）實跑抽取：

使用者現在完全看不到這件事。他選了基準、跑完掃描、拿到一份報告，才發現絕大多數條目是 skip——而 skip 的意思是「這條要人工判斷，工具幫不了你」。這正是原話裡「先請負責人去判斷、提前先處理」所指的缺口：199 條人工待判項如果在選擇當下就看得到，負責人可以提前展開作業；等報告出來才知道，等於白等一輪掃描。

1.3 三個需求

下一階段（FR-061）才做的是對基準內容動手的能力：選用範圍、豁免、人工判定、自訂項。本案只定義「資料模型必須支撐什麼」，不做實作——這些能力直接改變掃描參數，改錯會讓結果不正確，必須等瀏覽與分類上線、看到實際使用情形再定形狀。

1.4 為什麼一個「瀏覽功能」要順帶重構資料模型

決策者在討論過程中明確要求：「你要拿出你專業設計師的模式，而不是每次都用最快達到要求的模式把功能做出來，底層設計很重要。」

三個需求裡有兩個被現行資料模型直接卡住，第三個無處落腳：

1. 名稱被當成身分，所以改名改不動——現行唯一索引是 (detection_tool_id, tenant_id, name)。改名會撞索引、會讓版本鏈斷開。
2. 分類屬性歸屬錯層——分類是「這支基準是什麼」的屬性，應該跟著基準走，不該每個版本重填一次。現行單表沒有「基準」這一層，只有「某支基準的某一版」；分類存單表會每版重複，版更漏帶就漂移。
3. 控制項無處可放——234～708 條控制項是「某一版的內容」，需要一張自己的表，且要能被 FR-061 的豁免以外鍵參照。

因此本案第一步是主從拆表：

detection_profiles          基準主檔：名稱 / 描述 / 分類三軸 / 範圍 / 所屬工具 / 啟用狀態
  └─ detection_profile_versions   版本從檔：來源檔 / sha256 / 版號 / 當前版旗標 / 抽取狀態
       └─ detection_profile_controls  控制項：一條一列，跨格式正規欄 + attributes jsonb

而且現在是最便宜的時機：DEV 僅 13 筆資料（10 筆 SYSTEM／3 筆 TENANT）、FR-059 上線才兩天、沒有租戶真的在用。等 FR-061 把選用範圍與豁免綁上去再拆，成本是現在的好幾倍。

2.1 上傳到瀏覽的主幹道

使用者上傳 profile 壓縮檔
  → BE 結構驗證（找 inspec.yml / 防壓縮炸彈 / 防 zip-slip）── 同步、毫秒級
  → INSERT 版本列（extraction_status = pending）
  → 立即回應前端「上傳成功，內容解析中」    ← 不等抽取
  → 排入背景抽取工作（extraction_status = running）
  → 壓縮檔 bytes 落成臨時檔（NamedTemporaryFile，副檔名必須正確）
  → 依 profile_format 取對應 extractor（本期只實作 InSpec）
  → cinc-auditor json <臨時檔>      ── 234 條約 28 秒 / 708 條約 117 秒
  → 解析：剝掉 source_location 絕對路徑前綴 / 丟 code / 丟重複 desc
          impact == 0.0 標記人工待判
  → 批次 INSERT 控制項，extraction_status = succeeded
  → 刪除臨時檔
  → 前端輪詢（建議 5 秒一次）看到狀態轉換，開啟版本詳細頁瀏覽

失敗有三種分支，其中第三種最危險：

抽取耗時與體積為實跑數據，非推估：

欄位佔比實測：code 47.8%／tags 16.2%／descriptions 13.1%／desc 11.8%，其餘各低於 10%。丟掉 code 與與 descriptions.default 重複的 desc 共省 59.6%。

117 秒遠超任何 HTTP 逾時設定——抽取必須非同步，這一點沒有折衷空間，同步做法在 Windows 那支上必定逾時。

🔴 紅框一：人工待判項的判準是 impact == 0.0，不可用任何自訂 tag

四種寫法交叉比對的實測結果：

判準	命中條數	結果
impact == 0.0	199	✅ 正確。InSpec 原生語意，任何 profile 都有
code 含 skip	199	✅ 正確。與上者同一集合
tags.status == 'pending-mapping'	199	✅ 正確，但屬 TWGCB 自訂 tag，外來 profile 沒有
tags.check_type == 'pending'	193	❌ 錯誤，漏 6 條

twgcb_01_014_0079 ~ twgcb_01_014_0084 這 6 條標的是 check_type: 'service'，但實際上 impact 為 0.0 且程式碼只有一個 skip——它們是貨真價實的人工待判項，只是 tag 標錯了。

正解是 impact == 0.0——這是 InSpec 原生語意（impact 0 代表這條不做自動判定），客戶自帶的外來 profile 也一定有這個欄位，實測 100% 準確。不要依賴任何自訂 tag 做這個判定。（依 D19，此判準寫在 InSpec extractor 內，不是寫死在表結構的假設裡。）

2.2 既有派工鏈為何不受影響

本案 .1–.3 全在管理面，agent 拿到的 payload 形狀與今天一模一樣：

• common/util/detection_profile_ref.py 的 build_payload() 全部讀從檔欄位，拆表後原樣可用。
• agent_file_access_service._profile_ref_resolver 比對的是 upload_files 的 uid，根本不碰 profile 表。
• 兩條凍結契約的 soft-ref 不變：config.job_execution_detection_tools.tool_params JSONB 的 4 筆 profile:<uid> 字串、compliance.agent_tasks.params JSONB 的 6 筆 _profile 物件。因為 D4 定案「uid 由從檔逐列沿用」，這 10 筆既有引用零轉換、零風險。

⚠️ 注意 _profile.uid 的語意依 source_type 而異：url 型是 profile 列的 uid、file 型是 upload_files 的 uid（agent 拿它去打 FR-058.7 取檔通道）。兩個 uid 來自不同的表，搬遷時必須分開對待。

🔴 紅框二：派工鏈「零影響」的假設不成立，有兩處破口

實際 grep app/detection_tools/service/detection_orchestration_service.py 後發現兩處會壞，其中一處是無聲的授權漏洞：

破口 ① — _load_profile() 檢查 profile.is_active 拆表後 is_active 在主檔。若 _load_profile() 拿到的是從檔 entity：從檔沒有該屬性 → AttributeError → 500；從檔有但預設 None → None is False 為假 → 守門靜默失效，已停用的 profile 照樣派得出去。後者不會有人發現，比 500 更糟。

破口 ② — _humanize_profile_param() 用 getattr(profile, "name", None) name 拆表後在主檔。這裡有 default 值所以不會報錯，只會讓通知信裡的「掃描設定」靜默退化成 profile:<uuid>，而且目前沒有任何測試會抓到這個退化。

解法：domain service 新增 get_version_with_profile(uid)，回傳主檔＋從檔合成的 entity，orchestration 的三處改指它。對外行為零變化，且把「派工需要哪些欄位」收斂到一個方法裡。

2.3 環境紀律

開發期間所有 migration 只套 DEV。 STG 與 POC 一律等決策者當次明確指示才可套。 本案的拆表 migration 會 ALTER TABLE ... RENAME 一張 STG 正在服役的表，比加欄位危險一個量級。

連線帳號為 cmmgr（跑 migration）／cm_app（受 RLS），密碼請查 .env 的 DB_SECRET，不得寫入任何版控檔案。

🔴 紅框三：「STG 跑得順」不能當驗收依據

STG 與 DEV 同為 125 筆 migration、FR-059 全 5 支都在，但 STG 資料全部是 SYSTEM、沒有任何 TENANT 資料。這意味著搬遷 SQL 在 STG：

• 測不到租戶 RLS 路徑
• 測不到 id 32／33 的三欄 JOIN 陷阱（同 tenant、同 name、同 file_id 但屬不同工具）
• 測不到停用列造成的孤兒主檔（current_version_id IS NULL 的合法狀態）

驗收必須在 DEV 完成——那裡才有完整的資料形態。

以下每一項都含決策內容／定案理由／被排除方案與原因。被排除方案不可省略——未來要反悔時，必須看得到當初排除了什麼、為什麼。

3.0 已拍板兩項

✅ 抽取落點 ＝ BE 主機安裝 CINC Auditor

決策內容：抽取工作在 BE 主機執行，不派給 agent。安裝方式：

curl -fsSL https://omnitruck.cinc.sh/install.sh | bash -s -- -P cinc-auditor -v 7

定案理由：抽取是上傳當下就要發生的事，不能依賴 agent 在線。成本已列明並接受：體積 275MB（其中約 200MB 是本案用不到的 AWS／Azure／GCP SDK 與遠端 transport）、三台部署機加每台開發機都要裝、收尾要在 docs/claude/host-dependencies.md 新增第三項（現有兩項是中文字型與 LibreOffice）。

• ⚖️ 授權紅線：必須是 CINC Auditor（Apache 2.0）。絕不可換成官方 InSpec 6+ 商業 binary（需接受 Chef EULA 並取得 license key）；inspec-core gem 由 Chef 官方發布、同樣受 EULA 影響，也不可用。
• 路徑解析比照 LibreOffice 慣例（docs/claude/host-dependencies.md:85-89）：環境變數 CINC_AUDITOR_CMD → PATH → 絕對路徑 fallback。不要硬編 /usr/bin/cinc-auditor（macOS 開發機路徑不同）。

被排除：派 agent 抽取——BE 端零主機依賴是優點，但要新增一種 agent 指令型別，且依賴 agent 在線才能抽取。使用者上傳完卻因為 agent 離線而看不到內容，體驗不可接受。

✅ 版本鎖定 ＝ 鎖版 ＋ 提示

決策內容：任務綁定版本 uid（即現行行為），FR-059 D2 契約零變動、10 筆既有綁定零轉換。但要配一個提示徽章：「此基準已有新版 v3，目前使用 v1」加一鍵換版。

定案理由：純鎖版有合規漏洞——TWGCB 發了新版，排程任務會無聲地繼續掃舊版，使用者以為自己合規、實際上不是。在 GRC 系統裡這是正確性問題，不是 UX 瑕疵。換不換是使用者的決定，但必須讓他知情。拆表後「是不是現行版」就是主檔 current_version_id 的一次比對，menu API 順手帶回，成本極低。BE 側留在 FR-060；FE 的徽章與一鍵換版若範圍太肥可移到 FR-061（BE 先把資料備好）。

被排除：跟隨現行版——同一張任務前後兩次執行會跑出不同結果、稽核無法回溯、破壞 FR-059 已凍結的契約，還要轉換 10 筆既有資料。代價全付了，換來的性質卻更差。

D1 · 主從欄位歸屬

決策內容：

• 主檔 detection_profiles：name／description／分類三軸（標的類型／標的產品／基準體系）／scope／tenant_id／org_unit_id／detection_tool_id／is_active／current_version_id
• 從檔 detection_profile_versions：source_type／file_id／url／sha256／version／is_current／supports／extraction_status／控制項統計索引（總數／待判數）

定案理由：判準一句話——「換一版會不會變」。會變的進從檔，不會變的進主檔。supports（執行平台）放從檔，是因為它從該版的 inspec.yml 抽出來，不同版可能不同。detection_tool_id 放主檔，因為「這支基準給哪個工具用」是基準本身的屬性，行為與現行零變化。

被排除：分類放從檔——那等於每次上傳新版都要重填一次分類，且同一支基準的不同版可能分到不同類，篩選結果會前後矛盾。

D2 · 當前版指標：is_current 布林 ＋ partial unique index

決策內容：保留 FR-059 現行的 is_current 布林，配 UNIQUE (profile_id) WHERE is_current 的 partial unique index。current_version_id 仍可存在當作查詢便利欄（避免列表每次都 join 從檔篩 is_current），但唯一性的保證來源是 partial unique index，不是這個外鍵。

定案理由：資料庫直接擋住兩筆 current，demote_current 先降後插的順序是被索引強制的，不是靠開發者自律。

被排除：以 current_version_id 外鍵作為唯一性保證——這正是 oscal.frameworks 走過的路，而且官方已認錯並事實廢棄（2026-06-16 改用 main_version 純字串欄，外鍵降級為冗餘、列入待 DROP，見 docs/features/FR-038-2606-oscal-redesign/handoff/2026-06-16-framework-maintenance-fixes-record.md:60）。三個具體傷害：① 循環外鍵逼得 DDL 拆兩段、Python model 退化成 plain int 欄位；② 刪除流程被綁死，不能先刪版本只能靠 cascade；③ 資料庫保證不了「只有一個當前版」，而應用層從頭到尾沒實作過切換（add_version 完全不碰它）。

D3 · 從檔 RLS：冗餘欄位而非 EXISTS 子查詢

決策內容：從檔冗餘存 tenant_id／scope／org_unit_id，policy 與主檔逐字對稱（四段 × 兩表 = 八段）。

定案理由：

1. PostgreSQL 的 RLS 不沿外鍵繼承。 只掛主檔的話，SELECT * FROM 從檔 完全不受限制 → 租戶 A 能列出租戶 B 的全部 sha256／file_id／url。file_id 洩漏搭配 FR-058.7 取檔通道，就是一條實質的檔案越權路徑。
2. 從檔會被直接查——派工主幹道 _load_profile() 走的就是從檔的 get_by_uid，不是先查主檔再 join。
3. 本專案零 EXISTS 繼承前例——detection_executions、job_execution_detection_tools 等子表全部是冗餘欄位形狀，跟進既有形狀降低理解成本。

冗餘的代價：改主檔的 scope／tenant_id 時要同步更新從檔。但實務上這兩者建立後幾乎不變（fork 是建新列而非改欄位），代價很低；集中在 app service 層處理，不要散在各處。

被排除：EXISTS 子查詢繼承主檔判定——① 效能，每一列都要跑一次子查詢；② 子查詢本身還會再套一次主檔的 policy，形成 policy 套 policy，除錯時極難推理。

⚠️ 兩項實作陷阱：app_tenant_allowed_for_session(integer) 只接 integer，而 tenant_id 是 bigint → 必須寫 tenant_id::integer，四段 policy × 兩張表 = 共 8 處，漏任何一處都會在套 migration 當下硬失敗。另外本專案目前沒有任何「主從兩表都帶 RLS」的前例，FR-060 是首例，migration 內必須附上跨租戶讀取的驗證查詢。

D4 · uid 歸屬：從檔逐列沿用舊 uid，主檔另生新 uid

決策內容：舊表那 13 個 uid 逐列沿用給從檔；主檔另生新 uid。

定案理由：舊 uid 是凍結契約——job_execution_detection_tools.tool_params 的 4 筆 profile:<uid>、agent_tasks.params 的 6 筆 _profile 都指著它。從檔沿用等於這 10 筆既有引用零轉換、零風險；語意也對——派工綁的本來就是「某一版」不是「某支基準」。

被排除：主檔沿用舊 uid——那 10 筆引用全部要改寫（改 JSONB 內容），而且語意變成「派工綁基準」，與已拍板的「鎖版」相牴觸。

D5 · 分類三軸的定義與 enum 來源

決策內容：

enum 值來源定案：存 DB，由 root 維護（🔴 決策者 2026-08-03 推翻原「FE 寫死」建議）。

決策者原話：

D5 存 DB 不要寫死，這類最好都要可以維護。

定案理由：新增一個標的類型不該需要發版。原建議把八個類型視為「穩定的分類骨幹」，但這個前提在 D19 之後不成立——多工具擴充上線後，新格式帶進來的標的類型只會更頻繁（XCCDF 系的框架涵蓋面與 InSpec 系不同），每次都要發一版是不合理的維運模式。標的產品維持自由文字而非 enum，是因為產品名稱長尾極長（客戶自帶的 profile 可能是任何東西），硬做 enum 會逼使用者選「其他」，反而失去篩選價值。

被排除：FE 寫死常數——這是原討論稿的建議。排除理由是「要新增類型就得發版」，與 D19「擴充點一律是加資料、不動已上線的東西」的精神不一致：D19 才剛把工具與格式的擴充從「改表」降級成「加一列宣告」，分類 enum 卻要改常數再發版，兩者標準不一。 被排除：標的產品做成 enum——理由同上，長尾會讓 enum 失去篩選價值。

enum 存 DB 帶來的三個附帶需求（因本次改決策而新增）

原討論稿以「FE 寫死」為前提，故未涵蓋下列三項。改存 DB 後三項都是必做，不是可選：

前端三層 fallback 就是本案的多語方案

分類值改由 DB 供給 key 後，前端顯示邏輯直接照抄 DeviceManage.vue:36-57 的三層 fallback（那 28 行面對的是同一個問題：自由文字欄位要枚舉化、同時相容既有資料）：

1. i18n key 存在（用 te() 測試）→ 顯示翻譯
2. 否則顯示 DB 回傳的 key 本身
3. 再否則顯示原值；舊的自由文字用 unshift 保留在選項最前

這套 fallback 就是本案的多語機制，不需要另建任何東西——BE 只負責供給 key 與排序，翻譯是純前端的事。

⚠️ 這個做法的代價（要寫進 spec，不要讓未來的人以為是 bug）

root 在 DB 新增一個 enum key 之後，前端若還沒有對應的 i18n 條目，該值會以原始 key 顯示——畫面上會出現 network_device 而不是「網通設備」，要等前端補上翻譯並發版才會正常顯示。

這是可接受的優雅降級：不會壞、不會空白、不會報錯，篩選與分組功能全部照常運作，只是標籤不好看。但它必須寫進 spec，否則未來有人看到畫面上出現英數 slug 會當成 bug 去追。

換句話說，「新增分類值免發版」這件事只在功能層面成立；要讓新值顯示為中文，仍需一次前端發版。這個取捨是決策者裁示後的既定結果，記在此處供未來反悔時參考。

🔴 不要跟進 options.json

專案內另有一份 options.json 集中式 enum i18n 檔，但實查 grep "lang.options\." src/ 零命中——那份檔案是死的，沒有任何地方在用。看到它不要以為那是專案的 enum i18n 標準機制而跟進，正解是上面那套三層 fallback。

D6 · platform_hint 退役

決策內容：退役 platform_hint 欄位。拆表時不搬到新表，值隨舊表一起保留在 rename 後的 _deprecated 表裡。不要在新表建一個空的 platform_hint 欄位。

定案理由：它的功能被 D5 三軸完全覆蓋而且更精確——「這支基準是給什麼用的」由標的類型加標的產品表達，「它能在哪些平台跑」由 supports 自動抽取表達。而且實查 DEV 12 筆資料，值有兩種形態：空字串 '' 與大寫的 Windows，髒值已經存在。一個沒有約束、已經有髒值、語意含糊的自由文字欄位撐不起分類。保留在 _deprecated 表裡是為了觀察期內若發現有人在用還撈得回來。

被排除：保留並清洗——清洗 12 筆很容易，但清洗完它仍然與新三軸功能重疊，只是多一個要同步維護的欄位。 被排除：在新表建空欄位先佔位——那會變成第二個沒人維護的髒欄位。

D7 · 改名的語意：整鏈一起改，且不升版

決策內容：改名是主檔一列 UPDATE，所有版本天然共用同一個名稱；不升版。

定案理由：名稱是「這支基準叫什麼」，不是「這一版的內容」。若歷史版本保留舊名，列表上會出現兩個看起來不同的基準其實是同一支，比不改更混亂。這個行為是拆表的自然結果，不需要額外邏輯。

被排除：改名建新版——版號應該反映內容變更。改個錯字就升一版，會讓版號完全失去意義，也讓「有新版了」的提示變成噪音。

D8 · 新增編輯端點 PUT /detection-tool-profiles/<uid>

決策內容：承 D7，既然改名／改描述／改分類都不升版，就需要一個純粹的「編輯基本資料」端點。新增 PUT /detection-tool-profiles/<uid>，消費那顆已 seed 但至今沒人用的 detection-profile.update capability（FR-059 spec §12 坑 2 稱它為「預留孤兒」）。

權限規則：租戶只能編自己的（scope = TENANT 且 tenant_id 相符）；公版（scope = SYSTEM）只有 root 能編。此判定走 common/authz/ 的資源域守門（app service 層），不要另立 helper。

定案理由：現況完全沒有「編輯基本資料」的入口——名稱只能在 fork／copy 時順便改，等於「改名要先複製一份」，這正是需求 ② 的直接來源。附帶效益：那顆 capability 從孤兒變成有實際消費者，權限矩陣不再有一列是死的。

被排除：沿用建立端點做 upsert——建立與編輯的權限判準不同（建立看 scope 能不能選、編輯看資源歸屬），混在一起會讓授權判定難以推理。

D9 · fork／copy_to_tool 的版本複製語意

決策內容：只複製當前版，成為新基準的 v1（與現行為一致）；控制項一併複製（不重新抽取），extraction_status 一併設為 succeeded。fork 與 copy_to_tool 抽成共用的 _clone_profile()，差異收斂成三個參數（scope／tenant_id／tool_id）。

定案理由：fork 的意圖是「我要以這份為起點做我自己的」，歷史版本對新的那支沒有意義（那是原基準的演進史，不是新基準的），且複製全部版本會讓儲存量與 file_id 引用倍增。控制項內容完全相同，重抽要再等 28～117 秒沒有意義。

被排除：複製全部版本鏈——儲存量與引用倍增，換來的是對新基準無意義的歷史。 被排除：fork 後重新抽取控制項——內容完全相同，白等一輪抽取。

D10 · 抽取非同步化與 extraction_status 落點

決策內容：extraction_status 四態 pending／running／succeeded／failed，放從檔；再配一個 extraction_error 文字欄存失敗訊息。前端在列表與版本子表顯示狀態徽章，pending／running 時輪詢（建議 5 秒一次）。

定案理由：實測 708 條的 profile 抽取要 117 秒，遠超任何 HTTP 逾時，非同步是必然不是選項。狀態放從檔，是因為抽取是對某一版做的，不是對整支基準。

被排除：extraction_status 放主檔——主檔若只有一個狀態欄，上傳 v3 失敗會讓 v1、v2 的狀態一起被覆蓋成 failed，但那兩版的控制項其實好好的。 被排除：走 WebSocket 推播——為一個低頻操作接推播不划算，且專案的 SocketIO 走另一個 port。

D11 · 抽取失敗的判定條件

決策內容：exit != 0 或 controls == []，兩者任一都算失敗。

定案理由：實測第七種錯誤形狀——.rb 控制項檔有 Ruby 語法錯誤時，cinc-auditor json 會 exit 0、stderr 全空、輸出合法 JSON、但 controls 是空陣列，整個檔案的控制項（包含語法正常的那些）全部被靜默丟棄。若只看 exit code，使用者會拿到一支「抽取成功但零控制項」的基準，他會以為是這份基準本來就沒東西，而不是解析壞了。靜默的錯誤比明顯的錯誤更貴。

誤判風險評估：理論上存在「合法但零控制項」的 profile（純 wrapper profile 只有 depends 沒有自己的控制項），但那種 profile 在本系統的使用情境下也是無效的（掃了什麼都不會驗）。把它判成失敗是正確的，錯誤訊息寫「未解析到任何控制項，請確認 profile 內容」即可。

被排除：只看 exit code——會讓第七種錯誤形狀變成無人察覺的資料缺漏。

D12 · 控制項的存儲形式：一條一列拆表

決策內容：控制項一條一列存入 detection_profile_controls，欄位以「跨格式共通的最小集合」為正規欄，格式專屬的中繼資料整包進 attributes jsonb（見 D19），丟掉 code、丟掉與 descriptions.default 重複的 desc。

完整欄位：

🔴 欄位命名不可用 InSpec 專有名詞（D19 定調）：嚴重度欄位不叫 impact——那是 InSpec 的 0.0–1.0 浮點語意，XCCDF 用五級列舉，其他工具各有各的。改成 severity_raw（原樣存來源值，文字）＋ severity_norm（跨工具可比的統一級距）。is_pending 保留欄位名，但判準寫在各格式的 extractor 裡（InSpec 是 impact == 0.0，XCCDF 另有 role=unchecked），不是寫死在表結構的假設裡。

定案理由（決定性）：FR-061 的豁免要能綁單一控制項——那需要控制項是一列可被外鍵參照的資料，不是 jsonb 陣列裡的一個元素。這是不可逆的架構決定，現在做對成本很低，之後改要動 FR-061 已寫好的東西。其他理由：搜尋／篩選／分頁走 SQL 而非 Python；「人工待判 199 條」這種統計是一句 COUNT(*) WHERE is_pending；未來要跨 profile 找「哪些基準有驗這條」也有路。

attributes 整包存 jsonb 的實測理由：tag key 集合隨 profile 變動——TWGCB-01-014 的 twgcb_id／role／category／gpo_path／gcb_value／check_type 各 234/234、status 199/234；TWGCB-01-011 則多出一個 service_display_name（368/708）。客戶自帶的外來 profile 更不可能有 TWGCB 那套 key，schema 本來就不可寫死成固定欄位。

期望值兩條路都拿得到（tags.gcb_value 與 descriptions.gcb_value，本 profile 兩者一致），以 tags 為主、descriptions 為 fallback。

丟 code 的代價：使用者看不到「這條實際怎麼檢查」的 Ruby 原始碼。可接受——目標受眾是合規負責人不是 InSpec 開發者，47.8% 的體積換一個幾乎沒人看的欄位不划算；若日後有需求，從 source_ref 可以定位到檔案，不是完全無路。

被排除：整支 profile 的控制項存成一個大 jsonb——豁免無法以外鍵綁單條控制項，FR-061 直接卡死；搜尋、篩選、統計全部退回 Python 端處理。

⚠️ 兩個容易混淆的欄位：source_location.ref 是執行當下的絕對路徑（含臨時目錄名），落庫前要剝掉前綴只留 controls/xxx.rb，否則存進去的是無意義且會洩漏內部路徑的字串；頂層 sha256 是 CINC 自算的 profile 內容雜湊，與 detection_tool_profiles.sha256（壓縮檔原始 bytes 的雜湊，FR-039 對帳的信任根）不是同一個值，切勿混用。

D13 · menu API 保持扁平，由 FE 自己 groupBy

決策內容：BE 的 menu API 維持扁平陣列 [{value, name, target_type, target_product, benchmark_family, ...}]，分組由 FE 自己做。

定案理由：① 相容性——JobExecutionDrawer.vue:279-282 的 for (const m of items) 若拿到巢狀會靜默失效（不 throw、不進 catch），任務抽屜的參數顯示直接退回裸的 profile:<uuid>，使用者看到一串 UUID；② 彈性——FE 想改用哪一軸分組（依標的類型或依基準體系）不必動 BE；③ 符合 CLAUDE.md 的 Menu pattern（回傳 List[MenuDto] 不包 PageDataDto）。

PrimeVue 3.53 的分組能力已實查確認：Dropdown 支援 optionGroupLabel／optionGroupChildren（Dropdown.d.ts:289,293；Dropdown.vue:285-293,881-891），且 editable 與分組可以並存（editable 只切換輸入框呈現、visibleOptions 的計算完全不看 editable、isValidOption 已排除 group 分隔項）——這對本案關鍵，FR-059 P6 定案「select_or_text 手填能力保留」，分組不能犧牲手填。群組標頭天然不可點選；filter 與分組的協同路徑現成（Dropdown.vue:910-920）；專案內已有實例 RoundApAuthoringView.vue:779。

被排除：BE 回傳巢狀——省了 FE 十幾行 groupBy，換來一個靜默失效的相容性風險，不划算。

必配的 fallback 修補（不論選哪個形狀都要做）：DetectionConfigField.vue:82-92 有一段 opts.some(o => o.value === current)，用來判斷「目前選中的值是否還在選項裡」，不在就補一個「已不可用」的 fallback 項。選項改成巢狀後這個比對必然全部 miss（它比對到的是 group 物件不是 leaf 選項）→ 每一個已選值都會多長一個「已不可用」項。不會報錯、不會進 catch，只會讓每張已設定的任務都顯示成「這個 profile 已不可用」。對策：比對前先攤平選項樹；fallback 項本身也要包成一個群組，否則會混在群組之間造成渲染錯亂。

D14 · 列表語意：主列表一列 ＝ 一支基準

決策內容：主列表一列代表一支基準（主檔），預設只顯示 is_active 的；版本歷史走展開列（expander，pattern 抄 SheetPreviewControls.vue），並另有獨立分頁 API 供版本多的情況。原有的「顯示已停用與舊版」開關拆成兩個：主列表上是「顯示已停用基準」（主檔 is_active = false），版本子表上是「顯示歷史版本」（從檔 is_current = false；子表本來就該全顯，這個開關可能根本不需要）。

定案理由：拆表後「已停用的基準」與「非當前版」是兩個獨立概念，混在一個開關裡語意分裂。

被排除：一列一版本（維持現行形狀）——那等於沒拆表，改名、分類、篩選全部回到原點。

FE 實作素材：DetectionProfileManageView.vue 共 1,239 行，其中約 600–700 行要重構，建議趁機拆檔（主表格／版本子表／各 Dialog 各自獨立元件），否則會膨脹到 2,000 行以上。控制項清單（234～708 條）以 client-side DataTable ＋ :paginator 25 筆／頁即可（PrimeVue 只渲染當前頁）；搜尋複製 DetectionProfileManageView.vue:506-513 的 IconField（已含 300ms debounce）。不建議 server-side lazy loading——控制項是某一版的靜態內容，載一次快取住比每次翻頁多打 N 次 API 快得多；VirtualScroller 專案內零使用，除非實測超過 1MB 或 2 秒，否則不要為這個功能開一個新 pattern。分類枚舉化直接照抄 DeviceManage.vue:36-57 的三層 fallback（i18n key 存在用 te() 測 → DB 回傳的 key → 原值，舊的自由文字用 unshift 保留在最前）；⚠️ 不要跟進 options.json，實查 grep "lang.options\." src/ 零命中，那份檔案是死的。

D15 · is_active 只放主檔，從檔第一期不設停用欄

決策內容：is_active 只放主檔（＝停用整支基準），從檔不另設停用欄。

定案理由：現況 13 筆裡沒有任何「想停用某一版但保留其他版」的需求證據（唯一的停用列 id 33 是整支不要了）。加一個 boolean 欄很便宜，但憑空設計一套「版本級停用」的語意（停用當前版後哪一版變 current？）很貴。先不做，等出現實際需求再加。

id 33 的搬遷處理：它會變成「一支 is_active = false 的主檔，底下有一個版本，但 current_version_id 是 NULL」——這是合法狀態，UI 要能顯示（不要因為 current 是 NULL 就渲染爆掉），migration 的驗證查詢也要預期 current_version_id IS NOT NULL 只有 12 筆而非 13。

未來若要加：從檔加 is_deprecated（而非 is_active，避免與主檔同名混淆），且要定義「棄用當前版時 current 怎麼移轉」。

被排除：第一期就做版本級停用——沒有需求證據，且語意設計成本遠高於欄位成本。

D16 · 舊表 rename 保留，觀察期後另開 migration 才 DROP

決策內容：本案的 migration 只做 ALTER TABLE ... RENAME TO detection_tool_profiles_deprecated_20260803，不 DROP。DROP 另開一支 migration，於觀察期（建議一個 release 週期）後執行。

定案理由：專案慣例——「重構搬遷」與「刪舊表」是兩支獨立的 migration，中間隔一段觀察期。前例：2026-06-03-log-tables-partitioning.sql:66、2026-05-19-ssp-system-implementation-restructure.sql:255-280（附反向 ROLLBACK 註解）、2026-05-24-ssp-oscal-alignment-drop-old.sql（獨立成一支才真正 DROP）。

⚠️ rename 不會自動改索引名稱 → 新表的索引一律用新前綴（idx_dp_*／idx_dpv_*／idx_dpc_*），避免與舊表殘留的索引名撞名導致 migration 中途失敗。DROP 前比照 CLAUDE.md「DROP 退役表前安全四查」，實際 grep 確認沒有任何 live-wired 的 code 還在引用，不要假設。

被排除：本案直接 DROP 舊表——一旦搬遷有誤，資料無法回頭；且違反專案慣例。

D17 · 既有 13 筆的分類補登：有把握的才填，其餘留 NULL

決策內容：migration 內做部分補登——名稱裡含 twgcb-01-* 明確是作業系統、twgcb-02-003-google-chrome 明確是瀏覽器，這類從名稱可高信心推導的直接填；推不出來的留 NULL，由使用者在管理頁補。下拉分組時「未分類」放最後（分類明確是常態、未分類是待補的例外），列表篩選要有「未分類」選項讓使用者找得到待補的。

定案理由：13 筆裡有 10 筆是我們自己 seed 的 TWGCB 公版，我們比使用者更清楚它們是什麼。

被排除：全部留 NULL 等人工補——把已知資訊丟掉，等於讓使用者做我們已經知道答案的工。 被排除：全部靠猜測規則自動填——猜錯比留白更糟（使用者會信任錯誤的分類去篩選，篩掉他該看的東西）。寧可空著也不要猜。

D18 · 補做 root 建公版的 UI，讓兩個懸空 i18n key 活起來

決策內容：補做 root 建立公版的 UI，消費 FR-059 預留但未使用的 field_scope／hint_scope_system 兩個 i18n key（現況 createDialog.scope 恆為 TENANT，root 沒有辦法從 UI 建公版，只能靠 migration seed）。scope 欄位對非 root 隱藏或唯讀。

定案理由：本案要開放編輯基本資料（D8），編輯 Dialog 與新增 Dialog 是同一組欄位；既然都要重構那 600–700 行，順手補上成本極低。而且公版只能靠 migration 建本身就是 FR-059 未收乾淨的尾巴——每加一支公版又要寫一支 migration，正是 FR-059 立案時要消滅的維運模式。

被排除：標記刪除這兩個 key——那等於承認「公版只能靠 migration 建」是最終狀態，與 FR-059 的立案動機相牴觸。

若實作時發現範圍太肥：至少要在 FR-060 的 spec 明寫「公版建立目前仍走 migration」，不要讓這兩個 key 繼續懸空無人知曉。

D19 · 多工具擴充邊界（決策者當場定調，非「照建議」）

決策者原話（2026-08-03）：

要預留擴充方式，以目前有的工具為主，未來如果又有多工具有需要設定檔的，也要可以擴充，不能像這次一樣又大幅度更新，上線後很危險。

問題背景：工具維度本來就在——detection_tool_id 是建表就有的 not-null 欄位，唯一索引三欄含它，列表頁已有工具篩選、建立時必選工具、「複製到另一工具」整個功能繞著它轉。但目前只有 InSpec 系真的入庫：

掛在 openscap 底下那 1 筆是 id 33，即「使用者選錯工具後停用重建」的殘留，是誤操作痕跡不是 OpenSCAP 真的在用庫。

🔴 若照原提案直接刻 InSpec 語意，第二個工具進來就要改已上線的表。 原 D12 提案的欄位（impact 浮點／tags／descriptions／is_pending 由 impact==0.0 推導）是 InSpec 專有語意。XCCDF 的對應概念完全不同：severity 是五級列舉不是浮點、沒有「人工待判」概念（另有 role=unchecked）、中繼資料是 ident（CCE／CCI）／fixtext／rationale。第二個工具入庫時只剩兩條路：加一個 severity 欄，或把五級硬塞進浮點——兩條都是上線後改表，正是決策者指的「大幅度更新、上線後很危險」。

定案：三層擴充結構，擴充點一律是「加資料／加實作類別」，不是「加欄位／改欄位語意」

① 工具端宣告能力——沿用既有慣例，不發明新機制。 專案已有這個 pattern（detection_tool_param_schemas 的 options_source: profile_library 就是「這個工具的設定檔走庫」的宣告）。把宣告補完整：加 profile_format（inspec／xccdf／…）＋ supports_extraction（能不能抽內容）。新工具入庫 ＝ 加一列宣告，不動任何表。

② 抽取器走註冊表——依 profile_format 取對應 extractor。 管線不寫成「呼叫 cinc-auditor」，寫成「依格式取 extractor」。新格式 ＝ 新增一個 extractor 類別 ＋ 註冊一行，不動管線骨架、不動既有工具路徑。附帶效益：BE 裝 CINC 這項主機依賴只綁 inspec 格式，不會變成全平台前提。

③ controls 表存正規化語意 ＋ 原始中繼資料分離。 正規欄只收所有格式一定都有的最小集合（control_id／title／description／severity_raw／severity_norm／is_pending／source_ref）；格式差異全進 attributes jsonb；extraction_format 標記來源格式讓讀取端知道該期待什麼；origin（extracted ｜ custom）與它正交，供 FR-061 自訂項使用。

代價要講清楚：現在只有 InSpec 一種真實格式，正規化是「照一個實例抽象」，有抽錯風險。降低風險的做法是正規欄只做最小集合——不要為了預想中的 XCCDF 去猜欄位。寧可多留在 attributes 裡，日後有第二個實例驗證後再提升為正規欄（那是加欄位，不是改語意，成本可接受）。

被排除：明寫「profile 庫只服務 InSpec 系」——太樂觀。決策者已明確表示未來其他工具的設定檔也會在這裡維護，把邊界劃死等於把問題推給下一次改表。 被排除：現在就完整抽象化（正規欄涵蓋預想中的 XCCDF 欄位）——只有一種真實格式時抽象化容易抽錯，沒有第二個實例可以驗證抽象是否正確。抽錯的抽象比沒有抽象更貴，因為它會誤導後續實作照錯的形狀寫。

對其他決策項的影響：D12 欄位定義已依此改寫（不用 impact 當欄位名）；.1 建表採上述形狀；.3 抽取管線改註冊表骨架（工作量差異不大，都是新寫）；D5 的「基準體系」軸不受影響——CIS／STIG 本來就是跨格式的體系名。

D20 · url 型基準的抽取：BE 代為下載，但只在記憶體、掃描路徑一行不改

背景：.3 抽取管線（CM-1065）上線後，url 型基準（DEV 有兩支 dev-sec 公版）一律落 failed，訊息是「平台不代為下載」。使用者在下拉裡選得到它們，卻完全看不到內容——這正是本案 §1 原始需求要解的同一件事（「使用者完全不知道這個東西會驗證什麼」）。

推翻原假設的實測：協調者 2026-08-03 本機實測 cinc-auditor json <dev-sec tarball 網址> → exit=0、59 條控制項、profile name linux-baseline。CINC 原生就吃 URL。原本那道限制不是技術限制，是決策範圍問題。

P5 的原始範圍：FR-059 design P5「平台完全不經手檔案」的理由是 CM-992 限制②——「params.profile 是 secret:false 純文字，token 塞進 URL 會洩漏到 FE 執行紀錄與稽核 log」。那講的是掃描路徑代管私有 repo 憑證。而抽取是 FR-060 才有的另一個面向，且 dev-sec 兩支是完全公開、不需任何憑證的 GitHub URL。本決策不推翻 P5：URL 憑證／認證代管仍然不做。

選了「BE 代下載」而非「直接把 URL 餵 CINC」：後者看似更省事（少一段程式），但等於把出網整包交給 CINC——我們管不到逾時、大小上限、目標 IP，連它會不會跟隨重導向都不知道。走自家 httpx 才有地方掛防護。

SSRF 防護五道（決策者裁示不做網域白名單，新增來源要改設定的維護成本大於收益）：scheme 限 https／解析後每一顆 IP 都不得落私有保留段／IP pinning／50MB 邊讀邊斷／重導向 ≤3 跳且每跳重驗。實作在 common/util/safe_http_fetch.py。

🔴 IP pinning 是這裡最容易漏的一道：「解析 → 檢查 IP → 交給 httpx 連 hostname」的寫法，httpx 會自己再解析一次 DNS，攻擊者讓兩次解析回不同結果（DNS rebinding）即可完全繞過檢查。故改為用檢查過的那顆 IP 連線，Host header 與 TLS SNI 帶原 hostname，憑證驗證仍對原 hostname 生效（已實測：SNI 給錯會 CERTIFICATE_VERIFY_FAILED，安全性不是靠關掉驗證換來的）。同理「重導向每一跳都要重跑全部檢查」——突變測試證實只驗第一跳的話，302 到 127.0.0.1／//192.168.x.x／降級 http:// 三種繞過全部通過。

三條不變式（做錯任一條都會製造更難查的問題）：

1. 掃描路徑完全不動——agent 仍原樣把 URL 交給 cinc-auditor exec；_load_profile()／build_payload() 零異動（已逐欄比對 git HEAD 證明 payload 相同）
2. 下載只在記憶體——不寫 upload_files、source_type 維持 url、file_id／sha256 維持 NULL
3. 下載在 session_scope() 之外——_prepare() 對 url 型只回「待下載的網址」，實際下載由 worker 在兩段 session 之間做，維持既有三段式

被排除：把下載內容存進 upload_files 變成 file 型快照——那會讓 url 型悄悄變成 file 型，破壞 P5 的雙軌語意；更糟的是掃描（agent 自己拉 URL）與抽取（平台存的快照）從此可能是不同的內容，對不上時沒人知道該信哪個。 被排除：網域白名單——決策者裁示不做（新增來源就要改設定），改以上述五道防護收斂風險。

FE 對應：url 型指向的是 master branch tarball，內容會漂，且沒有 sha256 當信任根。所以 url 型的控制項清單不可以跟 file 型長得一模一樣（否則使用者會拿它當稽核依據），成功態加一條「內容取自外部網址的當下快照，實際掃描時以檢測代理取得的版本為準」＋顯示解析時間；file 型不顯示。

未來反悔條件：若出現私有 repo（需要憑證）的需求 → 回到 P5 的憑證代管議題，另案討論，不在本決策範圍內延伸。

3.20 四項不可逆決策

以下四項一旦上線就改不了（或改的成本高到不會有人願意付），是本案最需要現在想對的地方：

拆表不只是 DDL，會牽動既有的 repository、service 與派工鏈。以下是實際 grep 過程式碼後的盤點，不是推估。

4.1 同構前例：oscal.frameworks / oscal.framework_versions

這兩張表在 DEV 不存在，屬 jedi-oscal-v2 套件的表——只能參考程式碼模式，RLS 部分無實例可抄。

該抄的模式：ON DELETE CASCADE 掛從檔的 profile_id；不用 SQLAlchemy relationship()、純外鍵 int 欄（DDD 不在 infra 層 JOIN）；Query Entity 帶關聯欄位；對外只露 uid 不露 id；主檔列表內嵌 versions 之外，版本另有獨立分頁 API；serializer 自參照樹用 lambda: ＋ exclude 防遞迴。

該避的坑：

• 不要寫成 N+1 的 _enrich（每列主檔各打一次 list_versions）
• 不要在 Python 端過濾／排序／分頁
• 🔴 不要新增與既有 marshmallow schema 撞名的 class——已有 500 事故前例（兩個 module 出現同名 schema 造成 RegistryError）。本案要新增的 schema 數量不少（主檔／從檔／控制項／分類值各一組），命名前先 grep 確認

main_version_id 外鍵的失敗史已寫在 D2，不重複。

4.2 拆表的三個實質收益

4.3 🔴 派工鏈兩處破口（本章最重要的一節）

原本以為拆表只影響管理面。實際 grep app/detection_tools/service/detection_orchestration_service.py 後發現兩處會壞，其中一處是無聲的授權漏洞。

🔴 破口 ① — _load_profile() 檢查 profile.is_active

is_active 拆表後在主檔。若 _load_profile() 拿到的是從檔 entity，有兩種壞法：

從檔 entity 的狀態	後果	嚴重度
沒有 is_active 屬性	AttributeError → 500	高，但會被發現
**有但預設 None	None is False 為假 → 守門靜默失效，已停用的 profile 照樣派得出去**	更高——不會有人發現

後者是無聲的授權漏洞，比 500 更糟：使用者以為某支基準已經停用不再被掃描，實際上排程照跑。在 GRC 系統裡這是正確性問題。

🔴 破口 ② — _humanize_profile_param() 用 getattr(profile, "name", None)

name 拆表後也在主檔。這裡因為 getattr 帶 default 值所以不會報錯，只會讓通知信裡的「掃描設定」欄位靜默退化成 profile:<uuid>——使用者收到一封通知信，看到的是一串 UUID 而不是基準名稱。

而且目前沒有任何測試會抓到這個退化。 .1 收尾時要補一支測試斷言通知信的參數顯示不是 profile: 開頭的裸字串。

兩處共同的解法：domain service 新增 get_version_with_profile(uid)，回傳主檔＋從檔合成的 entity（從檔全欄位 ＋ 主檔的 name / is_active / detection_tool_id / 分類三軸），orchestration 的三處呼叫點改指它。

這個解法有兩個好處：對外行為零變化（agent 拿到的 payload 形狀與今天一模一樣）；把「派工需要哪些欄位」這件事收斂到一個方法裡——未來再有欄位搬家，只有這一個方法要改，不必再 grep 一輪 orchestration。

4.4 確認零影響的兩處

這兩處已實際確認拆表後原樣可用，實作時不要順手改：

4.5 兩條凍結契約的引用不動

依 D4「uid 由從檔逐列沿用」，下列 10 筆既有引用零轉換、零風險：

⚠️ 再次提醒 _profile.uid 的語意依 source_type 而異：url 型是 profile 列的 uid、file 型是 upload_files 的 uid。搬遷驗證查詢比對 uid 時必須分開對待，不要把兩者混在同一個 NOT EXISTS 裡比。

5.1 三張表的欄位定義

欄位歸屬照 D1（判準：「換一版會不會變」）。以下為邏輯欄位清單，實際 DDL 於 .1 的 migration 撰寫時定稿。

主檔 config.detection_profiles

唯一索引：(detection_tool_id, tenant_id, name) 仍然保留——同一租戶同一工具下不該有兩支同名基準。但它現在約束的是「基準」而不是「某一版」，改名不再撞版本鏈。

⚠️ id 33 搬遷後會產生 current_version_id IS NULL 的主檔，這是合法狀態（D15），UI 與 serializer 都要能處理。

版本從檔 config.detection_profile_versions

控制項 config.detection_profile_controls

欄位形狀照 D12 ＋ D19：正規欄只收跨格式共通的最小集合，格式差異全進 jsonb。

attributes 整包存 jsonb 的實測依據：tag key 集合隨 profile 變動——TWGCB-01-014 的 twgcb_id／role／category／gpo_path／gcb_value／check_type 各 234/234、status 199/234；TWGCB-01-011 多出一個 service_display_name（368/708）。客戶自帶的外來 profile 更不可能有 TWGCB 那套 key，schema 本來就不可寫死成固定欄位。

期望值兩條路都拿得到（tags.gcb_value 與 descriptions.gcb_value，本 profile 兩者一致），以 tags 為主、descriptions 為 fallback。

5.2 分類 enum 表（因 D5 改存 DB 而新增）

決策者裁示「DB 只存 key、由前端翻譯」，因此這張表要盡可能薄——不存顯示名稱、不開翻譯表。

表名建議 config.detection_profile_taxonomies（一張表容納兩個受控軸，用 axis 欄位區分，避免為兩個軸各開一張幾乎相同的表）。

唯一索引 (axis, key)。這張表是全域的（不分租戶）——分類骨幹由 root 統一維護，租戶不得增刪，否則篩選語意會漂移。因此不掛 RLS，比照專案內其他全域字典表的做法。

刪除保護（必做）

已被 profile 引用的分類值不可刪。刪掉之後既有 profile 的 target_type 會指向一個不存在的 key，列表篩選與下拉分組都會出現無法解釋的空白，且前端 fallback 只能顯示原始 key。

實作上兩層：

1. 應用層：刪除前 COUNT(*) 查引用數，非 0 直接擋下並回明確錯誤（引用數要一起回給前端，讓 root 知道擋在哪）
2. 偏好做法：根本不提供刪除，只提供停用（is_active = false）——停用不影響既有引用的解析，語意也更誠實：分類骨幹是歷史紀錄的一部分，本來就不該被抹掉

不要用 FK 約束來做這件事——分類值是 soft-ref（profile 存的是 key 字串不是 id），改成 FK 會牽動搬遷 SQL 與 D17 的部分補登（留 NULL 的那些）。應用層擋下即可。

維護介面的落點與但書

需要一個 enum 值 CRUD 的落點（列表／新增／改 key 排序／停用），權限限 root，走 common/authz/ 的主體域守門（platform-admin 軸，允許 route 層 decorator 形式）。

若 .2 的範圍評估後太肥，可先只做「讀 DB ＋ 靠 migration seed 維護」——但必須在 FR-060 的 spec 明寫「分類值目前仍靠 migration 維護，尚未有管理 UI」。D18 已有前例教訓：FR-059 預留了 field_scope／hint_scope_system 兩個 i18n key 卻沒做 UI，後來沒人知道那兩個 key 為什麼在那裡。不要製造第二個懸空孤兒。

5.3 RLS：兩表八段

現行 config.detection_tool_profiles 的四段 policy 結構，是本案要複製到兩張表上的樣板：

主檔與從檔各掛一套，共八段，policy 內容逐字對稱。控制項表不掛。

為什麼是兩表而不是三表：判準是「會不會被當作獨立查詢入口」

專案既有慣例佐證（實查 DEV 全庫）：本專案 RLS 一律掛在有租戶身分的主體表那一層，純附屬明細表不掛，且明細表通常連 tenant_id 欄位都沒有。實例：oscal.catalog_controls、oscal.poam_items、oscal.assessment_findings、oscal.ar_results、oscal.ssp_inventory_items、survey.task_survey_ref_items、survey.question_answer_history_details——九張明細表，零張掛 RLS。

其中 oscal.catalog_controls 與本案的控制項表是同一種東西（控制項明細），它就是不掛。本案跟進既有形狀，不開新做法。

判準寫成規則（未來新增子表時據以判斷）：

本專案 RLS 掛在「有租戶身分、且可能被直接查詢」的主體表；純附屬明細（必須經主體帶出）不掛，也不加冗餘 tenant_id。

🔴 從檔一定要自己掛 RLS

PostgreSQL 的 RLS 不沿外鍵繼承。 只掛主檔的話，SELECT * FROM 從檔 完全不受限制 → 租戶 A 能列出租戶 B 的全部 sha256／file_id／url。

file_id 洩漏搭配 FR-058.7 取檔通道，就是一條實質的檔案越權路徑。

而且從檔會被直接查——派工主幹道 _load_profile() 走的就是從檔的 get_by_uid，不是先查主檔再 join。

⚠️ helper 型別 cast 陷阱：八處漏一處就硬失敗

app_tenant_allowed_for_session(integer) 只接 integer，而 tenant_id 是 bigint → policy 內必須寫 tenant_id::integer。

四段 policy × 兩張表 = 共 8 處，漏任何一處都會在套 migration 當下硬失敗。這個失敗是明顯的（不是靜默），但會讓整支 migration 回滾重來，撰寫時逐處對過。

⚠️ 本專案首例：主從兩表都帶 RLS

目前沒有任何「主從兩表都帶 RLS」的前例，FR-060 是首例，沒有既有實作可抄。因此 migration 內必須附上跨租戶讀取的驗證查詢——以 cm_app 身分（受 RLS）分別模擬租戶 A 與租戶 B，確認：

1. 租戶 A 讀不到租戶 B 的從檔列（這是最關鍵的一條，主檔擋得住不代表從檔擋得住）
2. 兩者都讀得到 scope = 'SYSTEM' 的公版
3. 租戶 A 無法 INSERT／UPDATE 出 scope = 'SYSTEM' 的列

冗餘欄位的代價（D3 已述）：改主檔的 scope／tenant_id 時要同步更新從檔。實務上這兩者建立後幾乎不變（fork 是建新列而非改欄位），代價很低；集中在 app service 層處理，不要散在各處。

5.4 三段式遷移路徑

全程在 psql --single-transaction -v ON_ERROR_STOP=1 內原子完成。十個步驟：

⑩ 的驗證查詢（缺一不可）：

• 主檔 = 13 筆
• 從檔 = 13 筆
• current_version_id IS NOT NULL = 12 筆（不是 13——id 33 那條是合法的 NULL，D15）
• 🔴 uid 零遺失：以 NOT EXISTS 比對舊表全部 uid，結果必須是 0
• 跨租戶讀取驗證（§5.3 的三條）
• 收尾 INSERT public.schema_migrations

🔴 搬遷 JOIN 條件必須是 (tool_id, tenant_id, name) 三欄

DEV 的 id 32 與 33 同 tenant、同 name（twgcb-02-003-google-chrome）、同 file_id，但屬於不同工具（tool 8 vs tool 4）——是使用者選錯工具後停用重建留下的痕跡。

少一欄，32 與 33 會 cross join，搬出錯誤的主從關係。 而 STG 測不到這個陷阱（全 SYSTEM、無此形態資料），這條只有在 DEV 才驗得出來。

為什麼不用 DEFERRABLE：INITIALLY DEFERRED 會讓應用層每一次寫入都延到 commit 才檢查外鍵，錯誤發生點離現場很遠、極難除錯。而應用層「先 INSERT 從檔 → 再 UPDATE 主檔指標」的順序本來就自然，不需要 defer。遷移期間的循環相依用「先不加 FK、最後 ALTER 補上」解決即可。

⚠️ 索引命名一律用新前綴

RENAME TABLE 不會自動改索引名稱——舊表的索引名會原封不動留在 _deprecated 表上。新表的索引一律用新前綴 idx_dp_*／idx_dpv_*／idx_dpc_*，避免與舊表殘留的索引名撞名導致 migration 中途失敗。

舊表 DROP 另開一支 migration，觀察期（建議一個 release 週期）後執行，且比照 CLAUDE.md「DROP 退役表前安全四查」實際 grep 確認沒有 live-wired 的 code 還在引用（D16）。

5.5 抽取器註冊表（D19 的擴充骨架）

管線不寫成「呼叫 cinc-auditor」，寫成「依格式取 extractor」。三層結構：

① 工具端宣告能力 — 沿用既有慣例，不發明新機制。detection_tool_param_schemas 已有 options_source: profile_library 這個「這個工具的設定檔走庫」的宣告，把它補完整：

新工具入庫 ＝ 加一列宣告，不動任何表。

② 抽取器註冊表 — 依 profile_format 取對應 extractor 類別。新格式 ＝ 新增一個 extractor 類別 ＋ 註冊一行，不動管線骨架、不動既有工具路徑。

介面最小集合：吃「壓縮檔臨時路徑」，吐「控制項列表 ＋ profile 層中繼資料（supports 等）」，以及三種結果分支之一。本期只實作 InSpec 一種。

附帶效益：BE 裝 CINC 這項主機依賴只綁 inspec 格式，不會變成全平台前提——未來 XCCDF extractor 進來時，沒裝 CINC 的環境仍可處理 XCCDF profile。

③ controls 表存正規化語意 ＋ 原始中繼資料分離 — 已在 §5.1 定義。

代價要講清楚：現在只有 InSpec 一種真實格式，正規化是「照一個實例抽象」，有抽錯風險。降低風險的做法是正規欄只做最小集合——不要為了預想中的 XCCDF 去猜欄位。寧可多留在 attributes 裡，日後有第二個實例驗證後再提升為正規欄（那是加欄位，不是改語意，成本可接受）。

CINC 路徑解析

比照 LibreOffice 慣例（docs/claude/host-dependencies.md:85-89）三層解析：

1. 環境變數 CINC_AUDITOR_CMD
2. PATH
3. 絕對路徑 fallback

🔴 不要硬編 /usr/bin/cinc-auditor——macOS 開發機路徑不同。

⚖️ 授權紅線

必須是 CINC Auditor（Apache 2.0）。絕不可換成官方 InSpec 6+ 商業 binary（需接受 Chef EULA 並取得 license key）；inspec-core gem 由 Chef 官方發布、同樣受 EULA 影響，也不可用。

安裝：curl -fsSL https://omnitruck.cinc.sh/install.sh | bash -s -- -P cinc-auditor -v 7

成本：體積 275MB（其中約 200MB 是本案用不到的 AWS／Azure／GCP SDK 與遠端 transport），三台部署機加每台開發機都要裝，收尾要在 docs/claude/host-dependencies.md 新增第三項（現有兩項是中文字型與 LibreOffice）。

5.6 抽取管線的三種結果分支

壓縮檔 bytes 落成臨時檔（tempfile.NamedTemporaryFile(suffix=info.ext)，副檔名必須正確，CINC 靠副檔名判斷格式）後交給 extractor。全程零 extract() 呼叫——不解壓成目錄樹，與 FR-059 T-1.3「不落地解壓」驗收條件不衝突（該條件禁止的是解壓成目錄，那是 zip-slip 可能寫出惡意路徑的時刻）。

🔴 第三種分支：只看 exit code 會漏

.rb 控制項檔有 Ruby 語法錯誤時，cinc-auditor json 會 exit 0、stderr 全空、輸出合法 JSON、但 controls 是空陣列——整個檔案的控制項（包含語法正常的那些）全部被靜默丟棄。

若只看 exit code，使用者會拿到一支「抽取成功但零控制項」的基準，他會以為是這份基準本來就沒東西，而不是解析壞了。靜默的錯誤比明顯的錯誤更貴。

誤判風險：理論上存在「合法但零控制項」的 profile（純 wrapper profile 只有 depends 沒有自己的控制項），但那種 profile 在本系統的使用情境下也是無效的（掃了什麼都不會驗）。判成失敗是正確的。

落庫前的解析動作：剝掉 source_location.ref 的絕對路徑前綴、丟 code（省 47.8%）、丟與 descriptions.default 重複的 desc（合計省 59.6%）、impact == 0.0 標記人工待判。收尾刪除臨時檔。

耗時參考（實跑，非推估）：234 條約 28–29 秒（704 KB → 約 292 KB）、708 條約 117 秒（1.82 MB → 約 870 KB）。117 秒遠超任何 HTTP 逾時設定，非同步沒有折衷空間。

5.7 API 端點增修

PUT 端點的權限規則：租戶只能編自己的（scope = TENANT 且 tenant_id 相符）；公版（scope = SYSTEM）只有 root 能編。此判定屬資源域守門（要先 resolve 資源才知道判誰），走 common/authz/ 在 app service 層執行，不要另立 helper。

🔴 menu API 不可改成巢狀

JobExecutionDrawer.vue:279-282 的 for (const m of items) 若拿到巢狀會靜默失效（不 throw、不進 catch）——任務抽屜的參數顯示直接退回裸的 profile:<uuid>，使用者看到一串 UUID。

分組交給 FE 還有兩個好處：FE 想改用哪一軸分組不必動 BE；符合 CLAUDE.md 的 Menu pattern（回傳 List[MenuDto] 不包 PageDataDto）。

🔴 FE 必配的 fallback 修補（不論 BE 回什麼形狀都要做）

DetectionConfigField.vue:82-92 有一段 opts.some(o => o.value === current)，用來判斷「目前選中的值是否還在選項裡」，不在就補一個「已不可用」的 fallback 項。

選項在 FE 端改成巢狀後這個比對必然全部 miss（它比對到的是 group 物件不是 leaf 選項）→ 每一個已選值都會多長一個「已不可用」項。不會報錯、不會進 catch，只會讓每張已設定的任務都顯示成「這個 profile 已不可用」。

對策：比對前先攤平選項樹；fallback 項本身也要包成一個群組，否則會混在群組之間造成渲染錯亂。

本案不實作選用範圍、豁免、人工判定與自訂項，但資料模型必須現在就留好掛載點——這些是不可逆的架構決定，事後再改要動 FR-061 已寫好的東西。

6.1 四條硬約束

🔴 抽取欄位必須一次抽完整

不是抽「目前要顯示的子集」，是抽「CINC 給的全部（扣掉 code 與重複的 desc）」。

如果 FR-060 只抽 id／title／desc 三欄，FR-061 做豁免時發現需要 tags、做人工判定時發現需要 descriptions.gcb_value，就得把所有 profile 全部重抽一次——每支 28～117 秒，而且要寫一支資料回填 migration。

存下來不顯示，成本是幾百 KB；沒存要重抽，成本是一整輪重跑加一支 migration。

D19 讓這條約束更強：重抽的成本不只是時間——多工具之後，某些格式可能根本無法重抽（工具端 API 已改版、或原始檔已不在）。attributes 整包存下來是唯一保險。

6.2 InSpec 原生機制對照（FR-061 實作時的落點）

FR-061 的三種能力在 InSpec / CINC 都有原生對應，不需要自己發明機制——這也回頭確認了 FR-060 該抽哪些欄位：

6.3 已識別但本期不做：公版名稱／描述的多語化

決策者裁示（2026-08-03）：

D20 我不想把需求拉複雜，名稱跟描述之後再補吧，目前就先選單類型的做就好。

本期不做，但缺口已經識別出來，記在這裡免得半年後有人重新發現一次。

現況缺口（不是未來的問題，是現在就存在的）：公版（scope = SYSTEM）的名稱與描述是我們自己 seed 的中文字面值，英文語系租戶登入後看到的仍是中文。實例是 DEV 那 10 筆公版，名稱形如 TWGCB-01-014 Ubuntu 22.04 LTS v1.2（35 項自動檢查）、dev-sec Linux 基準（公開範例，適用 Linux 目標）。

為什麼本期不做：決策者裁示不擴大範圍。這件事牽涉 root 編輯權限、seed 流程、前端 i18n 檔補齊，是完整一條線；混進 .2 會讓「分類與編輯」這個子項失焦。

未來要做時的形狀（先寫下來，免得屆時重新設計一次）：

• 主檔加 name_i18n_key / description_i18n_key 兩個 nullable 欄
• 公版才填、租戶自建留 NULL
• 顯示走與 D5 相同的 fallback：有 key 且翻譯存在 → 顯示翻譯，否則顯示 name 字面值
• 🔴 name 欄一律保留字面值不變——搜尋（DetectionProfileManageView.vue:506-513 的 IconField 搜尋）與排序都在 SQL 端吃這個欄位，改成純 key 會讓搜尋與排序失效
• 這是純追加欄位、不改既有語意，符合 D19「擴充不動已上線的東西」的精神

與 D5 的區別（同一個問題在不同欄位有不同答案）

分類 enum 可以只存 key——值域有限、只被下拉選取與分組使用、沒有人會打字搜尋分類值。

名稱不行——它會被搜尋、會被排序，兩者都在 SQL 端執行。存成純 key 會讓搜尋框搜不到中文名稱、排序變成按 slug 字母序。

理由是存取方式不同，不是標準不一致。未來看到這兩處做法有別，是刻意的。

切線在管理面／執行面之間，不是在「BE／FE」之間。

FR-060
 .1 資料模型重構    主從拆表 + controls 表 + 13 筆搬遷 + RLS 移位
                    + repo/service 改寫 + 派工鏈兩處破口修補
 .2 分類體系 + 基本資料編輯（含改名）
 .3 控制項抽取 + 瀏覽    BE 裝 CINC + 非同步抽取管線 + 詳細頁
 ─────────  以上第一批：全在管理面，不碰 agent、不動派工參數
 .4 選用範圍 + 豁免      （FR-061，本案只定模型契約）
 .5 人工判定 / 自訂項    （FR-061，待 .1-.3 上線後看實際使用再定形狀）

順序：.1 → .2 ∥ .3

為什麼切線在這裡：.1–.3 最壞的情況是「詳細頁少一塊內容」——既有掃描零影響，因為這三項完全不動掃描參數。而 .4 開始就動掃描參數（--controls／--tags／--waiver-file），改錯會讓掃描結果不正確。在 GRC 系統裡，使用者以為自己合規但實際不是，是嚴重問題——這種風險等級的變更值得單獨立案、單獨驗收。

7.1 實作前的準備動作

1. BE 主機裝 CINC Auditor——三台部署機 ＋ 每台開發機，先確認 macOS 開發機的路徑解析可行（CINC_AUDITOR_CMD 環境變數）
2. POC 環境唯讀確認——本次未查（環境紀律），需確認 config.detection_tool_profiles 在 POC 的存在狀態與資料筆數，作為未來上版的基準
3. Notion 開卡，關聯 FR-059 與 CM-992

兩組分開：DEV 組是開發期間必須逐項打勾的；上版前組是決策者放行 STG／POC 之前的守門，兩組不可混淆。

🔴 「STG 跑得順」不能當驗收依據

STG 與 DEV 同為 125 筆 migration、FR-059 全 5 支都在，但 STG 的 10 筆資料全部是 SYSTEM、沒有任何 TENANT 資料。這意味著搬遷 SQL 在 STG：

• 測不到租戶 RLS 路徑（全公版，租戶隔離那段 policy 根本沒被走過）
• 測不到 id 32／33 的三欄 JOIN 陷阱（同 tenant、同 name、同 file_id 但屬不同工具的形態，STG 沒有）
• 測不到停用列造成的孤兒主檔（current_version_id IS NULL 的合法狀態）

驗收必須在 DEV 完成——那裡才有完整的資料形態（10 SYSTEM ＋ 3 TENANT）。

8.1 DEV 驗收（開發期間逐項打勾）

搬遷正確性

• 主檔筆數 = 13
• 從檔筆數 = 13
• current_version_id IS NOT NULL = 12（不是 13——id 33 是合法的 NULL）
• 🔴 uid 零遺失：NOT EXISTS 比對舊表全部 uid，結果必須是 0
• id 32 與 33 各自掛在正確的工具底下（三欄 JOIN 沒有 cross join）
• platform_hint 沒有出現在任何新表（D6：不搬、不佔位）
• 舊表已 rename 為 detection_tool_profiles_deprecated_20260803，未 DROP
• INSERT public.schema_migrations 已執行

RLS（本專案首例主從雙表，必須逐條驗）

• 以 cm_app 身分模擬租戶 A：讀不到租戶 B 的主檔列
• 🔴 以 cm_app 身分模擬租戶 A：讀不到租戶 B 的從檔列（這條是關鍵——主檔擋得住不代表從檔擋得住）
• 租戶 A 與 B 都讀得到 scope = 'SYSTEM' 的公版
• 租戶 A 無法 INSERT／UPDATE 出 scope = 'SYSTEM' 的列（主檔與從檔各驗一次）
• 八段 policy 的 tenant_id::integer cast 逐處確認（migration 能套過即代表通過）

派工鏈迴歸（兩處破口）

• 🔴 停用的 profile 派不出去——把某支 profile 設 is_active = false，確認 _load_profile() 的守門確實擋下（不是 500，也不是靜默放行）
• 🔴 通知信的「掃描設定」顯示基準名稱，不是 profile:<uuid>——並補一支測試斷言此事（目前沒有任何測試會抓到這個退化）
• agent 拿到的 payload 形狀與拆表前逐欄一致（build_payload() 輸出比對）
• 既有 10 筆 soft-ref 引用（4 筆 tool_params ＋ 6 筆 agent_tasks.params）零轉換仍可解析，url 型與 file 型分開驗

抽取管線（三種分支各驗一次）

• 正常：TWGCB-01-014 抽出 234 條，is_pending = 199，自動檢查 35 條，狀態 succeeded
• 明確失敗：餵一個無 inspec.yml 的壓縮檔 → failed ＋ extraction_error 有明確訊息
• 🔴 靜默失敗：餵一個 .rb 有 Ruby 語法錯的 profile → exit 0 但 controls == [] → 仍判 failed，訊息「未解析到任何控制項」
• source_ref 已剝掉絕對路徑前綴（值形如 controls/xxx.rb，不含臨時目錄名）
• code 欄位未落庫；與 descriptions.default 重複的 desc 未落庫
• 從檔的 sha256（壓縮檔 bytes）與 CINC 自算的 profile 雜湊沒有被混用
• 非同步驗證：TWGCB-01-011（708 條、約 117 秒）上傳後立即回應，前端輪詢看得到狀態轉換

分類與編輯

• enum 值取自 DB（detection_profile_taxonomies），非 FE 常數
• 🔴 刪除保護：已被 profile 引用的分類 key 不可刪（或已改為停用），且錯誤訊息帶引用數
• 新增一個 DB enum key 但前端無對應 i18n 條目時，畫面顯示原始 key、不報錯不空白（優雅降級，符合設計預期）
• 13 筆分類補登：twgcb-01-* 為作業系統、twgcb-02-003-google-chrome 為瀏覽器；推不出來的留 NULL（沒有猜測填值）
• 改名：主檔一列 UPDATE，不升版，版本鏈完整
• 權限：租戶編不動 scope = SYSTEM 的公版；root 可編
• 若維護介面未做 → spec 已明寫「分類值目前仍靠 migration 維護，尚未有管理 UI」

前端

• menu API 回扁平陣列，JobExecutionDrawer.vue 的參數顯示正常（非裸 UUID）
• 🔴 DetectionConfigField.vue 的 fallback 比對已改為先攤平選項樹——既有已設定的任務沒有多長出「已不可用」項
• 下拉分組與 editable 手填能力並存（FR-059 P6 契約）
• current_version_id IS NULL 的主檔（id 33）在列表渲染正常不爆掉
• 控制項清單 234／708 條在 DataTable ＋ paginator 25 筆／頁下體感流暢（未達 1MB 或 2 秒門檻則不引入 VirtualScroller）

8.2 上版前條件（決策者放行才執行）

開發期間所有 migration 只套 DEV。 STG（已服役、有 10 筆資料）與 POC（等同 production，對外 demo／客戶試玩）一律等決策者當次明確指示才可套。

• POC 環境唯讀確認——確認 config.detection_tool_profiles 在 POC 的存在狀態與資料筆數（本次未查，遵守環境紀律）
• 三台部署機已安裝 CINC Auditor，CINC_AUDITOR_CMD 路徑解析在各機實測可用
• docs/claude/host-dependencies.md 已新增第三項（CINC Auditor），含各主機已確認狀況
• DEV 驗收（§8.1）全數通過——含只有 DEV 驗得出來的三項（租戶 RLS 路徑、32／33 三欄 JOIN、孤兒主檔）
• 🔴 決策者當次明示放行，才依序套 STG → POC；派工單或交接文件若寫「三環境都套」，該指令本身可能就是錯的，停下問決策者
• 上版後 POC 的既有掃描任務仍可正常派工（10 筆 soft-ref 引用零轉換的實地確認）

8.3 觀察期後另案

• 舊表 detection_tool_profiles_deprecated_20260803 DROP——另開一支 migration，觀察期（建議一個 release 週期）後執行，且比照「DROP 退役表前安全四查」實際 grep 確認無 live-wired 引用（D16）