稽核執行頁 / AR 判定（Audit Review）

功能群：稽核執行｜階段轉換、AP→AR→POA&M 資料模型、AO 判定粒度先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出（FR-038 v2 round-based B5 AR + FR-041 稽核指引 + FR-044 稽核紀錄匯入）；API schema 逐條對照 api/project/serializers/audit_round.py 與 app/grc/service/assessment_result_app_service.py

變更紀錄

1. 功能描述

稽核執行頁是稽核輪次 auditing 階段的主工作區：稽核員逐一檢視在範圍控制項的證據，做出判定（met / not_met / pending）、記錄觀察（observation）、把不符合項組成系統風險（risk），最後 finalize 產出 AR（Assessment Results，評估結果）。判定的控制項母體來自凍結 SSP 快照；finalize 時 not_met 缺失自動生成 POA&M（見 _overview §2 / §4）。

本頁為 TabView 兩 tab 的導航 hub：Tab0「控制項稽核判定」（三欄判定工作區）與 Tab1「風險」（系統風險管理）各自的 field-level 逐欄規格拆成子頁；頁級 chrome（頂部統計徽章、FlowPhaseBanner finalize 推進、稽核紀錄 XLSX 匯入鈕、非 auditing 階段的整頁唯讀）與跨子頁共用的狀態機／權限基調留在本頁。

主要使用者：稽核員（auditor）、專案經理（manager，可代行）。

角色速覽（完整定義見 _overview §3；本群主角是 auditor）：

1.1 功能總覽（本頁全部功能）

本頁是 hub（頁級 chrome + 兩 tab 導航）：Tab0 判定工作區（樹 / 參考面板 / 判定 + 觀察）與 Tab1 風險管理各自的 field-level 逐欄規格拆成子頁，見「詳述」欄連結。

展開成 UC：判定 + 觀察（3/4/5）與內嵌風險見 稽核判定工作區 UC-AR-01；系統風險與關聯（8/9）見 稽核風險管理 UC-AR-02；本 hub 保留 finalize（11，UC-AR-03）與稽核紀錄 XLSX 匯入（10，UC-AR-04），因兩者是頁級（跨 tab）動作。純顯示 / 導覽類（1 樹導覽、2 參考面板、6 證據瀏覽、7 統計徽章、12 唯讀模式）不另開 UC。

2. Use Case（本頁保留 finalize / 匯入）

角色速覽（完整定義見 _overview §3；本群主角是 auditor）：

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

判定 + 觀察的 UC-AR-01 見 稽核判定工作區 §2；系統風險與關聯的 UC-AR-02 見 稽核風險管理 §2。本 hub 保留兩條跨 tab 的頁級動作 UC：

UC-AR-03 Finalize 結案判定

UC-AR-04 匯入稽核紀錄 XLSX 批次帶入判定 / 觀察

3. 權限矩陣

專案層角色基調見 _overview §3。本頁檢查點（FE / BE 對齊，phase guard BE 硬擋）：

判定 / 觀察 寫入的權限詳述見 稽核判定工作區 §3；風險寫入見 稽核風險管理 §3。

本頁 FE / BE 權限對齊良好：兩端都以 auditing 階段 + auditor/manager 判定；BE assert_round_phase 硬擋——過階段直接打 API 仍回 412（見 _overview §5 坑 2）。

4. 狀態機與前置條件

輪次狀態機見 專案管理群 _overview §2；本群階段轉換與 finalize 分歧見 _overview §2。本頁（頁級）相關 gate：

判定工作區 tab 內的樹 / 判定 gate 見 稽核判定工作區 §4；風險 tab 的 finalize 前置關聯規則見 稽核風險管理 §4。

5. UI 設計

實機截圖（STG，亮色模式，2026-07-05，帳號 blsadmin，專案「亞○ CMMC L1 合規」/ auditing 輪次）：

狀態呈現（頁級）：頂部統計徽章 met / not_met / not_applicable / pending 四色計數 + 進度文字（來源 stats）；非 auditing 階段整頁蓋唯讀 banner（Message）並禁用所有寫入表單。無 socket，各動作後手動重取（判定後 refreshStats）。Tab0 / Tab1 各自的狀態呈現（樹色點、per-按鈕 spinner、證據 lazy 快取）見各子頁 §5。

6. API 規格

Envelope：成功 {"code": 1, "data": …}、失敗 {"code": 0, "msg": "…"}。

6.1 總清單（本頁呼叫的全部 endpoint）

判定 / 觀察 的完整 request/response 見 稽核判定工作區 §6；風險 / 風險關聯見 稽核風險管理 §6。以下 §6.2 為本 hub 專屬（跨 tab）的 finalize endpoint 完整規格。

6.2 結案類（本 hub 專屬）

[POST] /audit-round/{round_uid}/ar/finalize

無 body。完整性檢查：stats.pending==0（否則 GRC_VERDICT_INCOMPLETE）、每 risk 至少 1 finding（否則 GRC_RISK_NO_FINDING_LINKED）。通過後依 not_met 數分歧。Response data：

