---
title: "結案報告與一包下載：階段結案報告、專案總報告、稽核報告掛稽核次、證據包 — 討論稿 (FR-145)"
brand: "Guidant AI · **FR-145** 結案報告"
eyebrow: "FR-145 · 討論稿 · 2026-10-17"
h1: "結案報告與一包下載"
subtitle: "稽核報告掛在稽核次後面結案即可下載；「專案調查結果」改造成結案報告，一輪一份階段報告、專案完成一份總報告，六章只有總結由人寫，其餘系統算；報告包含 Word／PDF、證據對照表、各稽核次報告與工作表、依控制結構分資料夾的凍結證據（問卷填答轉 PDF）"
lede: "一輪稽核跑完，現在沒有一個地方能把這輪的成果整包交給客戶：稽核計畫、稽核結果、改善計畫各自能下載但散在三頁；證據檔沒辦法打包；「專案調查結果」只是一個空白富文字框，顧問從零寫，系統什麼都沒幫。本案兩件事：①稽核報告（Word／PDF／Excel）掛在每個稽核次後面，結案就能下載；②「專案調查結果」改造成結案報告——輪次結案且仍有不符合時自動建該輪的階段結案報告、專案完成時自動建專案總報告，六章固定章節只有總結由人撰寫，其餘從稽核計畫、稽核結果、改善計畫即時算，下載報告包拿 Word、PDF、證據對照表、各稽核次報告與工作表、依控制族群／控制項／評估目標分資料夾的凍結證據。請先開 [雛形](prototype/index.html) 點一遍再看規格。"
chips: [
  {text: "D1～D16 全部定案（2026-10-17）", kind: ok},
  {text: "雛形五畫面已審三輪", kind: accent},
  {text: "不動套件；沿用 FR-141／142／143 匯出", kind: plain},
  {text: "站在 FR-143 之上（需等其落地）", kind: crit}
]
footer: "FR-145 · 討論稿 · 2026-10-17 · 輸入：決策者 2026-10-17 需求與三輪雛形審查、FR-140／141／142／143 設計 · 現況依據：程式碼（2026-10-17）· 沿革見 git log"
---

> D1～D16 已全部拍板，下一步寫 design.md；本稿定案後不再改寫。

**狀態**：定案（D1～D16 已裁，雛形五畫面已審）　｜　**日期**：2026-10-17　｜　**雛形**：[prototype/index.html](prototype/index.html)

路徑慣例：BE 路徑相對 `compliance-manager-be/`；FE 路徑相對 `compliance-manager-fe/`。接在 `feature/FR-139`（FR-141、FR-142 已併入；FR-143 實作中）。

名詞：**輪次**＝`project_audit_rounds` 一筆，第 1 輪與每個覆核輪各一筆；**稽核次**＝FR-140 的概念，一輪內每次稽核一筆（內稽第 N 次、外稽第 N 次），各自一組 AP／AR／POA&M；**階段結案報告**＝一個輪次一份的結案報告；**專案總報告**＝一個專案一份，專案完成時建立；**定稿**＝鎖定總結段、記版號、報告包改正式版；**報告包**＝下載的 zip；**證據對照表**＝報告包內的 Excel 索引，一列一筆佐證。

## 變更紀錄 {#changelog nav="變更紀錄"}

| 日期 | 變更 | 對應 |
|---|---|---|
| 2026-10-17 | 初稿：需求白話、現況盤點、D1～D16 定案、資料落點、報告包契約、流程、拆卡草案；雛形三輪審查結論全部收進定案表 | — |

---

## 分工概述（30 秒版） {#overview nav="概述"}

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

