Phase A0 Design — 既有 system_security_plan_system_implementations 表擴充

Phase：A0（基礎建設） 級別：重型 狀態：design draft，等 raymond review brainstorm 來源：requirement-understanding.md §2（10 個問題已 resolved） 依賴：無（Phase 2 的最前置） 後續依賴本 phase：A1, A2, A3, A4, A5（Track A 全部）+ B2, B5（Track B 內容組裝與 OSCAL 匯出）

擴充既有 oscal.system_security_plan_system_implementations 表，使其能同時承載：

1. 「合規資源庫」與「專案 SSP 版本」兩種範圍（既有只服 SSP）
2. 與 tenant 層的 public.devices / compliance.information_systems 鉤稽（既有只存純文字 name）
3. OSCAL leveraged-authorization 的特有欄位（既有無 party_uuid / date_authorized）
4. OSCAL component 的常用 optional 欄位（title / purpose / status）

完成後，Phase 2 後續所有匯入流程（A1~A5）寫入此表、所有匯出流程（B2 / B5）讀取此表，無需新建任何 OSCAL mirror 表。

2.1 Schema

oscal.system_security_plan_system_implementations
├── id (PK)
├── uid (UUID, unique, default uuid4)
├── system_security_plan_id (FK → oscal.system_security_plans.id, NOT NULL, ON DELETE CASCADE)
├── name (varchar(255), NOT NULL)
├── description (text)
├── implementation_type (varchar(50), NOT NULL)
├── responsible_party (varchar(100))
└── audit: created_at / updated_at / created_user / updated_user

2.2 既有 enum

SystemImplementationType（jedi-oscal common/enum/code_enum.py）：

class SystemImplementationType(StrEnum):
    SYSTEM = "system"
    SUBSYSTEM = "subsystem"
    SERVICE = "service"
    COMPONENT = "component"
    HARDWARE = "hardware"
    SOFTWARE = "software"

2.3 既有資料

DB 內 140 筆，全部 implementation_type='hardware'（= devices 鏡像，由 project_device_mapping_service 寫入）。

2.4 既有 caller

2.5 既有 jedi-oscal stack

3.1 ADD COLUMN（共 9 個新欄位）

3.2 既有欄位變更

3.3 enum 擴充

SystemImplementationType 加 1 個值：

LEVERAGED_AUTHORIZATION = "leveraged-authorization"

不加 inventory-item：既有 hardware 已 cover device 鏡像用途，加 inventory-item 會兩個 enum 值意義重疊。OSCAL 匯出時由 mapper 把 hardware 翻譯成 OSCAL inventory-item 結構，不動 DB enum。

3.4 新增 Index

3.5 Table COMMENT

COMMENT ON TABLE oscal.system_security_plan_system_implementations IS
'OSCAL system-implementation 多型鏡像表（v4 擴充：scope_type 區分 ssp / module_frame）。
 implementation_type 區分 hardware (device 鏡像) / component (information_system 鏡像) /
 leveraged-authorization / system / subsystem / service / software。';

3.6 GRANT 權限

GRANT SELECT, INSERT, UPDATE, DELETE ON oscal.system_security_plan_system_implementations TO cm_app;
-- sequence 既有，不需要重複 GRANT

4.1 既有 140 筆 hardware 資料

UPDATE oscal.system_security_plan_system_implementations
   SET scope_type = 'ssp',
       scope_id = system_security_plan_id
 WHERE scope_type IS NULL;  -- ADD COLUMN 後既有 row 此欄為 null

-- 驗證
SELECT COUNT(*) FROM oscal.system_security_plan_system_implementations
 WHERE scope_type = 'ssp' AND scope_id IS NOT NULL;
-- 預期 140

4.2 不動的部分

• implementation_type 維持 hardware（不轉 inventory-item）
• responsible_party 既有純文字保留
• 既有 system_security_plan_id 既有資料維持指向原 SSP（CASCADE FK 保留）

