Phase A0.1 Design — SSP system-implementation 結構重整（補丁）

Phase：A0.1（A0 之後補丁，非新 phase 而是 A0 的結構校正） 級別：重型（schema rename + 新建表 + 鉤稽路徑改動） 狀態：design draft，等執行 session 前置：A0 已 ship（commits c4804d7 / a1b80cc / e73b1aa / 60a4a2e / 5d8626e） 依賴本 phase：A1, A2, A3, A4, A5（Track A 全部）+ B2, B5（Track B 內容組裝與 OSCAL 匯出）

A0 完成時用「擴充既有表」方案處理 OSCAL system-implementation 鏡像。事後盤點發現幾個結構問題：

1. 既有表名稱誤導：system_security_plan_system_implementations 看似 main 表但實際是 items 集合（multi-row, implementation_type 區分）
2. 缺 OSCAL system-implementation block 層：OSCAL spec 上是 1:1 block per SSP，DB 沒對應 entity
3. 缺 OSCAL inventory-item.implemented-components[] 關聯：M:N 對應沒實作
4. 鉤稽路徑重疊：A0 加的 information_system_id soft FK 跟既有 system_characteristics 中介機制重複
5. table 命名不一致：oscal schema 內既有 ssp_* 前綴慣例（ssp_docx_parse_jobs / ssp_reference_documents），但新加的還是用舊式 system_security_plan_* 前綴

A0.1 是這些問題的補丁，設計校正而非新功能。

3.1 既有表 rename: system_security_plan_system_implementations → ssp_system_implementation_items

動作：

• Table RENAME
• Sequence RENAME（PG 不會自動跟）
• PK / UNIQUE / FK constraint RENAME
• 6 個 index RENAME（cosmetic，統一 ix_ssp_si_items_* 前綴）

既有 column 不動（含 A0 加的 9 個）：

id, uid, system_security_plan_id (nullable),
name, description, implementation_type, responsible_party,
created_at/updated_at/created_user/updated_user,
scope_type (NOT NULL), scope_id (NOT NULL),
device_id, information_system_id (即將 rename),
title, purpose, status, party_uuid, date_authorized

Column rename：

• information_system_id → system_characteristic_id
  • soft FK 從 compliance.information_systems.id 改鉤 oscal.system_security_plans_system_characteristics.id
  • 既有 140 筆此欄為 null，rename 不影響資料
  • 對應 index 同步改名

Column 新加：

• system_implementation_id INTEGER NOT NULL FK → ssp_system_implementations.id ON DELETE CASCADE
  • backfill：依 (scope_type, scope_id) 對應到新 main row

3.2 新建 oscal.ssp_system_implementations（main, 1:1 per scope）

column                    type          nullable  default               purpose
─────────────────────────────────────────────────────────────────────────────────
id                        SERIAL        NOT NULL  -                     PK
uid                       UUID          NOT NULL  gen_random_uuid()     OSCAL UUID (匯出時排除)
scope_type                varchar(20)   NOT NULL  -                     'ssp' or 'module_frame'
scope_id                  integer       NOT NULL  -                     對應 scope 的 id (soft FK)
remarks                   text          nullable  -                     OSCAL block-level remarks
props_jsonb               jsonb         nullable  -                     OSCAL block-level props
created_at                timestamptz   NOT NULL  NOW()                 audit
updated_at                timestamptz   NOT NULL  NOW()                 audit
created_user              varchar(50)   nullable  -                     audit
updated_user              varchar(50)   nullable  -                     audit
─────────────────────────────────────────────────────────────────────────────────
UNIQUE CONSTRAINT (scope_type, scope_id)         ← 強制 1:1 per scope
INDEX (scope_type, scope_id)

為什麼用 scope_type + scope_id 而非直接 ssp_id：對齊 A0 items 表設計，支援 module_frame scope（範本層也可有 system-implementation 紀錄）。

3.3 新建 oscal.ssp_inventory_item_components（M:N join）

