SSP OSCAL Alignment — Phase 3 DONE / Phase 4 WIP SUMMARY — 2026-05-25

---

Phase 3 v3.0.0 OSCAL-aligned 重組 ship 完（Excel + Docx 雙 import path），FE 端新 tab 已能看 BE component/LA/inventory 資料；但Phase 4 inline CRUD 跟移除舊 tabs 沒做（user 仍用舊 tabs 編輯 hardware/info_system），且 Phase 3.1 v3.0.0 Excel 樣板 ship 後 FE Excel preview 會顯示空 — Phase 4.4 「Reuse Excel preview component」必須在 Phase 4 collect 收掉。

---

FE repo 1 commit：bd23047 feat: Phase 4 FE — new「元件 + 授權 + 資產」第四 tab

Memory 更新：~/.claude/projects/-Users-chouraymond-Projects-Billows-Audit-Manager-compliance-manager-be/memory/feedback_cross_repo_read_claude_md_first.md（新）+ feedback_be_fe_version_alignment.md（修正不再勸切 session）+ MEMORY.md index 更新

---

Phase 3 ✅ DONE

Phase 4 部分 — DONE / WIP / TODO 一覽

---

3.1 Excel template v2.6.0 → v3.0.0 BREAKING

• v2.x 樣板被 parser 拒絕（GRC_EXCEL_TEMPLATE_VERSION_UNSUPPORTED），user 須重新下載 v3.0.0 樣板
• 新樣板 sheet 結構：基本資料 / 受評標的 / 單位 / 參與人員 / 利用授權 / 元件清冊 / 資產清冊 / 控制項與AO / 程序書
• 舊 in-flight v2.x parse_jobs 在 DB 內仍可走 confirm（derive_v2_bundle_keys 對 v1 keys mapping 兼容）；只有上傳新檔案會強制 v3.0.0

3.2 v3.0.0 Excel 上傳後 FE Excel preview 會空（最緊迫 follow-up）

• BE parser 現輸出 components / leveraged_authorizations / inventory_items keys
• FE SheetPreviewDevices.vue / SheetPreviewInfoSystems.vue / SheetPreviewLeveraged.vue 還讀 devices / info_systems / leveraged keys → 顯示空
• 必須 Phase 4.4 收掉

3.3 docx import 走新 path（樣板 .docx 還沒加 H2 section 時 fallback OK）

• adapter adapt_to_bundle() 新加 extract_components_table + extract_inventory_items_table 呼叫
• 樣板 .docx 若還沒加 「H2 System Components」/「H2 Hardware Maintenance」section → extractor 返 [] 不影響既有 T6 (CSP/CSO) / T7 (Category) 路徑
• 樣板加表編輯（圖形 Word）由 user 自己做；code 端已 ready

---

---

L1 — Phase 4 BE write endpoints route 端 + inventory_items CRUD

05ae6a19 加了 SspComponentsAppService 的 add_item/update_item/delete_item，但 routes 還沒對外暴露 POST/PUT/DELETE，且 SspInventoryItemsAppService 沒對應 CRUD。

需做：

1. api/oscal/routes/ssp/ssp_components_route.py：
   • SspComponentsListResource 加 post
   • 新加 SspComponentsDetailResource class（put + delete）
   • api/oscal/__init__.py add_resource 新 detail route
2. app/oscal/service/ssp_inventory_items_app_service.py：複製 components CRUD pattern
3. api/oscal/routes/ssp/ssp_inventory_items_route.py：同樣 list + detail route

L2 — Phase 4 FE inline CRUD on new tab

SspComponentsLeveragedInventoryTab.vue 目前是純展示。要加：

• 三個 Add/Edit dialogs × 三 entities（components / LA / inventory_items）
• Form validation（component_type 14 enum / impact_level 4 enum / required fields）
• LA dropdown 選擇器 within component edit（leveraged_authorization_uid FK link）
• Multi-select chip picker for inventory_items.implemented_component_uids
• 串 SspService.{create,update,delete}{Components,Inventory,Leveraged} 方法（已有 listLeveraged / updateLeveraged 等，需檢視齊全度）

L3 — Phase 4 移除舊 3 tab + 廢棄 vue 元件

新 inline CRUD 上線後：

1. SspTabPanel.vue 移除 tab 5/6/7（設備舊 / 資訊系統舊 / 外部利用服務舊）
2. SECTION_TAB_MAP 收回到只剩新結構
3. 刪 src/components/grc/ssp/SspLeveragedSection.vue
4. 刪 src/components/grc/ModuleFrameSspDevicesPanel.vue / ModuleFrameSspInfoSystemsPanel.vue（或標 deprecated 待 MF template-edit 確認也不用）
5. project-planning.json 移除 section.scope_devices / scope_info_systems / leveraged keys
6. count.devices / count.infoSystems / count.leveraged 從 SspTabPanel state 移除

L4 — Phase 4.1 5-tab 完整結構

設計 §4.1：[基本資料][受評標的][參與人員][元件+授權+資產][控制項]

需做：

1. 受評標的（SC）從 SspBasicSection.vue 拆出 → 新 SspSystemCharacteristicSection.vue 獨立 tab
2. 單位 + 參與人員 合併 → 新 SspPartiesSection.vue（或 ModuleFramePartiesPanel 加 mode 切換）
3. 加控制項 tab — 可指向既有 controls page，或 inline panel 在 ssp edit view 內

L5 — Phase 4.4 Reuse Excel preview component（緊迫）

Phase 3.1 v3.0.0 樣板 ship 後 FE Excel preview 會空。需做：

