SSP 匯入匯出 Phase 2

跨多 phase task arc，含 BE / FE / jedi-oscal / test 多 repo 起始日期：2026-05-18 主要驅動需求：raymond 狀態：A0 brainstorm 收斂完成，準備寫 A0 design

讓「合規資源庫」與「專案 SSP 版本」雙向支援：

• Excel 匯入：含 metadata / 單位 / 人員 / 設備 / 資訊系統 / leveraged / 控制項 / AO / 程序書 9 大資料領域
• SSP 匯出：docx / pdf / odt + OSCAL JSON / XML / YAML 共 6 種格式

詳細需求：

• 原始需求（raymond 草稿）：raw-requirement.md
• 完整需求理解（含全 phase scope）：requirement-understanding.md

---

⚠️ 規範：每完成一階段請更新此表的狀態欄與對應連結欄；ship 後加 commit hash

Track A：Excel 匯入

Track B：SSP 匯出

Track C：SSP 在專案內直接編輯（Phase 2 延伸補強）

Track A + B 測試後發現的架構問題；同 branch 繼續，獨立 tracker 在 docs/features/FR-011.3-2605-ssp-edit-in-project/README.md

完整分析：ssp-edit-in-project/analysis.md

---

重型 phase 預判：A0 / A3 / A4 / B5 共 4 個 — 才需要單獨 brainstorm 收斂。

---

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

• A0 是 Track A + Track B（B2 起算）共同前置，必須最先完成
• A0 完成後，A1 / B1 可平行起手
• B 內部 B3 / B4 / B5 皆依賴 B2，三者完成後接 B6 UI

---

不新建 OSCAL mirror 三表（v3 誤判），改擴充既有 system_security_plan_system_implementations 表：

• 既有表已是「OSCAL system-implementation 多型鏡像」設計用意，implementation_type enum 已支援多型
• 既有 140 筆 hardware 資料 + jedi-oscal 完整 stack（ORM / repo / mapper / DTO / enum）已運作
• 既有 caller：project_device_mapping_service + ssp_versioning_service 正在寫入
• 擴充比新建務實 — 不破壞既有 caller、不做大規模 migration

詳見 requirement-understanding.md §2。

---

---

1. 此 tracker 為單一事實來源 — 任何 session 開工前先讀這份
2. 每 phase ship 後三件事：
   • 更新本表狀態欄 + commit hash + changelog 連結
   • 寫 changelog（docs/changelog/）依 CLAUDE.md 規範
   • 對應 requirement-understanding §6 階段表加 ✅ shipped (commit, date) 標記
3. 重型 phase 開工前必先 brainstorm（A0 / A3 / A4 / B5）
4. memory 已記錄此 tracker 位置，新 session 自動載入

---

2026-05-18 — A0 shipped ✅

• BE migration: c4804d7
• jedi-oscal stack: 7 commits (afe7035 → dbb3d7c)
• Caller fix: a1b80cc
• Regression test: e73b1aa
• Tracker docs: 60a4a2e
• Changelog: docs/changelog/2026-05-18-tweak-ssp-system-impl-extension.md
• Analysis: docs/analysis/2026-05-18-ssp-system-impl-extend-vs-new-tables.md
• Handoff summary: docs/conversation-history/2026-05-18/ssp-import-export-phase2/SUMMARY.md

2026-05-19 — A0.1 shipped ✅

• BE Task 7 (caller + DI): eb9fa7e
• jedi-oscal 6 commits: 762d8fc → cc65e3b → c0fcae9 → d2178c1 → 8e3e58b → 4666091
• SQL migration（已執行於 dev DB）: scripts/sql/2026-05-19-ssp-system-implementation-restructure.sql
• Design: docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A0.1.md（含 §11 reconciliation）
• Plan: docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A0.1.md
• Analysis (v4 → v5 校正): docs/analysis/2026-05-19-ssp-system-impl-restructure-rationale.md
• Changelog: docs/changelog/2026-05-19-tweak-ssp-system-impl-restructure.md
• Handoff summary: docs/conversation-history/2026-05-19/ssp-import-export-phase2-A0.1/SUMMARY.md

A0.1 已 ship 變動：

• 既有 system_security_plan_system_implementations rename → ssp_system_implementation_items
• 新建 ssp_system_implementations（main, 1:1 per scope, UNIQUE on scope）
• 新建 ssp_inventory_item_components（M:N join, UNIQUE on inventory_item+component）
• Column rename information_system_id → system_characteristic_id（鉤稽路徑統一走 SSP 內 characteristic 中介）
• Items 加 system_implementation_id NOT NULL FK 指向 main + relationship
• jedi-oscal items stack 全 rename Ssp*Item* + 新建 main / join 完整 DDD stack（共 24 個檔）
• yaml_mapper 從 main 出發 + inventory-item.implemented-components[] 從 join 填入
• 主 BE 兩個 caller (project_device_mapping_service / ssp_versioning_service) 改寫支援 main upsert flow
• 累計 ~126 個 unit test 全綠（包含 6 個新加的 yaml_mapper / main / join / FK / upsert test）

已知 follow-up（不阻 A0.1 ship）：

