SSP 基本資料（System Characteristics）

功能群：專案管理｜上層見 系統安全計畫編輯器（本頁＝其 Tab「基本資料」子區）

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

1. 功能描述

基本資料是 SSP 的系統特性（system-characteristics）編制區：登錄受評範圍（受評標的）的身分與整體屬性——範圍名稱、識別碼、FIPS-199 安全分類、範圍類型、運行狀態、範圍負責人、授權邊界描述與描述。對應 OSCAL SSP 的 system-characteristics 物件，與 SSP 為 1:1（一份 SSP 一列 oscal.ssp_system_characteristics，ssp_id UNIQUE），寫入採 upsert（首次 PUT 自動建列）。

掛在 SSP 編輯器 的第一個子 Tab「基本資料」（FE SspBasicSection.vue）。與 SSP 其餘子區共用同一組可編輯 gate（manager + AP=planning），launch-audit 凍結後唯讀。同一支元件亦被範本編輯（module-frame）復用，差別只在 apiBase prop（ssp vs module-frame）與權限守門。

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

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

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

本頁無 DataTable / Dialog，是單一表單 1:1 upsert，故 §1.1 只有讀 + 寫兩項；UC（§2）展開唯一核心路徑 UC-SB-01（編輯系統特性），涵蓋名稱必填（FE 擋）、權限守門、首次自動建列、8 欄映射四個關鍵分支。

2. Use Case

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

UC-SB-01 編輯系統特性（1:1 upsert）

3. 權限矩陣

route 層僅 @jwt_required()（ssp_system_characteristic_route.py:24,39），實際角色守門在 app service 的 SspPermissionChecker.require_participant / require_manager——與 SSP 群其他頁一致。改權限以 service 層為準。

4. 狀態機與前置條件

承接 SSP 可編輯 gate（見 SSP 編輯器 §4）：AP=planning 且 manager 才可寫，凍結後唯讀。額外前置：

5. UI 設計

版面骨架與區塊職責（單一直式系統特性表單，無 DataTable / Dialog；彩色區塊可點跳本頁小節錨點，API 僅標代表性）：

📸 截圖待補（亮色模式）：基本資料表單整頁（含頂部受評標的說明 block）sspbasic-form.png。

單一直式表單（無 DataTable / Dialog），頂部一則 info block 說明「這頁要填什麼」（audit_subject_intro_body）。8 個表單欄位（SspBasicSection.vue template）：

狀態呈現：無 socket、無徽章；載入時顯示 ProgressSpinner；儲存成功 toast、失敗 toast（讀 e.response.data.msg）。readonly 時整組欄位 disabled、無「儲存」鈕。

6. API 規格

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

6.1 總清單

6.2 核心 endpoint

[PUT] /ssp/{ssp_uid}/system-characteristic

系統特性 1:1 upsert。所有欄位選填（allow_none）、route 層 strip None（只送有值欄位視為更新，缺欄位＝不變）。Request body：

{
  "name": "受評系統範圍名稱",
  "description": "系統摘要",
  "system_identifier": "SYS-001",
  "security_sensitivity_level": "high",
  "target_type": "資訊系統",
  "scope_description": "授權邊界描述",
  "status": "active",
  "owner_uid": "<user uid>"
}

映射與 upsert：_apply_payload 只動 payload 帶到的鍵、props 走 {name,value} 非破壞性合併；ssp 無列時 auto-create（NN 欄 system_name/description/status_state/authorization_boundary_description/system_ids 給空預設）。出處：app/oscal/service/ssp_system_characteristic_app_service.py:52-68、mapper app/module_frame/service/module_frame_system_characteristic_service.py:_apply_payload:91-113

[GET] /ssp/{ssp_uid}/system-characteristic

Response data（SspSystemCharacteristicResponseSchema + audit nickname enrich）：

出處：module_frame_system_characteristic_service.py:_to_dict:121-136、serializer api/oscal/serializers/ssp/ssp_system_characteristic_inproject.py

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

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

