Phase 2 A1 — T6 final（A1 task arc 完整收口）

日期：2026-05-19 本檔角色：A1 task arc 第三份 summary，承接 SUMMARY-be-partial-ship.md（T4+T5+partial T7 BE），涵蓋 T6 BE+FE+3 輪 UX polish = A1 整體 BE+FE shipped 狀態：A1 BE+FE shipped ✅（T0-T6 完成；T7 cucumber E2E pending follow-up） 剩下：T7 完整 E2E（cucumber + 完整 BE smoke 需 user 端配齊 GitLab env）

承接 BE partial ship (T0-T5)，T6 收口本 session 完成 7 個 commits（BE 7 + FE 2，扣除 1 個 tracker doc commit）：BE framework-version-scoped 新 endpoint + FE 兩個下載點 + 3 輪 UX polish（hidden cols / VLOOKUP autofill / required body fill / 黃底 border + 範圍限縮 / role enum 對齊 ParticipantRole + cross-domain finding 紀錄）。BE 106 unit test 全綠。A1 整體 shipped，剩 T7 cucumber E2E。

T6 BE — Framework-version-scoped endpoint（commit 3171116）

新 endpoint：

GET /api/1.0/ssp-import-template?framework_version_uid=<uid>&mode=blank&locale=

S1 場景：顧問訪談前下載「framework_version 全 catalog controls 樣板」（superset）。跟既有 MF-scoped endpoint（profile-scoped subset）互補。

範圍：

• TemplateDataBundle.mf_uid / mf_name 改 Optional
• App service generate_by_framework_version() + 3 helper
• DI wire 4 新 dep
• Route 加 SspImportTemplateByFrameworkVersionResource
• Error code 加 GRC_FRAMEWORK_VERSION_NOT_FOUND + GRC_TEMPLATE_FRAMEWORK_VERSION_REQUIRED
• design-A1.md §3.3 / §6.2.1 / §15.1 補
• +11 unit test

T6 FE — 兩個下載點 + Dialog（commit e0ff8f1 + 00b6662）

範圍：

• 新元件 DownloadSspBlankTemplateDialog.vue（兩層 picker，後續 fix-1 改 vertical stack）
• ModuleFrameTemplateService 加 2 個 method
• api.js 加 2 個 constant
• ModuleFrame.vue createMenuItems 加項
• ModuleFrameTemplateEditView.vue batchMenuItems 加 2 項
• i18n zh-tw + en 9 個 key
• 新 changelog

Tracker update（commit 66d0d13）

A1 status BE partial shipped → BE+FE shipped，commit chain 完整紀錄。

UX polish round 1（commit fbcf9f2）— 5 個問題

使用者下載樣板實際驗證後反饋：

• TEMPLATE_VERSION bump v1.0.0 → v1.1.0
• +15 unit test

UX polish round 2（commit 690f25c）— 3 個追加

• +5 unit test

UX polish round 3（commit faade8d + 2b1e93c）— 黃底細節

• faade8d：黃底蓋掉 Excel gridlines → CELL_THIN_BORDER 加深灰 thin border 到 header + required body
• 2b1e93c：空 sheet 黃底延伸 200 row 視覺糟 → 範圍限縮到 min(1 + len(filled_rows), MAX_DATA_ROW)，blank mode 不套 body（只 header）

Cross-domain role 不一致紀錄（commit b6b4870）

T6 fix2-C 把 SHEET_PERSONS role 改 ParticipantRole 後 audit 既有 docx 匯入流程發現：

• OSCAL oscal_responsible_parties.role_id 跟 GRC project_participants.role (ParticipantRole) 兩條獨立資料流，沒 mapping
• 既有 docx parser line 303 role_id=parsed.role or "" 無 validation
• dev DB 可能累積雜亂字串

處理：

• design-A1.md §15.3 紀錄完整 finding + A2 parser contract
• docs/issues/pending/2026-05-19-person-role-cross-domain-inconsistency.md 含 4 個修補計劃（A2 必做 / docx normalize / DB audit / 雙寫設計）
• T6 不動既有 docx parser；A2 開工時實作修補 A

BE — 16 commits 未 push（feature/ssp-import-export-phase2）

