FR-044 稽核紀錄 xlsx 匯入 — 實作收尾 SUMMARY

Date: 2026-07-04 · Branch feature/FR-044（BE + FE + 套件，皆未 push）· 狀態：修正待驗證（user STG 逐輪手測，五個非直觀 bug 已修）· Notion Case No: FR-044

1. 一句話

稽核員 / PM 上傳顧問逐條檢查紀錄 xlsx → 解析成控制層判定＋逐 AO 觀察＋佐證連結 → 三步 wizard 預覽 / 修改 / 確認 → 批次寫入本輪 AR（走既有 AssessmentResultAppService 的 judge_finding / create_observation / add_risk / link_risk_findings），本期支援亞航 CMMC L1 格式，架構 mirror FR-043 三段式管線（parse→preview→confirm）。

2. Commits

BE（`compliance-manager-be`，時序倒序）

commit	內容
`48ef1380`	設計規格
`a6365a29`	執行交接 handoff
`76a53649`	finalize na（第四態收斂）
`75c25d10`	`ar_xlsx_parse_jobs` 表 migration（org_unit_id / RLS / GRANT cm_app）
`d6fc20de`	持久層（entity/model/mapper/repo/domain service）
`2cfb363b`	`_METHOD_KEYWORDS` 自 FR-043 上收
`a47ca7eb`	import registry base 自 FR-043 上收
`7fdecd31`	亞航 CMMC L1 xlsx adapter（openpyxl，59 列 snapshot）
`f3cbf6b6`	純函式 `ar_import/`（ao_alignment / aggregation / evidence_matcher）
`bee7e139`	佐證 matcher（精確/模糊/無配對 + `(同N)` 交叉引用）
`84b0926a`	AR service 擴充 + error codes
`8105c7ce`	parse / preview
`08d37743`	confirm_import
`22346aeb`	route + DI wiring
`108af39a`	pin jedi-oscal-v2 2.2.0
`fc566d26`	實作計畫
`5b024097` / `5a522a29`	design 更新
`72d377fb`	fix identity-first 兩代 catalog（AG 式 / 舊 NIST 式共存）
`43c3c4d8`	fix 避開 return_response 頂層 meta 魔法分支（meta → report_meta + 契約測試）
`f7ac04df`	feat 佐證分級配對接上（每控制候選佐證池餵 matcher）
`766d8a61`	fix 佐證池跨控制汙染（workflow_execution_control_mapping 權威 scope）
`85b9a1e9`	fix 佐證預覽查無檔案（file_uid 存字串 uid、file_size 用 .size）
`f58701ad`	feat 重匯 = 最新覆蓋（清上一批匯入觀察）

FE（`compliance-manager-fe`）

commit	內容
`f676692`	na 第四態
`6a620a7`	三步 wizard `ArImportDialog.vue`
`16b7931`	report_meta 對齊（配合 BE meta 陷阱修法）
`e80e9d6`	佐證分級配對 UI
`450289e`	代碼美化

套件 jedi-oscal-v2

commit	內容
`5245f29`	release 2.2.0：`FindingState` 加 `NOT_APPLICABLE`；`ArFindingMatrixService` token `not-applicable` + stats `na` 桶（已推 Nexus；該 release 同時含 FR-045 v2.13 PDF parser）

3. 改動範圍

新增檔（BE）

表 oscal.ar_xlsx_parse_jobs + DDD 資料層（grc 模組，表在 oscal schema）
app/grc/service/import_adapter/（共用 registry base + _METHOD_KEYWORDS，自 FR-043 上收）
app/grc/service/ar_report_parser/（亞航 CMMC L1 xlsx adapter）
app/grc/service/ar_framework_profile/cmmc_l1.py（AG→NIST + verdict 詞彙）
app/grc/service/ar_import/（ao_alignment / aggregation / evidence_matcher 純函式）
app/grc/service/ar_xlsx_import_app_service.py（parse/preview/confirm/discard）
api/project/routes/ar_xlsx_import_route.py + api/project/serializers/ar_xlsx_import.py

改動檔（BE）

