SSP 匯入匯出 Phase 2 — 需求理解整理版

狀態：Phase 0+ — 需求理解 v5（A0.1 結構校正後） 建立日期：2026-05-18 最後更新：2026-05-19（v5：A0 後 review 發現 main 表缺、命名不一致、鉤稽雙路徑 → A0.1 結構重整補丁） 版本歷程：

• v1：草稿整理 + 11 個待釐清項
• v2：Raymond 第一輪回覆 → Q1~Q11 resolved + 補充 OSCAL 匯出 + Excel 樣板設計
• v3：誤判 — 主張建三張新 OSCAL mirror 表 + 廢既有通用表
• v4：校正 — 既有表本就是 OSCAL system-implementation 多型鏡像，改走「擴充既有表」方案（→ A0 shipped）
• v5：A0.1 結構重整 — main 表 / items rename / join 表 / 鉤稽路徑統一（詳見 design-A0.1.md + docs/analysis/2026-05-19-ssp-system-impl-restructure-rationale.md） 撰寫人：Claude（依 requirement.md 草稿整理） 下一步：A0.1 開工 → A1 / B1 平行

---

A0 shipped 後 review 發現幾個結構問題：

1. 既有 system_security_plan_system_implementations 表 = items 不是 main，缺 1:1 main 層
2. A0 加的 information_system_id 跟既有 system_characteristics 中介路徑重疊
3. OSCAL system-implementation 是 block（無 UUID），DB 仍應有 main 表（為 PG 規範 + block-level metadata anchor）
4. 表名 ssp_* 前綴慣例不一致

v5 補丁（A0.1）：

詳細 A0.1 規格見：

• docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A0.1.md
• docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A0.1.md
• docs/analysis/2026-05-19-ssp-system-impl-restructure-rationale.md

---

這份不是正式 spec，是 Claude 把 requirement.md 草稿讀完之後，把「我理解你想做的事情」用比較結構化的方式寫回來，方便：

1. raymond 一眼看出有沒有理解錯
2. 開始切階段、寫 design 之前先對齊認知
3. 列出我看到「草稿沒寫清楚」或「需要你決策」的項目

確認過後再進入 brainstorm + design.md + implementation-plan.md + test-plan.md。

---

1.1 「合規資源庫」是什麼

module_frame 是專案的範本層 — 顧問先把客戶現有的安全控制現況、政策程序書、組織單位、參與人員、設備、系統等資訊整理進「合規資源庫」，之後客戶建專案時，這些資訊會被當成預設值帶入該專案的 SSP，省去重複輸入，也作為 OSCAL 匯出的資料來源。

1.2 目前匯入匯出能力的限制

1.3 真正的痛點

• 顧問端：訪談時想用 Excel 收資料（客戶熟悉 Excel），但目前 Excel 只能收一小部分，其他還是要靠 docx 或手動進系統建。
• 客戶端：想拿到一份完整可讀的 SSP 文件（docx / pdf）作為交付物，目前系統只能匯 OSCAL 結構化資料。
• 資料一致性：Excel 匯入後沒有跟「設備 / 單位 / 人員 / 系統」做鉤稽，匯進來的是孤立字串，沒辦法被後續流程引用。

1.4 本期目標（一句話）

讓**「合規資源庫」的所有主要資料領域**都能透過 Excel 雙向同步（匯入 / 匯出），並讓「合規資源庫」與「專案 SSP 版本」都能匯出成可讀的 SSP 文件（docx / pdf / odt）+ OSCAL 結構化格式（JSON / XML / YAML）。

1.5 Raymond 第一輪回覆補充（2026-05-18）

補充 1：SSP 匯出加 OSCAL 格式

除了 docx / pdf / odt 三種可讀格式，匯出也要提供 OSCAL 結構化格式（JSON / XML / YAML）。這部分技術上：

• jedi-oscal 既有 yaml mapper（infra/mapper/ssp/ssp_yaml_mapper.py），可作為 base
• 系統目前沒看到 SSP 對外的 OSCAL export endpoint（只有 OSCAL import），所以本期屬於新增功能
• JSON / XML / YAML 三種是 OSCAL 標準格式，互轉成本低，做一個其他兩個幾乎免費

