稽核結果重做：設計定案

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

狀態：設計定案（2026-10-16）｜母卡 CM-2818｜雛形卡 CM-2819（六輪，Done）｜討論稿：discussion.md｜雛形：prototype/index.html｜範例 Excel：prototype/sample/FR-142-稽核結果範例.xlsx

🔴 實作在 FR-142 worktree：BE ~/Projects/Billows/Audit-Manager/wt-FR-142/compliance-manager-be、FE …/wt-FR-142/compliance-manager-fe、套件 ~/Projects/Jedicogy/module/wt-FR-142/jedi-python-package，皆 branch feature/FR-142（自 FR-139 b4048bd5e）；BE 8003 埠、FE 5181、專用庫 guidant_ai_fr142（從 DEV 複製，DEV 不碰；套件測試帶 JEDI_TEST_ENV 指 worktree .env）；合回 FR-139 時 DEV 補套套件 013。文件在主工作樹維護。

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

名詞：評估目標＝AO（assessment objective），控制項底下的檢查項目，全系統用 part_id 當鍵（<控制項代碼>_obj.N；控制項沒有 AO 時退回控制項代碼）；AR＝稽核結果（assessment results）；finding＝一條評估目標的判定；observation＝佐證紀錄；risk／remediation＝風險／改善建議；attestation＝稽核人員署名的文字陳述（第 7 章）；稽核次＝FR-140 的概念，一輪內每次稽核一筆，各自一份 AP 與一筆 AR result。

整案一句話：判定頁換成左樹到評估目標、中間一次一條評估目標（佐證→稽核發現→稽核結果→風險），控制項結論自動推算；稽核報告頁籤只寫第 7 章；Excel 延伸稽核計畫、佐證只關聯檔案；結案整份鎖定。

依賴：1a → 1b →（2、4、5、6 可平行）；3 等 2。

