結案報告與一包下載：設計定案

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

狀態：設計定案，已開卡｜討論稿：discussion.md｜雛形：prototype/index.html

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

名詞：輪次＝compliance.project_audit_rounds 一筆；稽核次＝compliance.audit_round_passes 一筆，各自一組 AP／AR／POA&M；階段結案報告＝一輪一份；專案總報告＝一專案一份；定稿＝鎖總結段、記版號、報告包改正式版；報告包＝zip；證據對照表＝報告包內的 Excel 索引；凍結佐證＝FR-142 結案時 ar_close_service._freeze 寫進 assessment_observations 的採用佐證，帶 content-hash 與 frozen-at props。

整案一句話：稽核報告掛在稽核次後面結案即可下載；「專案調查結果」改成結案報告，一輪一份階段報告（輪次結案仍有不符合才建）、專案完成一份總報告，六章只有總結由人寫，其餘系統算；報告包含 Word／PDF、證據對照表、各稽核次報告與工作表、依控制結構分資料夾的凍結證據。

依賴：1、2 可先派（1 的改善計畫節讀 FR-143 CM-2841 的 POA&M，若 CM-2841 未落地先用「尚未送出」分支）；3 等 2 與 FR-143 CM-2842；4 等 3；5 等 3、4；6 隨 FR-143 CM-2844。

定案理由與被排除方案見討論稿 D1～D16，此處只列結論供實作對照。

① 稽核次下載與改善計畫節（卡 1）

端點：GET /audit-round/<round_uid>/pass/<pass_uid>/report?format=docx|pdf|xlsx，守門沿用 audit_round_route.py 的 AR 匯出。

選檔邏輯（app service 層）：

pass.status in (closed, remediation) else 412 GRC_PASS_NOT_CLOSED
poam = poam_app_service.get_submitted(pass)        # FR-143 CM-2842；None＝尚未送出或無缺失
format xlsx:
    poam and poam.submitted → poam_workbook_export(pass, all_objectives=True)   # CM-2844 開關
    else                    → ar_workbook_export(pass)
format docx|pdf:
    model = ar_report_export_service.build(pass)
    model.poam_state = 'has' | 'none' | 'pending'    # none＝最終 not_met==0；pending＝有不符合但 POA&M 未送出
    model.poam_rows  = [(ctrl, task, owners, due, measure)]
    docx = ar_docx_generator.generate(model); pdf 經 SspLibreOfficeConverter

ar_docx_generator：generate() 在 _append_record_table 後呼叫 _append_poam_section(doc, model)：直式新節、標題「改善計畫」、poam_state 三態文案、has 時五欄表（控制項、改善任務、執行人員、到期日、改善措施），表頭重印沿用 _repeat_header。檔已 192 行，新節邏輯放新檔 ar_docx_poam_section.py 由 generator 一行呼叫。

FE：稽核作業清單加「稽核報告」欄，closed／remediation 放「下載報告」下拉（Word／PDF／Excel，Excel 項文字依後端回的 workbook_kind 顯示「改善計畫工作表」或「稽核結果工作表」）；auditing 印「結案後開放」。清單端點回每列加 report_available: bool、workbook_kind: 'poam'|'ar'。

② 資料模型與自動建立（卡 2）

migration（主線 phase=active，一支）：

ALTER TABLE compliance.project_summary_reports
  ADD COLUMN report_type varchar(20) NOT NULL DEFAULT 'legacy',   -- stage | final | legacy
  ADD COLUMN audit_round_id integer REFERENCES compliance.project_audit_rounds(id) ON DELETE CASCADE,
  ADD COLUMN status varchar(20) NOT NULL DEFAULT 'draft',          -- draft | issued
  ADD COLUMN issued_version integer NOT NULL DEFAULT 0,
  ADD COLUMN issued_at timestamptz,
  ADD COLUMN issued_user varchar(50);
CREATE UNIQUE INDEX uq_psr_round ON compliance.project_summary_reports(audit_round_id) WHERE audit_round_id IS NOT NULL AND is_delete = 0;
CREATE UNIQUE INDEX uq_psr_final ON compliance.project_summary_reports(project_id) WHERE report_type = 'final' AND is_delete = 0;
ALTER TABLE compliance.project_summary_report_history
  ADD COLUMN version_no integer, ADD COLUMN issued boolean NOT NULL DEFAULT false, ADD COLUMN bundle_ref varchar(500);
-- ui_routes id 15 name report-manage → closing-report（i18n key 跟著改）

既有列 report_type='legacy'、status='issued'（視為已定稿、唯讀）。

自動建立：主專案 app/project/service/（呼叫 audit_round_app_service.finalize_audit／close_round 的那層）在套件回傳後，同一 @transaction 內呼叫 closing_report_creator.on_round_closed(round)：

if round.status != closed: return
not_met = ar_objective_app_service.final_not_met_count(round.last_pass)
if not_met > 0: create_for_round(round)            # stage，name=f"第 {round.round_no} 輪結案報告"
project = reload; if project.status == COMPLETED: create_for_project(project)   # final，name="專案總報告"