| 棒 | 做什麼 | 產出 | 完成怎麼判定（決策者親手做什麼、看到什麼） |
|---|---|---|---|
| **0 雛形** | 純前端假資料五畫面 | `prototype/` | 已審定版（2026-10-17，三輪） |
| **1 稽核次下載＋報告加改善計畫節** | 「稽核作業」清單每列加「下載報告」下拉（Word／PDF／Excel）；FR-142 Word 報告附件後加「改善計畫」一節；Excel 選改善計畫版或稽核結果版 | FE 清單欄、BE 一支選檔端點、`ar_docx_generator` 加節 | 稽核作業清單上已結案列點「下載報告」選 Word，開檔最後一節是改善計畫表；無缺失的稽核次該節印「無」；稽核中列印「結案後開放」 |
| **2 報告自動建立＋結案報告清單** | 輪次結案事件：仍有不符合→建階段報告；專案完成事件→建總報告；清單一專案一列展開子列 | `project_summary_reports` 加欄、事件掛點、清單端點、FE 清單頁 | DEV 跑一輪有缺失結案，清單該專案展開多一列「第 N 輪結案報告 待撰寫」；跑一輪無缺失結案，只多「專案總報告」 |
| **3 階段結案報告頁＋Word／PDF** | 六章文件版面、第 5 章編輯器、存檔／定稿／修訂、下載 Word／PDF、附件一逐評估目標、下載日誌 | 新 app service、docx 範本、FE 報告頁 | 開報告頁六章內容與 DEV 該輪 AP／AR／POA&M 對得上；寫總結定稿後第 5 章唯讀、版本 v1；下載 Word 開檔六章加附件一；側欄下載紀錄多一列 |
| **4 報告包** | zip：Word、PDF、證據對照表、各稽核次 Word 與 Excel、證據資料夾（凍結版本）、問卷填答轉 PDF | `closing_report_bundle_service`、問卷轉 PDF | 下載 zip 解開，證據資料夾結構是族群／控制項／評估目標；對照表每列的路徑在 zip 內找得到檔；問卷佐證是 PDF；連結只在對照表 |
| **5 專案總報告** | 七章（多「各輪演進」與各輪總結帶入）、總報告包收各輪子包、合併證據對照表 | 沿用棒 3／4 加總報告分支 | 專案完成後清單多「專案總報告」，開頁第 2 章演進表一列一次稽核、第 5 章帶入第 1 輪已定稿總結；zip 內有各輪子資料夾 |
| **6 FR-143 Excel「列全部」開關** | 改善計畫工作表匯出加「列全部評估目標」開關（追加到 FR-143 棒 4，不另開） | `poam_workbook_*` | 匯出後符合的列也在、改善欄空 |

依賴：1 可先做（只靠 FR-141／142）；2 可先做；3、4、5 要等 FR-143 落地才有改善計畫資料；6 追加進 FR-143。

```{.mermaid cap="圖 1 — 棒次依賴"}
%%{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
    P[棒 0 雛形] --> R{決策者審 D1～D16}
    R --> D[design.md 開卡]
    D --> B1[棒 1 稽核次下載]
    D --> B2[棒 2 自動建立＋清單]
    B2 --> B3[棒 3 階段報告頁]
    B3 --> B4[棒 4 報告包]
    B3 --> B5[棒 5 專案總報告]
    B4 --> B5
    F143[FR-143 改善計畫] -.改善計畫資料、Excel.-> B1
    F143 -.-> B3
    F143 -.追加棒 6 開關.-> B4
```

---

## 需求 {#need nav="需求"}

### 決策者原話（2026-10-17）

> 1. 要可以下載結案報告一大包：調查結果 PDF（顧問）、控制項 Excel mapping 表、證據包（依照控制項結構分類）、稽核結果、稽核計畫
> 2. 要可以匯出稽核報告（內外都要）：內容是每個控制項的結果，以及改善計劃內容
>
> 稽核報告類型的 Excel 是不是只要給最後改善計劃出的那份就好，因為他有前面所有的延伸，但要調整成顯示全部的項目。Word 也只要有稽核結果的，這邊是不是跟在每一次的稽核輪後面、如果他已經完成的就可以下載？
>
> 結案報告有沒有機會分第一輪跟覆核輪分開出？當成兩次？最後還有一份總報告？我在模擬真實 PM 或顧問什麼時間點會被客戶要報告，那我們可能就在出該階段的報告。
>
> 要是都沒缺失，那就是直接寫總結報告。存檔、定稿、下載完整報告分開，下載用下拉選單按鈕來處理，可以參考稽核計畫那邊。要可以 PDF 或 Word 讓顧問自己去修正，我們紀錄有人下載、有日誌就好；至於顧問要怎麼拿回去修給客戶是他的事，我們介入不了。我們一樣提供定稿功能，後續我們不介入。

