SSP 元件清冊（Components）

功能群：專案管理｜上層見 系統安全計畫編輯器（本頁＝其 Tab「元件·授權·資產」的元件子區）

事實基準：2026-07-06 從 FE / BE code 掃出；表結構對 db_schema.json、endpoint 對 routes.json、欄位對 route 組裝碼 + mapper 逐條核

1. 功能描述

元件清冊是 SSP 系統實作（system-implementation）底下的 components 維護區：登錄構成這套受評系統的元件——軟體、硬體、服務、政策、流程等。對應 OSCAL SSP 的 system-implementation.components，掛在 ssp_system_implementations（首次新增時 get_or_create 自動建父）。每個元件可標 component_type（15 選）、狀態、關聯的利用授權（leveraged_authorization_uid，來源同頁「利用授權」子區），以及協定 / Port / 安全機制等擴充屬性。

掛在 SSP 編輯器 Tab「元件·授權·資產」的第一子區（元件 → 授權 → 資產），三子區共用同一個 Vue 元件（SspComponentsLeveragedInventoryTab.vue）。與 SSP 其餘子區共用可編輯 gate（manager + AP=planning），凍結後唯讀。

主要使用者：專案 manager（寫）、專案任一參與者（讀）。

角色速覽（完整定義見 _overview §3）：

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

UC（§2）展開 UC-SC-01（新增/編輯元件），涵蓋 15 型別、必填雙檢（title/type）、props 擴充欄、編輯 not-found 四個關鍵分支；清單顯示屬純顯示見 §5。

2. Use Case

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

UC-SC-01 新增 / 編輯元件

3. 權限矩陣

route 層僅 @jwt_required()，且收 raw request.get_json()、無 marshmallow schema 驗證（ssp_components_route.py:50,69）；角色守門與欄位處理都在 app service。

4. 狀態機與前置條件

承接 SSP 可編輯 gate（見 SSP 編輯器 §4）：AP=planning 且 manager 才可寫，凍結後唯讀。額外前置：system_implementation 不存在時，新增第一筆元件會 get_or_create_system_implementation 自動建立（ssp_components_app_service.py:66）。

5. UI 設計

版面骨架與區塊職責（一張元件 DataTable + 新增/編輯 Dialog；彩色區塊可點跳本頁小節錨點，API 僅標代表性）：

📸 截圖待補（亮色模式）：元件 DataTable + 新增/編輯 Dialog sspcomp-list.png。

一張 DataTable（此 SSP 全部元件，不分 type）+「新增元件」開 Dialog。DataTable 欄位：類型（Tag，COMPONENT_TYPE_SEVERITY 上色）/ 名稱 / 描述（兩行截斷）/ 狀態 / 利用授權（Chip leveraged_authorization_title——⚠️ 見 §12）/ 協定（props.protocol）/ 安全機制（props.security_auth）/ 動作（編輯 + 刪除）。

Dialog 欄位（SspComponentsLeveragedInventoryTab.vue 元件 Dialog）：

15 component_type（componentTypeOptions，i18n ssp_excel_import.component_type.*）：this-system / system / service / interconnection / hardware / software / network / policy / physical / process-procedure / plan / guidance / standard / validation / other。

狀態呈現：無 socket，寫入後 loadAll 重載；readonly 隱藏新增/編輯/刪除鈕。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"error_code": "…", "msg": "…"}。

6.1 總清單

6.2 核心 endpoint

[POST] /ssp/{ssp_uid}/components

新增元件。Request（route 收 raw JSON，無 schema；欄位由 service add_item 取用）：

{
  "title": "Web 應用伺服器",
  "component_type": "software",
  "description": "對外服務主機",
  "purpose": "承載受評應用",
  "status": "operational",
  "leveraged_authorization_uid": null,
  "protocol": "HTTPS",
  "port_ranges": "443",
  "security_auth": "TLS 1.3 + mTLS"
}

出處：app/oscal/service/ssp_components_app_service.py:61-82、mapper app/module_frame/service/module_frame_components_service.py:_build_props:164-181

[GET] /ssp/{ssp_uid}/components

Response data（陣列，_to_dict + enrich）：

⚠️ 無 leveraged_authorization_title：BE DTO 只回 leveraged_authorization_uid，DataTable 的「利用授權」Chip 綁 leveraged_authorization_title（FE 未貼），實際恆顯示「—」（見 §12）。出處：module_frame_components_service.py:_to_dict:131-146

