Phase 2 A1 — BE Partial Ship 收口

日期：2026-05-19 本檔角色：A1 task arc 第二份 summary，承接 SUMMARY.md（T0-T3 partial），涵蓋 T4 + T5 + partial T7（BE smoke + changelog + tracker）= BE 端全部 狀態：A1 BE partial shipped（7-task plan 完成 5+部分 = 6/7 effective） 剩下：T6 FE 下載按鈕 + T7 完整 E2E（cucumber + user 端 BE smoke）

承接上 session T0-T3（5 commits / 52 test），本 session 完成 T4 filled mode 非控制項 6 領域 + T5 控制項與AO 父子 row + partial T7（BE smoke + changelog + tracker），共 3 commits / +1455 / -65 / 71 test 全綠。A1 BE 端到此完整 ship；剩 T6 FE 下載按鈕 + T7 完整 E2E 留後續 session。

T4 — Filled mode 非控制項 sheet（commit c3de9fa）

7 個 pre-flight verify 全跑完，確認：

• device_container.device_domain_service.get_devices(DeviceQueryEntity())
• information_system_container.information_system_domain_service.get_information_systems(InformationSystemQueryEntity())
• oscal_container.oscal_party_domain_service.get_all(PartyQueryEntity(party_type='organization'))
• oscal_container.oscal_responsible_party_domain_service.get_all(ResponsiblePartyQueryEntity(context_type='module_frame', context_id=mf.id))
• oscal_container.system_implementation_item_domain_service.get_all(SspSystemImplementationItemQueryEntity(scope_type='module_frame', scope_id=mf.id))

實作範圍：

• 補 3 個 _fetch_*_lookup helper（devices name (ip) / info_systems abbr - name / orgs party.name）
• _populate_filled_data() 6 領域寫 bundle：metadata_row（mf 自有欄位）/ parties_org+person（rp link → party_uuid → party 分組）/ devices（hardware + join Device for IP/OS）/ info_systems（component family + join InformationSystem for owner）/ leveraged（leveraged-authorization + party join）/ ref_docs（mf own）
• generator _build_data_sheet 加 _write_filled_rows() + _select_filled_rows() sheet→bundle attr 對應 map
• DI 解循環依賴：module_frame_container 加 3 個 DependenciesContainer() slot；main containers.py device 直接傳 + oscal/info_system 用 override_providers (mirror line 175 既有 pattern)
• 13 個新 test（generator filled 6 + app service helpers 7）

T5 — 07_控制項與AO sheet（commit 419907d）

4 個 verify 跑完，確認：

• profile_service.get_profile_by_uid(uid) 一次拿到 eager-loaded profile→profile_controls→catalog_control→assessments tree（mirror 既有 module_frame_template_import_service._load_profile_controls）
• ModuleFrameControlDefaultDomainService.get_all(...) + entity control_identifier / implementation_status / implementation_description
• ModuleFrameControlObjectiveDefaultDomainService.get_all(...) + entity (control_identifier, statement_identifier) 為複合 key

實作範圍：

• _build_controls_with_aos() 父子 flat row 組裝
• _load_existing_ctrl_map / _load_existing_obj_map 對應預填 lookup
• generator _write_filled_rows 加 SHEET_CONTROLS 分支：父 row（statement_id=None）套 CONTROL_ROW_FILL F2F2F2 灰底覆蓋整 row、子 row 維持白底
• 3 個 service DI（profile_service / control_default / control_objective_default — 都已在 mf_container wired，不必動 main containers.py）
• 6 個新 test（5 個 app service + 1 個 generator 灰底）

Partial T7 — BE smoke + changelog + tracker（commit 46b8999）

BE smoke 結果：

文件交付：

