SSP 資產清冊（Inventory Items）
功能群：專案管理｜上層見 系統安全計畫編輯器（本頁＝其 Tab「元件·授權·資產」的資產子區）
事實基準：2026-07-06 從 FE / BE code 掃出；表結構對
db_schema.json、endpoint 對routes.json、欄位對 marshmallow serializer + service 組裝碼逐條核
1. 功能描述
資產清冊是 SSP 系統實作（system-implementation）底下的
inventory-items 維護區：登錄這套系統範圍內的資產。依
FR-032
分兩張表呈現——設備資產（asset_type='hardware'
或未設）與系統資產（asset_type='information_system'），兩者共用同一張
oscal.ssp_inventory_items 表、UI 分流顯示、picker
來源不同。資產可「鉤稽」既有的設備（/devices/menu）或資訊系統（/information-systems/menu）master，由
BE 做 snapshot；也可自由輸入。
掛在 SSP 編輯器 Tab「元件·授權·資產」的第三子區（元件 → 授權 → 資產）。與 SSP 其餘子區共用可編輯 gate（manager + AP=planning）。
主要使用者：專案 manager（寫）、參與者（讀）。
角色速覽（完整定義見 _overview §3）：
| 角色 | 一句話 |
|---|---|
| manager | 專案經理 — 唯一能增改刪資產者（需 AP=planning） |
| 參與者 | auditor / reviewer / viewer — 可讀不可寫 |
1.1 功能總覽（本頁全部功能）
| # | 功能 | 說明 | 位置 | 詳述 |
|---|---|---|---|---|
| 1 | 設備資產清單 | asset_type≠information_system 的資產（DataTable） |
設備資產表 | §5 |
| 2 | 系統資產清單 | asset_type='information_system' 的資產 |
系統資產表 | §5 |
| 3 | 新增 / 編輯設備資產 | 鉤稽設備 master 或自由輸入（asset_id / IP / MAC / OS 等 8 欄） | Dialog | UC-SI-01 |
| 4 | 新增 / 編輯系統資產 | pick 資訊系統 master（BE full-replace）或 free 自由輸入 | Dialog | UC-SI-01 |
| 5 | 對應元件（M2M） | 關聯此資產實作了哪些元件；編輯時鎖定，需 delete+重建 | Dialog MultiSelect | UC-SI-01 / §12 |
| 6 | 刪除資產 | 移除一筆（M2M join 隨 CASCADE 清） | 每列 | §6.2 |
UC（§2）展開 UC-SI-01（新增/編輯資產），涵蓋設備 vs 系統雙路徑、snapshot、M2M 鎖定三個關鍵分支；清單顯示屬純顯示見 §5。
2. Use Case
角色速覽（同 §1）。流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。
UC-SI-01 新增 / 編輯資產（設備 / 系統雙路徑）
| 項目 | 內容 |
|---|---|
| 角色 | 專案 manager |
| 前置條件 | 已載入 SSP；AP=planning；鉤稽 master 時該設備 / 資訊系統須存在 |
| 產出 / 後置條件 | 寫 oscal.ssp_inventory_items（props +
implemented_components jsonb）；鉤稽時 BE 由 master
snapshot；description 空 → GRC_400074 |
3. 權限矩陣
| 操作 | FE 判定 | BE 強制 | BE 檢查位置 |
|---|---|---|---|
| 讀清單 | 參與者即可 | require_participant |
app/oscal/service/ssp_inventory_items_app_service.py:65 |
| 新增 / 編輯 / 刪除 | canEdit（manager 且 AP=planning）；FE
readonly 隱藏按鈕 |
require_manager（manager + AP 可編輯，否則
GRC_403051 / GRC_412028） |
同檔 add_item:74 / update_item:95 /
delete_item:114 |
4. 狀態機與前置條件
承接 SSP 可編輯 gate（見 SSP 編輯器
§4）：AP=planning 且 manager
才可寫，凍結後唯讀。額外前置：system_implementation
不存在時新增第一筆會自動建立。
5. UI 設計
版面骨架與區塊職責（FR-032 依 asset_type 分設備 / 系統兩張 DataTable，各自對應 Dialog；彩色區塊可點跳本頁小節錨點，API 僅標代表性）：
📸 截圖待補（亮色模式）：設備資產表 + Dialog
sspinv-device.png、系統資產表 + Dialog（pick/free 兩模式）sspinv-system.png。
UI 分兩張 DataTable（設備 / 系統），各自「新增」開對應 Dialog。設備資產 Dialog 欄位：
| 欄位 | i18n / label | 型別 | 必填 | 儲存 | 備註 |
|---|---|---|---|---|---|
| description | col_device_name 名稱 |
InputText | 是 | 頂層 | 空 → GRC_400074 |
| ref_id（鉤稽設備） | dev_pick_label |
Dropdown（/devices/menu） |
否 | props ref-id |
選後自動帶入 IP / hostname / OS |
| asset_id | 資產編號 | InputText | 否 | props | |
| asset_tag | 資產標籤 | InputText | 否 | props | |
| ipv4_address | IPv4 | InputText | 否 | props | 鉤稽時自動帶入 |
| mac_address | MAC | InputText | 否 | props | |
| fqdn | FQDN | InputText | 否 | props | |
| hostname | 主機名稱 | InputText | 否 | props | 鉤稽時自動帶入 |
| software_name | 軟體 | InputText | 否 | props | |
| os_name | 作業系統 | InputText | 否 | props | 鉤稽時自動帶入 |
| implemented_component_uids | 對應元件 | MultiSelect | 否 | implemented_components |
編輯時 disabled（見 §12） |
系統資產 Dialog 有 pick / free 兩模式：pick 模式選
ref_id（/information-systems/menu，必填，否則
sys_pick_required）→ BE full-replace master；free 模式填
name（必填）/ abbreviation /
description / owner_name /
deployment_model（on-premise / cloud / hybrid /
co-location）/ system_status（同元件 status 列舉）。
狀態呈現：無
socket，寫入後重載；per-列動作；readonly 由父層依
role / AP 狀態傳入。
6. API 規格
Envelope：成功 {"status": true, "data": …}、失敗
{"error_code": "…", "msg": "…"}。
6.1 總清單
| 分類 | Method + Path | 說明 | 完整規格 |
|---|---|---|---|
| 資產 | GET / POST /ssp/{ssp_uid}/inventory-items |
列出 / 新增 | §6.2 |
| 資產 | PUT / DELETE
/ssp/{ssp_uid}/inventory-items/{item_uid} |
編輯（M2M 受限）/ 刪除 | §6.2 |
| picker | GET
/devices/menu、/information-systems/menu |
鉤稽 master 來源 | GAI-SD-02 |
6.2 核心 endpoint
[POST] /ssp/{ssp_uid}/inventory-items
Request：
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
| description | string | 是 | 資產名稱；空 / 空白 → GRC_400074 |
| asset_type | string | 否 | hardware（預設）/ information_system |
| ref_type / ref_id | string / uuid | 否 | 鉤稽 master（device / information_system +
對應 uid）；BE 由此 snapshot |
| props | object | 否 | 明細欄（asset_id / ipv4_address / mac_address / fqdn / hostname / software_name / os_name；系統資產：name / abbreviation / owner_name / deployment_model / system_status） |
| implemented_component_uids | array | 否 | 對應元件 uid 陣列（僅新增有效） |
鉤稽行為：ref_id 有值時，設備走
merge（snapshot_device 帶 hostname / ipv4
/ os_name，其餘 props 保留；ref_id 無效 →
GRC_404035）；系統走
full-replace（snapshot_information_system
全取 master，不信 FE；ref_id 無效 →
GRC_404020）。Response：資產
DTO（見下）。出處：app/oscal/service/ssp_inventory_items_app_service.py:64-116、app/module_frame/service/system_asset_snapshot.py
[GET] /ssp/{ssp_uid}/inventory-items
Response data（陣列，每項）：
| 欄位 | 型別 | 說明 |
|---|---|---|
| uid | string | 資產 uid（ssp_inventory_items.uuid；改刪用） |
| description | string | 資產名稱 |
| asset_type | string | hardware / information_system（取自 props
保留鍵 asset-type） |
| ref_type / ref_id | string｜null | 鉤稽來源（props 保留鍵 ref-type /
ref-id） |
| props | object | 明細欄（見上） |
| implemented_components | array | [{uid, title}]——反查元件 title |
| created_user / updated_user | string | login_name |
出處：app/module_frame/service/module_frame_inventory_service.py:144-164（_to_dict）
[PUT] /ssp/{ssp_uid}/inventory-items/{item_uid}
同 POST，但 implemented_component_uids 只在
payload 帶有此鍵時才覆寫；FE
編輯模式不送此欄（M2M 鎖定），故既有關聯不動。item_uid
不存在 → GRC_404034。
7. 前端檔案地圖（compliance-manager-fe/）
| 檔案 | 角色 |
|---|---|
src/components/grc/ssp/SspComponentsLeveragedInventoryTab.vue |
本子區（設備 / 系統兩表 + Dialog + snapshot 帶入 + M2M） |
src/service/SspService.js |
getSspInventoryItems /
createSspInventoryItem /
updateSspInventoryItem /
deleteSspInventoryItem + picker menu |
8. 後端檔案地圖（本頁核心鏈路）
| 鏈路 | Route | App Service | 底層 |
|---|---|---|---|
| 資產 CRUD | api/oscal/routes/ssp/ssp_inventory_items_route.py |
SspInventoryItemsAppService（require_participant/require_manager） |
oscal.ssp_inventory_items；snapshot
app/module_frame/service/system_asset_snapshot.py；mapper
module_frame_inventory_service.py |
9. DB
9.1 資料表總清單（本頁讀寫的全部表）
| 表 | 讀寫 | 說明 | 詳述 |
|---|---|---|---|
| oscal.ssp_inventory_items | 讀 / 寫 | 資產本體（props + implemented_components jsonb） | §9.3 |
| oscal.ssp_system_implementations | 讀 | containment 父（首次新增自動建） | GAI-SD-03 |
| public.devices / public.information_systems | 讀 | 鉤稽 master（snapshot 來源） | GAI-SD-03 |
9.2 ER 圖
資產隸屬 ssp_system_implementations（containment），見
SSP 編輯器 §9.2 ER；本頁不另繪。
9.3 核心表欄位（取自 DEV DB dump）
oscal.ssp_inventory_items
| 欄位 | 型別 | 說明 |
|---|---|---|
| system_implementation_id | bigint | containment FK → ssp_system_implementations |
| uuid | uuid | 資產身分（對外 uid） |
| description | text | 資產名稱（必填） |
| props | jsonb | [{name,value}]；保留鍵
asset-type / ref-type / ref-id +
明細（asset_id / ipv4_address / …；系統資產 name / abbreviation /
…）；讀時 _to_dict pop 保留鍵到頂層 |
| implemented_components | jsonb | [{"component-uuid": uid}]——軟式參照元件
uuid，無 FK；讀時反查 title |
| responsible_parties | jsonb | 負責單位 / 人員（選填） |
⚠️ schema 註：本頁欄位一律取自
db_schema.json（system_implementation_id/uuid/propsjsonb）。asset_type/ref_id不是獨立欄位，是存在props的保留鍵。
10. 頁面邏輯與資料對應
FE hardwareItems / systemAssets 由
asset_type 前端 filter 分表。鉤稽設備
onPickDevice 自動帶
ipv4_address/hostname/os_name（FE
便利，BE 仍會 snapshot 覆蓋設備三欄）。系統 pick 模式
onPickSystem FE 先帶 name/abbreviation，BE full-replace
為準。錯誤對應：GRC_400074（名稱必填）/
GRC_404020（資訊系統不存在）/
GRC_404035（設備不存在）/
GRC_404034（資產項不存在）→ toast。
11. 背景行為與外部依賴
| 類型 | 內容 |
|---|---|
| socket | 無 |
| snapshot | 鉤稽時由 master 撈當下快照存進資產；master 日後更新不會回溯同步到已建資產 |
| 依賴 | /devices/menu（設備
master，FR-032）、/information-systems/menu（資訊系統
master） |
12. 邊界情況與已知坑
- M2M
implemented_component_uids編輯時鎖定：BE update path 只在 payload 帶該鍵時覆寫；FE 編輯模式:disabled="!!invEditing.uid"不送此欄。改對應元件要 delete + 重建。_build_implemented回[]不回None（避免 silent-skip）。 - 設備 merge vs 系統 full-replace：鉤稽設備只覆蓋 hostname / ipv4 / os_name（其餘 props 保留）；鉤稽系統全取 master、不信 FE——同一「鉤稽」語意在兩型不同，維護留意。
- snapshot 單向凍結：資產存的是 master 當下值，不隨 master 更新。
- props 保留鍵：
asset-type/ref-type/ref-id是 props 內保留鍵、非 DB 欄位；讀時被_to_dict提到頂層。改欄位名要同步 mapper。 - description 同 SSP 內唯一（MF 版有、SSP 版目前無驗證）：module-frame 版有 case-insensitive 去重，SSP scope 目前無此檢查、FE 亦無提示（潛在 follow-up）。
13. 開發與驗證
- 跑起來：起 BE + FE；登入見
.env/ 部署文件測試帳號（需該專案 manager） - 導航：規劃頁 Tab1「系統安全計畫」→ 子
Tab「元件·授權·資產」→ 資產區（或
?section=scope_devices/scope_info_systems深連結，會 redirect 到整合 tab） - 前置資料：需有 living SSP 的專案（AP=planning）+ 幾筆設備 / 資訊系統 master 測鉤稽 snapshot；建元件後測 M2M 鎖定（新增可選、編輯鎖）
- 相關：元件見 SSP 元件清冊；設備 / 資訊系統 master 見系統管理群