FR-040 行程鉤稽控制項/受評對象/參與人員 — 實作計畫

Date: 2026-06-20 · 設計見同夾 design.md · 決策見 docs/analysis/2026-06-20-ap-task-control-subject-linkage.md 原則：先文件後 code；開工前先跑「Phase 0 pre-flight」驗證假設（plan→build 常漂移）。

1. jedi_oscal_v2 ApTasksEntity 確有 associated_activities / subjects / responsible_roles（JSONB）—— 已查屬實。
2. ap_assessment_activities 表/entity 確有 related_controls / props / steps —— 已查屬實。
3. 確認 ap_assessment_activities 的 repo + set/upsert 方法： jedi_oscal_v2/infra/repository/ap/ap_assessment_activities_repo_impl.py 的 CRUD signature （能否 by ap_id 全量覆寫，mirror ap_tasks 的 set_tasks）。
4. 確認 AssessmentPlanAppService.set_tasks / self._ap.set_tasks 的套件 signature （現在只寫 ap_tasks；要擴成同 transaction 內先寫 activities 再寫 tasks）。
5. 確認 control-id 形狀：related_controls.control-selections[].include-controls[].control-id 用的是 OSCAL control-id（如 ac-6.1），跟 Tab1 reviewed-controls 存的 control_ids 同源（verify 一致，否則對不上）。
6. 確認 Tab2 受評對象（ap_assessment_subjects）回前端的 subject 結構（subject_uuid / subject_type / title）， 作為前端 options + payload 來源。
7. 確認專案參與者查詢（auditor/manager party uuid / user uuid）既有 service（FE 受評對象/參與者面板已有類似）。

user 2026-06-21 允許改外部套件。dev 走 poetry path-dependency，feature 完成才發 Nexus。

• 新增 model/entity/mapper/repo：
  • ap_task_subjects（task_id FK CASCADE, subject_uuid, subject_type, include, sort_order, title, audit 欄）
  • ap_task_participants（task_id FK CASCADE, party_uuid, role_id, sort_order, audit 欄）
  • 比照 ap_assessment_subjects 既有風格；index on (task_id) + (subject_uuid)/(party_uuid)。
• repo 提供 by-task 全量覆寫（mirror set_tasks 策略）。
• mapper（OSCAL 序列化）：
  • 匯出：ap_task_subjects → task.subjects[]（依 type 群組 include-subjects）； ap_task_participants → task.responsible-roles[]（依 role_id 群組 party-uuids）。
  • 匯入：反向 parse。
• ap_tasks.subjects / responsible_roles 兩 JSONB 欄改為不寫（SoT 移到新表）；是否 drop 欄由套件決定（建議保留欄位但停用，降風險）。
• SQL：scripts/sql/2026-06-2x-fr040-ap-task-link-tables.sql（建表 + GRANT cm_app/cmmgr + index + schema_migrations），cmmgr 套 DEV（feature 階段先 DEV）。

檔：app/grc/service/assessment_plan_app_service.py

• set_tasks(ap_uid, tasks, ...) 每條行程：
  1. 組 ApAssessmentActivitiesEntity：related_controls = controls → control-selections 結構； props = methods → [{name:"method",value:m}]（沿用既有 _methods_to_props）；uuid = 新 uuid4。
  2. 組 ApTasksEntity：timing（既有）、associated_activities = [{activity-uuid: <上面 activity uuid>}]。
  3. 寫 link 表：ap_task_subjects（subjects）、ap_task_participants（participants），by task_id。
  4. 全量覆寫：同 @transaction 內依序重建 activities → tasks → link 表。
• 新增 helper：_controls_to_related_controls / 反向（controls ↔︎ related_controls JSONB）。
• methods 仍走 props（不動既有 _methods_to_props），只是搬到 activity 而非 task。
• subjects/participants 不再組 OSCAL JSONB（直接落表，OSCAL 形狀交給 Phase 1 mapper）。

同檔 _to_ap_detail（約 line 127-144）

• tasks 改成 join ap_tasks + ap_assessment_activities + ap_task_subjects + ap_task_participants。
• 每條還原：methods（activity.props）、controls（activity.related_controls）、 subjects（ap_task_subjects）、participants（ap_task_participants）、timing。
• audit 欄位規範：participants/subjects 的 party/subject uuid → enrich nickname/name（比照既有 enrich pattern）。

• 載入：除既有 fetchAp，補抓 Tab1 控制項集、Tab2 受評對象集、專案參與者集（多數已在頁面其他 tab 抓過，能重用就重用）。
• 每條行程 row 加 3 個 MultiSelect：控制項 / 受評對象（依 type 分組）/ 參與人員。
  • options 分別 = Tab1 勾選集 / Tab2 全集 / 參與者（auditor·manager）。
• saveTasks payload 擴充 controls / subjects / participants（見 design §6）。
• readonly 規則沿用既有。
• i18n：補欄位標籤 key（zh-tw + en），沿用 lang.ap_authoring.*。