### 白話複述（決策者 2026-10-17 逐項裁決後定版）

1. **稽核報告掛在稽核次後面**。「稽核作業」清單每列右邊一顆「下載報告」，稽核次已結案才出現（矯正中也可，改善計畫章節印「尚未送出」）。點開三項：Word、PDF（FR-142 報告，附件後加一節「改善計畫」）、Excel（有改善計畫給改善計畫工作表、沒有給稽核結果工作表，一律列全部評估目標）。
2. **結案報告兩層**。階段結案報告一輪一份，只在輪次結案時仍有不符合（後面接覆核輪）才建；專案總報告一專案一份，專案完成時建。一次通過的專案只有總報告。覆核又沒過再開一輪，照樣建該輪的階段報告。
3. **報告由系統自動建立**，掛在輪次結案與專案完成兩個既有事件上，不設「建立」鈕。建立即「待定稿」，客戶要的時候進去寫總結。
4. **清單一專案一列**，點開看該專案的報告子列，階段報告依時間排、總報告固定最後。分段鈕：待撰寫／已完成／尚未結案。
5. **報告頁是文件版面**：封面資訊、編號章節、段落敘述、表格只放數字、右側固定目次。階段報告六章（專案概況、整體符合度、主要缺失與風險、改善計畫摘要、總結與建議、附件清單）加附件一逐評估目標判定；總報告七章（多「各輪演進」與「各輪總結」帶入）。只有「總結與建議」由人撰寫，不標撰寫者；其餘即時從 AP／AR／POA&M 算，不可編輯。
6. **三顆按鈕**：存檔（草稿）、定稿（鎖總結、記版號、報告包改正式版）、下載（下拉：Word、PDF、報告包 zip、報告包內容）。定稿後存檔消失、定稿變修訂，再定稿為下一版。未定稿下載為草稿版加浮水印。
7. **Word 與 PDF 都給**，顧問拿回去自行修改交付，系統不介入；每次下載記日誌（誰、何時、哪份、格式、版本）。
8. **報告包**：完整報告 Word 與 PDF、證據對照表 Excel、各稽核次 Word 與 Excel、證據資料夾（族群／控制項／評估目標，用結案時凍結的版本）。問卷填答轉 PDF 放進證據資料夾；連結只進對照表；未採用佐證留一列不收檔。總報告包原封收各輪子包，加合併對照表。
9. **版本回溯沿用既有歷史表**，每次存檔一筆、定稿標版號；還原只還總結段文字。
10. **不做**：差距分析報告（規劃期交付物，另案）；總報告「至今版」（未完成不出）；改善計畫 Word（FR-143 D7 已裁不做）；舊的未綁輪次「專案調查結果」留唯讀不遷移。

### 五個畫面長什麼樣

- **畫面 1 稽核作業下載**（[`audit-pass-exports.html`](prototype/audit-pass-exports.html)）：FR-142 清單原樣，最右欄「稽核報告」放「下載報告」下拉；稽核中列印「結案後開放」。
- **畫面 2 結案報告清單**（[`closing-report-list.html`](prototype/closing-report-list.html)）：一專案一列（專案進度、幾份待撰寫、最新定稿日），展開子列（報告、涵蓋稽核次、狀態、不符合、定稿日、版本、撰寫／開啟）。
- **畫面 3 階段結案報告**（[`round-closing-report.html`](prototype/round-closing-report.html)）：文件版面六章加附件一；頁首下載／存檔／定稿；右側目次與下載紀錄；「報告包內容」對話框看 zip 樹與對照表。`?issued=1` 看已定稿狀態。
- **畫面 4 專案總報告**（[`project-final-report.html`](prototype/project-final-report.html)）：七章，第 2 章各輪演進與跨多次稽核未改善項目判定軌跡，第 5 章帶入各輪總結。
- **索引**（[`index.html`](prototype/index.html)）。

---

## 現況盤點 {#inventory nav="盤點"}

### 能直接沿用的