AssessmentResultAppService（匯入寫入方法對接 + error codes）
grc / root DI container（parse-job + import registry + framework profile + app service）
common/util/response_util.py 使用端避讓（回傳改 report_meta，未動 helper 本身）
docs/claude/domain-capabilities.md（登記 return_response 頂層 meta 陷阱）

FE

src/components/grc/ar-xlsx-import/ArImportDialog.vue（三步 wizard）+ 佐證分級配對 UI
src/service/ArImportService.js + api.js 端點常數
稽核執行頁入口按鈕 + 匯入成功重整；i18n（zh-tw / en）

4. 行為差異（使用者可見）

稽核執行頁（auditing 階段 + manager/auditor + AR 已存在）多一顆「匯入稽核紀錄」按鈕。上傳亞航 xlsx → 三步 wizard：① 控制層判定（AO 聚合成控制層四態）② 逐 AO 觀察 ③ 佐證分級配對（精確自動勾／模糊勾＋徽章／無配對人工補）→ 確認批次寫入：每控制 judge_finding、每 AO create_observation（帶佐證連結）、NOT MET 自動建風險（嚴重度預設「中」）並連結 finding。重傳同輪 xlsx = 最新覆蓋（上批匯入觀察被替換、手動觀察保留）。既有手動流程不變。

5. 五個 STG fix 對照

#	症狀	root cause	修法	commit
1	交集空、誤觸 GRC_400095	兩代 catalog 格式共存、無條件 AG_TO_NIST	identity-first candidate resolution	`72d377fb`
2	preview `data: null`	return_response 頂層 meta 魔法分支丟其餘欄位	meta → report_meta + 登記陷阱	`43c3c4d8` / `16b7931`
3	稽核頁佐證顯示不出	control-tree 池吸別控制同名證據、matcher 誤配	workflow_execution_control_mapping 二次 scope	`766d8a61`
4	佐證預覽查無檔案	數字 file_id 誤存進 file_uid（端點要字串 uid）	file_uid 存字串 uid、file_size 用 .size	`85b9a1e9`
5	重傳觀察累加重複	observation 累加語意 vs 匯入應覆蓋	import_summary 追蹤 observation_uids、confirm 前清上批	`f58701ad`

詳見 docs/analysis/2026-07-04-fr044-stg-bugfix-decisions.md。

6. 部署狀態

DB migration：ar_xlsx_parse_jobs 已套 DEV + STG（STG 另補 FR-043 ap_docx_parse_jobs 落後的 2 支）；POC / PROD 待套
套件：jedi-oscal-v2 2.2.0 已推 Nexus；主專案 pin 2.2.0
git：BE + FE + 套件所有 commit 皆未 push（等 user 明示）
BE 無 hot reload → 部署重啟；FE 重新 build

7. 已知 follow-up

POC DB migration 未套（ar_xlsx_parse_jobs；PROD 亦待）
push 待 user 明示（BE / FE / 套件三 repo）
FR-045 隨 jedi-oscal-v2 2.2.0 一起出（v2.13 PDF parser 同 release，發版時一併注意）
佐證 manual-from-full-pool 未做：無配對 AO 目前只能人工補該控制 scope 內的佐證，尚未支援從全池手選（後續 UX 增強）
e2e 測試待補（compliance-manager-test repo）

8. 測試狀態

BE pytest：adapter snapshot / 純函式（ao_alignment / aggregation / evidence_matcher）/ app service 各套件綠
STG 實測 round c80f1e51（v2.13 AG 式 catalog）：user 逐輪手測，五個非直觀 bug 已修並驗證
e2e：延後至手測後補

9. 規範文件清單

✅ 設計規格 design.md
✅ 前置研究 docs/analysis/2026-07-03-ar-import-verdict-mapping.md
✅ 實作計畫 implementation-plan.md
✅ STG bugfix 決策 docs/analysis/2026-07-04-fr044-stg-bugfix-decisions.md
✅ changelog docs/changelog/2026-07-04-feat-fr044-ar-xlsx-import.md（+ 4 份 fix/feat 分主題）
✅ 陷阱登記 docs/claude/domain-capabilities.md（return_response 頂層 meta）
✅ 本 SUMMARY