dev 期間走 poetry path dependency（主專案 pyproject.toml 改 path 指本地 source），Phase 2 完成後一次性 bump 版本推 Nexus。

5.1 ORM model 擴充

jedi_oscal/infra/model/ssp/ssp_system_implementation.py：

加 9 個 Mapped[] column 對應 §3.1；system_security_plan_id 改 nullable=True；補 3 個 Index。

5.2 Entity / Query Entity 擴充

jedi_oscal/domain/entity/ssp/：

• SspSystemImplementationEntity 加 9 個 attribute
• SspSystemImplementationQueryEntity 加 scope_type / scope_id / device_id / information_system_id 篩選欄位

5.3 Repository 擴充

jedi_oscal/infra/repository/ssp/ssp_system_implementation_repo_impl.py：

• 既有 CRUD 維持
• 補 query method：list_by_scope(scope_type, scope_id) / find_by_device_id(device_id) / find_by_information_system_id(info_system_id)

5.4 Mapper 擴充

jedi_oscal/infra/mapper/ssp/system_implementation_mapper.py：

entity ↔︎ model 對應 9 個新欄位的雙向 mapping

5.5 OSCAL YAML Mapper 擴充

jedi_oscal/infra/mapper/ssp/ssp_yaml_mapper.py：

依 implementation_type 分支序列化：

• hardware → OSCAL inventory-items[*]（含 uuid / description / props（補 device_id soft ref））
• component / software / service 等 → OSCAL components[*]（含 type / title / description / purpose / status）
• leveraged-authorization → OSCAL leveraged-authorizations[*]（含 title / party-uuid / date-authorized）

5.6 DTO 擴充

jedi_oscal/app/dto/ssp/ssp_system_implementation_dto.py：加 9 個欄位。

5.7 Enum 擴充

jedi_oscal/common/enum/code_enum.py：SystemImplementationType 加 LEVERAGED_AUTHORIZATION = "leveraged-authorization"。

A0 不改變既有 caller 的寫入行為（既有 caller 不寫新增的 9 欄，全部 nullable 預設 null）。但要驗證：

6.1 project_device_mapping_service

• 既有寫入 hardware row 流程不變
• 驗證新欄位 nullable 不影響 insert

6.2 ssp_versioning_service

• 既有 SSP 版本複製流程不變
• 驗證 system_security_plan_id 改 nullable 後不影響既有複製邏輯

6.3 既有 query

grep 全 repo 確認沒有 hard-code 假設 system_security_plan_id 為 NOT NULL 的 query。

實作開工前需 verify：

• jedi_oscal/infra/model/ssp/ssp_system_implementation.py 仍存在且結構與 §2.1 相符
• jedi_oscal/common/enum/code_enum.py 內 SystemImplementationType 仍有 6 個值
• app/associations/service/project_device_mapping_service.py + app/oscal/service/ssp_versioning_service.py 仍是既有 caller
• DB 140 筆 hardware 數量未變
• 主專案 pyproject.toml 內 jedi-oscal 版本 pin 確認，準備改 path dependency

A0 視為 shipped 的條件：

1. ✅ Migration SQL 在 dev DB 跑通，140 筆既有資料 scope_type='ssp' 補全
2. ✅ jedi-oscal 8 個層（ORM / entity / query_entity / repo interface + impl / mapper / yaml_mapper / DTO / enum）擴充完成
3. ✅ 新欄位 CRUD 單元測試 + scope query 測試通過
4. ✅ Mapper round-trip 測試通過
5. ✅ OSCAL YAML 三分支 serialize 測試通過
6. ✅ 既有 caller (project_device_mapping_service + ssp_versioning_service) integration 測試通過
7. ✅ 主專案 dev 啟動 + smoke test 通過（驗證 nullable 化既有欄位後 boot 不破）
8. ✅ Changelog 完成（type=tweak，因為是基礎建設不直接讓 user 能做新事情）