POA&M 矯正頁（Plan of Action & Milestones）

功能群：稽核執行｜階段轉換、AP→AR→POA&M 資料模型、角色基調先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出（FR-038 v2 round-based，POA&M 由 AR finalize 生成）；API schema 逐條對照 api/project/serializers/audit_round.py 與 app/grc/service/poam_app_service.py

1. 功能描述

POA&M 矯正頁是稽核輪次 remediation 階段的主工作區：AR finalize 時把 not_met 缺失自動生成 POA&M items，本頁由專案經理管理每項缺失的矯正計畫（remediation / response）與里程碑（milestone），追蹤到全部結案後 close-round。POA&M 內容承接 AR 的 findings / risks / observations（見 _overview §4），本頁只在 remediation 階段可寫。

主要使用者：專案經理（manager）。里程碑可指派給任何使用者執行整改，但編輯 POA&M 結構是 manager 的職責。

角色速覽（完整定義見 _overview §3）：

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

UC（§2）已展開本頁所有具實質後端邏輯的功能：矯正計畫 + 里程碑管理（5/7/8，UC-PM-01）、刪除矯正計畫含 recommendation 保護（6，UC-PM-03）、完成改善 close-round（11，UC-PM-02）。純顯示 / 唯讀 / 導覽類（1 概況、2 清單、3 篩選、4 抽屜開啟、9 缺失脈絡、10 證據、12 唯讀模式）見 §5 / §10；缺失脈絡 / 證據是承接 AR 的唯讀檢視、於此不重複展開。

2. Use Case

角色速覽（完整定義見 _overview §3）：

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

UC-PM-01 管理矯正計畫與里程碑

UC-PM-02 完成改善（close-round）

UC-PM-03 刪除矯正計畫（recommendation 保護）

3. 權限矩陣

專案層角色基調見 _overview §3。本頁編輯者是 manager（與 AP/AR 頁的 auditor 不同）：

本頁 FE / BE 權限對齊良好：兩端都以 remediation 階段 + manager 判定；BE assert_round_phase 硬擋過階段寫入（見 _overview §5 坑 2）。

4. 狀態機與前置條件

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

5. UI 設計

版面骨架與區塊職責（左 POA&M 項目表，點列開右明細抽屜三 tab；彩色區塊可點跳對應小節錨點，API 僅標代表性）：

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

項目明細抽屜（矯正措施 tab）、里程碑編輯、缺失脈絡 / 證據 tab 三張截圖從缺：2026-07-05 盤點 STG 全庫，目前無任何存活專案的輪次有 POA&M 項目（project_audit_rounds.poam_id 全為空），暫無真實資料可拍；待有缺失改善資料再補。

狀態呈現：里程碑狀態點三態色（open / in_progress / done），可點循環（canEdit 時）；目標日逾期 / 近期加警示樣式；per-操作後重載明細 + 列表（無 socket）。負責人以頭像 + nickname 顯示（BE 層 enrich，見 §11）。

6. API 規格

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

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

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

6.2 載入類

[GET] /audit-round/{round_uid}/poam-items

Response data.poam_items[]（陣列，每項）：

出處：app/grc/service/poam_app_service.py::list_items（回傳 dict :256-270、狀態推導 :196-197、deadline :200-206）

[GET] /audit-round/{round_uid}/poam-item/{item_uid}

Response data：項目明細，含 risks[]（每風險其 remediations[]，每 remediation 其 milestones[]）、observations[]（缺失脈絡）——證據承接 AR、巢狀掛在每筆 observations[].relevant_evidence[]，無頂層 evidence[] key（poam_app_service.py:301-309）。

milestone 物件（已 enrich 負責人）：

出處：poam_app_service.py::get_item（milestone enrich :237-245、脈絡 :140-158）

6.3 寫入類

[POST] /audit-round/{round_uid}/ar/risk/{risk_uid}/remediations

Request：

{
  "title": "string",       // 必填
  "description": "string",  // 必填
  "lifecycle": "planned",   // 預設 planned
  "uuid": "string"          // 選填，upsert
}

Response：

{
  "uid": "string",
  "risk_uid": "string",
  "title": "string",
  "description": "string",
  "lifecycle": "string",
  "milestone_count": 0
}

出處：serializer CreateRemediationRequest（audit_round.py:190-198）、service add_remediation

[POST] /audit-round/{round_uid}/remediation/{remediation_uid}/milestones

Request：

