稽核計畫填寫頁（AP Authoring）

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

事實基準：2026-07-05 從 FE / BE code 掃出（FR-038 v2 round-based + FR-040 行程鉤稽架構）；API schema 逐條對照 api/project/serializers/audit_round.py 與 app/grc/service/assessment_plan_app_service.py

1. 功能描述

稽核計畫填寫頁是稽核輪次 audit_planning 階段的主工作區：稽核員（auditor）在此定義本輪的 AP（Assessment Plan，評估計畫）——要查哪些控制項、用什麼行程與查核方法進行、實地會碰到哪些受評對象、由哪些稽核人員執行。編輯對象是輪次的 AP 文件（oscal.assessment_plans），其 import_ssp_id 指向 launch-audit 當下凍結的 SSP 快照（見 _overview §4）；start-auditing 推進後 AP 凍結、本頁轉唯讀。

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

角色速覽（完整定義與 manager 全域代行慣例見 _overview §3；本群主角是 auditor）：

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

UC（§2）展開本頁所有具實質後端邏輯的功能：行程規劃（1，含 2~5 / 7 的鉤稽與儲存）、就地新增稽核人員（6）、DOCX 匯入（10）、階段推進 / 啟動稽核（11）。受評控制項 / 受評對象兩 tab（8 / 9）是行程選取的唯讀投影（BE _backfill_scope_from_tasks 回填），非獨立編輯；唯讀模式（12）是頁面狀態切換——兩者屬純顯示，見 §4 / §6.1。生成草稿（generate-draft）是啟動稽核時的內部產物、非本頁常態操作（規格見 §6.3）。

2. Use Case

角色速覽（完整定義與 manager 全域代行慣例見 _overview §3；本群主角是 auditor）：

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

UC-AP-01 規劃稽核行程並儲存

UC-AP-02 就地新增稽核人員

UC-AP-03 稽核紀錄 DOCX 匯入

UC-AP-04 推進階段（啟動稽核）

3. 權限矩陣

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

本頁 FE / BE 權限對齊良好（與專案規劃頁的三層遞進不一致不同）：兩端都用「audit_planning 階段 + auditor/manager」判定，且 BE assert_round_phase 硬擋——過階段直接打 API 也會被 412 擋，不像專案規劃頁 SSP 寫入可繞過（見 _overview §5 坑 2）。

4. 狀態機與前置條件

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

5. UI 設計

版面骨架與區塊職責（TabView 三 tab；Tab0 行程卡在 editable / readonly 兩態 v-if 切換；彩色區塊可點跳對應小節錨點，API 僅標代表性）：

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

稽核紀錄 DOCX 匯入 dialog 截圖從缺：該匯入動作僅在 audit_planning（規劃中）階段開放，2026-07-05 盤點 STG 全庫無任何存活專案處於此狀態，暫無真實資料可拍。

狀態呈現：每個儲存動作 per-按鈕 spinner（savingTasks / savingParty）；無 socket，儲存後靠前端 state 更新（saveTasks 會依日期重排行程並刷新畫面）。DOCX 匯入成功後整頁重載。方法標籤 i18n key lang.ap_authoring.method_<value>，缺翻譯時顯示原始碼。

6. API 規格

Envelope：成功 {"code": 1, "data": …}、失敗 {"code": 0, "msg": "…"}（見專案根 CLAUDE.md Response Format）。

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

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

6.2 載入類

[GET] /audit-round/{round_uid}/ap

本輪 AP 明細，頁面據此填三 tab。無 query 參數。Response data：

Task 節點（tasks[] 每項）：

出處：app/grc/service/assessment_plan_app_service.py:268-281（AP detail 組裝）

6.3 AP 寫入類（全量覆寫）

[PUT] /ap/{ap_uid}/tasks

行程 + 方法（全量覆寫：送出的陣列即最終狀態，未列入即刪除）。Request：

副作用：_backfill_scope_from_tasks（assessment_plan_app_service.py:564-589）把所有行程的 controls / subjects 聯集回填 ap_reviewed_controls / ap_assessment_subjects——故受評控制項 / 對象兩 tab 是行程的投影，不需另存。Response：完整 AP detail（同 §6.2）。出處：serializer SetTasksRequest（api/project/serializers/audit_round.py:91-96，其行項 schema _TaskItem 在 :65-88）、service set_tasks（assessment_plan_app_service.py:501-562）

[PUT] /ap/{ap_uid}/reviewed-controls

查核控制項全量覆寫。Request（control_ids required、不可為空，為空回 GRC_AP_REVIEWED_CONTROLS_REQUIRED）：

{ "control_ids": ["string"] }

Response：

{ "ap_uid": "string", "reviewed_control_count": 0 }

出處：serializer SetReviewedControlsRequest（audit_round.py:19-24）、service set_reviewed_controls（assessment_plan_app_service.py:464-474）

[PUT] /ap/{ap_uid}/assessment-subjects

抽查對象全量覆寫。Request：

{
  "subjects": [
    {
      "subject_type": "string",  // OneOf: component / inventory-item / location / party / user
      "subject_uuid": "string",
      "include": true,
      "title": "string"
    }
  ]
}

Response：

{ "ap_uid": "string", "subjects": [] }

出處：serializer SetAssessmentSubjectsRequest（audit_round.py:27-46）、service set_assessment_subjects（assessment_plan_app_service.py:476-499）

[POST] /audit-round/{round_uid}/ap/generate-draft

