稽核判定工作區（Audit Verdict）

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

事實基準：2026-07-05 從 FE src/views/project/RoundAuditReviewView.vue + AuditTreeNav.vue / AuditControlRef.vue / EvidencePreviewDialog.vue + BE assessment_result_app_service.py / serializer api/project/serializers/audit_round.py 掃出（FR-038 v2 B5 AR + FR-041 稽核指引）

變更紀錄

1. 功能描述

稽核判定工作區是 稽核執行頁 的 Tab0「控制項稽核判定」：三欄版面——左欄控制項樹導覽（AuditTreeNav）、中欄控制項參考面板（AuditControlRef：稽核指引 / SSP 現況 / AO 與各 AO 證據頁籤）、右欄判定面板（verdict SelectButton + 說明、not_met 時內嵌風險、觀察區）。稽核員選中控制項後在右欄逐 AO 做判定（met / not_met / not_applicable / pending），記錄觀察（看到什麼），判定為 not_met 時可就地帶出風險。判定的控制項母體來自凍結 SSP 快照（見 _overview §4）。

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

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

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

展開成 UC：UC-AR-01（判定控制項並記錄觀察，含 not_met 內嵌風險）。系統風險本體管理與跨風險關聯見 稽核風險管理；頁級 finalize / 統計徽章 / 唯讀模式見 稽核執行頁 hub。純顯示 / 導覽類（1 樹導覽、2 參考面板、6 證據瀏覽）於 §5 描述，不另開 UC。

2. Use Case

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

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

UC-AR-01 判定控制項並記錄觀察

3. 權限矩陣

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

內嵌風險（not_met 時）走風險寫入路徑，權限見 稽核風險管理 §3；finalize / 匯入等頁級操作見 稽核執行頁 §3。

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

4. 狀態機與前置條件

輪次狀態機見 專案管理群 _overview §2；本群階段轉換見 _overview §2。本頁相關 gate：

finalize 前置（無 pending / 風險皆關聯）等頁級 gate 見 稽核執行頁 §4。

5. UI 設計

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

狀態呈現：樹節點帶判定色點與 findings 數；判定 per-按鈕 spinner（savingVerdict / savingObs）；證據 lazy 載入並 per-控制項快取。SelectButton 設 unselectable=false 防 null 判定。無 socket，判定後 refreshStats（重取統計，驅動頂部徽章與樹範圍），觀察增改刪後重取對應清單。

6. API 規格

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

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

風險 / 風險關聯端點見 稽核風險管理 §6；finalize / 匯入 / 專案載入端點見 稽核執行頁 §6。

以下 §6.2~6.3 為本頁核心 endpoint 完整規格（欄位逐條對照 serializer / service 組裝碼，出處標在各段末）；標 GAI-SD-02 者屬常規 CRUD，細節見 API 規格書或 Swagger /swagger-ui/。

6.2 載入類

[GET] /audit-round/{round_uid}/ar/findings

AO 全量判定矩陣（控制項分組）。無 query 參數。Response data：

Control 節點（controls[] 每項）：

ao_findings[]（每項）：

observations[]（每項）：

planning（FR-041 稽核指引）：

出處：app/grc/service/assessment_result_app_service.py:385-446（get_findings）。

6.3 判定 / 觀察類

[PUT] /audit-round/{round_uid}/ar/finding/{finding_uid}

存單一 AO 判定（upsert）。Request：

Response data：

verdict 值 API↔︎DB 映射：assessment_findings.target_status_state 直接存 4 種 product token——met→satisfied、not_met→not-satisfied、not_applicable→not-applicable、pending→pending（not-applicable/pending 是 OSCAL 規格外的 product token，直存於同一欄，非落 JSONB）。target_status JSONB 是全狀態鏡射（含 reason）非 pending 專屬。出處：serializer JudgeFindingRequest（api/project/serializers/audit_round.py:114-122）、service judge_finding（assessment_result_app_service.py:509-543）、jedi-oscal-v2 .../domain/service/ar/ar_finding_matrix_service.py。

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