| 需要的 | 現況 | 本案動作 |
|---|---|---|
| 稽核計畫 Word／PDF／Excel／zip | FR-141 `ap_report_export_service`、`ap_workbook_export_service`，`GET /ap/<uid>/export?format=` | 報告包直接呼叫 |
| 稽核結果 Word／PDF／Excel／zip | FR-142 `ar_report_export_service`、`ar_workbook_export_service`，報告名已帶「第 N 次內部／外部稽核」 | 棒 1 在 `ar_docx_generator` 附件後加「改善計畫」一節；報告包直接呼叫 |
| 改善計畫 Excel、OSCAL JSON | FR-143 棒 4（實作中） | 棒 6 追加「列全部」開關 |
| 稽核次結案鎖定與佐證凍結 | FR-142 D10 `ar_close_service`：守門三條→凍結採用佐證（雜湊、版本、問卷快照識別）→標記鎖定 | 證據包只用凍結那批 |
| 輪次結案／專案完成事件 | FR-140 `finalize_audit(terminal=)`、`close_round`；專案狀態 `ProjectStatus.COMPLETED` | 棒 2 在兩個事件掛「建報告」 |
| 「專案調查結果」頁與表 | `compliance.project_summary_reports`（name、summary）、歷史表 `project_summary_report_history`（type U 更新／R 還原）、能力點 `grc.summary-report.{read,create,update,delete,export}`、側選單 `report-manage`（`/project-summary-report`，群組 42 sort 70）、TipTap 編輯器 | 加欄綁輪次／專案與報告類型，頁面重做，選單改名「結案報告」，能力點沿用 |
| 稽核作業清單 | FR-142.8 改名「稽核作業」，歸屬判準 `project_participants` role in (auditor, manager, reviewer) | 加「下載報告」欄 |
| PDF 渲染 | `render_pdf`（WeasyPrint）、`SspLibreOfficeConverter`（docx→pdf） | 結案報告 Word 走 FR-141／142 同一份 docx 範本，PDF 經 LibreOffice |
| 稽核事件日誌 | `reference_audit_event_logging_pattern` 既有埋點機制 | 下載日誌走這裡，不另開表 |

### 缺口（要新做）

| 缺口 | 說明 |
|---|---|
| 控制項 Excel 對照表 | SSP 控制項實作只有 Excel 匯入沒匯出。本案以「證據對照表」承接：一列一筆佐證（稽核次、族群、控制項、評估目標、類型、名稱、zip 內路徑、雜湊／快照、採用） |
| 證據打包下載 | 全系統沒有把佐證檔依控制結構打包的能力 |
| 問卷填答轉 PDF | 問卷只有畫面，無匯出；證據包需要 |
| 結案報告內容生成 | 現在只有一個富文字框；六章要從 AP／AR／POA&M 即時算 |
| 逐評估目標判定軌跡 | 「每條評估目標在各稽核次怎麼判」沒有現成讀模型，要跨稽核次彙整 |

---

## 決策定案 D1～D16 {#decisions nav="定案"}

::: {.callout .decided}
**D1 稽核報告掛在稽核次後面，已結案（含矯正中）才可下載**

「稽核作業」清單每列最右「稽核報告」欄放「下載報告」下拉。稽核次狀態 closed 或 remediation 才出現；auditing 印「結案後開放」。矯正中（改善計畫未送出）可下載，Word 的改善計畫章節印「改善計畫尚未送出」。

**為什麼**：客戶常在內稽剛結束就要報告，等改善計畫送出才給會擋到。被排除：等改善計畫送出才亮。
:::

::: {.callout .decided}
**D2 Word 一份＝FR-142 報告加「改善計畫」一節；Excel 一份＝有改善計畫給改善計畫工作表、沒有給稽核結果工作表，一律列全部評估目標**

Word 在逐評估目標附件後加一節，列每條不符合評估目標的改善任務、執行人員、到期日、改善措施（從 FR-143 送出內容帶）；無缺失印「本次稽核無不符合項目，無改善計畫」。Excel 的「列全部」開關追加到 FR-143 棒 4，預設開，符合與不適用的列改善欄留空。PDF 與 Word 同內容。

**為什麼**：改善計畫工作表是三份往右延伸的終點，有完整軌跡；但 FR-143 的版本只列不符合，客戶要看全部。無缺失的稽核次沒有改善計畫，退回稽核結果版才不會沒 Excel 可下載。
:::

