↑ 需求首頁 ⌂ 需求中心

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. 驗收標準

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 共用。