• 新 changelog: docs/changelog/2026-05-19-feat-mf-ssp-import-template-download.md（含 8 commits 鏈 + API spec + 行為差異 + 父子 row contract + TEMPLATE_VERSION SemVer + DI 解法 + 部署 handover）
• Tracker update: docs/features/FR-011.2-2605-ssp-import-export-phase2/README.md A1 row 改 "BE partial shipped (5/7)" + 完整 commit 鏈 + ship 範圍與未完項說明

46b8999 docs(ssp-import-export-phase2): A1 partial T7 — BE smoke + changelog + tracker    ← 本 session
419907d feat(ssp-import-template): A1 T5 07_控制項與AO sheet — profile-scoped 父子 row + MF defaults 預填 + 6 tests  ← 本 session
c3de9fa feat(ssp-import-template): A1 T4 filled mode 非控制項 sheet — 6 領域預填 + DI + 12 tests  ← 本 session
f14a942 docs(ssp-import-export-phase2): A1 partial summary — T0-T3 收口 + 換 session 交接   ← 上 session
ffd5d63 feat(ssp-import-template): A1 T3 blank mode — generator 主邏輯 + lookup wiring + 30 tests  ← 上 session
f68525f feat(ssp-import-template): A1 T2 generator base — sheet defs + styles + lookup + DV helpers  ← 上 session
d9d54c2 feat(ssp-import-template): A1 T1 skeleton — route + app service + DI 接通  ← 上 session
f59c4ff docs(ssp-import-export-phase2): A1 T0 verify 結果回填 design.md (4 處)  ← 上 session
b18db55 docs(ssp-import-export-phase2): A1 phase docs — design + implementation plan  ← 上 session

8 commits 未 push — user 後續決定 push 時機。

有效完成度：6/7 ≈ 86%（T7 BE 部分計入）

• dev DB：無 migration（A1 是新 endpoint + 新 generator，不動 schema）
• BE boot：撞 A0.1 follow-up #7 jedi-issue GitLab env 問題（已知環境問題；BE code 完整可運作，user 端配齊 GitLab env 後可跑完整 smoke）
• jedi-oscal：仍 path-dep 模式（A0.1 既有，A1 沒動套件層）
• pyproject.toml：A0.1 dev-only path-dep 改動仍在 working tree（不 commit，整 Phase 2 收口時還原）

1. URL contract（不變，T3 起 frozen）

GET /api/1.0/module-frame/<uid>/ssp-import-template?mode=blank|filled&locale=zh_Hant_TW

走既有 module_frame Blueprint (url_prefix='/api/1.0')，跟 /template/download + /control-defaults/template/download 三條 URL 共存不衝突。

2. TemplateDataBundle 13 個欄位全用上

T0-T3 預留結構，T4 / T5 補實際 row data。bundle 結構在 app/module_frame/excel_template/generator.py。

3. ALL_SHEETS spec frozen at TEMPLATE_VERSION = "v1.0.0"

8 個資料 sheet 結構固定，欄位增刪走 design.md §14 SemVer SOP。A2 parser 必須先讀 00_說明 R1 的版本字串作為相容性 anchor。

4. LookupSource 6 個 source 全用

5. 控制項 sheet B 模式 contract（T5 拍板）

• profile-scoped 全 control 列出（不只 MF 已填的）
• 父 row（control）statement_id=None, control_id=cc.control_id, control_name=cc.control_title
• 子 row（AO）statement_id=str(a.uid), control_id=cc.control_id（同父）, objective_id=a.name（"AC-1_smt.a" 短碼）
• MF defaults 預填：control_default key=control_identifier、obj_default key=(control_identifier, statement_identifier)
• 父 row 套 CONTROL_ROW_FILL F2F2F2 灰底覆蓋整 row；子 row 白底
• A2 parser 識別父子：statement_id 為空 → control row、為 AO uid → AO row；兩者皆帶 control_id 方便連續性判斷

6. DI 循環依賴解法

oscal_container 依賴 module_frame_container（containers.py:141），反向不可注入。解法（mirror line 175 既有 pattern）：