DDD 提醒：app service 不自寫 mapping，直接複用範本版 ModuleFrameSystemCharacteristicService 的靜態 _apply_payload / _to_dict，確保 MF 與 SSP 兩端欄位映射單一真相。

9. DB

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

9.2 ER 圖

系統特性以 ssp_id（UNIQUE 1:1）隸屬 system_security_plans，見 SSP 編輯器 §9.2 ER；本頁不另繪。

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

oscal.ssp_system_characteristics（本頁只寫下列 8 欄映射的欄位；其餘 v2 補欄 CRUD 未觸及）

⚠️ schema 註：欄位一律取自 db_schema.json。target_type / owner_uid 不是獨立欄位，是存在 props 的保留鍵（target-type / owner-uid）；system_identifier 是 system_ids jsonb 陣列第一項的 id，非獨立欄位。表另有 network-architecture / data-flow / security-objective 等多組 v2 補欄，本頁 8 欄 UI 未觸及。

10. 頁面邏輯與資料對應

進子 Tab 由 useSspSystemCharacteristic.load(uid, {apiBase}) GET 載入，寫入 form（8 欄）。欄位對應：

儲存流程：onSave 先 client 檢查 name.trim() 非空（空 → toast warn 不送）→ 全 8 欄一次 PUT（name trim、其餘 || ''）→ invalidate cache → toast success → emit saved。載入 fallback：security_sensitivity_level 空 → high、status 空 → active（避免 dropdown 顯示空白）。錯誤對應：GRC_403051（非 manager）/ GRC_412028（AP 關閉/封存）→ toast（讀 msg）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. name 必填只有 FE 擋、BE 無守門：SspBasicSection.onSave client 端檢查 name.trim() 非空（toast warn 不送）；但 SspSystemCharacteristicUpdateSchema 全欄 allow_none、route strip None、mapper payload.get('name') or ''——直接打 API 送空 name 不會被拒（與 inventory 的 GRC_400074 BE 守門不同，此頁無等價碼）。
2. 運行狀態 FE 4 值 / value active 對不上 DB 慣用：FE statusOptions 只 4 項（value active / under-development / disposition / other），且第一項 label 是 status_operational 但 value 存 active；DB status_state comment 列的是 operational / under-development / under-major-modification / disposition / other（5 種、用 operational）。故 DB 實際存進 active 而非 operational，且 under-major-modification FE 選不到。維護 OSCAL round-trip 時留意此 value 不一致。
3. uid 恆為 null：v2 ssp_system_characteristics 無 OSCAL uuid 欄，_to_dict 硬回 uid: None；前端不可拿此頁 uid 當識別鍵（1:1 對 SSP，用 ssp_uid 即可）。
4. 空 placeholder 的 sensitivity 預設 high：無列時 GET 回 security_sensitivity_level='high'（非 DB 值，是 placeholder 常數）；FE 載入亦有 || 'high' fallback——兩層預設一致，改預設要同步兩處。
5. props 保留鍵非 DB 欄：target-type / owner-uid 存在 props jsonb、非獨立欄位；改鍵名要同步 mapper _PROP_TARGET_TYPE / _PROP_OWNER_UID（module_frame_system_characteristic_service.py:35-36）。
6. SSP 寫入無 phase guard（BE）：唯讀由 FE readonly prop 鎖；凍結後直接打 PUT 仍會改 living SSP——同 SSP 編輯器 §12。

13. 開發與驗證

• 跑起來：起 BE + FE；登入見 .env / 部署文件測試帳號（需該專案 manager）
• 導航：規劃頁 Tab1「系統安全計畫」→ 子 Tab「基本資料」（SspBasicSection）
• 前置資料：需有 living SSP 的專案（AP=planning）；測首次 upsert（空 SSP 進來按儲存自動建列）+ 既有列更新；備幾個 user 測範圍負責人 dropdown
• 相關：其餘 SSP 子區見 參與方 / 元件 / 利用授權 / 資產清冊；範本版同欄位見 module-frame 系統特性；OSCAL system-characteristics 概念見 oscal-knowledge skill