兩個 create 都 idempotent（查唯一索引已有就跳過）。不改套件；套件事件已有 _sync_project_status 寫 COMPLETED，主專案只需在呼叫後重讀。

清單端點：POST /project-summary-reports（既有）回模型改為一專案一列：

{"project_uid","project","framework","manager","consultant","progress":{"round_no","stage_label","at"},
 "bucket":"pending|done|none","draft_count","issued_count","latest_issued_at",
 "reports":[{"uid","report_type","label","covers":[稽核次標籤],"status","not_met_final","issued_at","issued_version"}]}

bucket 由後端算；分段鈕筆數走 meta.bucket_counts。歸屬：_require_participant 既有邏輯（manager／auditor），reviewer 不列（D15）。

FE：ProjectSummaryReportManage.vue 重做為 DataTable 行展開（expandedRows 用物件 key）；子列欄照雛形；點子列進卡 3 報告頁。選單 i18n report-manage 改「結案報告」。

③ 階段結案報告讀模型與頁面（卡 3）

讀模型 closing_report_app_service.get_stage_report(report_uid)，全部即時算：

端點：

Word：新 closing_report_docx_generator.py，範本 app/oscal/templates/closing/stage_report_template.docx（從 FR-142 ar_report_template.docx 複製改章節）；docxtpl 渲染六章，附件一用 python-docx 橫式表（沿用 ar_docx_generator._landscape_section、_repeat_header）。第 5 章 HTML → docx 走既有 bleach 白名單後以 html2docx 風格轉段落（先查 SSP 匯出是否已有 HTML→docx helper，有就用）。

FE ClosingReportView.vue：文件版面照雛形 round-closing-report.html（封面、章節、表格、右側目次與下載紀錄）；頁首存檔／定稿／下載下拉；TipTap 第 5 章；定稿後唯讀＋修訂。超過 800 行拆子元件（封面、章節表、附件表、側欄）。

④ 報告包（卡 4）

closing_report_bundle_service.build(report) -> BytesIO：

<專案>_<第N輪|專案總報告>_結案報告[_v<N>]/
├─ 00-完整報告.docx、00-完整報告.pdf                 ← 卡 3 export
├─ 01-證據對照表.xlsx                               ← 本卡
├─ 第<seq>次<內部|外部>稽核/                        ← 每個 pass
│   ├─ 稽核計畫.docx                                ← ap_report_export_service
│   ├─ 稽核報告.docx                                ← 卡 1 選檔（含改善計畫節）
│   └─ 改善計畫工作表.xlsx | 稽核結果工作表.xlsx     ← 卡 1 選檔
└─ 證據/<族群代碼 族群名>/<控制項>/<評估目標>/
    ├─ <原檔名>                                     ← upload_files 以凍結 content-hash 對應版本
    └─ 問卷填答_<問卷名>.pdf                         ← survey_answer_pdf

凍結項來源：assessment_observations 該 AR result 的採用項（_observations.list_adopted(ar_result_id)，CM-2826 已有讀法），每項 relevant-evidence[].href：/files/<uid>→檔案、urn:guidant:task-survey:<uid>→問卷、其他→連結；props 取 content-hash、frozen-at。檔案以 content-hash 對 upload_files.sha256 取版本，取不到（檔被刪）在對照表標「檔案已不存在」不中斷。

證據對照表欄：稽核次、控制族群、控制項、評估目標、類型（檔案／問卷／連結）、名稱、包內路徑、雜湊／快照識別、採用（是／否）、備註。未採用項來自同 observation 的 adopted=false 紀錄，留列不收檔。

問卷 PDF survey_answer_pdf.render(task_survey_uid) -> bytes：get_answer_list_by_task_survey_uid 取題目與答案，HTML 表（問卷名、填答人、填答時間、題號／題目／答案）經 render_pdf。凍結時記的是 survey_uid，答案取當下最新一筆 history（問卷填答在稽核後不會再改，FR-142 D10 已鎖）。

定稿版存檔：issue 時 build 一次存儲存後端，history.bundle_ref 記路徑；歷史頁該筆可重下載。draft 下載即時 build 不存。

大小：證據檔總量超過 1 GB 時改背景工作（background_jobs）產檔後通知，本案先同步產、超過門檻回 413 提示；門檻進 config。

⑤ 專案總報告（卡 5）

同卡 3 讀模型加 report_type=final 分支：

總報告包：第1輪/、覆核輪/ 各放該輪 stage 報告包內容（有定稿版用定稿版，否則即時 build）；01-證據對照表.xlsx 合併各輪加「輪次」欄；00-專案總報告.docx／pdf。

⑥ FR-143 Excel 開關（卡 6，追加 CM-2844）

poam_workbook_export(..., all_objectives: bool = False)：True 時列全部評估目標，符合／不適用列改善欄空、灰底唯讀；頁面匯出鈕旁勾選「列全部評估目標」預設勾；卡 1 呼叫固定 True。