%%{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
    A1[1a 套件 OSCAL 修正] --> B1[1b 評估目標層矩陣<br/>observation／attestation]
    B1 --> C2[2 BE API]
    B1 --> C4[4 Excel]
    B1 --> C5[5 報告]
    B1 --> C6[6 FR-140 對齊]
    C2 --> C3[3 FE 新頁]
    C2 --> C5

座標以 2026-10-16 為準，runner 開工先開檔核一次。FR-141 已完整併入 feature/FR-139（git merge-base --is-ancestor 成立），其頁面骨架、六支 app/flow_control/service/ap_*.py、docx 範本都在主工作樹。

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

② 套件服務與主專案端點

③ FE 現況

④ 可沿用的匯出匯入能力

OSCAL 落點（AR，v1.2.2）

官方必填核對（v1.2.2 JSON schema）：finding（uuid／title／description／target，target 再需 type／target-id／status）、observation（uuid／description／methods／collected）、risk（uuid／title／description／statement／status）、remediation（uuid／lifecycle／title／description）、result（uuid／title／description／start／reviewed-controls）、attestation（parts）——上表每一項都有來源，畫面不需多填。

%%{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
    AO[評估目標頁<br/>佐證／其他佐證／稽核發現<br/>稽核結果／風險] --> F[finding<br/>target-id=part_id<br/>status.state / reason<br/>implementation-status]
    AO --> O1[observation 佐證<br/>EXAMINE<br/>relevant-evidence=檔案／連結／問卷]
    AO --> O2[observation 其他佐證<br/>methods 從稽核計畫帶<br/>description=文字]
    AO -->|判不符合且有填| K[risk<br/>characterizations.facets severity<br/>status=open]
    K --> M[remediation<br/>lifecycle=recommendation]
    F -.related-observations.-> O1
    F -.related-observations.-> O2
    F -.related-risks 連結表.-> K
    T[稽核報告頁籤第 7 章] --> A[result.attestations<br/>part name=audit-conclusion]

讀寫 API（棒 2）

全部掛在既有 /audit-round/<round_uid>/ar 下，讀取時以 FR-140 的「目前稽核次」取 AR result（GET 可帶 pass 讀指定稽核次）。新邏輯一律新檔 app/flow_control/service/ar_objective_app_service.py，不往套件 824 行的 assessment_result_app_service.py 加。

鎖定：結案後所有寫入端點回 409（新 error code，GRC_409xxx）。權限：寫入要專案稽核人員角色，走 common/authz 資源域守門（同既有 AR 端點）。

候選佐證：public.workflow_execution_control_mapping（workflow_execution_id, version_id, control_id, ao_part_id）對到該控制項的工作流程 → compliance.job_evidences 類型 FILE／LINK／SURVEY；二次 scope：只留 workflow_execution_id 真的對到該 control_id 的（memory feedback_evidence_per_control_scope_wf_control_mapping）；同 uid 去重。relevant-evidence 存字串 file_uid，不存數字 file_id。

採用狀態存法：observation（佐證那筆）relevant_evidence[] 存「被採用」的完整清單（不是存排除清單），讀取時「候選且在清單中＝勾選」。首次讀取該評估目標時尚無 observation，畫面視為全部勾選；第一次存檔才寫入。

畫面（棒 3）

照雛形 prototype/ar-authoring.html。FE 新檔 src/views/project/RoundAuditResultView.vue 加 src/components/grc/ar-result/ 子元件：ArObjectiveTree.vue（左樹三層＋燈號＋圖例）、ArControlOverview.vue、ArObjectiveForm.vue（佐證清單、其他佐證、稽核發現、稽核結果、風險）、ArEvidencePicker.vue、ArConclusionTab.vue、ArReportPreview.vue。左樹可沿用 FR-141 src/components/grc/ap-plan/ApObjectiveTree.vue 的結構但需擴到評估目標層。路由 /project/projects/:id/round/:roundUid/audit 改指新頁；舊 RoundAuditReviewView.vue（1,083 行）退役。D4：舊稽核次（finding target_id 不含 _obj.）用新頁唯讀。

Excel 契約（填寫說明、計畫概要、評估目標、可選清單四頁，延伸 FR-141）

「評估目標」頁欄序：

「可選清單」頁：稽核結果、風險等級、佐證檔案三欄（黃底），其餘沿用 FR-141。「計畫概要」頁唯讀、匯入不讀。範例：prototype/sample/FR-142-稽核結果範例.xlsx（產生腳本 make_sample_xlsx.py）。

匯入預覽（prototype/import-preview.html）：同一畫面預覽模式；異動的評估目標標示、原值劃掉；無效值與找不到的檔名標「待確認」就地處理；對不到 part_id 的列略過；全部處理完才能匯入。

報告（棒 5）

匯出三選一

GET /audit-round/<round_uid>/ar/export?format=docx|pdf|xlsx|zip&with_findings=true|false：

• 稽核報告（Word／PDF）：標題帶稽核次；第 1～6 章從 AP 帶；第 7 章＝attestation 全文；附件依 D11。
• 稽核結果工作表（Excel）：上面四頁。
• 全部檔案（ZIP）：docx＋xlsx。

範本：複製 app/oscal/templates/ap/ap_report_template.docx 為 ar_report_template.docx（打包只收 app/oscal/templates/，不要放 flow_control）；正文 1～7 章直式，附件獨立 section 橫式，8 欄依 D11。生成沿用 FR-141 app/flow_control/service/ap_docx_generator.py 的寫法、pdf 沿用 SspLibreOfficeConverter。新檔 ar_report_export_service.py、ar_docx_generator.py。

縮範圍規則（棒 6）

pkg/jedi-compliance-audit/app/service/pass_scope_rule.py（28 行）carried_control_ids 改讀評估目標層 finding，套 D5 的同一支規則：控制項結論為不符合者帶入下一次稽核。舊稽核次（控制項層 finding）維持原邏輯。

1. 新稽核次：DEV 從 FR-140 流程開一個新的內部稽核次，進稽核結果頁，左樹三層、全部燈號空心，DB 該 result finding 數為 0。
2. 逐條判定：AC.L1-b.1.iv [a] 取消一份佐證、寫其他佐證與稽核發現、判不符合、風險等級高與改善建議，存檔重整還在；左樹 [a] 紅燈、控制項紅燈、族群紅燈；控制項總覽依據寫「評估目標 [a] 不符合」。
3. 符合有風險：另一條判符合，按「新增風險」填風險等級中，所屬控制項變不符合。
4. Excel 來回：匯出 Excel，改兩格稽核結果、加一個專案內檔名、寫一個不存在的檔名，匯回，預覽標出異動與「佐證檔案找不到」，選「改為其他佐證文字」後匯入，畫面更新。
5. 第 7 章與報告：稽核報告頁籤按帶入不符合事項、修改、預覽報告：第 1 頁 1～7 章，第 2 頁橫式附件、判定中文、不符合列淡紅；下載 Word 用 Word 開確認。
6. 結案：還有未判定時按結案被擋並列原因；補完後結案成功，頁面唯讀，再呼叫寫入 API 回 409；有不符合時 POA&M 有產生。
7. OSCAL：匯出該 AR 的 OSCAL JSON，用 ~/.claude/skills/oscal-knowledge/references/json-schemas/oscal_assessment-results_schema.json 驗證通過；finding 的 target.status.state 為 satisfied／not-satisfied、risk 的 characterizations 為陣列、finding 的 related-risks 有值。
8. 第 2 次內稽：從有不符合的稽核次開下一次內稽，新稽核計畫只剩不符合評估目標所屬控制項。