::: {.callout .decided}
**D3 兩層：階段結案報告一輪一份，專案總報告一專案一份**

階段結案報告綁 `audit_round_id`；專案總報告綁 `project_id`。清單同一入口，用子列位置區分（總報告固定最後）。

**為什麼**：客戶要報告的時間點是「這輪做到哪」與「整案做完了」，兩種用途不同；第一輪外稽沒過客戶就要知道狀況，不會等覆核。被排除：只有一份綁專案（沒有階段交付物）；只有階段報告沒總報告（董事會或認證機構要整案）。
:::

::: {.callout .decided}
**D4 階段結案報告只在輪次結案時仍有不符合才建；無不符合直接建總報告；覆核又沒過再開一輪照樣建**

輪次結案事件：該輪最終稽核 not_met > 0 → 建階段報告；= 0 → 專案隨之完成 → 建總報告。覆核輪結案若仍有不符合（再開下一輪）→ 建該輪階段報告。

**為什麼**：無缺失時階段報告與總報告內容幾乎相同，建兩份顧問看到的是重複；覆核沒過客戶一樣要報告。
:::

::: {.callout .decided}
**D5 報告由系統自動建立，不設「建立」鈕；建立即「待定稿」**

掛在 FR-140 既有的輪次結案與專案完成事件上。顧問看到的是清單上該專案多一份待定稿，客戶要時進去寫總結。結案報告不是流程站，停在待定稿不阻擋任何作業。

**為什麼**：前五章全是算出來的，建立本身沒有任何需要人決定的事，多一次「建立」只是多一個會忘的步驟。
:::

::: {.callout .decided}
**D6 狀態只有兩個：待定稿、已定稿；清單分段鈕依專案分「待撰寫／已完成／尚未結案」**

定稿後修訂再定稿為下一版，不另設狀態。清單不列尚未結案的輪次佔位列；尚無報告的專案仍列、標「尚未結案」。

**為什麼**：第一版四個狀態（待撰寫／可建立／已定稿／輪次未結案）決策者看不懂，其中兩個其實是「報告還不存在」的理由不是狀態。
:::

::: {.callout .decided}
**D7 清單一專案一列，展開子列；子列依時間序、總報告固定最後**

外層：專案、進度（第幾輪哪一站）、報告總覽（幾份待撰寫、幾份已定稿）、最新定稿日、顧問、專案經理。子列：報告名加「階段／總報告」小標籤、涵蓋稽核次、狀態、不符合、定稿日、版本、撰寫／開啟。PrimeVue DataTable 行展開。

**為什麼**：一列一份平鋪時同專案三份散在表裡，看不出一組；位置本身說明階段與總的關係。被排除：兩個頁籤（同專案要切兩邊）；卡片式（專案多撐不住，決策者裁清單一律表格）。
:::

::: {.callout .decided}
**D8 報告頁是文件版面；階段報告六章加附件一，總報告七章；只有總結由人寫、不標撰寫者**

封面（報告類型、標題、副標、基本資料八格）→ 編號章節（每章右上標資料來源）→ 段落敘述先於表格、表格加「表 N-M」標號 → 右側固定目次與下載紀錄。階段報告：1 專案概況、2 整體符合度（各稽核次總表＋控制族群 × 各稽核次矩陣，最右定論）、3 主要缺失與風險（最終稽核全部不符合，依風險排，不給勾選）、4 改善計畫摘要、5 總結與建議（編輯器）、6 附件清單、附件一逐評估目標判定（各稽核次 × 最終）。總報告：1 專案概況、2 各輪演進（一列一次稽核收斂表＋跨多次稽核未改善項目判定軌跡）、3 最終符合度（每條評估目標取最後一次判定）、4 缺失與改善紀錄、5 各輪總結（帶入各輪已定稿總結，唯讀）、6 專案總結與建議（編輯器）、7 附件清單、附件一。

**為什麼**：第一版資料卡堆疊被決策者說「像硬塞的、很不專業」；逐評估目標客戶愛收但 CMMC L2 有 320 條塞正文會撐爆，放附件。第 3 章不給勾選：系統已有紀錄，再篩是多餘；撰寫者不固定，不標「顧問」。
:::