1. Excel preview 路由：src/views/module-frame/ImportExcelPage.vue 或同等
2. 改 SheetPreviewDevices.vue / SheetPreviewInfoSystems.vue / SheetPreviewLeveraged.vue：
   • 讀 v2-bundle keys：components / inventory_items / leveraged_authorizations
   • 或 generalize 三檔成單一 SheetPreviewComponents.vue / etc.
3. Excel app service _apply_content_overrides._ROW_OVERRIDE_SHEETS 增加 components / leveraged_authorizations / inventory_items（或拆 v3 path 抽單獨 _apply_v2_bundle_overrides 接 docx 端 Bug C 同 pattern）
4. 對齊 docx 端 preview UI — Phase 4.4 spec 講 generalize 兩端共用

L6 — i18n keys 規範

SspComponentsLeveragedInventoryTab.vue 目前 i18n keys 走 ?? '中文 fallback'。要在 src/config/locales/i18n/zh-tw/grc-shared.json + en/grc-shared.json 加 namespace ssp_components_leveraged_inventory.*。

L7 — Phase 1+2 Bug B 仍未查（handoff 2026-05-25-phase1-phase2-FINAL-SUMMARY.md §8 L2）

docx import 5 parties 全 decision=skip → 0 parties 寫入。FE diff stepper 預設 decision UX 跟 BE 收 payload 對應不明。Phase 4 FE 改 stepper UX 時順手釐清。

L8 — L1 jedi-oscal 進版 + Nexus push + 主專案 pin 還原（user 拍板才做）

per Phase 1+2 SUMMARY §7.1。Phase 5 已 defer 但 Phase 3+4 ship 完仍要 bump 套件版本（套件 layer 沒改但主專案使用方式有改）。user 2026-05-25 拍板「進版不用做，等測完才會說」 — 等 user。

L9 — BE/FE 版號 1:1 對齊（v1.1.0 → v1.2.0？）

per memory feedback_be_fe_version_alignment。整個 feature 收尾後同步 bump，user 拍板進版時做。

---

6.1 部署順序

1. jedi-oscal（套件本身沒改但對應 caller 改了 → 不需 bump，pin 不變）
2. 主專案 deploy（含 Phase 3.1 v3.0.0 sheet 重組）
3. FE 同步 deploy（新 tab + Phase 4 完工部分）
4. 重要：user 必須先「下載 v3.0.0 樣板」再上傳；現有 v2.x 樣板會被 reject

6.2 BE 重啟必做

per feedback_be_restart_after_service_change：

• 改了 app/oscal/service/excel_parser/*.py（4 個檔）
• 改了 app/oscal/service/ssp_components_app_service.py / ssp_inventory_items_app_service.py
• 改了 app/module_frame/excel_template/sheet_definitions.py / generator.py
• 改了 app/module_frame/service/ssp_import_template_app_service.py
• 改了 domain/oscal/parser/docx_section_extractors.py / domain/oscal/adapter/cmmc_ssp_adapter.py

kill -9 <pid> 後 restart（per feedback_backend_restart_orphan_pids）。

6.3 兩 repo git push

兩 repo 都還 local（主專案 28 commits ahead / FE 1 commit ahead）。Push 需 user 明確指示。

---

你接手 SSP OSCAL Alignment Phase 4 收尾。Phase 3 全完工（§3.1 v3.0.0 sheet 重組 +
§3.2 docx extractors + §3.3 reference regen），Phase 4 部分完工（BE read endpoints +
FE 新 tab read-only display + BE write endpoints WIP）。Phase 5 已 defer。

按以下順序讀文件（共 5 個）：
1. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-DONE-phase4-WIP-SUMMARY.md
   （本 SUMMARY — 整個本期完工 + 未完項目）
2. docs/features/FR-028-2605-ssp-oscal-alignment/design.md §3 + §4（Phase 3 + Phase 4 spec；§5 已 defer 可跳）
3. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md
   §8 L1/L2/L3（Bug A/B/C + 進版 leftover）
4. app/oscal/service/ssp_components_app_service.py（WIP CRUD 已加，看 pattern）
5. FE 端必讀：~/Projects/Billows/Audit-Manager/compliance-manager-fe/CLAUDE.md
   （per memory feedback_cross_repo_read_claude_md_first — 跨 repo 動工必讀）

開工順位（per 本 SUMMARY §5 L1~L9）：
- **緊迫**：L5 Phase 4.4 FE Excel preview 對齊 v3 keys（Phase 3.1 ship 後 preview 空）
- 必收：L1 BE write endpoints route + inventory CRUD → L2 FE inline CRUD → L3 移除舊 tabs
- 完整度：L4 5-tab 結構 → L6 i18n 規範
- 排查：L7 Bug B / L8 進版 / L9 BE/FE 版號對齊

開工前 pre-flight：
- git branch --show-current → feature/ssp-oscal-alignment（兩 repo 一致）
- git status: M pyproject.toml only（dev-only path-dep，**永不 stage**）
- BE test smoke：poetry run pytest tests/test_excel_parser_v2_bundle.py
  tests/test_excel_parser.py tests/test_ssp_import_pipeline_smoke.py
  tests/test_cmmc_ssp_adapter_v3_bundle.py — 全綠
- FE test smoke：cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe && npx vite build → 通

收尾後（user 拍板才做）：jedi-oscal 進版（如有改套件）+ 兩 repo git push + BE/FE
版號對齊 bump（per memory feedback_be_fe_version_alignment）。

---