# FR-044 執行交接 Prompt（設計已核可 → 進入 plan + 實作）

> 產生日期：2026-07-03。設計 session 已完成 design.md（過 spec review 一輪修正，含
> 控制層聚合規則）＋ analysis ＋ FR 登記 ＋ Notion 任務（Case No: FR-044）。
> 以下 prompt 直接貼給執行 session。

---

你是 FR-044「稽核紀錄 xlsx 匯入」的執行工程師。設計已核可（含聚合規則：任一
not_met→not_met／全 na→not_applicable／含 pending→pending／餘含 met+na 混→met），
你的工作是產出 implementation plan、經 user 確認後實作。

## 0. 前提與邊界（違反即錯誤行為）

- 工作 branch：BE `feature/FR-044`（已存在）。**永不切 branch**；FE repo 在當下 branch 作業。
- 可自行階段性 commit（顯式 `git add <檔名>`，禁 `-am`）；**push 永遠等 user 明示**。
- **jedi_oscal_v2 套件異動已核准、範圍限定三件事**（design.md §3）：`FindingState` 加
  `NOT_APPLICABLE`、`ArFindingMatrixService` state↔token 對照加 `'not-applicable'`、
  `list_findings` stats 加 na 桶。**dev 期一律走 poetry path dependency**（主專案
  pyproject.toml 取消註解該套件 path 形式；此改動 dev-only 不 commit），
  **絕不自行發版/推 Nexus**，發版等 user 明示。超出三件事的套件改動 → 停下回報。
- 收尾動作（changelog / SUMMARY / Notion 更新）等 user 下令才做。
- BE 改 code 後提醒 user 重啟 BE；服務由 user 自己起。

## 1. 必讀（依序，開工第一步）

1. BE repo `CLAUDE.md`
2. `docs/features/FR-044-2607-ar-xlsx-import/design.md` — 本功能 single source of truth
3. `docs/analysis/2026-07-03-ar-import-verdict-mapping.md` — 對應依據與決策脈絡
4. FR-043 已實作的匯入管線（直接 mirror 的骨架）：
   `app/grc/service/ap_docx_import_app_service.py`、`app/grc/service/ap_report_parser/`
   （registry ＋ `_METHOD_KEYWORDS`，本 FR 要泛化上收）、`api/project/routes/ap_docx_import_route.py`、
   FE `ApDocxImportDialog.vue`
5. 寫入目標：`app/grc/service/assessment_result_app_service.py`
   （`judge_finding` / `create_observation` / `add_risk` / `link_risk_findings` /
   `_check_auditor` / `finalize_assessment`）、`app/grc/service/ao_derivation.py`
   （`derive_ao_pairs`）
6. FE 動工前：FE repo `CLAUDE.md` ＋ `docs/claude/frontend-overview.md`；
   目標頁 `src/views/project/RoundAuditReviewView.vue`

## 2. Pre-flight verify（寫 plan 前必做）

- [ ] `judge_finding` / `create_observation` / `add_risk` / `link_risk_findings` 實際簽名
  （`create_observation` 需加 optional `collected` 參數 — 確認現狀硬寫 now）
- [ ] jedi_oscal_v2 `FindingState`（common/enum/oscal_enums.py）與
  `ArFindingMatrixService._STATE_TO_TOKEN`（domain/service/ar/）現值
- [ ] `derive_ao_pairs` 回傳形狀與順序穩定性（AO 順序對齊的分母）；
  用樣本專案驗證 15 條控制項 AO 數 = 6/2/6/5/3/3/2/4/6/8/2/6/2/1/3
- [ ] `ssp_excel_parse_job` model 形狀（新表照抄）＋ `_EXCEL_MAX_SIZE`（10MB）
- [ ] 本輪測試專案 profile 的實際 control_id 格式（AG `AC.L1-b.1.i` ↔ catalog 對照表基準）
- [ ] 樣本檔可讀：`/Users/chouraymond/Desktop/AirAsia實際稽核檔案/AP稽核計畫匯入測試檔案/亞航-CMMC L1內部稽核報告附件-稽核紀錄.xlsx`
- [ ] `finalize_assessment` 的 POA&M 掃描 token（`'not-satisfied'`）與
  `stats["pending"]` 前置、FE `judgedCount` 計算式
- 任何一項與 design.md 不符 → 先回報 user，不自行改 spec 硬上。

## 3. 產出 implementation plan

用 `superpowers:writing-plans` skill，輸出到
`docs/features/FR-044-2607-ar-xlsx-import/implementation-plan.md`
（絕不可用 `docs/superpowers/` 預設路徑）。Phase 建議：

- Phase A：jedi_oscal_v2 三件事（path dependency 接上）＋ BE 全測試綠（enum 加值的
  regression）＋ FE verdict 第四態＋i18n＋stats na 卡
- Phase B：`ar_xlsx_parse_jobs` migration（含 tenant_id＋**org_unit_id**、GRANT、
  schema_migrations）＋ entity/repo/DI
- Phase C：共用 import 基建泛化（registry base ＋ `_METHOD_KEYWORDS` 上收
  `app/grc/service/import_adapter/`；**FR-043 測試全綠為 regression 門檻**）＋
  `airasia_cmmc_l1_ar_v1` adapter（TDD：59 列 snapshot、AO 數不一致降級、(同N) 解析、
  一格多名拆分）
- Phase D：`ArImportAppService`＋route＋serializer — 聚合規則、佐證分級配對
  （88 名稱 fixture 調門檻）、風險建立＋`link_risk_findings`＋防重、
  `create_observation` 加 `collected`、gate 提 public helper
- Phase E：FE `ArImportDialog.vue` 三步 wizard＋入口按鈕（stage＋role 雙條件，
  role 需另取 participant）＋draft localStorage
- Phase F：test plan（`feature-test-planner`）＋ e2e（compliance-manager-test repo）

Plan 寫完給 user 過目，核可後才動工。

## 4. 實作紀律

同 FR-043（@transaction／repo lazy session／route 不碰 DB／權限 app service 層
fail-closed／禁重複造輪子／app service test 記得 logger patch fixture）。
SQL migration 用 `cmmgr`、`-p 25432`、先套 DEV。

## 5. 驗收基準（亞航樣本）

上傳樣本 xlsx 後：preview 15 個控制項全部聚合為 met（樣本 59 列全 MET）、
59 筆 observation 預覽（各帶 AO 原文＋方法＋判定尾註）、佐證高信心者自動勾選
（模糊配對帶徽章、無配對灰列）、無風險建立（無 NOT MET）。confirm 後稽核執行頁
15 控制項判定=met、observations 掛對控制項、stats 正確、`finalize_assessment`
可正常推進（不被 pending／risk-no-finding 擋）。另用改造樣本（改幾列 NOT MET／N/A／
留空）驗聚合四規則＋中風險自動建立＋防重。

---
（prompt 結束）