Session Handoff — 2026-05-24

1. 今天主軸：docx import 補完 → 驗證可用 → 浮出 OSCAL 結構性對齊議題 → 規劃 5 phases / 25d 的 ssp-oscal-alignment feature
2. 目前狀態：
   • Stage 1 (docx-import-parity) 已上線運作、BE 能完整解客戶 docx
   • Excel template v2.6.0 — leveraged 14 cols + parties 補 address/phone/title
   • FE LeveragedSection 對齊 13 欄 + row expander 顯示完整資料
   • ssp-oscal-alignment design.md 完整規劃寫好（766 行）
3. 明天起重點：開始走 ssp-oscal-alignment — 最大風險在 Phase 1 jedi-oscal 套件異動（要新增 3 entity / 3 service / 3 repo / 4 ORM model）
4. 未 push：CLAUDE.md「push 永遠要 user 明確指示」— Claude 整段在 local commit；user 自行決定何時 push

=== ssp-oscal-alignment 規劃 ===
daf2475  docs(ssp-oscal-alignment): design.md — 5 phases foundation→export 完整規劃

=== Excel template 擴張（leveraged + parties）===
d388476  feat(ssp-excel-template): SHEET_ORGS/PERSONS 加 OSCAL Party 完整欄位 + bump v2.6.0
c280982  chore(ssp-excel-template): regenerate reference 樣板 to v2.5.0
ebfcce3  chore(ssp-excel-template): bump TEMPLATE_VERSION v2.4.0 → v2.5.0
078f227  feat(ssp-excel-template): SHEET_LEVERAGED 加 7 個 CMMC 結構化欄位 + docx adapter 對齊

=== Stage 1 (docx-import-parity) ===
57019d3  docs(docx-import-parity): stage1 changelog + overnight handoff SUMMARY (S10)
6d758e7  tweak(docx-import-parity): 加 dev BE 啟動 wrapper script (S8)
530c328  feat(docx-import-parity): app service 上傳後自動 accept track changes (S7+)
4a04e83  test(docx-import-parity): smoke test script for end-to-end parse (S7)
e2bab11  feat(docx-import-parity): app service 補 logger.error + 傳 doc 給 adapter (S6)
2b4fb1a  feat(docx-import-parity): adapter 接 extractor 補欄位 (S5)
3c87b03  test(docx-import-parity): 加 customer fixture integration test (S4)
4ccfff4  tweak(docx-import-parity): scrub 客戶檔產 test fixture (S3)
8262b9e  test(docx-import-parity): 加 extractor unit tests 用 reference docx (S2)
3f2d51d  feat(docx-import-parity): 加 docx section anchor extractors (S1)
f605920  docs(docx-import-parity): stage1 design + plan + gitignore 客戶檔

FE repo (compliance-manager-fe) 對應 commits（路徑 ~/Projects/Billows/Audit-Manager/compliance-manager-fe/）：

e873fae  feat(ssp-docx-import): LeveragedSection 對齊 Excel 13 欄 schema + row expander
38c9e25  feat(ssp-docx-import): mount MetadataSection + LeveragedSection 到 preview tabs

3.1 OSCAL 對應勘誤（驗證過 OSCAL official metaschema）

之前的對應有錯，已修正在 design.md §1：

官方驗證來源：

• OSCAL repo src/metaschema/oscal_implementation-common_metaschema.xml
• shared-constraints allowed-values-component-type.ent：14 個 type enum + allow-other="yes"

3.2 客戶 docx 重要發現（亞航 SSP）

• 客戶檔（docs/reference/亞航-CMMC-SSP-20260520-1會議討論版.docx）有 Word track changes 未 accept，造成 BE python-docx 解出 0 parties
• BE 已加 _normalize_docx_revisions() 在 parse 前自動 accept 所有 revisions（in-memory only，原檔 bytes 保留在 MinIO 不變）
• 客戶檔在 .gitignore，scrubbed 版本在 tests/data/oscal/customer_sample_scrubbed.docx
• Customer real data 浮出後 scrub 規則加了 30+ rules（屏東飛機維修廠 / Sierra Nevada / 真實姓名電話地址 / Crowdstrike / Fortinet 等）— 下次拿到別份客戶 docx 要重跑 scrub script 並補 SCRUB_RULES

