FR-032 系統資產盤點（資訊系統作為資產納入 SSP inventory）— 設計文件

1.1 白話需求

合規資源庫範本（Module Frame）與專案 SSP 目前的「資產清冊」只盛裝設備（device 性質的資產：IPv4 / MAC / 主機名稱 / 作業系統…）。實務上做資產盤點時，資訊系統本身也是一種資產，需要跟設備並列在盤點清冊裡。

使用者希望在 /module-frame/<uid>/template-edit 的「系統元件、外部授權與資產」tab，於既有「資產清冊」下方再多一張「系統資產」表，可以：

1. 從現有資訊系統清單挑選，自動帶入欄位
2. 系統清單沒有對應資料時，允許直接在表單自由輸入
3. 同時保存鉤稽 id，方便溯源

1.2 受評標的維持獨立（不動）

information_system 在系統中目前對應 OSCAL SSP 的 system-characteristics（受評標的）：一份 SSP 只有一個受評主體。本期不改變受評標的的角色與資料。系統資產是「同一筆 information_system 在別的範本 / SSP 中以資產身分被引用」的新視角，與受評標的並存。

1.3 三者 OSCAL 對照（釐清「不是同一個東西」）

合規資源庫（Profile）與受評標的（SSP）是不同層；受評標的與資訊系統現況是同一概念的兩個名字。本期讓資訊系統多一個資產身分。

2.1 雙重身分（dual-identity）

同一筆 compliance.information_systems：

• 在它自己的受評案裡 → 受評標的（system-characteristics，主體）
• 在別的範本 / SSP 裡被引用 → inventory-item（資產），純引用

2.2 Hybrid soft-ref（複製欄位 + 選填鉤稽 id）

採用專案既有的 soft-ref + 快照 + 自由輸入模式（對齊 OSCAL party / 參與人員 matching：matched_user_id soft ref + enrich 顯示快照 + 配不到維持自由輸入）：

• 一筆系統資產列存複製下來的欄位（一定有值，文件自包含）＋選填的 ref（ref_type + ref_id）
• ref 只負責「自動帶入」與「溯源」，不負責即時同步
• 同步方向單向：master → 表單（挑選時 / 未來重新帶入時）；永不回寫 master

選此模式而非純 reference / 純 copy 的理由：

2.3 與設備並存、共用管線

設備維持 copy 行為不動（jedi-device 未接入，本就無 master 可鉤稽）；系統因有 master（information_systems）才走 hybrid。兩者同桌（共用 inventory 表），靠 asset_type 鑑別，UI 渲染成兩張表。

2.4 雙重身分安全保證

在 inventory 表（範本 default 或 SSP copy）的任何編輯只動本地列，永不回寫 compliance.information_systems master。改 master 只能走資訊系統管理頁。

3.1 共用 inventory 表加欄位（純 additive，既有設備列零影響）

於 compliance.module_frame_inventory_item_defaults（範本層） 與 oscal.ssp_inventory_items（SSP 層） 各加：

Migration：

• 既有列 backfill asset_type='hardware'、ref_type/ref_id=NULL → 設備行為完全不變
• 只加欄位、不新建表，既有 GRANT 沿用（無需新授權）
• 兩張表的 migration 各加日期註解，檔頭加 -- Date: YYYY-MM-DD（per SQL migration 規範）
• migration 用 cmmgr 帳號跑（cm_app 受 RLS）

3.2 系統資產列的資料落點

不放 CIA（security_objective_*）與 authorization_boundary — 那是受評標的層級，避免兩邊重疊混淆。

審計欄位：owner_id 配 owner_name（nickname）。注意：本設計的 owner_name 是 snapshot 當下凍結進 props 的值（符合 §2.2「凍結」原則），讀取時不再 re-enrich。這與一般「審計欄位 read 時批次轉 nickname」慣例不同 — 系統資產是時間點快照，刻意保留挑選當下的 owner nickname。snapshot 寫入時（BE 抓 master 那一刻）查 User.login_name → nickname 一次即可。implementation plan 要明確標示此點，避免被誤改成 read 時 re-enrich。

A. 範本層（template-edit 頁）
   「系統資產」表 →「新增系統資產」
     ├─ 從清單挑：picker 撈 /information-systems/menu → 選定
     │    → BE 用 ref_id 回 master 撈 → snapshot 欄位進 props + 存 ref_type/ref_id
     │      （snapshot 由 BE 抓 master，不信 FE 傳值）
     └─ 自由輸入：直接填 → ref 為 null
   存入 compliance.module_frame_inventory_item_defaults（asset_type='information_system'）
        │
        │ B. 啟動專案 clone（沿用既有 INSERT...SELECT，補上 3 個新欄位）
        ▼
   oscal.ssp_inventory_items：props 快照逐字複製、ref 帶過來 → SSP 凍結評估當下狀態
        │
        │ C. 專案內 SSP 編輯（同表、同元件、同 picker；編輯只動該份 SSP copy，與 master 分岔可接受）
        ▼
   D. 匯出：mapper 對 asset_type='information_system' 列吐 inventory-item + asset-type prop

clone 的最小改動：現有 clone step 已逐字複製 props，只需把 asset_type / ref_type / ref_id 加進 INSERT...SELECT 欄位清單；系統資產列同桌故自動 clone，不另寫管線。

5.1 範本層（沿用既有 inventory 端點，加 asset_type 分支）

沿用 /module-frame/<uid>/inventory 的 POST/PUT/DELETE，payload 多帶 asset_type + 選填 ref_type/ref_id：

• service 分支：
  • ref_id 有值 → 注入 information_system_domain_service 回 master 撈、組 props 快照
  • 無 ref_id → 收 FE 自由輸入的 props