補充 2：Excel 匯入樣板的設計規範

樣板必須：

1. 分 sheet 做不同事情 — 每個資料領域一個 sheet（metadata / parties-organizations / parties-persons / devices / information-systems / leveraged-services / controls / AOs / reference-documents），不擠在同一個 sheet
2. 欄位顏色提示 — 必填欄位用底色標示（沿用既有 template 黃底慣例），選填用無底色或淺色
3. 系統有的資料 → Excel 下拉選單 — 對 Excel data validation 規格做下拉選項，使用者選的時候有 dropdown，例如：
   • system_owner → 下拉選 tenant 內既有 user（顯示 nickname）
   • org_unit → 下拉選既有組織單位
   • device → 下拉選既有 public.devices
   • information_system → 下拉選既有 compliance.information_systems
   • impl_status / sensitivity_level / deployment_model 等 enum → 下拉選 enum 值
4. 原本系統表單就是下拉的，Excel 也要下拉 — 對齊 UI 表單行為，避免使用者用 Excel 填了系統不接受的字串

💡 設計考量：Excel 下拉選單在資料量多時會卡（如 user 上千人），需要評估是用「name list 直接列舉」還是「named range + 工作表隱藏」處理。實作階段再決定。

---

✅ 架構決策（v4 校正）：擴充既有 system_security_plan_system_implementations 表，不新建三張表。既有表已是「OSCAL system-implementation 多型鏡像」的設計用意，implementation_type 已用於區分 system / subsystem / service / component / hardware / software（用 enum SystemImplementationType），且 140 筆 hardware 資料 + jedi-oscal 完整 stack 已在運作。擴充比新建更務實。

2.1 既有表現況盤點

Schema（既有）：

程式碼 stack（既有，jedi-oscal）：

• ORM：jedi_oscal/infra/model/ssp/ssp_system_implementation.py
• Entity / Query Entity：jedi_oscal/domain/entity/ssp/
• Repository interface + impl：jedi_oscal/domain/repository/ssp/system_implementation_repo.py + jedi_oscal/infra/repository/ssp/
• Mapper：jedi_oscal/infra/mapper/ssp/system_implementation_mapper.py
• DTO：jedi_oscal/app/dto/ssp/ssp_system_implementation_dto.py
• Enum：jedi_oscal/common/enum/code_enum.py 內的 SystemImplementationType
• YAML mapper：jedi_oscal/infra/mapper/ssp/ssp_yaml_mapper.py（OSCAL 序列化已部分接通）

Caller（主專案）：

• app/associations/service/project_device_mapping_service.py（專案 device mapping）
• app/oscal/service/ssp_versioning_service.py（SSP 版本服務）

資料量：140 筆 hardware（= 已用作 devices 的 OSCAL 鏡像）。

2.2 擴充內容（A0 主體工作）

欄位擴充（ADD COLUMN）

既有欄位調整

enum 擴充（v4 校正：只加 1 個值）

SystemImplementationType (jedi-oscal common/enum/code_enum.py) 只加一個新值：

• LEVERAGED_AUTHORIZATION = "leveraged-authorization"（OSCAL leveraged services 用）

既有 enum 值的延用：

為什麼不加 inventory-item：

OSCAL 字面術語上 hardware 是 component.type 子分類，inventory-item 才是「具體 deployed asset」。但既有 code 已用 hardware 涵蓋同一概念、140 筆都是這樣，加 inventory-item 會讓兩個 enum 值意義重疊（dev 心智負擔 + caller 寫入分流）。OSCAL 匯出時若需要 inventory-item 結構，由 mapper 層把 hardware 翻譯成 OSCAL inventory-item JSON 即可，不必動 DB。

既有 140 筆 hardware 資料：

• 不轉換 implementation_type（維持 hardware）
• 只 migration 補 scope_type='ssp' + scope_id=system_security_plan_id（讓既有資料能被新 scope query 撈到）