從輪次凍結 SSP 重生 AP 草稿（clone Profile 控制項成 AP tasks/AO）。無 body。前置：輪次有凍結 ssp_id、非 close-out 輪。Response：完整 AP detail。出處：assessment_plan_app_service.py:591-613

6.4 稽核人員類

[GET] /ap/{ap_uid}/parties

Response data（陣列，每項）：

出處：assessment_plan_app_service.py:633-641

[POST] /ap/{ap_uid}/parties

就地新增稽核人員。Request：

Response：

出處：serializer ApPartyAddRequest（audit_round.py:99-110）、service add_ap_party（assessment_plan_app_service.py:643-672）

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

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

DDD 提醒：AP 寫入 API 都照層級走（route 不碰 DB、app service @transaction、resolve_ap_and_check_auditor + assert_round_phase 雙檢查）——這是本群 phase-guard 的正確樣板，新增本群寫入 API 照抄。

9. DB

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

9.2 ER 圖（本頁讀寫範圍）

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

oscal.assessment_plans — AP 文件 root

一份 AP = 「要評估哪份 SSP、評估哪些控制項、用什麼活動與排程」。GRC 專案啟動時即建立並從 Profile clone 控制項。required=[uuid, metadata, import-ssp, reviewed-controls]。

oscal.ap_reviewed_controls — 查核範圍（1:1）

assessment-plan.reviewed-controls（AP root required）：本次評估涵蓋哪些控制項。對 AP root 是 required [1]——建 AP 時必同 transaction 建一筆（應用層保證）。

oscal.ap_tasks — 行程（task）

assessment-plan.tasks[]：評估工作項。required=[title, type, uuid]。

oscal.ap_assessment_activities — 查核方法（activity）

local-definitions.activities：可重用評估活動。查核方法存 props（{name:method, value:EXAMINE…}）、per-方法指引存 steps、鉤稽控制項存 related_controls。required=[description, uuid]。

oscal.ap_assessment_subjects / ap_task_subjects — 抽查對象

ap_assessment_subjects（AP 層彙整）與 ap_task_subjects（FR-040 行程層 link，task.subjects[] 的 SoT）欄位對稱：

oscal.ap_task_participants — 行程參與人員（FR-040）

task.responsible-roles[] 的 SoT。

oscal.parties — 稽核人員

metadata.parties[]：以 metadata_id 掛在 AP 文件下。就地新增的稽核人員即寫此表。

10. 頁面邏輯與資料對應

載入時序：

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

儲存流程：「儲存行程」= 單一 PUT /ap/{apUid}/tasks 全量覆寫，BE 連帶回填受評範圍；saveTasks 後前端依日期重排行程並更新 state（不重拉）。受評控制項 / 對象兩 tab 是 computed 投影，切過去才看到最新彙整（無自動刷新）。就地新增稽核人員：POST 後 fetchApParties() 重載並自動選入觸發行程。

錯誤對應：BE error envelope → toast；常見碼 GRC_NOT_AUDITOR（403，非稽核員）、GRC_ROUND_PHASE_READONLY（412，過階段）、GRC_AP_REVIEWED_CONTROLS_REQUIRED（412，查核控制項空）、GRC_AP_PARTY_NAME_EXISTED（409，稽核人員同名）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. phase guard BE 硬擋：AP 寫入只在 audit_planning，過階段直接打 API 也回 412（與專案規劃頁 SSP 寫入可繞過不同，見 _overview §5 坑 2）
2. 行程是唯一編輯面，受評範圍是投影：受評控制項 / 對象兩 tab 唯讀，由 _backfill_scope_from_tasks 從行程聯集回填；想加控制項要去行程勾，不是在 Tab1 加
3. 全量覆寫語意：PUT /ap/{apUid}/tasks 送出的陣列即最終狀態——漏帶某行程 = 刪除該行程；reviewed-controls 送 [] 會被 412 擋（不可為空）
4. timing 正規化：FE 單一 Calendar → 一律送 {on-date:{date: ISO 帶時區}}；BE 可能回 within-date-range，FE 讀取時取第一個可用字串（RoundApAuthoringView.vue:490-509）
5. subject registry 是記憶體 map：行程對象標籤靠 subjectRegistry 快取，候選未預載時可能顯示 UUID 而非名稱
6. 就地新增稽核人員 vs SSP parties：AP parties（稽核人員，可就地新增）與 SSP parties（受評方人員，唯讀）是兩組；FE 無交叉使用防呆，BE 靠 metadata_id scope 分離
7. 方法 i18n 缺翻譯顯示原始碼：system_menu 新增方法時 FE 直接顯示，但 lang.ap_authoring.method_<value> 缺 key 前顯示原始 value（如 EXAMINE）
8. engagement 共用 AP：覆核輪（close-out）不另開 AP，launch-reverify 走 clone_ap_for_round（party uuid 依 name remap）；generate-draft 對 close-out 輪擋下
9. date-only 顯示 08:00 陷阱：行程時間欄位若吐 YYYY-MM-DDTHH:MM:00 無 tz，前端顯示留意（見 專案管理群 _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 / 部署文件）
• 導航路徑：登入 → 專案 → 進入 audit_planning 狀態的輪次 → 稽核計畫填寫
• 前置資料：輪次需已 launch-audit（有凍結 SSP + AP）；沒有 AP 先 generate-draft 或走 launch-audit 自動生成
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；以 稽核計畫 / ap-authoring 搜尋
• 相關文件：FR-038（v2 遷移，docs/features/FR-038-2606-oscal-redesign/）、FR-040（行程鉤稽模型）；稽核執行頁見 稽核執行頁 / AR 判定；DB / API 全量見 GAI-SD-02/03