# FR-041 稽核結果（AR）填寫優化 — 實作計畫

> 設計見同夾 `design.md`。原則：先文件後 code；每階段先跑 pre-flight 驗假設再動。
> 實作序 **A → B → C**（C 依賴 A）；每階段 user 手測通過才進下一階。AR 是敏感管線，逐塊上、不一次全炸。

## Phase A — 繼承 AP 查核指引進 AR（小、零破壞先行）

### A.0 Pre-flight
1. **AR control detail / findings API 餵 FE 中欄的資料路徑**：`assessment_result_app_service.get_findings` 與 control-detail 端點回什麼；FE `AuditControlRef` 的 `controlDetail`/`controlMeta` 從哪來（決定規劃指引塞哪個欄位回前端）。
2. **AR init 現況**：`init_ar_matrix_for_round` / `_assessment_log_from_tasks` 實際 echo 哪些；AP activities（steps/props/related_controls）怎麼依控制項取（control-id 對 activity.related_controls）。
3. **snapshot 落點**：規劃脈絡塞 `assessment_log` entry vs 新 `planning_context` JSONB —— 傾向不動 schema（塞 assessment_log 或 detail API 即時組）。確認 AR 是否要「凍結」規劃（snapshot）還是「即時讀 AP」（若 AP 已凍結則即時讀亦可）。

### A.1 BE
- AR 讀取依控制項回傳規劃脈絡：`{control_id: {methods, guidance:[{method, description}], subjects}}`，由 AP activities 組（steps→guidance、props→methods、related_controls→control 對應）。
- 落點依 A.0.3：優先在 control-detail/findings API 即時組（不動 schema）；若要 snapshot 才寫 AR init。

### A.2 FE
- `AuditControlRef` 加「規劃查核指引」區（唯讀）：方法 chip + 各方法指引文字。
- 資料接 A.1；i18n 補標題（zh-tw + en）。

### A.3 測試 + 驗收
- BE：規劃脈絡組裝（含無指引/無 AO fallback）單元測試。
- 手測：判定頁選控制項 → 中欄看得到 AP 規劃的方法 + 指引。

## Phase B — 缺失 → 風險 → 矯正打通

### B.0 Pre-flight
1. **Risk 模型欄位**：jedi_oscal_v2 `risk`/AR risk entity 有哪些欄（severity 確定有；驗有無 remediation/影響欄）；既有 risk 端點 payload（`POST /risks`、`PUT /risk/{uid}`、`/risk/{uid}/findings`）。
2. **POA&M 生成路徑**：`poam_app_service` close round 生成 POA&M 時讀 finding 還是 risk、帶哪些欄（決定矯正建議/嚴重度怎麼流進去）。
3. **finding↔risk link**：既有 `risk.linked_findings` 機制（FE `notMetControls` → risk sources）。

### B.1 BE
- risk 加「矯正建議 / remediation」承載（schema 有欄用欄、無則 props 或套件補；對齊 OSCAL `risk.remediation`/POA&M item）。
- POA&M seed 讀 risk 的 severity + remediation（依 B.0.2）。

### B.2 FE
- 判定區 `not_met` → 就地展開風險小表單（嚴重度 + 風險/影響描述 + 矯正建議）；存判定一併 upsert risk + link 該 finding（沿用既有端點）。
- 「風險」分頁保留為總覽。

### B.3 測試 + 驗收
- BE：risk remediation 存讀；POA&M seed 帶 severity/remediation。
- 手測：判定 not_met → 就地開風險+矯正 → 風險分頁/POA&M 看得到。

## Phase C — 觀察引導化（依賴 A）

### C.0 Pre-flight
1. **observation 端點/欄位**：`POST /observations`（description/methods/subjects/relevant_evidence）能否標記「對應哪個規劃方法」（用 methods 即可？需 props？）。
2. **evidence 來源**：`loadEvidence`（job 檔/問卷/Drive）的結構，作為「證據引用」下拉母體。

### C.1 FE（主要）
- 右欄觀察區改：照 A 帶進的規劃方法逐項列「看到什麼 + 證據引用 + 對象」；存 observation（methods 預填該項）。保留額外自由觀察入口。

### C.2 BE
- 原則零新欄（沿用 observation）；必要時 props 標記規劃方法對應。

### C.3 測試 + 驗收
- 手測：照規劃方法逐項記觀察+證據 → 重整還原 → finding 連結正確。

## DB / 套件異動（全 feature）
- **目標零新表**；A 傾向不動 schema（即時組規劃脈絡）。
- B 若 risk 缺 remediation 欄 → jedi_oscal_v2 補（dev symlink/path-dep，發版等 user 明示）。
- C 原則零 schema。

## 收尾（每階段 user 下令才做）
- changelog（type=feat）各階段一份：A 繼承指引 / B 風險矯正串接 / C 觀察引導化。
- design.md §10 狀態更新；Notion 任務；push 等 user。