# FR-046 客戶交付文件套件（架構顧問評估版）— Design

- **日期**：2026-07-04
- **狀態**：設計核可（user approved via brainstorming session）
- **目的**：產出一套可交付外部顧問的正式技術文件（Word），讓顧問理解 Guidant AI 全系統並提出架構建議
- **對應版本**：v1.8.0（文件內容以此版本的 code / DB 為真相基準）

---

## 1. 背景與範圍

客戶端需要交付文件給外部顧問做**架構評估**。經討論收斂：

| 決策點 | 結論 |
|--------|------|
| 文件範圍 | 架構 / API / DB / 權限安全 / jedi-* 套件 / 授權清單，共 6 份（不含部署、維運、使用手冊）|
| API 文件深度 | **完整規格版** — 全部 endpoint 的完整 request/response schema |
| 語言 | 繁體中文，技術名詞保留英文 |
| 系統範圍 | **全系統** — BE + FE（Vue 3）+ jedi-* 套件 + 部署拓撲（含 evidence agent）|
| jedi-* 揭露程度 | **完整揭露** — 寫到內部設計層級（模組結構、關鍵 class/service、依賴圖）|
| 交付格式 | Word（.docx），正式專業排版 |
| 產出方式 | **方案 A**：Markdown 內容源 + 共用 python-docx renderer 管線 |
| 封面 | 「OOOO 版權所有」佔位（公司名未定）+ 密等標示 |
| 產出位置 | `docs/交付文件/v1.8.0/` |

## 2. 交付物清單

| 編號 | 文件名 | 預估篇幅 | 內容主軸 |
|------|--------|---------|---------|
| **GAI-SD-01** | Guidant AI 系統架構說明書 | 60~80 頁 | 全系統拓撲（BE/FE/jedi-*/evidence agent/PostgreSQL/Redis）、DDD 分層與 DI 機制、BE 模組地圖、FE 架構章（Vue 3 + Pinia + PrimeVue、與 BE 整合方式）、部署架構（premise / AWS 兩型態）、技術棧與版本矩陣 |
| **GAI-SD-02** | Guidant AI API 規格書 | 300+ 頁 | 第一部：API 設計規範（envelope、JWT 認證、分頁、error code 體系、i18n）；第二部：28 模組全量 endpoint 完整規格（method/path/權限/request schema/response schema/error codes）|
| **GAI-SD-03** | Guidant AI 資料庫設計說明書 | 100~150 頁 | Schema 總覽（compliance / oscal / public）、全表結構（欄位/型別/預設值/註解）、FK 關係、ERD 圖（按領域分張）、RLS 設計、JSONB 欄位結構、migration 機制（schema_migrations）|
| **GAI-SD-04** | Guidant AI 權限與安全設計說明書 | 40~60 頁 | RBAC 三層（角色/ui_routes/capabilities）、RLS tenant 隔離（session 變數注入機制）、JWT 生命週期與 refresh、密碼/secret 管理、mTLS（evidence agent 通道）|
| **GAI-SD-05** | Guidant AI 內部套件設計說明書 | 60~80 頁 | 每個 jedi-* 套件一章：定位與抽離理由、模組結構、關鍵 class/service、公開介面、與主專案依賴圖、版本策略與發版機制（Nexus）|
| **GAI-SD-06** | Guidant AI 第三方元件與授權清單 | 15~25 頁 | BE（poetry）/ FE（npm）全依賴清單（名稱/版本/license/用途一句話）、license 類型彙總與風險註記、自有元件（jedi-*）標註 |

## 3. 目錄結構與產出管線

```
docs/交付文件/v1.8.0/
├── conventions.md                 # 撰寫規範（所有 agent 的共同憲法，見 §5）
├── src/
│   ├── doc-01-architecture/       # 每份文件一資料夾，每章一個 md（NN-<章名>.md）
│   ├── doc-02-api-spec/
│   ├── doc-03-database/
│   ├── doc-04-security/
│   ├── doc-05-internal-packages/
│   ├── doc-06-licenses/
│   ├── glossary.md                # 六份共用術語表（各文件附錄引用同源）
│   └── assets/                    # Graphviz .dot 源檔（build 時轉 PNG）
└── GAI-SD-0N-<文件名>-v1.8.0.docx  # build 產物，最終交付版才 commit
scripts/deliverables/render_docx.py  # 共用 renderer（md → docx）
```

原則：
- **Markdown 是唯一內容源**，docx 是 build 產物；改版只改 md 重跑 renderer。
- Renderer 統一產出：封面（文件編號 / 版本 / 日期 / 密等 / 「OOOO 版權所有」/ 撰寫與審核欄）、版本紀錄表、自動目錄、多層章節編號、頁首頁尾（文件編號 + 密等 + 頁碼）、統一表格樣式、Graphviz 圖嵌入。
- md 格式約定（heading 層級 ↔ Word 樣式對映、表格語法、圖引用語法）定義在 `conventions.md`，renderer 按約定解析。

## 4. 內容真相來源（鐵則：從 code / DB 產生，不從舊文件抄）

