稽核計畫重做：設計定案

🔴 這份是設計決策，不是現況。 內文停在 2026-10-16 定稿當時，實作改動不回頭改寫這裡。

狀態：已實作、決策者驗收（2026-10-16）；實作與複測期間改判的規則見下方「實作後改判」，以該節為準｜母卡 CM-2799｜雛形卡 CM-2800（三輪）｜討論稿：discussion.md｜雛形：prototype/index.html

檔案路徑與行號以 2026-10-16 為準，查不到時以函式名重新定位。路徑慣例：BE 路徑相對 compliance-manager-be/；pkg/<套件>/ 代表 ~/Projects/Jedicogy/module/jedi-python-package/<套件>/<套件底線名>/；FE 路徑相對 compliance-manager-fe/。

名詞：AP＝稽核計畫（assessment plan）；AO＝評估目標（assessment objective），控制項底下的檢查項目，全系統用 part_id 當鍵（<控制項代碼>_obj.N；控制項沒有 AO 時退回控制項代碼本身）；計畫概要＝一份 AP 的表頭（依據、目的、稽核單位、稽核日期起迄、稽核範圍、稽核方法論、稽核人員）；activity＝OSCAL AP 裡「一個查核動作」，本案一條 AO 一個；稽核次＝FR-140 的 compliance.audit_round_passes，一輪內每做一次稽核一筆、每筆自己一份 AP；finding＝AR 裡對一條 AO 的判定紀錄。

整案一句話：稽核計畫頁換成「計畫概要」＋「評估目標」兩個頁籤，顧問逐條 AO 填怎麼查、查誰、誰查；一份 Excel 匯出即匯入範本；一鍵匯出亞航格式報告稿。

依賴：A1 → A2、A3、A4；B1 → B2、B3；B4 只依賴 B1。A 線與 B 線可平行（A 碰 terms 表與 docx、B 碰 activity 與 Excel）。最先看得到畫面的是 A2。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
    subgraph A[A 線：計畫概要與報告稿]
      A1[A1 terms 表＋API] --> A2[A2 新頁殼＋計畫概要頁籤]
      A1 --> A3[A3 報告稿匯出]
      A1 --> A4[A4 docx 匯入改落點]
    end
    subgraph B[B 線：逐 AO 與 Excel]
      B1[B1 AP 逐 AO 存] --> B2[B2 評估目標頁籤]
      B1 --> B3[B3 Excel 匯出匯入]
      B1 --> B4[B4 縮範圍規則＋選單 seed]
    end
    A2 -.頁殼.-> B2

B2 掛在 A2 的頁殼上；A2 先完成最順，若 B2 先到可先建頁殼、A2 接上。

實作後改判

實作與決策者複測期間定下或推翻的規則。與上表或下方內文衝突時，以本節為準。

① 資料模型（套件 jedi-oscal-v2，schema oscal，pkg/jedi-oscal-v2/infra/model/ap/）

套件服務 pkg/jedi-oscal-v2/app/service/ap/assessment_plan_service.py（215 行）的 set_reviewed_controls（:113）、set_assessment_subjects（:153）、set_tasks（:184）一律整批先刪後寫，task uuid 每次重產。

jedi-oscal-v2 在主專案目前是 pin 2.6.0（pyproject.toml:85），path dependency 註解在 :139。要改套件的卡先切 path、收口時還原 pin 並發版。jedi-compliance-audit 已是 path（:124，pin 在 :70 註解）。

② 主專案 AP 服務與端點

③ 可沿用

④ FE

資料模型與 OSCAL 落點

新表 oscal.ap_terms_and_conditions

主線 migration scripts/sql/2026-10-16-fr141-ap-terms-and-conditions.sql，比照 2026-06-21-fr040-ap-task-link-tables.sql（IF NOT EXISTS、GRANT cm_app、sequence 權限、INSERT schema_migrations）。新增主線 migration → 出貨基線待重產。

套件 model 新增 pkg/jedi-oscal-v2/infra/model/ap/ 對應 ORM、entity、repo、service 方法 set_terms(ap_id, parts)／get_terms(ap_id)（以 part_name upsert，不先刪後寫）。

一份 AP 一個 task

A1 起，新頁寫入時一份 AP 只保留一個 task（type＝action，title＝「稽核計畫」），放日期起迄與 associated_activities。舊資料可能有多個 task：讀取時取第一個 task 的 timing 當日期起迄；第一次以新頁存檔時合併成一個 task（其他 task 的 associated_activities 搬過來）。

🔴 動手前 grep task uuid 的下游引用（wecm、AR、job、ap_task_subjects、ap_task_participants）；set_tasks 先刪後寫會重產 uuid，任何拿 task uuid 當鍵的地方都會斷。B1 改 activities 寫法時對 activity uuid 做同一件事——activity 以 AO part_id 做自然鍵 upsert，不先刪後寫，uuid 才穩定。