::: {.callout .decided}
**D9 第 2 章定論取本輪最後一次稽核；總報告最終符合度取每條評估目標最後一次判定**

階段報告：定論＝該輪最後一個稽核次的 AR 結果（與稽核報告對得上）；前面各次列為軌跡。總報告：覆核輪只稽縮範圍，故逐條取最後一次判定彙整（57 條來自第 1 輪外稽、2 條來自覆核輪）。

**為什麼**：階段報告要與該輪稽核報告數字一致；總報告跨輪，最後一次稽核不是全範圍，只能逐條取。被排除：階段報告也逐條取（只有內稽的輪次會與稽核報告對不上）。
:::

::: {.callout .decided}
**D10 三顆按鈕分開：存檔、定稿、下載（下拉）；定稿後存檔隱藏、定稿變修訂**

存檔＝草稿不記版；定稿＝鎖第 5 章、記 v1／v2、報告包改正式版；下載下拉四項：完整報告 Word、完整報告 PDF、報告包 zip、報告包內容（看 zip 樹與對照表）。未定稿下載為草稿版加「草稿」浮水印，定稿後檔名帶版號。下拉元件照 FR-141 稽核計畫頁。

**為什麼**：存檔與定稿後果差太多（一個按錯沒事、一個要走修訂），合成一組反而易誤按；稽核計畫頁也是儲存與送審分開。被排除：存檔與定稿做一組下拉。
:::

::: {.callout .decided}
**D11 Word 與 PDF 都給，顧問自行修改交付；系統不介入，只記下載日誌**

每次下載記：誰、何時、哪份報告、格式、版本，走既有稽核事件機制不另開表；報告頁側欄顯示下載紀錄。定稿功能照舊提供。

**為什麼**：決策者裁「顧問怎麼拿回去修給客戶是他的事，我們介入不了」；日誌是唯一需要留的。
:::

::: {.callout .decided}
**D12 報告包結構與證據對照表；問卷填答轉 PDF；連結只進對照表；證據用結案凍結版本**

```
<專案>_<第N輪|專案總報告>_結案報告_v<N>/
├─ 00-完整報告.docx、00-完整報告.pdf
├─ 01-證據對照表.xlsx
├─ 第1次內部稽核/ 稽核報告.docx、改善計畫工作表.xlsx（或稽核結果工作表.xlsx）
├─ 第2次內部稽核/ …
├─ 第1次外部稽核/ …
└─ 證據/<族群>/<控制項>/<評估目標>/ 原檔、問卷填答_<問卷名>.pdf
```
對照表欄：稽核次、控制族群、控制項、評估目標、類型（檔案／問卷／連結）、名稱、包內路徑、雜湊／快照識別、採用。未採用留一列標「否」不收檔。證據取 FR-142 D10 結案凍結的那批（雜湊與版本已記）。總報告包：`第1輪/`、`覆核輪/` 原封收各輪子包，另加合併對照表（多「輪次」欄）與總報告。

**為什麼**：外稽單位拿到一包，看到「佐證是問卷」卻看不到內容等於沒給，故問卷轉 PDF；連結無法打包；用凍結版本才不會結案後證據被換導致包與報告對不上。被排除：問卷只寫進對照表不產 PDF；抓 living 證據池。
:::

::: {.callout .decided}
**D13 版本回溯沿用既有歷史表，定稿標版號；還原只還總結段**

`project_summary_report_history` 每次存檔一筆（type U），定稿一筆加 `version_no` 與 `issued=true`，還原一筆（type R）。歷史清單標出定稿版；定稿版的報告包存檔可重新下載。前五章即時算不存，無「還原到舊數字」。

**為什麼**：輪次已結案資料凍結，算出來永遠一樣，存快照是多餘；既有歷史頁已有載入與還原，只缺「哪幾筆是定稿」。
:::

::: {.callout .decided}
**D14 總報告定稿前各輪階段報告未定稿不擋；第 5 章該輪標「尚未定稿」**

**為什麼**：擋了會逼顧問回頭補一份客戶沒要的東西。
:::