3.3 FedRAMP Package ID 是什麼

• FedRAMP = Federal Risk and Authorization Management Program（美國政府雲服務資安授權標準）
• 每個取得授權的 CSO 在 https://marketplace.fedramp.gov/ 有唯一識別碼（如 FR18078583629）
• 客戶 Crowdstrike 那筆是 FedRAMP authorized → 在 OSCAL 同時是 <component> 跟 <leveraged-authorization> 兩個元素
• 在我們系統內：不是 first-class column on component table，而是 ssp_leveraged_authorizations.props.fedramp_package_id（design.md §1.2）

3.4 Excel template version 軌跡

v2.3.x — 既有
v2.4.0 — 之前: leveraged 加 date_authorized + description
v2.5.0 — 本日: leveraged 加 7 個 CMMC props (nature_of_agreement / impact_level /
              data_types / authorized_users / protocol / security_auth / fedramp_package_id)
v2.6.0 — 本日: parties 加 OSCAL Party 完整欄位 (org: address/telephone;
              person: title/telephone/address)
v3.0.0 — 未來 ssp-oscal-alignment Phase 3：major bump
              拆 06_外部利用服務 → 06a/06b
              05_資訊系統 合併進 06a
              04_設備 → 04_資產清冊
              breaking change，v2.x 樣板強制不支援

3.5 jedi-oscal 套件異動策略

Phase 1 是這 feature 最大風險點：

• 套件側要新增 3 entity (Component / LeveragedAuthorization / InventoryItem) + 3 service + 3 repo + 4 ORM model (含 M2M join)
• 照 CLAUDE.md 規範：
  • 開發期間用 poetry path dependency（pyproject.toml path =本地），不每改必 bump version
  • 主專案 pyproject.toml path 改動 不該 commit（dev-only）
  • feature 完成、smoke 通過後 才一次性 bump + 推 Nexus
  • poetry update（不用 poetry lock，會卡）

3.6 confirm path 雙路徑相容策略

design.md §2.4 詳述：

• parse_jobs.parsed_result JSONB 加頂層 schema_version key
• 舊路徑（v1-ssp）跑既有 _legacy_confirm()，新路徑（v2-bundle）跑新 orchestrator
• in-flight 舊 parse_job 走舊路徑、新 parse 寫新 schema
• 不強制 user 重 parse、不刪資料

4.1 測試 logger patch（CLAUDE.md feedback 已記）

寫 app service test 必加 @pytest.fixture(autouse=True) patch logger 為 MagicMock，否則 jedi DBLogHandler 對 SessionLocal=None 路徑炸 'NoneType' object is not callable。

@pytest.fixture(autouse=True)
def patch_logger():
    with patch("app.<module>.service.<svc>.logger", MagicMock()):
        yield

Pattern: tests/test_ssp_docx_import_app_service.py 已有範例。

4.2 既有 pre-existing test failures（不是本 session 造成的）

跑 regression 時這兩個會紅，不要花時間 debug：

tests/test_ssp_docx_import_create_no_diff.py::TestCreateModeRegression::test_create_mode_get_parse_result_all_controls_added
tests/test_ssp_excel_import_app_service.py::TestConfirmGuards::test_400_when_blocking_validation_error_present

兩個都已驗證在 S0 commit (f605920) 之前就 fail，跟本期改動無關。

4.3 docs/reference/亞航*.docx 已 gitignore

• 客戶實際檔含敏感資訊（屏東 / Sierra Nevada / 真實人名電話等）
• .gitignore 已加 docs/reference/亞航*.docx + *.xlsx
• 檔案本身仍在 disk（user 本機 only），但 git 不追蹤
• 下次拿到別份客戶 docx 要重跑 scripts/scrub_customer_docx.py 產 test fixture

4.4 BE 啟動 .env 含 JSON 值 shell 解析錯

