SSP 匯入匯出 Phase 2 — 最終 SUMMARY（2026-05-22）

§1

一句話摘要

Track A（Excel 匯入 A0~A5）+ Track B（SSP 匯出 B1~B6）全部 shipped，含 DB schema 擴充、9 大資料領域匯入鉤稽、6 種格式匯出（docx/pdf/odt/json/yaml/xml）。

§2

功能範圍

Track A：Excel 匯入

Phase	功能	狀態
A0 / A0.1	DB schema 擴充（3 張表 + backfill）	✅ shipped
A1	Excel 樣板設計 + 下載	✅ shipped
A2	Excel Parser + 解析 API	✅ shipped
A3	共用 matcher（parties / org-units 鉤稽）	✅ shipped
A4	devices / info_systems / leveraged / 控制項 / AO / 程序書鉤稽	✅ shipped
A5	預覽 UI + Confirm 寫入	✅ shipped

Track B：SSP 匯出

Phase	功能	狀態
B1~B4	DOCX generator + MF/SSP version loader + PDF/ODT	✅ shipped
B5	OSCAL JSON / XML / YAML	✅ shipped
B6	FE 匯出按鈕 + CMMC DOCX 格式升級 + bugfixes	✅ shipped

§3

Commit 清單（feature/ssp-import-export-phase2 vs main）

BE（compliance-manager-be）重點 commits

Commit	說明
`c4804d7`	A0 schema 擴充
`eb9fa7e` / `6deacef`	A0.1 重整補丁
`b18db55`→`2b1e93c`	A1 Excel 樣板 (16 commits)
`f7b44ff`→`43cc206`	A2 Parser (7 commits)
`b011f2f`→`761fd7c`	A3 matcher (5 commits)
`57a9567`→`600f50a`	A4 寫入 pipeline (10 commits)
`535b931`→`c61ef02`	A5 BE (6 commits) + bugfix x3
`062782d`	B1~B4 docx pipeline
`25909f2`	B5 OSCAL 格式
`8df2525`	B6 DOCX 格式升級
`8ee55f5`	fix: LibreOffice binary 自動偵測
`43a9389`	fix: Unicode 檔名 (BE)

FE（compliance-manager-fe）重點 commits

Commit	說明
`e0ff8f1` / `00b6662`	A1 FE
`c95d02a`→`332b393`	A5 FE (5 commits) + bugfix x3
`7231b6a`	B6 匯出按鈕
`c21372c`	fix: Unicode 檔名 (FE)

jedi-oscal（套件）

Commit	說明
`afe7035`→`dbb3d7c`	A0 ORM/repo/mapper/DTO 擴充
`762d8fc`→`4666091`	A0.1 重整同步
`0.0.17` pin	主專案 pyproject.toml 鎖定版本

§4

升版步驟

前置確認

# 確認 branch 已 merge 到 main 或在 main 上
git log --oneline -3

# 確認 pyproject.toml 是 Nexus pin（不是 path dep）
grep "jedi-oscal" pyproject.toml
# 預期: jedi-oscal = "0.0.17" 或更高，不是 { path = "..." }

Step 1 — DB Migration（cmmgr 帳號）

PGPASSWORD='<查 .env DB_SECRET rds_master_password>' \
psql -h <DB_HOST> -p <DB_PORT> -U cmmgr -d <DB_NAME> \
    -f scripts/sql/2026-05-22-ssp-import-export-phase2-upgrade.sql

⚠️ RENAME 不冪等：若環境已部分執行過舊 migration，先跑確認查詢，已完成的 step 手動跳過。確認方式：
-- 若回傳 NULL 代表 Step 2 已跑（表已改名），可跳過 Step 2
SELECT to_regclass('oscal.system_security_plan_system_implementations');

Step 2 — 安裝相依套件

poetry update
# 或指定版本：poetry update jedi-oscal

Step 3 — 部署 BE

# 停舊 process
lsof -ti:8000 | xargs kill -9

# 啟動
python main_socketio.py
# 或 nohup python main_socketio.py > log/app.log 2>&1 &

Step 4 — 部署 FE

cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
npm run build
# 或 yarn build

FE 有 3 個修改檔需確保已 build：

src/views/module_frame/ModuleFrameTemplateEditView.vue

src/views/project/ProjectPlanningView.vue

src/components/grc/DownloadSspBlankTemplateDialog.vue

Step 5 — 系統需求確認（PDF/ODT）

PDF / ODT 匯出依賴 LibreOffice：

# macOS
brew install libreoffice   # 若尚未安裝

# Linux (Debian/Ubuntu)
apt-get install libreoffice

# 自訂 binary 路徑（非標準位置）
export LIBREOFFICE_CMD=/path/to/soffice

Step 6 — Smoke Test

# 取 JWT token（blsadmin / Billows@123!）
TOKEN=$(...)

# 1. Excel 樣板下載
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/1.0/module-frame/3699fc01.../ssp-template?source=module_frame&mode=filled" \
  -o test_template.xlsx

# 2. DOCX 匯出（確認中文檔名）
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/1.0/module-frame/3699fc01.../ssp-export?format=docx" \
  -OJ    # -OJ 讓 curl 用 Content-Disposition 的 filename

# 3. PDF 匯出（確認 LibreOffice 正常）
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/1.0/module-frame/3699fc01.../ssp-export?format=pdf" \
  -OJ

# 4. OSCAL JSON 匯出
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/1.0/ssp/<ssp_uid>/export?format=json" \
  -OJ

§5

已知遺留項目（非阻塞）

項目	說明	優先級
E2E 測試	A1/A2/A3/A4/B 全線缺 cucumber	低（下一輪補）
Pending issue	`docs/issues/pending/2026-05-19-person-role-cross-domain-inconsistency.md`	中
Docx parser 對齊	需求文件 Q3 明確 defer，等 Phase 2 完工後處理	低
`_resolve_ssp_id` 多版本 SSP	`get_one(profile_id=...)` 隨機取，latent issue	低
AO 無中文翻譯	catalog 尚無 ZH 翻譯	低
jedi-oscal 正式發版流程	完整 bump + Nexus push — 待 user 明確指示	待 user

§6

新增的 SQL 檔

scripts/sql/2026-05-18-extend-ssp-system-implementations.sql    ← A0
scripts/sql/2026-05-19-ssp-system-implementation-restructure.sql ← A0.1
scripts/sql/2026-05-19-backfill-ssp-system-implementation-items-device-id.sql
scripts/sql/2026-05-20-ssp-excel-parse-jobs.sql                 ← A2
scripts/sql/2026-05-21-ssp-excel-import-consolidated.sql        ← 舊整合入口（\ir 版）
scripts/sql/2026-05-22-ssp-import-export-phase2-upgrade.sql     ← 本次整合（單檔，升版用）

升版一律跑 2026-05-22-ssp-import-export-phase2-upgrade.sql，其餘子檔保留備查。