讀寫 API

全部寫入端點在 app service 層呼叫 resolve_ap_and_check_auditor，GET 走既有讀取守門。error code 進 common/code/grc_error_code.py，前綴 GRC_。

計畫概要頁籤（A2）

照雛形 prototype/ap-authoring.html 計畫概要頁籤：依據、目的、稽核範圍、稽核方法論為多行文字框；稽核單位單行（提示「只填公司名稱」）；稽核日期起迄兩個日期時間；稽核人員多選可當場新增。頁首：麵包屑「專案 › 第 N 輪 › 第 N 次 內部／外部稽核 › 稽核計畫」，稽核次膠囊點開列同輪全部稽核次（目前、已結束唯讀、未開始不可點），讀 FR-140 卡 10 的列稽核次 API；稽核性質為 NULL 時顯示「未標示」。頁籤「計畫概要」「評估目標」，評估目標頁籤在 B2 前先放「建置中」佔位。

新頁檔：src/views/project/RoundApPlanView.vue（殼）、src/components/grc/ap-plan/ApPlanOverviewTab.vue、ApPassBreadcrumb.vue、composable src/composables/useApPlan.js。

評估目標頁籤（B2）

照雛形評估目標頁籤：左側樹（控制族群→控制項，完成狀態點、搜尋、篩選「全部／尚未填／已覆寫人員」、完成計數）；右側一次一條控制項：實務要求與執行說明唯讀、控制項預設區塊（已拿掉，見「實作後改判」）；每條 AO 一張卡（方法組不限數量、受評人員、受評元件／資產、稽核人員預帶概要名單可覆寫可還原、「承襲自第 N 次」標籤改過即消）；上一條／下一條只在篩選後可見的控制項間跳；「總覽（唯讀表格）」子檢視。

「填好」＝至少一個方法，且受評人員或元件／資產至少一個。

新檔：ApPlanObjectivesTab.vue、ApObjectiveTree.vue、ApObjectiveControlForm.vue、ApObjectiveCard.vue、ApMethodGroups.vue、ApObjectivesOverview.vue、composable useApObjectives.js。每支 Vue 檔 800 行內、script 函式 40 行內。

Excel 契約（B3，D1）

四頁，匯出的檔就是匯入範本；空 AP 匯出就是空白範本。

「評估目標」頁：

解析一律串流讀、列數上限（沿用 SSP 匯入的上限常數，先 grep）、檔案大小上限、只收 .xlsx；儲存格寫出一律經 export_safety。解析結果暫存（比照 ap_docx_parse_jobs，新表或沿用同表加 kind 欄由卡上先 grep 決定），確認時以 part_id upsert，只寫有變更的 AO。

預覽在正式頁的「預覽模式」呈現（雛形 prototype/import-preview.html）：頂部橫幅計數＋確認匯入；左樹「待處理」「有變更」徽章；被改欄位黃底、原值灰字；未知方法詞與人名就地對應；全部對應完才能確認；「略過的列」對話框。

報告稿（A3）

docx 範本 app/flow_control/templates/ap/ap_report_template.docx（由腳本產，比照 SSP），標題「{框架} 第 N 次{內部／外部}稽核計畫」（稽核性質 NULL 時省略「第 N 次…」），段落：一 依據、二 目的、三 稽核單位（「由{稽核單位}協助辦理。」＋稽核人員一句）、四 稽核日期（起迄同日印「YYYY年MM月DD日上午HH:MM-HH:MM」，跨日印「…至…」）、五 稽核範圍、六 稽核方法、七 稽核結果（佔位「（評估結果完成後帶入）」）；附件「稽核檢查紀錄表」：序號、索引號、實務要求、執行說明、評估目標、查核方法：指引（一行一組）、受評對象（P2 可關）、稽核人員（P2 可關）。B1 之前 AP 尚無逐 AO 資料，附件表以控制項列出、方法欄空白；B1 完成後自動帶入。

pdf 經 SspLibreOfficeConverter。zip＝docx＋xlsx（xlsx 要 B3 完成；B3 之前 zip 選項隱藏）。

縮範圍規則（B4，P1）

narrowed_control_ids_from_parent（assessment_result_app_service.py:360）改為：

control_ids   = 上一次 AP 的 in-scope 控制項
ao_to_control = 上一次 AP 的 AO→控制項對照
judged        = { finding.target_id: finding.target_status_state }  for 上一次 AR 的 findings
帶入控制項 = { ao_to_control[ao] for ao in ao_to_control if judged.get(ao) != "satisfied" }

