# FR-046 交付文件內容架構（Phase 2 撰寫藍圖）

- **日期**：2026-07-04
- **狀態**：🛑 等 user 審核（核可後才 dispatch Task 6~10）
- **用途**：定義 GAI-SD-01/02/03/04/05 每份文件的章節骨架，作為 fan-out agent 的撰寫依據
- **真相來源**：endpoint 清單 `out/routes.json`（563 ep / 32 模組）、表清單 `out/db_schema.json`（146 表）、依賴 `out/licenses.json`
- **格式**：每章一個 `NN-<slug>.md`，章序 = meta.yaml `chapters`；標記規範見 conventions §C/§D

---

## GAI-SD-01 系統架構說明書（Opus · 預估 60~80 頁）

| 章 | 檔名 | 內容 | 圖 |
|----|------|------|----|
| 1 | 01-overview.md | Guidant AI 定位、合規稽核平台、稽核輪次模型（一專案=一輪主稽核+N覆核）、交付對象與閱讀指引 | — |
| 2 | 02-topology.md | 全系統拓撲：BE / FE / evidence agent / PostgreSQL / Redis / 外部 AI 的部署與資料流 | 拓撲圖 .dot |
| 3 | 03-tech-stack.md | 技術棧與版本矩陣（BE Python 3.11 / Flask、FE Vue 3 / Vite、PostgreSQL、Redis 版本表） | — |
| 4 | 04-backend-ddd.md | 後端 DDD 四層（api/app/domain/infra）職責邊界 + dependency-injector DI 機制 + @transaction session | 分層圖 .dot |
| 5 | 05-backend-modules.md | 後端模組地圖：32 個註冊模組各一段職責 + endpoint 數（取自 routes.json by_module） | — |
| 6 | 06-frontend.md | 前端架構：Vue 3 Composition API + Pinia + Vue Router + PrimeVue、BaseService/envelope 整合、i18n | FE 分層圖 .dot |
| 7 | 07-deployment.md | 部署架構：premise 與 AWS 兩型態、環境配置矩陣（佔位符）、進版/發版流程概觀 | 部署圖 .dot |
| 8 | 08-integrations.md | 外部整合：Google Drive 同步、AI 供應商（分類/報告）、evidence agent mTLS 通道概觀（詳見 SD-04） | — |

## GAI-SD-02 API 規格書（Sonnet ×6 · 預估 300+ 頁 · toc_depth=2）

**第一部 — API 設計規範總則**（batch 0 共同章，隨 batch 1 的 oscal agent 一起寫）

| 章 | 檔名 | 內容 |
|----|------|------|
| 1 | 01-api-conventions.md | envelope（code/data/msg）、JWT 認證與 get_user_context、分頁（RequestMetaSchema/PageDataDto）、error code 體系（GRC_<HTTP><序號>）、i18n、審計欄位慣例（created_user_name…）、RLS 對 API 的意義 |

**第二部 — 32 模組全量 endpoint 規格**（563 個，§D pattern：一 endpoint 一 H3 `### [METHOD] /path`，內固定小節 說明/權限/Request/Response/Error codes）

> 每個模組 = 一個 `NN-<module>.md` 章；撰寫分 6 batch（均分工作量，非章序）。章序按模組名。

| Batch | 撰寫模組（endpoint 數） | 小計 |
|-------|------------------------|------|
| 1 | oscal (97) | 97 |
| 2 | module_frame (73), evidence_classification (11), system_menu (9), translate (1) | 94 |
| 3 | auth (61), project_summary_report (13), device (10), uploadfile (7), notification (2) | 93 |
| 4 | survey (49), remote_agent (16), cloud_integration (11), bulletin (9), user_auth_provider (6), report (2) | 93 |
| 5 | project (41), participant (18), task_survey (14), feedback (11), information_system (6), log (2), label (1) | 93 |
| 6 | grc (35), flow_engine (29), system_config (12), subtask_status_history (9), ai (2), ai_dashboard (2), captcha (2), issue (1), notify_config (1) | 93 |

## GAI-SD-03 資料庫設計說明書（Sonnet · 預估 100~150 頁）