• 套件 pytest（jedi_oscal_v2）：新 model/repo CRUD + mapper round-trip（表 ↔︎ OSCAL task.subjects/responsible-roles）。
• BE pytest：set_tasks round-trip（存→讀形狀一致）、methods 仍落 props、controls 落 activity、 subjects/participants 落 link 表；全量覆寫不殘留舊 activity/link。logger patch autouse fixture（DBLogHandler 雷）。
• FE/E2E：在 compliance-manager-test 專案補（行程加控制項/對象/人員 → 存 → 重整還原）。
• 測試計畫由 feature-test-planner agent 產出 test-plan.md（Phase 4 SOP）。

• 新增 2 張表（jedi_oscal_v2）：ap_task_subjects / ap_task_participants（見 Phase 1）。
• migration scripts/sql/2026-06-2x-fr040-ap-task-link-tables.sql（建表+GRANT+index+schema_migrations），dev 先套。
• 控制項/方法/timing 零 schema 變更（用現有欄位）。
• 套件異動走 dev poetry path-dep，feature 完成 + smoke 過才發 Nexus（依套件發版規範）。

確認結果：零新表 —— oscal.assessment_plans.metadata_id(1:1) 已存在、oscal.parties/oscal.roles 以 metadata_id scope，重用即可。per-task 沿用既有 ap_task_participants。

• Phase 6.0 pre-flight：確認 (a) party_repo_impl / SSP party CRUD 能以任意 metadata_id 操作（非寫死 SSP）； (b) AP draft 生成時 metadata row 是否已建、是否已有 roles；(c) 權限（誰能在 AP 加 party）。
• BE：新增 ap_party_app_service（list/add/update/delete parties，scope = ap_uid → assessment_plans.metadata_id）， mirror ssp_party_app_service；首次操作確保 oscal.roles 有 assessor（AP metadata scope）。 route：GET/POST /ap/{apUid}/parties、PUT/DELETE …/parties/{uid}。DI wiring。
• set_tasks/_ap_detail：participants 的 party_uuid 改指 AP party uuid（資料形狀不變，來源語意換）。
• FE：taskParticipantOptions 改抓 GET /ap/{apUid}/parties（取代 SSP people）； 下拉加「＋新增」inline quick-add（姓名 / 類型 / role=assessor）→ 呼 POST parties → 選入。
• OSCAL 匯出（後續）：AP parties→metadata.parties、assessor→metadata.roles、ap_task_participants→task.responsible-roles。
• 零新表 / 零 migration（重用 oscal.parties/roles/metadata）。
• 取代過渡版（commit 1e8c231 稽核人員=SSP parties）。

• 新增 2 張表（jedi_oscal_v2）：ap_task_subjects / ap_task_participants（見 Phase 1）。
• migration scripts/sql/2026-06-21-fr040-ap-task-link-tables.sql（建表+GRANT+index+schema_migrations），dev 已套。
• 控制項/方法/timing 零 schema 變更（用現有欄位）。
• Phase 6（稽核人員 AP parties）零新表：重用 oscal.parties/oscal.roles（metadata-scoped）。
• 套件異動走 dev poetry path-dep / symlink，feature 完成 + smoke 過才發 Nexus（依套件發版規範）。

完整設計見 design.md §11。零套件改動、零 migration（ap_assessment_activities.steps 欄位早已存在、 entity/mapper 已雙向接好）。BE 12 測試綠 / FE build 過。changelog docs/changelog/2026-06-21-feat-fr040-phase7-ap-task-step-guidance.md。 實作細節對齊下方；差異：i18n 區塊標題實際用 task_guidance / task_guidance_ph（非 task_step_guidance）。 附帶同頁修補：查核指引方法標籤改 soft pill；受評對象 party 角色改走 lang.oscal_role.ssp_party_role i18n。

• BE（assessment_plan_app_service.py）：
  • set_tasks：payload steps:[{method, description}] → activity.steps，每筆補 uuid/props=[{name:"method",value:method}]/title=method/description。規則 steps ⊆ methods。
  • _ap_detail：讀 activity.steps → steps:[{method(from props), description}]。
  • helpers _steps_from_payload / _steps_to_payload。
  • route _TaskItem 增 steps 欄（List of {method, description}，load_default None）。
• FE（RoundApAuthoringView.vue）：
  • TaskRow 增 stepGuidance: Record<methodValue,string>；載入由 tk.steps 還原。
  • 卡身「查核方法」下加「查核指引」區：v-for over tk.methods 動態列每方法一個 Textarea。
  • saveTasks payload steps = methods.filter(有指引).map(m => ({method:m, description:guidance[m]}))。
  • i18n：區塊標題 task_step_guidance 等。
• 測試：set_tasks round-trip 含 steps；steps ⊆ methods；method 取消其 step 不存。
• description（整體備註）保留不動。