[PUT] /ssp/{ssp_uid}/components/{item_uid}

編輯。只更新 payload 帶到的鍵（component_type/title/description/purpose/status + props 非破壞性合併）；item_uid 不存在於此 SSP → GRC_404034。出處：ssp_components_app_service.py:84-101

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

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

DDD 提醒：mapping 共用範本版 helper。⚠️ SSP 版 add_item 無同名去重、MF 版有（MODULE_FRAME_COMPONENT_NAME_EXISTED）——public method 各自實作，勿誤認行為相同（見 §12）。

9. DB

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

9.2 ER 圖

元件隸屬 ssp_system_implementations（containment），元件 uuid 被 ssp_inventory_items.implemented_components 軟參照，見 SSP 編輯器 §9.2 ER；本頁不另繪。

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

oscal.ssp_components

⚠️ schema 註：以 db_schema.json 為準（tbls .md 版曾 drift 寫成 ssp_id/component_type/leveraged_authorization_uid 欄，皆錯）。本表 無 leveraged_authorization_uid 欄（在 props）、無 tenant_id / is_active；協定/Port 亦不落 protocols OSCAL 欄而在 props。

10. 頁面邏輯與資料對應

loadAll 一次 Promise.all 拉元件 / 利用授權 / 資產 / 資訊系統 menu / 設備 menu；元件 raw 存 components。欄位對應：

儲存流程：saveComponent 先 client 檢查 title.trim() + component_type（缺 → toast warn 不送）→ POST/PUT → loadAll 重載。LA 使用計數：FE laReferenceCounts 由 component.leveraged_authorization_uid 反查授權被幾個元件引用。錯誤對應：GRC_404034（元件不存在）/ GRC_403051 / GRC_412028 → toast。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. DataTable「利用授權」Chip 恆空：欄位綁 data.leveraged_authorization_title，但 BE _to_dict 只回 leveraged_authorization_uid、loadAll 未把授權 title join 回元件——leveraged_authorization_title 永遠 undefined，Chip 恆顯示「—」。要顯示需 FE 用 leveragedAuthOptions map uid→title 或 BE enrich（follow-up）。
2. title 必填只有 FE 擋、BE 無守門：saveComponent client 檢查 title/type；但 route 收 raw JSON、service add_item 用 payload.get('title') or ''——直接打 API 送空 title 不會被拒（無等價 error code）。
3. SSP 版新增無同名去重、MF 版有：ModuleFrameComponentsService.add_item 有 case-insensitive 同名 ConflictError；SspComponentsAppService.add_item 沒有——SSP scope 可建同名元件。
4. component_type 預設 FE/BE 不同：FE startAddComponent 預設 system、BE add_item 缺省 software；因 FE 恆送 component_type，BE 預設幾乎不觸發，但直打 API 不帶此欄時會落 software。
5. 協定/Port/利用授權皆走 props、非核心欄：props['protocol'] / ['port_ranges'] / ['security_auth'] / ['leveraged-authorization-uid'] 是產品擴充；DB 的 protocols OSCAL jsonb 欄本頁不寫。改鍵名要同步 mapper _PROP_KEYS / _PROP_LEVERAGED。
6. 元件 uuid 被資產 M2M 軟參照：ssp_inventory_items.implemented_components 以 component-uuid 軟參照元件（無 FK）；刪元件不會連動清資產側關聯，留意孤兒參照。
7. SSP 寫入無 phase guard（BE）：唯讀由 FE 鎖；凍結後直接打 API 仍會改 living SSP——同 SSP 編輯器 §12。

13. 開發與驗證

• 跑起來：起 BE + FE；登入見 .env / 部署文件測試帳號（需該專案 manager）
• 導航：規劃頁 Tab1「系統安全計畫」→ 子 Tab「元件·授權·資產」→ 元件區
• 前置資料：需有 living SSP 的專案（AP=planning）；先建幾筆利用授權測元件的 LA dropdown + 使用計數；測 15 type Tag 上色、測 props 欄 round-trip
• 相關：利用授權見 利用授權、資產見 資產清冊；其餘子區見 基本資料 / 參與方；OSCAL component 概念見 oscal-knowledge skill