建立觀察（證據引用不複製）。Request：

Response data：

出處：serializer CreateObservationRequest（audit_round.py:125-133）、service create_observation（assessment_result_app_service.py:545-574）。

PUT /ar/observation/{obs_uid}（UpdateObservationRequest，全欄選填 partial update）/ DELETE（解除所有 finding 連結）同檔。

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

Tab1 風險元件見 稽核風險管理 §7。

8. 後端檔案地圖

風險鏈路見 稽核風險管理 §8；finalize / 階段推進鏈路見 稽核執行頁 §8。

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

9. DB

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

風險相關表（assessment_risks / assessment_finding_risks）欄位卡見 稽核風險管理 §9.3。

9.2 ER 圖（本頁讀寫範圍）

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

oscal.assessment_results / ar_results — AR root / 每輪結果

assessment_results 是 AR 文件 root（import_ap_id → AP，NOT NULL）；ar_results 是 results[]（一份 AR 多輪，每輪一筆 result）。

oscal.assessment_findings — 逐 AO 判定

assessment-common finding（AR / POA&M 共用）。owner = ar_result_id 或 poam_id（擇一，應用層保證）。

oscal.assessment_observations — 觀察

assessment-common observation。owner = ar_result_id / poam_id。required=[collected, description, methods, uuid]。

10. 頁面邏輯與資料對應

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

儲存流程：判定 = PUT finding → refreshStats（重取統計）；not_met 內嵌風險同存（新建走 POST risk + PUT risk/findings，既有走 PUT，端點見 稽核風險管理）；觀察增改刪後重取對應清單。findingByControl 用淺拷貝觸發 notMetControls / inScopeTreeGroups 重算。

錯誤對應：BE error envelope → toast；本頁常見碼 GRC_NOT_AUDITOR（403）、GRC_ROUND_PHASE_READONLY（412，過階段）。412 由 axios interceptor → event bus → App.vue toast 統一處理。finalize 相關錯誤碼見 稽核執行頁 §10。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. phase guard BE 硬擋：判定 / 觀察 寫入只在 auditing，過階段直接打 API 也回 412（見 _overview §5 坑 2）
2. verdict 值 API↔︎DB 映射：API FindingState（met/not_met/pending＋第 4 值 not_applicable）；DB target_status_state 直存 4 種 product token satisfied/not-satisfied/not-applicable/pending，target_status JSONB 是全狀態鏡射非 pending 專屬，比對以 target_status_state 為準（_overview §5 坑 4）
3. 判定 AO 層 / 顯示與 POA&M 控制項層：stats 有 met/not_met/pending（AO 計數）與 controls_with_not_met（控制項計數）兩套；控制項 verdict 由 AO roll-up（任一 AO not_met → 控制項 not_met）
4. 證據自包含 + lazy 快取：觀察 relevant_evidence 內含 file 中繼資料（供 POA&M 免 N+1）；證據 per-控制項 lazy 載入並快取，切控制項可能短暫顯示前一個的快取
5. 範圍過濾：inScopeTreeGroups 只顯示有 finding 的控制項（AP reviewed-controls 可能縮小 scope），樹上看不到的控制項不代表不存在、是不在本輪範圍
6. 內嵌風險走風險寫入路徑：not_met 就地帶的風險與 Tab1 是同一批資料，notMetControls 依賴 refreshStats 重算——改完 verdict 未刷新前，風險來源清單可能過時（見 稽核風險管理 §12）

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 狀態的輪次 → 稽核執行 → Tab「控制項稽核判定」
• 前置資料：輪次需已 start-auditing（AR 矩陣已初始化）；控制項要有證據才判得動
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 稽核執行 / audit-review / 判定 搜尋
• 相關文件：上層導航 稽核執行頁；稽核風險管理（Tab1 系統風險與關聯）；FR-038（v2 遷移 B5 AR）、FR-041（稽核指引）；DB / API 全量見 GAI-SD-02/03