Response：enrich 後的 milestone（同 §6.2）。出處：serializer AddMilestoneRequest（audit_round.py:200-210）、service add_milestone（assignee 解析 :75-89）

[PUT] /audit-round/{round_uid}/poam-milestone/{milestone_uid}

Request（全欄選填 partial）：

狀態循環（狀態點點擊）= 只送 {status}。出處：serializer UpdateMilestoneRequest（audit_round.py:212-224）、service update_milestone

DELETE /poam-milestone/{uid}（刪里程碑）、DELETE /remediation/{uid}（刪 response + 其里程碑，recommendation 型回 GRC_POAM_RECOMMENDATION_PROTECTED）同檔。

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

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

DDD 提醒：POA&M 寫入 API 照層級走（route 不碰 DB、app service @transaction、_check_manager + assert_round_phase 雙檢查）——與 AP/AR 頁一致的 phase-guard 樣板。負責人 nickname / org_unit name 在 app service 層 enrich（不存 DB、不在 infra JOIN，符合 CLAUDE.md 審計欄規範）。

9. DB

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

9.2 ER 圖（本頁讀寫範圍）

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

oscal.poams — POA&M 文件 root

追蹤評估後待矯正的缺失；內容多由 AR 的不符合 findings 轉入。required=[uuid, metadata, poam-items]；import-ssp 選填。

oscal.poam_items — 矯正項目

plan-of-action-and-milestones.poam-items[]。required=[description, title]（uuid 選填）。

oscal.assessment_remediations — 矯正計畫（response）

risk.remediations[]（response）關聯化：milestone 掛在 response 下（OSCAL-faithful），非直接掛 risk。CMMC 多為一風險一整改計畫。

oscal.poam_milestones — 里程碑

response.tasks[]（type=milestone）。掛在 remediation(response) 下。per-milestone assignee 支援跨部門整改拆分。

10. 頁面邏輯與資料對應

載入時序：

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

儲存流程：各寫入後重載明細（loadDetail）+ 列表（fetchItems）以刷新推導狀態；狀態點循環 = 單一 PUT {status}。close-round 由 FlowPhaseBanner 觸發（先 BE 檢查全 item closed）。

錯誤對應：BE error envelope → toast；常見碼 GRC_NOT_MANAGER（403）、GRC_ROUND_PHASE_READONLY（412，過階段）、GRC_POAM_NOT_ALL_CLOSED（412，close 前置）、GRC_POAM_RECOMMENDATION_PROTECTED（409，刪稽核建議）、GRC_PROJECT_PARTICIPANT_NOT_FOUND（404，指派非參與者）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. POA&M item 狀態不存 DB、讀時推導：全里程碑 done → item closed，否則 open；改最後一個里程碑成 done 會讓 item 自動結案（無「結案 item」單獨動作）
2. recommendation-lifecycle response 受保護：稽核員在 AR 階段建的矯正建議（lifecycle=recommendation）不可在 POA&M 刪，回 GRC_POAM_RECOMMENDATION_PROTECTED；只有自建（planned）可刪
3. phase guard BE 硬擋：POA&M 寫入只在 remediation，過階段直接打 API 也回 412（見 _overview §5 坑 2）
4. close-round 前置全 item closed：任一 item open 即 GRC_POAM_NOT_ALL_CLOSED；close-round 由 banner 觸發、非本頁按鈕
5. assignee 傳 uid 不傳 id：FE 送 assignee_user_uid，BE 轉 user_id（非參與者 → GRC_PROJECT_PARTICIPANT_NOT_FOUND）；回傳 enrich nickname
6. 里程碑父層是 remediation 不是 risk：OSCAL-faithful，加里程碑要先有 response；CMMC 常一風險一 response，UI 建風險時可帶預設 response
7. 證據 / 缺失脈絡承接 AR：POA&M 的 observations / findings owner = poam_id，內容源自 AR finalize 轉入；本頁唯讀不改
8. date-only 目標日顯示：target_date 為 date 型（無時間），顯示留意時區慣例（見 專案管理群 _overview）

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 / 部署文件）
• 導航路徑：登入 → 專案 → 進入 remediation 狀態的輪次 → POA&M 矯正
• 前置資料：輪次需已 AR finalize 且有 not_met 缺失（才會生成 POA&M items）；沒有 not_met 則輪次直接 closed、不進本頁
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 POA&M / poam / 矯正 搜尋
• 相關文件：FR-038（v2 遷移，POA&M 生成）；前置稽核判定見 稽核執行頁 / AR 判定；DB / API 全量見 GAI-SD-02/03