::: {.callout .decided}
**D15 權限沿用 `grc.summary-report.*`；讀與下載給 manager 與 auditor，寫總結與定稿只給 manager；reviewer 不給**

稽核作業清單的「下載報告」沿用 FR-142 稽核結果匯出守門（看得到列即可下載），不另加能力點。選單「專案調查結果」改名「結案報告」，位置 群組 42 sort 70 不動（稽核計畫 40 → 稽核作業 50 → 改善計畫 55 → 結案報告 70）。

**為什麼**：帶案顧問在專案裡就是 manager；稽核人員要能拿報告但不該改總結。
:::

::: {.callout .decided}
**D16 調查結果 Word／PDF 套 FR-141／142 同一份 docx 範本；編輯器沿用 TipTap**

封面、頁首頁尾、字型與稽核計畫書、稽核報告一致。TipTap 3.7（MIT）已在用、資安已過，不換；工具列與內容排版已於 2026-10-17 重整（FE `760d6648`）。第 5 章 HTML 匯入 Word 前走既有 `bleach` 白名單。

**為什麼**：顧問交出去是一套；Quill 有已知 XSS 弱點且已自專案移除，其餘可選套件各有缺點（Lexical 無官方 Vue、Editor.js 輸出 JSON、CKEditor 商用要付費、wangEditor 排除）。
:::

---

## 資料落點 {#model nav="資料落點"}

### `compliance.project_summary_reports` 加欄

| 欄 | 型別 | 說明 |
|---|---|---|
| `report_type` | varchar(20) | `stage`（階段結案報告）／`final`（專案總報告）／`legacy`（既有未綁輪次） |
| `audit_round_id` | int FK `project_audit_rounds.id` | 階段報告必填；總報告 null |
| `status` | varchar(20) | `draft`／`issued` |
| `issued_version` | int | 最新定稿版號，未定稿 0 |
| `issued_at`、`issued_user` | timestamptz、varchar(50) | 最新定稿 |

既有 `name`、`summary`（第 5 章 HTML）、`project_id` 沿用；既有列 `report_type='legacy'`。唯一約束：同一 `audit_round_id` 一份、同一 `project_id` 的 `final` 一份。

### `compliance.project_summary_report_history` 加欄

`version_no` int（定稿才填）、`issued` bool。既有 type U／R 沿用。

### 下載日誌

走既有稽核事件：`event=closing_report_download`，payload `{report_uid, report_type, format(docx|pdf|zip), version, round_uid?}`。報告頁側欄讀該報告的事件。

### 定稿版報告包

定稿時產 zip 存儲存後端（既有 storage 設定），`project_summary_report_history` 定稿那筆記 `bundle_ref`；歷史頁可重下載該版。未定稿下載即時產、不存。

### 讀模型（即時算，不存）

| 章 | 來源 |
|---|---|
| 專案概況 | project、該輪 passes、每次 AP 的 terms-and-conditions（受稽單位、顧問、稽核人員、期間） |
| 整體符合度 | 每個稽核次 AR finding 統計；族群矩陣＝finding 依 control family 分組 × passes |
| 主要缺失與風險 | 最後一次稽核 finding state=not-satisfied，join risk characterizations severity、observation、remediation(recommendation) |
| 改善計畫摘要 | FR-143 POA&M：poam-item → response(planned) → task（執行人員、到期日、改善措施） |
| 附件一 | 逐 part_id：各 pass 的 finding state，縮範圍未涵蓋為 null |
| 總報告各輪演進 | 每輪每次 AR 統計；跨多次未改善＝同 part_id 連續 ≥2 次 not-satisfied |
| 總報告最終符合度 | 逐 part_id 取最後一次 finding |

---

## 端到端流程 {#flow nav="流程"}

```{.mermaid cap="圖 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 TD
    A[稽核次結案<br/>FR-142 ar_close] --> B{稽核作業清單<br/>該列「下載報告」亮}
    B --> B1[Word／PDF：FR-142 報告＋改善計畫節]
    B --> B2[Excel：改善計畫版或稽核結果版]
    A --> C{輪次結案<br/>FR-140 close_round}
    C -- 仍有不符合 --> D[建階段結案報告<br/>待定稿]
    C -- 無不符合 --> E[專案完成]
    E --> F[建專案總報告<br/>待定稿]
    D --> G[結案報告清單<br/>該專案展開多一列]
    F --> G
    G --> H[開報告頁<br/>六／七章即時算]
    H --> I[寫總結 → 存檔]
    I --> J[定稿：鎖總結、v N、報告包正式版]
    H --> K[下載：Word／PDF／zip<br/>記日誌]
    J --> K
    J --> L[修訂 → 再定稿 v N+1]
```