Index 補充

2.3 「不做」清單（v4 校正）

2.4 表名語意爭議

問題：表名是 system_security_plan_system_implementations（含 system_security_plan 前綴），但新增 scope_type='module_frame' 後也會裝 module_frame 資料，名稱語意稍偏。

處理方向（A0 brainstorm 待決）：

• 方案 1：表 rename 為 oscal_system_implementations（更通用），既有 ORM / repo 同步改名
• 方案 2：保留表名，加 docstring + table COMMENT 解釋
• 方案 3：保留表名，建 view oscal.system_implementations 對齊新名稱供新功能讀

此項列入剩餘 brainstorm 題目。

---

下面是「Excel 匯入」要新增的範圍，依資料領域逐項展開：

3.1 基本資料（Metadata）

內容（依 docx parser v2 已建立的欄位推估）：

• 系統名稱、簡稱、版本
• 系統概述、邊界、敏感度分類（FIPS 199）
• 授權邊界（Authorization Boundary）
• 網路架構、資料流概述

匯入挑戰：

• 純文字長段落，Excel 用一個 cell 還是分多個欄位？建議分多欄但長文字 cell 不限制長度。
• 部分欄位是 enum（如 FIPS 199 機敏等級），匯入時要 validate。

3.2 設備 / 單位 / 參與人員 / 系統 — 要鉤稽

這四類有共同特性：Excel 內填的是「字串名稱」，匯入時要對到系統內既有的實體。

鉤稽的兩種狀況

各領域細節

寫入路徑（confirm 階段 BE 行為）：

            user 在預覽頁 confirm
                    │
                    ▼
       ┌────────────────────────┐
       │  鉤稽結果分流           │
       └────────────────────────┘
          │           │            │
   matched      inline 新建    純文字保留
          │           │            │
          ▼           ▼            ▼
   只寫鏡像表   先寫 tenant   只寫鏡像表
  (含 soft FK)  層表 → 再寫   (soft FK
                鏡像表        = null)

註：「鏡像表」= system_security_plan_system_implementations，依 implementation_type 區分 inventory-item / component / leveraged-authorization。

✅ Q3 已 resolved：docx parser 本期不擴充到 devices / information_systems，列入「最後統整優化清單」 — 等 Phase 2 完工後再一起處理 docx parser 對齊。同樣的 OSCAL mirror 表新建後，docx parser 之後要對齊寫入這幾張表。

✅ Q8 已 resolved：鉤不到時除了「選現有 / 純文字保留」，也支援直接在預覽頁面新建 — 例如 user 在預覽頁看到 unmatched device，可直接 inline 輸入 ip/os 等欄位，confirm 時先寫 public.devices 再寫 oscal_inventory_items（soft FK 串起來）。

3.3 控制項 / AO 現況說明

已有功能，但要對齊 docx 匯入體驗：

• 既有 Excel 匯入是「同樣 module_frame、同樣 control_id」做精確 join 然後寫入；
• 草稿希望改成「用編號或名稱模糊比對」的方式，並讓 user 在預覽介面檢查匹配結果。

意涵：這代表新 Excel 不再綁定某個 module_frame，使用者可以拿任意 Excel（甚至從別的 framework 來的）匯進來，由系統幫忙比對。這跟既有「先匯出某 module_frame 的樣板 → 填 → 匯回同一個」的 round-trip 模式有差異，要釐清是否兩種模式並存。

3.4 程序書（Reference Documents）

草稿沒明說，但既有 Excel template 有 參考程序書 欄位，docx parser v2 也有 SSP document pool 模式。新版要：

• 程序書名稱填在 control / AO 列上；
• 匯入時把程序書建到 pool（如果不存在），並建 control/AO ↔︎ document 的 mapping；
• 同 docx 模式做 name-match 鉤稽。

---

草稿明確說「匯入模式可以參考 docx 匯入模式」。把 docx 匯入流程（v2 已上線）抓出來，對應到 Excel：

4.1 左右比對的可行性

