# GAI-SD-07 功能規格總覽 — 執行者 Prompt（自包含，可獨立 session 執行）

> 給執行 session 的開場 prompt（複製貼上即可）：
> ```
> 請讀 docs/features/FR-046-2607-client-delivery-docs/handoff/2026-07-04-gai-sd-07-functional-spec-prompt.md，
> 依其指示撰寫 GAI-SD-07 功能規格總覽（先完成冷接自檢與讀序，再開工），
> 完成後更新 tracker.md Task 14 與總藍圖 #9，停下等 user 驗收，不做收尾。
> ```
> 建議模型：**Opus**（跨模組業務綜合，非機械抽取）。

| 項目 | 內容 |
|------|------|
| 交付物 | `docs/交付文件/v1.8.0/src/doc-07-functional-spec/`（meta.yaml + 各章 md）+ build 出 `GAI-SD-07-Functional-Specification-v1.8.0.docx` |
| Branch | `main`（不切 branch、不 push） |
| 定位 | FR-046 交付套件的追加文件（總藍圖 #9），與 GAI-SD-01~06 同規範同管線 |

## 🧭 原始需求 / WHY

公司將 Guidant AI 交付客戶，外部顧問做架構評估，另需讓**客戶端工程師與 PM 從業務面理解系統做什麼**。GAI-SD-01~06 都是技術視角（架構 / API / DB / 安全 / 套件 / 授權），缺一份**業務功能視角**的總覽：系統有哪些功能、給誰用、典型使用流程、模組之間怎麼串。這就是 GAI-SD-07 要補的洞 —— 讀者拿它當「地圖」，再深入其他六份技術文件。

**冷接自檢 3 問**（答不出來先讀 design.md，別開工）：
1. 這份文件的讀者跟 GAI-SD-02（API 規格）的讀者用法差在哪？（業務地圖 vs 技術參考——決定本文件寫「情境與流程」，不寫 request schema）
2. 為什麼章節按「業務功能領域」分群、不按 32 個技術模組逐一寫？（讀者心智模型是功能，不是 code 目錄）
3. 內容真相來源的優先序是什麼？（現有系統實際行為 > 文件敘述；不確定就開 code / FE 選單驗證）

## §0 讀序（按順序，全讀）

1. `docs/features/FR-046-2607-client-delivery-docs/design.md`（§1 決策 / §5 規範）
2. `docs/交付文件/v1.8.0/conventions.md` **全文**（§A 語言 / §B 敏感資訊 / §C md 子集 / §E meta.yaml / §F 圖規範 / §G glossary 規則）
3. 已完成的參考範本：`docs/交付文件/v1.8.0/src/doc-01-architecture/`（尤其模組地圖章 — 32 模組職責一覽，本文件的功能分群要與它對得上）與 `doc-06-licenses/`（合格內容源長相）
4. 業務素材：`docs/user-manual/lifecycle-and-use-cases.md`（稽核全生命週期情境）、`docs/features/README.md`（FR 登記表 = 功能演進史）
5. `scripts/deliverables/out/routes.json`（32 模組清單 — 功能分群的完整性 checklist）

## §1 文件結構（章節骨架）

`docs/交付文件/v1.8.0/src/doc-07-functional-spec/`，meta.yaml：`doc_id: GAI-SD-07`、`name: Functional-Specification`、`title: Guidant AI 功能規格總覽說明書`、`subtitle: 架構評估交付文件`、`version: v1.8.0`、`classification: 機密 Confidential`、`copyright: OOOO 版權所有`、`audience: 外部架構顧問、客戶端工程與產品團隊`、`toc_depth: 3`。

| 章 | 內容 |
|----|------|
| 01 產品總覽 | Guidant AI 定位（合規稽核平台）、目標客群、使用者角色（系統管理員 / 稽核主管 manager / 稽核員 auditor / 受稽方…以系統實際角色為準）、支援的合規框架（CMMC 2.0、ISO 27001…以系統實況為準） |
| 02 稽核生命週期 | 全生命週期 4 階段流程（依 user-manual 素材 + 系統實況），一張 Graphviz 流程圖；每階段：目的 / 主要操作 / 產出物 |
| 03 功能模組總覽 | 業務功能分群 × 32 技術模組對照表（分群 ↔ 模組 ↔ 一句話職責 ↔ 主要角色），與 GAI-SD-01 模組地圖對齊、與 routes.json 32 模組零漏 |
| 04 專案與稽核管理 | 專案建立 / 參與者與角色指派 / 稽核輪次（一專案一輪主稽核 + N 覆核）/ BPMN 任務流程 |
| 05 合規框架與控制項管理 | 框架 PDF 匯入 / Catalog 與 Profile（基準線）/ 控制項結構（AO） |
| 06 SSP 管理 | SSP 建立與範本 / docx-xlsx 匯入匯出 / 版本管理 / 程序書引用 |
| 07 稽核執行 | AP 撰寫（行程 / 查核方法）/ AR 判定（觀察→發現→風險）/ POA&M 矯正追蹤 / xlsx-docx 匯入輔助 |
| 08 證據管理 | 上傳與集中儲存 / 證據分類（AI 輔助）/ Google Drive 同步 / 分散式檔案 agent |
| 09 報表與儀表板 | 專案摘要報表 / 儀表板 / 匯出 |
| 10 系統管理 | 帳號與 MFA / 選單與權限設定 / 系統參數 / 公告通知 / 日誌 |

