# 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