1. 稽核次下載：DEV 一個已結案有缺失的稽核次，稽核作業清單該列「下載報告」→ Word 最後一節「改善計畫」有表；同專案無缺失稽核次該節印「無」；矯正中列可下載、該節印「尚未送出」；稽核中列印「結案後開放」。Excel：有 POA&M 的下載到改善計畫工作表且含符合列、改善欄空；無 POA&M 的是稽核結果工作表。
2. 自動建立：從 FR-140 流程開一輪，外稽留 2 條不符合結案 → 結案報告清單該專案展開多「第 1 輪結案報告 待定稿」；再開覆核輪全過 → 專案完成，多「專案總報告 待定稿」。另一專案一次全過結案 → 只有「專案總報告」。
3. 報告頁：開第 1 輪報告，第 2 章各稽核次數字＝DEV AR 統計；族群矩陣第 2 次內稽未涵蓋族群印「未稽核」；第 3 章兩條不符合與風險等級、稽核發現與稽核報告一字不差；第 4 章任務與 FR-143 送出內容一致；附件一列數＝評估目標數。
4. 存檔／定稿：第 5 章空白按定稿 → 擋；寫字存檔 → 歷史多一筆 U；定稿 → 狀態已定稿 v1、第 5 章唯讀、存檔鈕消失、定稿鈕變修訂、歷史該筆 issued；修訂→改字→定稿 → v2；歷史頁「還原到 v1」→ 第 5 章回 v1 文字、狀態仍 draft。
5. 下載與日誌：draft 下載 PDF 有「草稿」浮水印、檔名無版號；issued 下載檔名 _v2；每次下載側欄「下載紀錄」多一列（人、時間、格式）；DB 稽核事件表多 closing_report_download。
6. 報告包：issued 下載 zip 解開：結構照契約；對照表每列「包內路徑」在 zip 內存在；問卷佐證是 PDF 開得了、題目答案齊；連結類只在對照表；未採用項有列無檔；改一個 DEV 證據檔再下載 → 包內仍是舊版（雜湊相符）。
7. 總報告：專案完成後開總報告，第 2 章四列（內稽 1、內稽 2、外稽 1、覆核）、跨多次未改善兩條軌跡；第 3 章合計符合 57 不符合 0 不適用 2；第 5 章帶入第 1 輪 v2 總結；zip 內 第1輪/ 與 覆核輪/、合併對照表有「輪次」欄。
8. 權限：auditor 帳號開報告頁可讀可下載、存檔與定稿 403；reviewer 帳號清單不列；viewer 403。
9. 舊資料：既有「專案調查結果」列仍在清單（子列標「舊版」）、點開唯讀、無報告包。
10. FR-142 既有：test/ 下 ar 相關測試與 FR-142 e2e 不壞；稽核結果頁「結案」行為不變。

序列組：卡 1 與卡 2 可平行；卡 3 之後序列。卡 1 與卡 3 都動 ar_docx_generator 周邊，卡 3 等卡 1 合回。

• 證據必須取凍結版本：assessment_observations 採用項 props 的 content-hash 才是報告包要用的；用 upload_files 現在的檔會在結案後被換。對應版本取不到要在對照表標出，不中斷打包。
• 問卷 href 是 urn:guidant:task-survey:<uid>（ar_objective_view.py:77），不是檔案路徑；分類型時先判 scheme。
• 縮範圍的 null ≠ 未判定：第 2 次內稽未涵蓋的評估目標在附件一與族群矩陣印「未稽核」，有 finding 但 state 空才是「未判定」。讀模型兩者分開欄位。
• 改善計畫章節三態：has（POA&M 已送出）、none（最終 not_met==0）、pending（有不符合但未送出）。判 none 看 AR 不看 POA&M。
• 自動建立要 idempotent：輪次結案事件可能重入（覆核輪 close_round 與 finalize_audit 都會 _sync_project_status），用唯一索引擋重複，不靠流程保證只叫一次。
• hook 放主專案不放套件：_sync_project_status 在 jedi-compliance-audit；本案在主專案呼叫套件 app service 的那層之後掛，避免動套件發版。
• 既有列 report_type 要有預設：NOT NULL DEFAULT 'legacy'，否則 migration 在有資料的庫炸。
• ar_docx_generator 已 192 行、ProjectSummaryReportManage.vue 329 行：新節與新頁一律新檔，不往裡塞（CLAUDE.md 800／60 行規則）。
• PDF 浮水印：LibreOffice 轉出的 PDF 加浮水印要在 docx 範本層做（頁首浮水印文字框 + 條件），不是事後蓋 PDF。
• 下載日誌 payload 不含內容：只記識別、格式、版本（資安 log 規則）。
• DataTable 行展開：PrimeVue 3.53 expandedRows 用物件 {[uid]: true}，不是陣列。
• 報告包大小：證據總量大時同步產會逾時；門檻進 config，超過回 413，背景產檔列為後續。
• 本卡 2 新增主線 migration 1 支：回寫時明講「出貨基線待重產」。