column              type          nullable  purpose
─────────────────────────────────────────────────────────────
id                  SERIAL        NOT NULL  PK
inventory_item_id   integer       NOT NULL  FK → ssp_system_implementation_items.id (type='hardware')
component_id        integer       NOT NULL  FK → ssp_system_implementation_items.id (type IN component family)
description         text          nullable  OSCAL link 補充說明
created_at          timestamptz   NOT NULL  audit
...                                          (省略 audit)
─────────────────────────────────────────────────────────────
UNIQUE CONSTRAINT (inventory_item_id, component_id)
INDEX (inventory_item_id)
INDEX (component_id)
FK both with ON DELETE CASCADE

設計約束：兩個 FK 都指向 items 表，但 implementation_type 不同。application 層需驗證：

• inventory_item_id 指向 row 的 implementation_type = 'hardware'
• component_id 指向 row 的 implementation_type IN ('component', 'system', 'subsystem', 'service', 'software')

DB 層無 CHECK 約束強制此語意（PG 不支援跨 row CHECK），由 SQLAlchemy event listener 或 service 層守。

4.1 既有檔案 rename（語意對齊）

改 __tablename__："system_security_plan_system_implementations" → "ssp_system_implementation_items"

改 column：information_system_id → system_characteristic_id（含 ORM Mapped / Entity attribute / mapper to_model+to_entity / DTO）

加 column：system_implementation_id Mapped[int] + relationship to main

4.2 新建檔案（main 完整 stack）

核心方法：

• find_by_scope(scope_type, scope_id) -> Optional[entity]（拿主檔）
• upsert_by_scope(scope_type, scope_id, **kwargs) -> entity（找不到就建，找到就返回 — caller 寫 items 前的 prerequisite）

4.3 新建檔案（join 完整 stack）

4.4 YAML mapper 更新

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

• _system_implementation_to_dict() 改成從 main 出發 + 讀 items + 三分支：
  • 從 ssp_system_implementations main 拿 block-level (remarks / props)
  • 從 ssp_system_implementation_items 撈 items
  • 依 implementation_type 三分支序列化（A0 Task 9 已有的邏輯）
  • 加 inventory-item.implemented-components 從 join 表填入

4.5 既有 ssp_yaml_mapper / ssp_mapper 父層引用更新

• infra/model/ssp/ssp.py：SSP ORM 的 system_implementations relationship 改指向 main 表
• infra/mapper/ssp/system_security_plan_mapper.py：mapping 父層引用 main
• domain/entity/ssp/ssp_entity.py：SSP entity 內 system_implementation 屬性指 main entity 而非 items list

5.1 既有 caller 改寫

5.2 既有 caller 不動（已 verify）

純應用層擴 enum / 字串值，不需 DDL migration：

新 context_id 都指向 main.id 或 items.id 對應。

7.1 既有 140 筆 hardware items（scope_type='ssp'）

migration 步驟（SQL 內已包）：

1. 不動既有 items 資料
2. 為 distinct (scope_type, scope_id) 建 main row（預期約 128-140 個，看 distinct 數）
3. backfill items.system_implementation_id = main.id（用 scope match）
4. information_system_id rename → system_characteristic_id（既有 140 筆此欄全為 null，rename 安全）

7.2 既有資料是否需要轉 system_characteristic_id？

既有 140 筆 hardware 的 information_system_id 全 null，不需要資料轉換。Column rename 只動 metadata（schema info），資料層完全不變。

未來如有 caller 把 information_system 鉤上來的需求，要走新的 system_characteristic 中介路徑（透過 compliance.project_system_characteristic_mapping）。

8.1 jedi-oscal 既有測試（需要 fix）

• tests/test_ssp_system_implementation_extension.py（A0 32 個測試）
  • import 改新 class 名
  • column rename information_system_id → system_characteristic_id 對應
  • 加新 main / join 的 CRUD 測試

8.2 主 BE 既有測試（需要 fix）

• tests/test_ssp_system_implementation_regression.py（A0 regression）
  • import 改新 class 名
  • 加 main upsert smoke test
• test/test_ssp_versioning_service.py（既有 SSP versioning test）
  • 確認 clone 流程通新表結構

8.3 新增測試

• main 表 CRUD 測試 + UNIQUE constraint 測試
• join 表 CRUD + M:N relationship 測試
• yaml_mapper 三分支序列化 + implemented-components 輸出測試