即不合格、待判（pending）或沒有 finding 的 AO 所屬控制項帶入。DEV 2026-10-16 實查 oscal.assessment_findings.target_status_state 三種值：pending 113、satisfied 58、not-satisfied 20——只有明確 satisfied 才排除，pending 等同未判定，要帶入。這支同時供覆核輪（launch_reverify）與第 N 次內稽使用，覆核輪一起變。新邏輯開新檔（assessment_result_app_service.py 已 860 行），原處一行委派。

clone 時 AO 層資料（activities、associated_activities.subjects、responsible_roles、terms）一併複製，被縮掉的控制項的 AO activity 不複製；複製來的 AO 在 activity props 記 inherited-from-pass＝來源 pass_no，FE 據此顯示「承襲自第 N 次」，使用者改過該 AO 即清掉此 prop。

方法選單 seed（B4，P3）

DEV 選單（2026-10-16 實查 system_menus group AUDIT_METHOD）：檢視 EXAMINE、訪談 INTERVIEW、測試 TEST、文件檢查 DOCUMENT_REVIEW、電腦設定比對 COMPUTER_CONFIG_COMPARE、門禁系統設定比對 ACCESS_CONTROL_CONFIG_COMPARE。

🔴 開工前先回寫問決策者：docx 匯入詞庫 pkg/jedi-compliance-audit/app/service/import_adapter/method_keywords.py:11 已把「現場實地觀察」對到 EXAMINE（檢視）。NIST 800-171A 的三法是 Interview／Examine／Test，「現場觀察」就是 Examine 的一種。兩條路：

• 甲（建議）：不新增選項，把 EXAMINE 的顯示名改成「檢視／現場觀察」，詞庫補「現場觀察」。選項不重複、與 NIST 三法對得起來。
• 乙：新增第七項「現場觀察」ONSITE_OBSERVATION，phase=seed migration（ON CONFLICT DO NOTHING，先例 2026-05-22-seed-oscal-ssp-roles.sql），詞庫「現場實地觀察」改對新項。

兩案都同步 B3 匯入比對與 FE i18n；改顯示名也走 seed migration（UPDATE 該列 key），不寫死。phase=seed 不需重產出貨基線。

1. 計畫概要：DEV 開一輪走到稽核計畫填寫站，進新稽核計畫頁，麵包屑顯示第 N 次 內部／外部。計畫概要頁籤填六段、稽核單位「鈊安資安顧問」、日期起迄、兩位稽核人員，儲存、重整還在。DB：oscal.ap_terms_and_conditions 該 AP 四列；oscal.parties 多一筆 organization。
2. 報告稿：匯出 docx，Word 開看到標題帶稽核次、三段寫「由鈊安資安顧問協助辦理。」、四段日期格式正確、第 7 段佔位、附件表；匯出 pdf 內容相同；關掉 P2 兩欄再匯出，附件表少兩欄。
3. docx 匯入：匯入亞航報告稿，計畫概要六段有值、行程說明不再重複貼長文。
4. 逐 AO 填寫：查核項目規劃頁籤逐條 AO 填方法與人員（控制項預設已拿掉），改其中一條 AO 的稽核人員，存檔重整還在；左樹完成數正確；總覽表格內容一致。DB：每條 AO 一個 activity，related_controls 帶 control-objective-selections。
5. AR 不壞：同一輪進稽核執行，AR 頁的方法顯示與改動前一致（逐 AO）。
6. Excel：匯出 Excel，四頁齊全、A 欄隱藏；在「評估目標」頁改兩格、把一個方法寫成「文件檢視」、一個人名打錯，匯入：預覽黃底標出兩格、未知方法與人名就地對應，對應完確認，畫面更新。
7. 第 2 次內稽範圍：第 1 次內稽判 1 條 AO 不合格、另一條控制項的 AO 全部不判，走完改善回規劃再到稽核計畫填寫站：第 2 次 AP 包含這兩條控制項、其餘不在；帶進來的 AO 顯示「承襲自第 1 次」，方法與人員跟第 1 次一樣。覆核輪同規則。
8. 選單：後台方法選單看得到「檢視／現場觀察」（P3 裁甲，見「實作後改判」）；匯入含「現場觀察」的 Excel 對到該項、不再被列為未知。

互斥：A1 與 B1 都改 jedi-oscal-v2 AP service，但檔案不同（A1 新 terms 方法、B1 改 activities）；同時派時各自只 add 自己的檔。B3 與 B2 都碰 FE 稽核計畫頁，B3 的預覽模式等 B2 元件到位再做畫面部分。B4 改 clone_ap_for_round 時 B1 必須已完成。

收口（不開卡，母卡收尾時做）：jedi-oscal-v2 與 jedi-compliance-audit 發版、還原 pin（jedi-compliance-audit 與 FR-140 同批發）；出貨基線重產（A1 的主線 migration）；docs/spec-site/current/audit-execution/ap-authoring.md 改寫；e2e 另開一棒。