✅ Q6 已 resolved：本期不做左右比對。Excel 不像 docx 容易渲染成 PDF，純單欄式預覽 + 編輯介面即可（方案 C）。

4.2 Excel 樣板結構（依 §1.5 補充 2）

按資料領域分多 sheet，欄位顏色 + 下拉選單規格：

💡 已有資料下拉如果量大（如 user 上千人），實作階段用「named range + 隱藏 lookup sheet」處理。

---

5.1 範圍（含 OSCAL 結構化格式）

✅ Q5 已 resolved：「合規資源庫」與「專案 SSP 版本」兩邊都要提供匯出。

匯出來源 × 匯出格式組合矩陣：

兩個來源的差異：合規資源庫匯出的是「範本層」資料（顧問建好的 default）；專案 SSP 版本匯出的是「實際填寫的現況」（含每個 AP round 的差異）。

5.2 多格式支援的真實成本

✅ Q4 已 resolved：odt 本期要做。

5.3 範本（Template）

✅ Q10 已 resolved：先用 CMMC 通用樣板，後續如果有法規資料不同的需求再抽象化。

• 從 ASIA-CMMC-SSP-DRAFT-with-user-info-202604.docx 拆出章節結構、版面樣式、placeholder
• 含封面頁、版本更新紀錄表、Word 自動目錄（依 CLAUDE.md DOCX 規範）
• 章節結構與 OSCAL system-security-plan 對應，方便未來轉 OSCAL JSON / XML / YAML

5.4 匯出資料 API vs UI

• API：
  • 合規資源庫：POST /module-frame/<uid>/export?format=docx|pdf|odt|json|xml|yaml
  • 專案 SSP：POST /projects/<project_id>/ssp/<version_id>/export?format=...
• UI：
  • 合規資源庫頁面加「匯出 SSP」按鈕 + 格式選擇 dropdown
  • 專案規劃頁面同模式加按鈕

---

草稿說「不要全照我的切，要的話再分更細」。下面是我的版本，跟草稿的差異會標出。

6.1 切分原則

1. 可獨立 ship：每階段完成後系統都還能正常用，不依賴後續階段
2. 可平行：匯入 / 匯出 兩條主線可平行進行（不同人 / 不同 session）
3. 小批次驗收：每階段 1~2 週可完成，避免長尾
4. 基礎先行：共用的 parser 架構 / 鉤稽框架先做

6.2 階段規劃

Phase A0：基礎設施 — 擴充既有 system_security_plan_system_implementations 表（前置必做 ✅ shipped (BE c4804d7 + jedi-oscal afe7035→dbb3d7c, 2026-05-18)）

A0 包含項目：

• SQL migration（ALTER TABLE 加 9 個 column + 改 system_security_plan_id nullable + 加 3 個 index）
• 既有 140 筆 hardware 資料 migration（只補 scope_type='ssp' + scope_id=system_security_plan_id；不轉 implementation_type，維持 hardware）
• jedi-oscal 套件擴充（dev 期走 poetry path dependency，不立即發版）：
  • ORM model：ssp_system_implementation.py
  • Entity / Query Entity：jedi_oscal/domain/entity/ssp/
  • Repository interface + impl
  • Mapper：system_implementation_mapper.py + ssp_yaml_mapper.py（OSCAL 序列化）
  • DTO：ssp_system_implementation_dto.py
  • Enum：SystemImplementationType 加新值
• 既有 caller 驗證：project_device_mapping_service + ssp_versioning_service 確保不破壞
• 補單元測試（新欄位 CRUD + scope 篩選 + soft FK 整合）

A0 是 Track A 與 Track B OSCAL 線（B5）共同前置 — 任何 Excel 匯入 / OSCAL 匯出邏輯都要等這層基礎建好才能接。

Track A：Excel 匯入（5 階段）

跟草稿的差異：草稿把「Excel 匯入功能」當一個階段，我拆成 4 階段（A2~A5）+ A0 基礎建設，因為鉤稽邏輯是高風險區域、需要分批驗證；A3 把 docx 既有 matcher 抽出共用，避免兩套 parser 行為不一致。