---

## 拆卡草案 {#cards nav="拆卡"}

| 卡 | 做什麼 | 主要檔 | 依賴 |
|---|---|---|---|
| 1 | 稽核作業清單「下載報告」下拉（FE）；BE 一支 `GET /audit-round/<uid>/pass/<pass_uid>/report?format=docx\|pdf\|xlsx` 依有無 POA&M 選檔；`ar_docx_generator` 加「改善計畫」一節 | FE 清單元件、`app/flow_control/service/ar_docx_generator.py`、新 route | FR-143 棒 1（POA&M 讀取） |
| 2 | migration 加欄；輪次結案／專案完成事件掛建報告；清單端點（一專案一列＋子列）；FE 清單頁重做；選單改名；舊列標 legacy | `scripts/sql/`、`app/project_summary_report/`、FE `ProjectSummaryReportManage.vue` 重做 | — |
| 3 | 階段結案報告讀模型（六章＋附件一）、報告頁 FE（文件版面、編輯器、存檔／定稿／修訂）、docx 範本與 Word／PDF 匯出、下載日誌 | 新 `closing_report_app_service.py`、`closing_report_docx_generator.py`、範本、FE 報告頁 | 2、FR-143 落地 |
| 4 | 報告包：zip 組裝、證據對照表、證據資料夾（凍結版本）、問卷填答轉 PDF、定稿版存檔 | 新 `closing_report_bundle_service.py`、`survey_response_pdf.py` | 3 |
| 5 | 專案總報告：七章讀模型、各輪演進、總報告包收子包與合併對照表 | 沿用 3／4 加分支 | 3、4 |
| 6 | （追加 FR-143 棒 4）改善計畫工作表匯出「列全部」開關 | `poam_workbook_*` | FR-143 |

守衛：卡 2 migration 走 `sql-migration` skill（主線 phase=active，出貨基線待重產）；卡 1～5 改到 `ar_docx_generator` 與報告範本時，FR-142 既有 e2e 不可壞。

---

## 不做清單 {#out nav="不做"}

- 差距分析報告（規劃期交付物；另確認 SSP 匯出是否印缺失與建議兩欄即可）。
- 總報告「至今版」（專案未完成不出）。
- 改善計畫 Word（FR-143 D7）。
- 舊「專案調查結果」遷移（標 legacy 唯讀，不給報告包）。
- 報告範本自訂（套 FR-141／142 同一份）。
- 編輯器更換（TipTap 沿用）。

---

## 坑與陷阱 {#pitfalls nav="坑"}

- **證據必須取凍結版本**：`ar_close_service._freeze` 記的雜湊與版本才是報告包要用的；抓 living 證據池會在結案後被換檔。
- **問卷快照識別**：凍結時記的是「填答快照識別」，轉 PDF 要用那個快照不是現在的填答。
- **縮範圍稽核的 null**：附件一與族群矩陣中，第 2 次內稽未涵蓋的評估目標是「未稽核」不是「未判定」，兩者語意不同，讀模型要分開。
- **改善計畫章節的三態**：有（印表）、無缺失（印「無」）、尚未送出（印「尚未送出」）；用 POA&M 存在與否加 round status 判。
- **報告包檔名含版號**：定稿版 `_v<N>`，草稿版不帶版號且 PDF 加浮水印；兩者不可混。
- **`project_summary_reports` 既有列**：`report_type` 預設要給 `legacy`，不可 NOT NULL 無預設直接加。
- **下載日誌 payload 不含內容**：只記識別與格式，不塞報告文字（資安 log 規則）。
- **DataTable 行展開**：PrimeVue 3.53 `expandedRows` 要用物件 key 不是陣列（FE frontend-overview §3.6 已列）。