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

設計見同夾 design.md。原則：先文件後 code；每階段先跑 pre-flight 驗假設再動。 實作序 A → B → C（C 依賴 A）；每階段 user 手測通過才進下一階。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 規劃的方法 + 指引。

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 看得到。

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 連結正確。

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

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