2b1e93c  tweak(ssp-import-template): T6 fix4-A 黃底範圍限縮到實際 filled rows
b6b4870  docs(ssp-import-template): T6 fix2-C 跨域 role 不一致 — design.md §15.3 + issue
faade8d  tweak(ssp-import-template): T6 fix3-A — 黃底 cell 加 thin border 補回視覺分隔
690f25c  feat(ssp-import-template): T6 fix2 round 2 — required body fill + recalc + role enum
fbcf9f2  feat(ssp-import-template): T6 fix UX polish — hidden cols + VLOOKUP + ref_docs schema
66d0d13  docs(ssp-import-export-phase2): A1 T6 FE shipped — update tracker README
3171116  feat(ssp-import-template): A1 T6 BE — framework-version-scoped endpoint (superset)
c653f05  docs(ssp-import-export-phase2): A1 BE partial ship task arc 收口 — SUMMARY + handoff prompt
46b8999  docs(ssp-import-export-phase2): A1 partial T7 — BE smoke + changelog + tracker
419907d  feat(ssp-import-template): A1 T5 07_控制項與AO sheet — profile-scoped 父子 row + MF defaults
c3de9fa  feat(ssp-import-template): A1 T4 filled mode 非控制項 sheet — 6 領域預填 + DI
f14a942  docs(ssp-import-export-phase2): A1 partial summary — T0-T3 收口 + 換 session 交接
ffd5d63  feat(ssp-import-template): A1 T3 blank mode — generator 主邏輯 + lookup wiring
f68525f  feat(ssp-import-template): A1 T2 generator base — sheet defs + styles + lookup + DV helpers
d9d54c2  feat(ssp-import-template): A1 T1 skeleton — route + app service + DI 接通
f59c4ff  docs(ssp-import-export-phase2): A1 T0 verify 結果回填 design.md (4 處)
b18db55  docs(ssp-import-export-phase2): A1 phase docs — design + implementation plan

外加最終收尾 commit（含 round 3 changelog + 本 SUMMARY）尚未 commit。

FE — 2 commits 未 push（feature/ssp-import-export-phase2）

00b6662  tweak(ssp-import-template): T6 fix-1 Dialog 框架名跑版 — 兩 dropdown 改 vertical stack
e0ff8f1  feat(ssp-import-template): A1 T6 FE — Excel 匯入樣板兩個下載點

Changelog（6 份，含本次收尾 round 3）

Issue（1 份）

docs/issues/pending/2026-05-19-person-role-cross-domain-inconsistency.md — Person role 跨 OSCAL/GRC domain 不一致，4 個修補計劃（A2 phase 開工必看）

Design

docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A1.md v1.2，含：

• §3.1 主下載 endpoint（既有）
• §3.2 權限檢查
• §3.3 framework-version-scoped endpoint（T6 新增）
• §6.2.1 framework-version-scoped 資料組裝（T6 新增）
• §11 Acceptance Criteria（含 T6 新項）
• §14 樣板演進 SemVer SOP
• §15.1 T6 新 endpoint reconciliation
• §15.2 T6 fix UX polish 5 項
• §15.3 跨域 role 不一致 finding（必看）

Tracker

docs/features/FR-011.2-2605-ssp-import-export-phase2/README.md A1 row 標 BE+FE shipped ✅

$ pytest tests/test_excel_template_*.py tests/test_ssp_import_template_app_service.py
106 passed (Unit test 全綠)

範圍：

• test_excel_template_base.py — 26（含 ColumnDef invariant + lookup_builder + DV builder + helpers）
• test_excel_template_generator_blank.py — 25（含 structure / styling / DV / hidden cols / autofill / border / required body fill / role enum）
• test_excel_template_generator_filled.py — 20（filled mode 各 sheet）
• test_ssp_import_template_app_service.py — 35（app service helpers + T6 framework_version + helpers）

累計：106 全綠（A1 partial ship 時 71 + T6 改動 +35 = 106）

對 dev DB

無需 migration — A1 純粹是新 endpoint + 新 generator，不動 schema。

對 staging / production

• A1 完整 ship 後（含 T7 E2E + 完整 BE smoke）才考慮 deploy
• BE boot 需配齊 GitLab / GitHub env vars（A0.1 既有 follow-up）
• jedi-oscal 仍 path-dep — Phase 2 整體完工再一次性 bump Nexus

BE 重啟（user 端配齊 env 後）

lsof -ti:8000 | xargs kill -9
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
set -a; source .env; set +a
nohup poetry run python main_app.py > /dev/null 2>&1 &