出處：app/grc/service/audit_round_app_service.py::finalize_audit:422-462 → assessment_result_app_service.py::finalize_assessment:795-822；POA&M 生成 PoamService.generate_from_findings。

7. 前端檔案地圖（compliance-manager-fe/）

Tab0 判定工作區元件（AuditTreeNav / AuditControlRef / EvidencePreviewDialog）見 稽核判定工作區 §7；Tab1 風險元件見 稽核風險管理 §7。

8. 後端檔案地圖（本頁核心鏈路）

判定矩陣 / 判定寫入 / 觀察鏈路見 稽核判定工作區 §8；風險鏈路見 稽核風險管理 §8。

DDD 提醒：AR 寫入 API 都照層級走（route 不碰 DB、app service @transaction、_check_auditor + assert_round_phase 雙檢查）——與 AP 頁一致的 phase-guard 樣板。

9. DB

9.1 資料表總清單（本頁讀寫的全部表）

9.2 ER 圖（本頁讀寫範圍）

核心表（assessment_results / ar_results / assessment_findings / assessment_observations）欄位卡見 稽核判定工作區 §9.3；assessment_risks / assessment_finding_risks 欄位卡見 稽核風險管理 §9.3。

10. 頁面邏輯與資料對應

載入時序：

頁級關鍵欄位對應（畫面 ↔︎ API）：

Tab0 判定 / 觀察的欄位對應見 稽核判定工作區 §10；Tab1 風險欄位對應見 稽核風險管理 §10。

頁級儲存流程：判定後 refreshStats（重取統計）驅動頂部徽章與樹範圍；finalize 走 POST ar/finalize，成功後輪次階段變更由 FlowPhaseBanner 反映。

錯誤對應：BE error envelope → toast；頁級常見碼 GRC_VERDICT_INCOMPLETE（412，finalize 有 pending）、GRC_RISK_NO_FINDING_LINKED（412，風險未關聯）。412 由 axios interceptor → event bus → App.vue toast 統一處理。判定 / 風險 tab 內的錯誤碼見各子頁 §10。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. phase guard BE 硬擋：AR 寫入只在 auditing，過階段直接打 API 也回 412（見 _overview §5 坑 2）
2. verdict 值 API↔︎DB 映射：API met/not_met/pending、DB target_status_state 存 satisfied/not-satisfied、pending 落 target_status JSONB；比對兩邊都要看（_overview §5 坑 4）。詳見 稽核判定工作區 §12
3. 判定 AO 層 / 顯示與 POA&M 控制項層：stats 有 met/not_met/pending（AO 計數）與 controls_with_not_met（控制項計數）兩套；控制項 verdict 由 AO roll-up（任一 AO not_met → 控制項 not_met）
4. risk severity 存 JSONB：assessment_risks 無 severity 欄，等級在 characterizations（_overview §5 坑 5）。詳見 稽核風險管理 §12
5. finalize 前置雙檢查：無 pending + 每風險至少 1 finding，缺一即 412。判定存檔後風險來源清單已自動刷新（2026-07-09 FR-047 六項#4）——saveVerdict 收尾 await fetchFindings() 重建 findingByControl → notMetControls 依伺服器真相重算，不再停留在改判定前的過時清單
6. i18n namespace 與檔名不齊：本頁讀 lang.round_audit.* namespace，但檔案為 audit-review.json（key 為 audit_review）；round_audit key 定義在 round-audit-poam.json——動本頁 i18n 前先確認 namespace↔︎檔案對應，勿只看檔名
7. 證據自包含 + lazy 快取：觀察 relevant_evidence 內含 file 中繼資料（供 POA&M 免 N+1）；證據 per-控制項 lazy 載入並快取，切控制項可能短暫顯示前一個的快取。詳見 稽核判定工作區 §12
8. engagement 共用 AR：覆核輪不另開 AR root，append 一筆 ar_results；比對 workflow_execution_uid 找輪次是死路（_overview §5 坑 7）
9. 範圍過濾：inScopeTreeGroups 只顯示有 finding 的控制項（AP reviewed-controls 可能縮小 scope），樹上看不到的控制項不代表不存在、是不在本輪範圍

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境稽核員角色帳號（密碼見 .env / 部署文件）
• 導航路徑：登入 → 專案 → 進入 auditing 狀態的輪次 → 稽核執行
• 前置資料：輪次需已 start-auditing（AP reviewed-controls 非空 → 進 auditing，AR 矩陣已初始化）；控制項要有證據才判得動
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 稽核執行 / audit-review / AR 搜尋
• 相關文件：稽核判定工作區（Tab0 判定 / 觀察 / 內嵌風險）、稽核風險管理（Tab1 系統風險與關聯）；FR-038（v2 遷移 B5 AR）、FR-041（稽核指引）、FR-044（稽核紀錄匯入）；稽核計畫填寫見 稽核計畫填寫頁、後續整改見 poam.md（待撰）；DB / API 全量見 GAI-SD-02/03