# module_frame_containers.py
class ModuleFrameContainer(containers.DeclarativeContainer):
    device_container = providers.DependenciesContainer()
    oscal_container = providers.DependenciesContainer()
    information_system_container = providers.DependenciesContainer()
    ...

# containers.py 後段（oscal/info_system 建立後）
module_frame_container.override_providers(
    oscal_container=oscal_container,
    information_system_container=information_system_container,
)

device_container 早於 module_frame_container 建立，可在 instantiation 時直接傳。

對 dev DB

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

對 staging / production

• A1 完整 ship 後（T6/T7 完成後）才考慮 deploy
• 完整 BE boot 在已配置 GitLab / GitHub env 環境執行
• jedi-oscal 仍 path-dep，Phase 2 整體完工再一次性 bump

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 &

完整 smoke 步驟（T7 完整版範本）

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

# Blank mode
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_blank.xlsx

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

# Verify
poetry run python3 -c "
from openpyxl import load_workbook
for fn in ['/tmp/template_blank.xlsx', '/tmp/template_filled.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)}')"

• 顯式 git add <file>，禁 -am / -A — 全 3 commits（T4 / T5 / partial T7）都遵守
• 所有 commits 含 Co-Authored-By: Claude Opus 4.7 (1M context) footer
• jedi-oscal 沒動，仍 path-dep，未推 Nexus
• pyproject.toml dev-only path-dep 改動沒被 commit
• T0 verify 結果不符 design 假設時主動修 design.md（T0 階段做的，本 session 沒新增 design 偏差）
• DDD 嚴格分層（Route 不碰 DB，App Service @transaction，Generator 純函式不依賴 DI）
• @transaction 寫對位置（app service public method generate()）
• Test 用 mock 包 logger 避開 jedi DBLogHandler 撞 SessionLocal=None（既有 _patch_logger autouse fixture + 新加 _patch_generator_logger for filled test）
• Pre-flight verify 動工前必驗（T4 V1-V7、T5 V1-V4）
• DI 解循環依賴用既有 pattern（override_providers）+ DependenciesContainer slot

T6 — FE 下載按鈕（0.5d）

切到 ~/Projects/Billows/Audit-Manager/compliance-manager-fe/ repo。

• 加 MF 詳細頁工具列 SplitButton：主按鈕「下載樣板」+ 下拉「空白 / 已填」
• service method downloadExcelTemplate(uid, mode) 包 axios responseType: 'blob'
• i18n 加 zh_Hant_TW / en 對應按鈕 / dropdown 文字
• API endpoint constant 加進 src/config/api/api.js

實作 anchor 範例見 plan：docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A1.md Task 6 (line 533-577)

T7 完整 — E2E + 完整 BE smoke（0.5d）

切到 ~/Projects/Billows/Audit-Manager/compliance-manager-test/ repo。

• 寫 features/.../mf_excel_template_download.feature（cucumber + Playwright）
• 兩個 scenario：blank / filled 下載 → openpyxl 驗 9 sheet 結構 + filled row 對齊
• user 端 BE：先配齊 GitLab env（A0.1 follow-up #7），然後跑完整 smoke 驗 curl 兩個 mode

後續更大階段

A1 全 ship 後，Phase 2 next stop：

• A2 — Excel Parser + 解析 API（中型，待 A1 全 ship）
• 或 B1 — Docx 樣板 + generator 骨架（中型，可平行 A1，依賴 A0.1）

A1 7-task plan BE 端走完 5+部分 task（86% effective）。feature/ssp-import-export-phase2 branch 累計 8 commits 未 push 涵蓋 T0-T7 BE 全部。71 個 unit test 全綠，blank / filled 兩模式 code 層級完整可用；唯一卡點是 user 端 jedi-issue GitLab env 設定，配齊後立即可做完整 boot smoke。

A1 BE 收口。剩 T6 FE + T7 完整 E2E 留後續 session。