| 章 | 檔名 | 內容 | 圖 |
|----|------|------|----|
| 1 | 01-overview.md | 三 schema 定位（compliance 稽核 runtime / oscal 文件模型 / public 平台IAM）、146 表分佈、命名慣例、分區表說明（api_logs/system_logs） | — |
| 2 | 02-erd.md | ERD 按領域分張（每張 ≤25 節點）：① GRC runtime ② OSCAL 文件模型 ③ 平台 IAM | 3+ 張 .dot |
| 3 | 03-schema-compliance.md | compliance 41 表（§D 一表一 H3）；H2 分組：專案與稽核輪次 / Module Frame / 工作流與任務執行 / Remote agent | — |
| 4 | 04-schema-oscal.md | oscal 58 表；H2 分組：Catalog/Profile / SSP / Component Definition / AP / AR / POA&M / 共用 metadata | — |
| 5 | 05-schema-public.md | public 47 表；H2 分組：使用者與認證 / 多租戶與組織 / RBAC 權限 / 系統設定與日誌 / Drive 整合 / 裝置 / 公告議題標籤 / Migration | — |
| 6 | 06-rls.md | RLS tenant 隔離設計、session_scope 注入 app.user_id/allowed_tenant_paths、policy 樣式 | — |
| 7 | 07-jsonb.md | 重點 JSONB 欄位結構展開（挑 stage_objects / element_variables / oscal metadata 等） | — |
| 8 | 08-migration.md | Migration 機制：schema_migrations / schema_version / alembic_version 三者角色、SQL migration 慣例 | — |

## GAI-SD-04 權限與安全設計說明書（Opus · 預估 40~60 頁）

| 章 | 檔名 | 內容 | 圖 |
|----|------|------|----|
| 1 | 01-overview.md | 安全設計總覽、威脅邊界、認證/授權/隔離三支柱 | — |
| 2 | 02-rbac.md | RBAC 三層（角色 / ui_routes / capabilities），對照 roles/role_capabilities/route_capabilities/ui_routes 表；新功能納入權限流程 | RBAC 圖 .dot |
| 3 | 03-rls.md | RLS tenant 隔離機制、session 變數注入、與 DB policy 協作（與 SD-03 §6 交叉引用） | — |
| 4 | 04-jwt.md | JWT 生命週期：簽發 / 驗證 / refresh、claims 結構、middleware 攔截 | 流程圖 .dot |
| 5 | 05-secret-mgmt.md | 密碼 / secret 管理原則（DB_SECRET/JWT_SECRET/REDIS_SECRET 變數化、佔位符，不揭實值） | — |
| 6 | 06-mtls-agent.md | evidence agent mTLS 通道：build_cloud_mtls_context、憑證階層、JWT mint（agent 通道） | 通道圖 .dot |
| 7 | 07-audit-logging.md | 稽核事件與日誌：api_logs（90天）/ system_logs（180天）、event_code、留存政策 | — |

## GAI-SD-05 內部套件設計說明書（Opus · 預估 60~80 頁）

| 章 | 檔名 | 內容 |
|----|------|------|
| 1 | 01-overview.md | jedi-* 套件總覽、抽離理由（跨專案共用）、19 個使用中套件清單 + 依賴圖 |
| 2 | 02-versioning.md | 版本策略與發版機制：path dependency（dev）→ Nexus pin（release），poetry update 流程（Nexus URL 佔位符） |
| 3+ | 03-jedi-common.md … | **每個使用中 jedi-* 套件一章**：定位、模組結構、關鍵 class/service、公開介面、與主專案依賴。以 pyproject 實際 pin 的套件為準（撰寫前掃 pyproject 確認清單） |

> 套件章數 = 使用中套件數（pyproject 確認，約 19）；依賴圖 .dot 一張。

---

## 共同鐵則（每個 fan-out agent 都遵守）

1. 內容真相對照 code/DB 核實後才寫；清單類（endpoint/表/依賴）以 out/*.json 為唯一來源，不抄舊文件。
2. 格式守 conventions §C（md 子集）/ §D（對帳 heading pattern）；圖一律 .dot 進 src/assets/。
3. 敏感資訊佔位符（§B）；產品名 Guidant AI；禁晶晶體 / 禁「GRC 系統」。
4. 術語只引用/擴充 glossary.md，不自建定義段。
5. 完成後自跑 renderer build 確認能過；顯式 git add 檔名、禁 -am、不切 branch、不 push。