Track B：SSP 匯出（6 階段，新增 OSCAL 線）

跟草稿的差異：草稿是 3 階段（樣板 / API / UI），我拆成 6 階段：

1. 樣板拆成 B1（generator 骨架）+ B2（data model 組裝），技術重點不同
2. 多了 B5 OSCAL 結構化匯出線（raymond 第一輪回覆補充）
3. ODT 不能等 docx 順手就拿到，獨立做 B4
4. UI 集中在最後 B6（含格式 dropdown）

6.3 階段相依關係

              ┌── A1 ── A2 ── A3 ── A4 ── A5  (Excel 匯入完成)
              │
A0 ───────────┤
(OSCAL mirror │
 表基礎)      │
              │   B1 ── B2 ──┬── B3 ── B4 ──┐
              └──────────────┤              ├── B6 (SSP 匯出完成)
                             └── B5 ────────┘

關鍵 dependency：

• A0 是 Track A 與 Track B（B2 起算）共同前置 — 一定要先做
• A0 完成後，A1 / B1 可平行起手
• A 跟 B 主線可平行；B 內部 B3 / B4 / B5 可平行（都依賴 B2 data model）

6.4 各階段的「最小可驗收」

• A0 ship：既有表擴充 migration 跑通、jedi-oscal 擴充欄位 ORM + repository CRUD 測試通過、既有 caller (project_device_mapping_service + ssp_versioning_service) regression 測試通過、140 筆既有資料 scope_type='ssp' migration 完成
• A1 ship：可下載空白樣板 + 已填樣板（兩個檔案，含必填顏色 + 下拉選單）
• A2 ship：API 可解析 Excel 回傳 JSONB，postman 可測
• A3 ship：解析結果含 matched / unmatched parties / org-units 標記，docx 路徑同時切換到共用 matcher 行為不變
• A4 ship：解析結果擴充含 devices / information_systems / leveraged / controls / AOs match 標記，confirm 寫入 OSCAL mirror 表
• A5 ship：完整 UI flow，含 inline 新建 device / information_system / party 能力（同步寫 tenant 表 + OSCAL mirror 表）
• B1 ship：可產出空殼 docx（封面 / 目錄 / 章節骨架，無實際資料）
• B2 ship：可從 module_frame 與 專案 SSP 版本兩種來源產出含實際資料的 docx
• B3 ship：兩支 export endpoint 上線（docx）
• B4 ship：pdf + odt 兩格式接上
• B5 ship：OSCAL JSON / XML / YAML 三格式接上（讀 A0 三張新表序列化）
• B6 ship：UI 按鈕 + 格式下拉，6 種格式都可下載

---

7.1 範圍類

7.2 體驗類

7.3 範本類

7.4 衍生新議題（v2+v3+v4 補充）

---

---

• ❌ docx parser 擴充到 devices / information_systems（Q3 決議 → 列入「最後統整優化清單」，Phase 2 完工後處理）
• ❌ Excel / docx 雙向同步（雙向同步是另一個議題）
• ❌ 跨 module_frame 的 bulk import / export（一次只處理一個 MF）
• ❌ 既有舊版 Excel 匯入功能的下線（Q11 決議：保留並移到批次維護「現況說明」下）
• ❌ 跨 AP round 合併匯出（N4：預設只匯當前最新版本，跨 round 比較列 follow-up）

9.1「最後統整優化清單」（Phase 2 完工後處理）

---

raymond 確認這份理解版本後，按 docs/claude/feature-development-workflow.md 進入：

1. Phase 1 — Brainstorm：針對 Q1~Q11 待釐清項目逐一收斂
2. Phase 2 — 歸檔到 features/：把這份搬到 docs/features/FR-011.2-2605-ssp-import-export-phase2/raw-requirement.md
3. Phase 3 — design.md：依切分後的 Track A / B 分別寫 SDD（或合一份大的）
4. Phase 4 — implementation-plan.md + test-plan.md：交給 feature-test-planner agent
5. Phase 5 — 實作：依階段 ship

---