完整 BE smoke（T7 完整版範本）

TOKEN="..."  # from dev login
MF_UID="..." # dev DB existing MF uid
FW_VERSION_UID="..."  # dev DB existing framework_version uid

# MF-scoped blank
curl -H "Authorization: Bearer $TOKEN" -H "X-Tenant-ID: 102" \
     "http://localhost:8000/api/1.0/module-frame/$MF_UID/ssp-import-template?mode=blank" \
     -o /tmp/template_mf_blank.xlsx

# MF-scoped filled
curl -H "Authorization: Bearer $TOKEN" \
     "http://localhost:8000/api/1.0/module-frame/$MF_UID/ssp-import-template?mode=filled" \
     -o /tmp/template_mf_filled.xlsx

# FW-version-scoped blank (T6 新增)
curl -H "Authorization: Bearer $TOKEN" \
     "http://localhost:8000/api/1.0/ssp-import-template?framework_version_uid=$FW_VERSION_UID&mode=blank" \
     -o /tmp/template_fw_blank.xlsx

# Verify via openpyxl
poetry run python3 -c "
from openpyxl import load_workbook
for fn in ['/tmp/template_mf_blank.xlsx', '/tmp/template_mf_filled.xlsx', '/tmp/template_fw_blank.xlsx']:
    wb = load_workbook(fn)
    visible = [s for s in wb.sheetnames if not s.startswith('_lookup_')]
    print(f'{fn}: total={len(wb.sheetnames)}, visible={len(visible)}')"

FE 重啟

FE 有 hot reload，dev server 自動更新；但建議 hard refresh 瀏覽器（避免 cache）。Dialog 元件 + i18n 改動需重新 build production 才會生效。

Manual 驗證 UI

• 顯式 git add <file>，禁 -am / -A — 全 7 個 T6 commits（BE 5 個 + FE 2 個）+ doc commits 都遵守
• 所有 commits 含 Co-Authored-By: Claude Opus 4.7 (1M context) footer
• jedi-oscal 沒動，仍 path-dep
• pyproject.toml dev-only path-dep 改動沒被 commit
• DDD 嚴格分層（Route 不碰 DB，App Service @transaction，Generator 純函式）
• @transaction 寫對位置
• BE 重啟提醒（每次 BE service 改動都告知 user 要重啟）
• T6 fix 流程：每輪 user 反饋 → 修補 → test → commit
• 跨 repo 切換時提醒（BE / FE 不同 repo，commit 分開）
• 跨域 role 不一致紀錄 issue（不擠在 changelog）
• design.md §15 reconciliation 段補 T6 變動

A1 已 BE+FE shipped。Phase 2 next stop：

A2 — Excel Parser + 解析 API（中型）

依賴 A1 已 ship。涵蓋：

• Excel 上傳 + 解析 + parse_uid TTL
• 03 role 強制 enum validation（issue 修補 A 必做）
• A2 預覽 UI + Confirm 寫入（A5 範圍）
• 區分 superset upload（建新 MF）vs MF update upload（更新既有 MF）兩條 import flow

B1 — Docx 樣板 + generator 骨架（中型）

可平行 A2；依賴 A0.1。涵蓋：

• SSP docx 匯出樣板 + jedi-docx 整合
• 對齊 OSCAL responsible_party / system_implementation_item / control_implementation

T7 — A1 E2E（小型補完）

跨 compliance-manager-test repo：

• cucumber feature 兩 scenario（MF-scoped + FW-version-scoped 下載）
• Playwright step + page object
• openpyxl 驗 sheet 結構 / 黃底 / hidden cols
• BE 完整 smoke 需 user 端配齊 GitLab env

A1 task arc 跨 3 session 完工：

• session 1 (T0-T3)：design + plan + skeleton + generator base + blank mode
• session 2 (T4-T5 + partial T7)：filled mode + 控制項與AO + BE smoke
• session 3 (T6 + 3 輪 UX polish)：FW-version-scoped endpoint + FE 兩個下載點 + UX 反饋細節整修

feature/ssp-import-export-phase2 branch 累計 17 commits（含本份 SUMMARY 收尾 commit）。BE 106 unit test 全綠。

A1 整體 BE+FE shipped。剩 T7 E2E 跨 test repo 留 follow-up。