.env 內 DB_SECRET={"key": "value"} 形式 shell source 會炸 brace expansion。對策：

• Claude 用 scripts/start_be_overnight.sh（用 python-dotenv load）
• User 自己起 BE 走慣用流程（沒問題）

4.5 Customer file 解出 name 在 preview 顯示成 null

DB 內 parsed_result.parties[].name 完整，但經 diff_service.annotate_parse_result() 後 preview API response 把 name 蓋成 null。這是既有 diff service 行為，跟 docx import 本身無關。

對應的 issue：應該由 Stage 4 (FE 重設計) 一併修，或單獨開 bug ticket。design.md §5 風險表沒涵蓋這個（補一條）。

4.6 schema_version 命名衝突

parse_jobs 表已有 version column（但不是 schema 版本概念）。新加 parsed_result.schema_version 在 JSONB 內，不要改 column 名避免 migration 風險。

按順序執行，第一個 Yes 不通過就停下問 user：

• branch 確認 — 仍在 feature/real_doc_import？或要新開 feature/ssp-oscal-alignment branch？（建議新開、Phase 1 完成 merge 回主線）
• Stage 1 commits push 與否決定 — 見 Q1
• jedi-oscal 套件本機路徑確認 — ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/ 是否乾淨 working tree
• 跟 user 確認套件 PR 對哪個 branch — 見 Q3
• brainstorming SOP 跑一遍 — design.md 已寫但仍要走 brainstorm 確認沒漏 edge case（特別是 inventory_implemented_components M2M write order）
• writing-plans SOP 產 implementation-plan-phase1.md — 切細 step 並標 commit point
• path dependency 設定 — 主專案 pyproject.toml 把 jedi-oscal 改 path =本地，不 commit

• ❌ 不要直接 push Stage 1 改動到 main — feature branch 上 working
• ❌ 不要在 Phase 1 前先動 Excel/Docx 樣板 — 樣板加表 (Phase 3) 依賴 dataclass shape (Phase 1)，反過來會二次工
• ❌ 不要省略 schema_version 雙路徑 — 既有 in-flight parse_job 直接走新 path 會炸（adapter 形狀不對）
• ❌ 不要在套件 PR 帶主專案 path dependency 改動 — 那是 dev-only，會污染套件 commit history
• ❌ 不要把 Component type 直接寫 'api' / 'cli' — OSCAL enum 沒這兩個，會被 schema validator 拒。要 fallback 到 'service' + framework prop

本 session 跨多個關鍵設計決策（leveraged 雙寫 / docx import 補欄位 / Excel template 擴張 / OSCAL 對齊規劃），強烈建議歸檔到 docs/conversation-history/2026-05-24/ssp-oscal-alignment-planning/。

歸檔流程（per CLAUDE.md）：

poetry run python scripts/extract_claude_sessions.py \
    --date 2026-05-24 \
    --topic ssp-oscal-alignment-planning \
    --auto

如果 JSONL 跨多個 phase（譬如「docx import 補欄位」跟「ssp-oscal-alignment 規劃」是兩個 task arc），可以分兩個 sub-topic：

docs/conversation-history/2026-05-24/
├── docx-import-parity-fields-supplement/  # Excel leveraged + parties 擴欄
└── ssp-oscal-alignment-planning/           # OSCAL 對齊規劃

1. 不要重做今天已決定的：design.md 的 OSCAL 對應已經跟官方 metaschema cross-check 過，不要再去 web fetch 一次浪費 token
2. brainstorm SOP 要跑 — design.md 是 single approach，brainstorm 確認沒第二條更好路徑
3. plan SOP 要跑 — design.md 是 design layer，plan layer 切細到「每個 commit 對應什麼 step」
4. Phase 1 不會一個 session 跑完，預估 5d work，分多 session ship
5. 跟 user 確認 risk tolerance：套件異動方向若 user 不同意，要 fallback 「主專案內定義」（不動套件）— 這條退路設計上可行但長期維護差
6. 不要 push、不要切 branch — CLAUDE.md 規範