定案維持 Phase 7 per-method（每方法一條 textarea）為最終形態，AO 下沉 + 逐列儲存暫不做。 理由與未來反悔條件見 design §12 banner。下方 8.0~8.5 保留為「若未來要 per-AO 報表自動拆分」時的現成 plan。

Phase 8.0 — Pre-flight（開工第一步，逐項驗，漂移就停）

1. AO 顯示 label 來源：catalog_control_parts 的 AO part，[a][b][c] 標籤從哪來 — 驗 part.props(name=label?) vs part_id 尾碼 vs prose 首段；FE grid 顯示要的 label/prose 取得方式定案。
2. AO 端點落點 + DI：AP app service 現無 _part_repo/_catalog_control_repo/_profile_import_repo； 決定 (i) AP service 補 wiring（傾向，read 歸屬 AP）還是 (ii) route 借 assessment_result_app_service 既有 _project_catalog_controls+_derive_ao_map。驗 derive_ao_pairs 能否順帶回 part title/prose（目前只回 id）。
3. 逐列儲存 repo 能力：驗 jedi_oscal_v2 ApTasksRepo/ApAssessmentActivitiesRepo 有無單列 update/delete by uid/id（現 set_tasks 走全量 delete-all+_ap.set_tasks 全覆寫）；task 是否有穩定 uid（_ap_detail 已回 t.uid → 有）。
4. OSCAL step shape：確認 select-control-by-id.statement-ids 是放 AO _obj.N 的正確欄（vs control-objective-selections）； 挑與 AR/匯出未來相容者。
5. control_id ↔︎ catalog 比對鍵一致性（沿用 Phase 7：related-controls 的 control-id == reviewed-controls control_id == catalog control_id）。

Phase 8.1 — BE：AO 清單端點

• assessment_plan_app_service.list_control_objectives(ap_uid) → {control_id: [{ao_id, label, prose}]}，只取 AP reviewed-controls。
  • 重用 AR 既有 AO 推導鏈（cc_map ← AP→SSP→profile→catalog；derive_ao_pairs），補抓 part title/prose/label。
• route GET /ap/{apUid}/control-objectives（auditor/manager read；沿用既有 round/AP 解析守門）。
• DI wiring 依 8.0.2 決定。

Phase 8.2 — BE：steps 改 (control_id, ao_id, method) + helpers

• _steps_from_payload([{control_id, ao_id, method, description}]) → OSCAL step（props method + reviewed-controls.control-selections.include-controls[{control-id, statement-ids:[ao_id]}]，ao_id 為 None 則省 statement-ids）。只存有指引者。
• _steps_to_payload(activity.steps) → [{control_id, ao_id, method, description}]（向後相容：無 reviewed-controls 的舊 step → control_id/ao_id=None，歸控制層）。
• serializer _TaskStepItem 加 control_id(allow_none) / ao_id(allow_none)。

Phase 8.3 — BE：逐列儲存端點（Part B）

• add_task(ap_uid, task) → 建 1 task + 1 activity + link，回 uid。
• update_task(ap_uid, task_uid, task) → 更新該 task 的 activity(related_controls/props/steps) + 重建其 link 表，by task_uid。
• delete_task(ap_uid, task_uid) → 刪 task（cascade activity + link）。
• routes：POST /ap/{apUid}/tasks、PUT/DELETE /ap/{apUid}/tasks/{taskUid}；守門沿用。
• 既有全量 set_tasks 保留（相容/批次）；helper 抽共用（單列與全量共用組裝邏輯）。
• repo 單列能力不足則於套件補（走 symlink/path-dep，發版等 user）。

Phase 8.4 — FE：控制項→AO→方法 指引 grid + 逐列儲存

• 載入 GET …/control-objectives；tk.stepGuidance key 改三元組 "<control_id>|<ao_id>|<method>"。
• 卡身指引區 grid：v-for 控制項 → v-for AO → v-for 已選方法；無 AO 控制項退單層。
• 每卡「儲存此行程」呼單列端點、「刪除」呼 delete；新增呼 add。未存變更離開提示。
• i18n：AO/grid 標題、儲存/刪除單列按鈕。

Phase 8.5 — 測試

• BE：_steps_from_payload/_steps_to_payload 含 AO round-trip + 向後相容（舊 method-only step）； list_control_objectives AO 推導（含控制層 fallback）；add/update/delete_task 單列正確 + 不誤動他列。
• FE/E2E（compliance-manager-test）：行程加多控制項多 AO 指引 → 逐列存 → 重整還原。

DB / 套件異動（Phase 8）

• 零新表 / 零 migration（沿用 ap_assessment_activities.steps）。
• 若 repo 單列 add/update/delete 能力不足 → jedi_oscal_v2 補 repo 方法（dev symlink/path-dep，發版等 user 明示）。

• changelog（type=feat）：套件加表+mapper / BE set_tasks 擴充 / FE 三連動 / Phase 6 AP parties / Phase 7 steps / Phase 8 AO 指引+逐列儲存，各別記。
• design.md §9 範圍外項目逐一保留為 follow-up。