• SQL migration 在 dev DB 跑通，140 筆 items 全部補 system_implementation_id（shipped: 129 個 distinct scope → 129 main rows, 140 items 全部補 FK）
• jedi-oscal 既有 ORM rename + 新建 main + join 完整 stack 完成（6 commits 762d8fc / cc65e3b / c0fcae9 / d2178c1 / 8e3e58b / 4666091）
• 既有 32 個 jedi-oscal 測試全綠 + 新加 47 個 unit test
• 主 BE 既有 caller (project_device_mapping_service / ssp_versioning_service) 改用新 class 後 regression 測試通（33 BE test passed）

• [⚠️] BE 主程式 smoke boot 通過 — partial：DI / service / DB sanity 4 項都通，但完整 boot 撞到 jedi-issue / python-gitlab + PyGithub 環境問題（非 A0.1 引入，缺 GITLAB_*/GITHUB_TOKEN env vars）。已記為 follow-up。

• 新 main / join 表 CRUD + relationship 測試通（unit test）
• yaml_mapper inventory-item.implemented-components 輸出 OSCAL 結構正確
• A0.1 changelog 完成（docs/changelog/2026-05-19-tweak-ssp-system-impl-restructure.md）
• tracker README A0.1 row 標 shipped + commit hashes

實作過程相對於原 spec / plan 的偏離紀錄。保留作為未來讀者的決策軌跡（不是補救文件，是脈絡保留）。

11.1 _system_implementation_to_dict 簽章設計偏離

Spec / Plan 寫：(main_entity, items_list, join_links) — main_entity 為第一 positional 參數。

實際實作：(items_list, main_entity=None, join_links=None) — items_list 維持第一 positional，main/join_links 為可選 kwarg。

為何偏離：既有 7 個 yaml_mapper 測試（A0 ship 時建的）均以 positional 方式 _system_implementation_to_dict(sis_list) 呼叫此 method。若照 spec 把 main_entity 放第一位，這 7 個 test 會把 sis_list 當 main_entity，全部破。改 backward-compatible 簽章是 minimal-disruption 工程決策，行為層面等價，spec/code reviewer 雙確認 ACCEPTABLE。

11.2 _clone_system_implementations 用 old_ssp.system_implementations 替代 old_main.items

Plan 虛擬碼：透過 main 的 items relationship for old_item in old_main.items: ...。

實際實作：用 SSP 既有 relationship for old_impl in (old_ssp.system_implementations or []):。

為何偏離：SSP ORM 已有指向 items list 的 relationship（A0 既有），複用無需新增 main → items 反向 relationship。Spec reviewer 確認語義等價。

11.3 Items 9 個 extension 欄位 clone

A0 既有 clone 只複製 6 個欄位（name / description / implementation_type / responsible_party + scope_type / scope_id）。A0.1 補齊：device_id / system_characteristic_id / title / purpose / status / party_uuid / date_authorized 共 7 個 — 對齊 A0 既有 ORM 但 clone 流程未補的欄位。scope_type / scope_id 因 caller 直接賦值不走 getattr，commit message 寫「9 個」是 A0 全部 OSCAL extension 欄位的總數，實質 clone 流程補了所有缺漏。

11.4 BE 全套 boot smoke 改為 partial

Plan 寫：nohup poetry run python main_app.py 後驗證 schema mismatch / IntegrityError 無。

實際執行：BE 啟動撞到 jedi-issue 套件初始化（python-gitlab api_version=None AssertionError + PyGithub Auth.Token(None) AssertionError）。這是環境配置問題（缺 GITLAB_URL / GITLAB_API_VERSION / GITLAB_PRIVATE_TOKEN / GITHUB_TOKEN env vars），與 A0.1 改動無關。改做 partial smoke：

• DI OscalContainer / AssociationsContainer 可實例化
• 6 個新 providers 全部 callable（item / main / inventory_item_component 各自的 repo + domain service）
• SspVersioningService 可建構
• ProjectDeviceMappingService constructor 含兩個新 kwarg
• DB 三表狀態正確：129 main + 140 items（FK 全補）+ 0 join

完整 boot smoke 留給已配置 GitLab / GitHub env 的環境執行（user 自行 or 後續 phase 補）。

11.5 Minor follow-ups（不阻 ship，code reviewer 建議）