| 文件 | 真相來源 |
|------|---------|
| GAI-SD-02 endpoint | **實際掃 code**：Flask route 註冊（`config/app_modules.py` + 各模組 `api/`）+ marshmallow schema。既有 `docs/api/` SA/SD 完整度不一，只當敘述參考，不當清單來源 |
| GAI-SD-03 表結構 | 連 DEV DB `information_schema` + ORM model（含 `comment=`）匯出；`docs/claude/database-schema.md` 只當敘述參考 |
| GAI-SD-06 依賴 | `poetry show` / `pyproject.toml` + FE `package.json` / `npm ls`，license 欄位程式化取得 |
| GAI-SD-01/04/05 | 以 `docs/system-design/`、`docs/claude/architecture-details.md`、`docs/claude/jedi-packages.md` 等素材為底，但每個技術描述必須對照當前 code 校驗後才寫入 |

## 5. 撰寫規範重點（完整版落在 conventions.md）

1. **語言**：繁體中文；技術名詞保留英文（endpoint / JWT / RLS…）；動詞與連接詞一律中文（禁晶晶體）。
2. **產品名**：一律 **Guidant AI**，不得稱「GRC 系統」。
3. **敏感資訊鐵則（客戶交付版，比內部文件更嚴）**：
   - 內部 IP（`192.168.x.x`）、dev / stg 帳號密碼、內部 Nexus URL、`.env` 內容**一律不得出現**。
   - 環境描述用佔位符（`<DB_HOST>`、`<NEXUS_URL>`）。
   - 驗收時全文 grep 掃描為 0 才過。
4. **文件編號**：`GAI-SD-<NN>`；封面含版本（v1.8.0）、日期、密等（**機密 Confidential**）、「OOOO 版權所有」、撰寫 / 審核欄位。
5. **圖**：架構圖 / ERD / 流程圖一律 Graphviz `.dot` 源檔進版控，build 時轉 PNG 嵌入；禁止手畫貼圖。
6. **術語表**：六份共用 `glossary.md`（SSP / AP / AR / POA&M / RLS / tenant…），各文件附錄由 renderer 帶入同一份。
7. **可程式解析標記（供 §7 對帳）**：GAI-SD-02 每個 endpoint、GAI-SD-03 每張表在 md 中必須用 conventions.md 定義的固定 heading / 表格 pattern 呈現，對帳 script 依 pattern 計數；「28 模組」為估計值，實際模組清單以執行時掃 `config/app_modules.py` 為準。

## 6. 執行規劃（agent 分工，三階段）

- **Phase 1（序列，先走通管線）**：
  1. 寫 `conventions.md`（含 md ↔ Word 格式約定）
  2. 寫 `scripts/deliverables/render_docx.py`（依 `docs/claude/docx-generation-pattern.md` 既有 python-docx 模式升級為通用 renderer）
  3. 用 **GAI-SD-06**（最小的一份）當 pilot 走完「md → docx」全流程，**user 驗收專業感合格後才放量**
- **Phase 2（並行 fan-out）**：
  - GAI-SD-01 / 03 / 04 / 05 各 1 個 agent
  - GAI-SD-02 按模組拆 5~6 個 agent（28 模組分批，各自掃 route / schema 產出全量規格）
  - 每個 agent 的 dispatch prompt 必含：conventions.md 全文、真相來源指示（§4）、顯式 git add 禁 `-am`
- **Phase 3（收斂）**：
  1. consistency reviewer agent 跨六份查術語 / 樣式 / 交叉引用一致性
  2. 程式化對帳（見 §7）
  3. build 全部 docx → user 人工審 → 最終交付版 commit

## 7. 驗收標準

- [ ] 每份 docx 封面 / 版本紀錄 / 目錄 / 頁首頁尾 / 表格樣式與 pilot 一致
- [ ] GAI-SD-02：文件內 endpoint 數 = 實際 route 註冊數（程式化對帳，不靠人眼）
- [ ] GAI-SD-03：文件內表清單 = DEV DB `information_schema` 表清單（程式化對帳）
- [ ] GAI-SD-06：依賴清單 = `poetry show` + `npm ls` 輸出（程式化對帳）
- [ ] 全文掃描：無內部 IP、無帳密 / secret、無「GRC 系統」字樣、無晶晶體
- [ ] 六份文件術語與 glossary.md 一致

## 8. 被排除的選項與理由

- **API 文件顧問評估版（代表性 endpoint）**：user 明確選完整規格版；Swagger 匯出附錄的混合案也被排除。
- **每份文件各寫 python-docx script（方案 B）**：內容埋在 code 裡難 review、六份樣式必然漂移；僅適合單份文件的既有 Setup Guide 情境。
- **pandoc + reference.docx（方案 C）**：封面 / 版本紀錄表 / Graphviz 嵌入控制力不足，「專業感」上限低。
- **英文或雙語**：顧問情境不需要，成本高。

## 9. 未來反悔條件

- 公司名確定後：renderer 封面常數換掉「OOOO」，重跑 build 即可，內容 md 零改動。
- 若顧問回饋「API 全量規格翻不完」：可從同一批 md 另 build 一份「精華版」（renderer 加章節過濾），不需重寫內容。
- 若日後要交付英文版：md 結構已按章拆分，可逐章翻譯另出 `src-en/`，renderer 共用。