• jedi-oscal 套件 Nexus 發版（Phase 2 整體完工一次性 bump）
• 主 BE jedi-issue / python-gitlab + PyGithub 啟動環境問題（與 A0.1 無關，缺 GITLAB_*/GITHUB_PRIVATE_TOKEN env vars）
• 3 個 code review 建議的 robustness improvement（main audit trail / orphan main cleanup / yaml component-uuid 排序穩定性）
• 10 筆 hardware items device_id 無法 backfill（item.name 對不上當前 device — 可能 device 已刪 / 改名，需業務判斷）

A0.1 e2e 驗證 follow-up（同日 ship）：

• 6deacef fix(associations): ProjectDeviceMappingService 寫 SSP item 補填 device_id soft FK + backfill SQL 對 135 筆既有資料補回（10 筆 unmatchable 保留 NULL）

下一步：A1（Excel 樣板）或 B1（Docx 樣板）— 兩條可平行。

---

2026-05-19 — A1 BE partial shipped ⏳（5/7 task）

• 8 commits 全在 feature/ssp-import-export-phase2 branch：
  • b18db55 docs(ssp-import-export-phase2): A1 phase docs — design + implementation plan
  • f59c4ff docs(ssp-import-export-phase2): A1 T0 verify 結果回填 design.md (4 處)
  • d9d54c2 feat(ssp-import-template): A1 T1 skeleton — route + app service + DI 接通
  • f68525f feat(ssp-import-template): A1 T2 generator base — sheet defs + styles + lookup + DV helpers
  • ffd5d63 feat(ssp-import-template): A1 T3 blank mode — generator 主邏輯 + lookup wiring + 30 tests
  • f14a942 docs(ssp-import-export-phase2): A1 partial summary — T0-T3 收口 + 換 session 交接
  • c3de9fa feat(ssp-import-template): A1 T4 filled mode 非控制項 sheet — 6 領域預填 + DI + 12 tests
  • 419907d feat(ssp-import-template): A1 T5 07_控制項與AO sheet — profile-scoped 父子 row + MF defaults 預填 + 6 tests
• Design: docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A1.md（含 §14 SemVer SOP）
• Plan: docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A1.md
• Changelog: docs/changelog/2026-05-19-feat-mf-ssp-import-template-download.md
• Handoff summary: docs/conversation-history/2026-05-19/ssp-import-export-phase2-A1/SUMMARY.md（T0-T3）— T4/T5/T7 handoff 待補
• TEMPLATE_VERSION = v1.0.0（A2 parser 讀此版本作為相容性 anchor）

A1 已 ship 範圍（T0-T6 完成 + 3 輪 UX polish）：

BE：

• GET /api/1.0/module-frame/<uid>/ssp-import-template?mode=blank|filled&locale=...（MF-scoped）
• GET /api/1.0/ssp-import-template?framework_version_uid=<uid>&mode=blank（T6 新增 FW-version-scoped，supersetcontrols 走 catalog 全 controls，供 S1 訪談前下載）
• 9 sheet 結構（00_說明 + 01~08 資料）+ 6 個隱藏 lookup sheets
• blank mode 純結構 + 下拉資料源
• filled mode 預填 7 sheet
• 父 row CONTROL_ROW_FILL 灰底覆蓋（07 視覺區分）
• TEMPLATE_VERSION = v1.1.0

UX polish（3 輪）：

• Hidden columns：framework_version_uid / profile_uid / statement_id（user 看不到，A2 parser 仍可讀）
• 必填欄位：header 黃底 + body 套黃底到實際 filled rows 數量（空 sheet 不延伸）+ thin border 補回視覺分隔
• VLOOKUP autofill（限 blank mode 寫公式，filled mode 不覆蓋既有）：matched_user/device/info_system 選定後 email/name/IP 自動帶入（VLOOKUP 自動算 follow-up，Excel 開檔可能需 Ctrl+Alt+F9 強制重算）
• 程序書欄位對齊 schema：刪 doc_no/doc_type/version（系統 schema 無）
• 03_參與人員 role 對齊 ParticipantRole（manager/reviewer/auditor/viewer）+ required

FE：

• 列表頁右上「新增合規資源庫」menu 加「下載 SSP 匯入樣板」→ DownloadSspBlankTemplateDialog（framework + version 兩層 picker，stack layout 避免長框架名跑版）
• MF template-edit 頁批次維護 menu 加 2 項（下載空白/已填樣板）
• i18n zh-tw + en

測試：BE 106 unit test 全綠（81 base + 11 T6 endpoint + 14 polish + 4 修改 = 106）

• 71 個 unit test 全綠

A1 未完項（partial ship 原因）：

• T6 FE 下載按鈕（compliance-manager-fe）— MF 詳細頁加 SplitButton + axios blob + i18n
• T7 完整版（剩 cucumber e2e + 完整 BE smoke）— BE smoke 撞 A0.1 follow-up #7 jedi-issue GitLab env，user 端配齊環境後可跑

下一步：A1 收尾（T6 FE + T7 完整 E2E）或先推 B1（Docx 樣板）。

以下全部由 build 掃資料夾產生，新增檔案重 build 即自動出現。標題連結指向渲染後的 HTML，md 連向源檔。

需求與討論

設計

實作與測試

交接與收口時間軸（handoff/，43 份）

由新到舊。每份是某一棒次交接當下的完整現況快照，看某個時間點「當時知道什麼」請從這裡進。

資產子資料夾（無文件，不建頁）：reference/（5 個檔）