每個功能章（04~10）固定小節：`功能目的`、`主要使用情境（Use Cases）`、`角色與權限重點`、`與其他功能的關聯`、`對應技術模組`（列模組名，供讀者跳 GAI-SD-02 查 API）。

### Use Case 規格格式（「主要使用情境」小節的固定寫法）

每個情境一個 UC，**一個 UC 一個 H4 + 一張表**，格式固定（供顧問評估與日後測試文件以 UC 編號溯源）：

```
#### UC-04-01 建立稽核專案並指派參與者

| 項目 | 內容 |
|------|------|
| 角色 | 稽核主管（manager） |
| 前置條件 | 已登入；具專案建立權限；合規框架已匯入 |
| 主要流程 | 1. 進入專案管理頁點「建立專案」 2. 填名稱 / 選框架與基準線 3. … |
| 例外情況 | 框架未匯入 → 無可選基準線，導引至框架管理；… |
| 產出 / 後置條件 | 專案建立，狀態為規劃中；參與者收到通知 |
```

- UC 編號規則：`UC-<章號>-<序號>`（如 UC-06-02 = 06 章 SSP 管理的第 2 個情境）。
- 主要流程寫在單一儲存格內以 `1. 2. 3.` 編號（conventions §C 儲存格不放多段落，用編號句即可）。
- 每章 2~5 個 UC，挑該功能**最核心的操作路徑**，不求窮舉；例外情況只列使用者實際會遇到的。
- 02 章生命週期的各階段段落，結尾以「相關 UC：UC-04-01、UC-07-02…」串接對應章的 UC 編號。

## §2 內容真相來源與紀律

1. **系統實際行為優先**：不確定的功能描述，開 BE route/service code 或 FE 選單（`public.ui_routes` enable=1）驗證，**不要憑 FR 文件的計畫內容寫**（計畫可能沒做完或改了）。
2. 角色名稱、狀態名稱、階段名稱以系統實際字面為準（查 i18n `config/translations/` 或 FE 顯示字串）。
3. 模組完整性：03 章對照表必須涵蓋 routes.json 全部 32 模組，一個都不能漏（可多個模組歸同一功能群）。
4. 寫作高度：**業務功能層**。不寫 endpoint path、不寫 table 名、不寫 class 名（那些屬 GAI-SD-01~05）；「對應技術模組」小節只列模組名。
5. UC 的前置條件與例外情況**以系統實際檢查為準**（對照 service 層前置條件驗證與 error code），不要寫想像中的規則；不確定就開 code 驗。
5. conventions §A/§B 全部適用：繁中、禁晶晶體、禁「GRC 系統」、敏感資訊佔位符。

## §3 執行步驟

1. 讀序（§0）→ 回答冷接自檢 3 問
2. 建 `doc-07-functional-spec/` + meta.yaml + 各章 md（图放 `src/assets/`，命名 `fs-*.dot`）
3. build 驗證：`poetry run python scripts/deliverables/render_docx.py "docs/交付文件/v1.8.0/src/doc-07-functional-spec"` 必須 ✅
4. 自查：conventions §B grep 掃描 0、「GRC 系統」0、03 章模組數 = routes.json 模組數
5. Commit（**顯式 git add 檔名，禁 `-am` / `add -A`**）：訊息 `docs(FR-046): GAI-SD-07 功能規格總覽 內容（總藍圖 #9）`；docx 不 commit
6. 更新 `docs/features/FR-046-2607-client-delivery-docs/tracker.md`：Task 14 狀態/commit/日期 + 總藍圖 #9 改 ✅ + session 紀錄加一列，一併 commit
7. **停**：給 user 一句話 status；不寫 changelog / SUMMARY / Notion（收尾等 user 下令）

## §4 不在 scope（別順手做）

- 不動 GAI-SD-01~06 內容（發現它們有錯 → 記下來回報，不直接改）
- 不做 Phase 3（對帳 script / 一致性 review / build 全部）
- 不碰 renderer（build 有問題先回報）