• 不另開新資源，維持 API 面最小
• marshmallow schema 必須加 asset_type / ref_type / ref_id 欄位：既有 inventory route 若用嚴格 use_kwargs，未宣告的新 payload key 會在進 service 前被 silently drop（plan pre-flight 要驗 schema 是否嚴格、補欄位）

5.2 SSP 層（C）

沿用 FR-011.3「專案內直接編輯 SSP」既有的 SSP inventory 編輯端點，同樣加 asset_type 分支。 實作期 pre-flight 必驗：FR-011.3 既有端點的實際路徑與 service 方法（plan vs reality）。

5.3 picker

直接重用既有 GET /information-systems/menu，不新增端點。

5.4 權限與 error code

• 寫入走 service 層 manager/auditor 角色檢查（per 開發規範：寫入 API 必須角色權限檢查）
• 新 error code（per GRC_<HTTP><序號> 命名）：information_system ref_id 無效時拋 NotFound
  • 實作期到 common/code/grc_error_code.py 查最大序號 +1，避免序號被佔（per plan vs reality）

5.5 DDD 規範

• Route 不查 DB、不 import ORM model；權限檢查在 service 層透過 domain service
• app service public method 加 @transaction；snapshot 抓 master 走 information_system_domain_service
• 不直接 import infra ORM model

6.1 Pre-flight 驗證後的 live 現實（取代原假設）

驗證確認「資產清冊」live path = module_frame_inventory_item_defaults（範本，經 /module-frame/:uid/inventory）→ clone → oscal.ssp_inventory_items（SSP）。但匯出 loader 沒跟著 §11.29 遷移 repoint：

• MfSspContentLoader（範本匯出）讀 resources（= 廢棄的 ssp_components devices/info_systems），不是 module_frame_inventory_item_defaults → 連 rich 設備列現在都匯不出（既有遺漏）
• SspVersionContentLoader（專案 SSP 匯出）讀永遠空的 ssp.system_implementations → inventory/components/leveraged 全空
• OSCAL-native（json/yaml/xml，ssp_yaml_mapper）同讀空的 system_implementations

6.2 D1-A 決策

把 docx/pdf/odt 匯出的 inventory builder repoint 到 live 表，同時吐 hardware + information_system：

• MfSspContentLoader._build_inventory_items → 改讀 module_frame_inventory_item_defaults（按 asset_type 分流）
• SspVersionContentLoader._build_inventory_items → 改讀 ssp_inventory_items（按 asset_type 分流）
• 系統資產列在 docx 內以 inventory 列呈現（SspInventoryItemExportItem.device_type='information-system' 區分；或視 generator 渲染另立 sub-section）
• 副作用（已知並接受）：設備匯出輸出改為讀正確的新表（一併修好既有遺漏）

6.3 本期不碰（follow-up）

• OSCAL-native json/yaml/xml：讀空 system_implementations 是跟本功能無關的更深層既有缺陷（影響整個 system-implementation 區塊）→ 列 follow-up，不在 FR-032 修
• 因此 §原「asset-type prop on OSCAL inventory-item」shape（含 system-name/deployment-model 等 props）屬 OSCAL-native path，遞延到該 path 修復時再落地；本期 docx 走 rendered 列
• ref_id 本期不寫進任何匯出（round-trip 是 E 期）

• 新「系統資產」表元件，置於「系統元件、外部授權與資產」tab 的資產清冊下方，比照既有 inventory 表樣式（PrimeVue / BaseService / src/config/api/api.js 常數，per FE CLAUDE.md）
• 「新增系統資產」dialog：
  • 上方 picker（下拉選系統，選了自動帶入欄位）
  • 下方可編輯欄位（支援自由輸入 / 微調帶入值）
• 同一元件於 C 的專案內 SSP 編輯畫面重用
• 跨 repo 作業：動工前先讀 FE CLAUDE.md（per 跨 repo 規範）

• BE app service 測試：
  • 範本層 add/update 系統資產（有 ref / 無 ref 兩路徑）
  • ref_id 無效 → 拋 NotFound
  • snapshot 由 master 取值（不採 FE 傳值）
  • clone 帶過 asset_type / ref_type / ref_id
  • docx 匯出（repoint 後）含系統資產列 + 設備列（D1-A）
  • 加 logger patch autouse fixture（per DBLogHandler 雷，抄 test_ssp_excel_import_app_service.py:46）
• E2E（後續於 compliance-manager-test repo）：template-edit 新增系統資產 → 啟動專案 → SSP 內可見可編輯 → docx 匯出含系統列

已廢棄但可借用的成熟邏輯：SspResourcesContextService（§11.29 前的 info_systems 機制）已實作 information_system soft-ref + matched_* enrich + information_system_domain_service 注入 —— 搬這套邏輯到新 inventory 機制，不重新發明。

A/B/C/D/F 收尾（2026-06-04）逐條列出與原設計的偏差與原因。E-a 換 session 接手（見 handoff）。

E-a 收尾（2026-06-04，Excel round-trip）

§11 index（對應段同步）

• A/B/C/D/F：完工
• E-a：✅ 完工（2026-06-04，見 FIXED SUMMARY + §11.11~11.19）
• G（jedi_information_system 拆套件）：✅ 完工（2026-06-04，解耦 jedi-auth + 抽 jedi-information-system==0.0.1 推 Nexus；見 analysis 可行性評估 + changelog 2026-06-04-tweak-fr032-g-jedi-information-system-extract.md）
• E-b / OSCAL-native 匯出 / docx components-leveraged repoint：follow-up