跳至主要内容

ADR-004: docs-server/guides 文檔架構

ADR 編號: 004 狀態: 已接受 (Accepted) 決策日期: 2026-02-01 決策者: Development Team

摘要​

採用「功能模組導向」架構組織 docs-server/guides/ 文檔，以框架提供的功能模組為主要分類維度，輔以快速開始、設計指南、最佳實踐等輔助分類。

背景 (Context)​

問題陳述​

AppFuse Server 是一個 Spring Boot 工具集框架，提供多個獨立的功能模組（如 Cache、HTTP、OAuth2 等）。需要一個文檔架構能：

  1. 讓開發者快速找到特定模組的使用說明
  2. 清晰展示框架提供的功能範圍
  3. 支援模組級別的深入學習

與 docs-web/guides 的差異​

面向docs-serverdocs-web
框架性質工具集（獨立模組）應用框架（整合式）
使用模式按需引用特定模組整體架構理解後使用
讀者需求「這個模組怎麼用？」「我想完成某個任務」
適合分類功能模組導向任務/情境導向（Diátaxis）

限制條件​

  • 需與現有 autogenerated sidebar 機制相容
  • 模組數量約 15 個，持續增加中
  • 需支援不同深度的閱讀需求（快速查閱 vs 深入理解）

考量的方案 (Options Considered)​

方案 A: Diátaxis 框架​

說明: 與 docs-web/guides 相同，採用 tutorials/how-to/concepts/reference 分類

優點:

  • ✅ 與 docs-web 一致
  • ✅ 有明確的分類標準

缺點:

  • ❌ 模組會被拆散到不同分類，難以完整了解單一模組
  • ❌ 讀者常見問題是「Cache 模組怎麼用」而非「我想解決快取問題」
  • ❌ 框架工具集的使用模式與應用框架不同

評分: 2/5

方案 B: 功能模組導向​

說明: 以框架提供的功能模組為主要分類，輔以通用分類

優點:

  • ✅ 符合讀者查詢習慣（按模組名稱找文檔）
  • ✅ 單一模組的所有資訊集中
  • ✅ 與程式碼結構對應，易於維護
  • ✅ 清晰展示框架功能範圍

缺點:

  • ❌ 需額外提供「學習路徑」引導新手
  • ❌ 跨模組的整合主題需獨立分類

評分: 4/5

方案 C: 混合式（模組 + Diátaxis）​

說明: 模組內部採用 Diátaxis 子分類

優點:

  • ✅ 結合兩者優點

缺點:

  • ❌ 結構過於複雜
  • ❌ 單一模組文檔量不足以支撐四種分類
  • ❌ 維護成本高

評分: 2/5

決策 (Decision)​

選擇方案: B - 功能模組導向

核心理由:

  1. 符合工具集框架的使用模式
  2. 讀者查詢習慣以模組為單位
  3. 與程式碼結構對應，降低維護成本

目標結構​

docs-server/guides/
├── README.md                 # 導覽頁（含學習路徑）
├── overview.md               # 框架概述
│
├── quickstart/               # 🚀 快速開始
│   ├── create-new-project.md
│   ├── project-structure.md
│   └── first-api.md
│
├── core/                     # 🔧 核心工具
│   ├── cache.md
│   ├── http.md
│   ├── csv.md
│   └── content.md
│
├── data/                     # 💾 數據存儲
│   ├── jpa.md
│   ├── search.md
│   ├── file.md
│   └── image.md
│
├── auth/                     # 🔐 安全認證
│   ├── security.md
│   ├── oauth2.md
│   ├── tenant.md
│   └── bearer-token-authentication.md
│
├── services/                 # 📮 應用服務
│   ├── mail.md
│   ├── nls.md
│   ├── link.md
│   └── error.md
│
├── design/                   # 📐 設計指南
│   ├── README.md
│   ├── database-design.md
│   ├── multi-tenancy.md
│   ├── authority-model.md
│   ├── file-handling.md
│   ├── file-storage.md
│   └── reference-data.md
│
├── integration/              # 🔌 整合指南
│   └── frontend-integration.md
│
├── security/                 # 🛡️ 安全架構
│   ├── security.plan.md
│   ├── security.tests.md
│   └── security.tasks.md
│
├── examples/                 # 💡 使用範例
│   └── cache-usage-examples.md
│
└── best-practices/           # ⭐ 最佳實踐
    └── overview.md

分類定義​

分類職責​

分類目的內容類型
quickstart/新手入門步驟式教學，30 分鐘內完成
core/核心工具模組HTTP、Cache、CSV、Content
data/數據存儲模組JPA、Search、File、Image
auth/安全認證模組Security、OAuth2、Tenant
services/應用服務模組Mail、NLS、Link、Error
design/設計原則架構決策的「How」說明
integration/整合指南與其他系統/框架的整合
security/安全架構安全性規劃與測試
examples/使用範例完整的實作範例
best-practices/最佳實踐經驗總結與建議

模組文檔結構​

每個模組文檔應包含以下章節：

# 模組名稱

## 概述
模組用途說明

## 快速開始
最簡使用範例

## 功能說明
詳細功能介紹

## 配置選項
Spring 配置參數

## 進階用法
複雜場景說明

## API 參考
主要類別與方法（或連結到 /server/api/）

## 相關資源
- 相關模組連結
- ADR 連結（如有）

實作指南 (Implementation Guidelines)​

新增文檔時的判斷流程​

這份文檔是關於什麼？
│
├─ 單一模組的使用說明
│  └─ → 對應模組目錄（core/、data/、auth/、services/）
│
├─ 新手入門教學
│  └─ → quickstart/
│
├─ 架構設計原則
│  └─ → design/
│
├─ 多模組整合
│  └─ → integration/
│
├─ 完整實作範例
│  └─ → examples/
│
└─ 經驗建議
   └─ → best-practices/

必須遵守的規則​

  1. 模組文檔完整性：單一模組的所有資訊應集中在同一文件
  2. 學習路徑：README.md 需提供新手學習路徑
  3. 交叉引用：模組間有關聯時，使用連結說明
  4. ADR 連結：涉及架構決策的模組，連結對應 ADR

命名慣例​

分類命名規則範例
模組文檔小寫模組名cache.md、oauth2.md
設計文檔小寫-連字號database-design.md
快速開始動詞-名詞create-new-project.md
範例模組-usage-examplescache-usage-examples.md

檢查清單​

新增模組文檔時：

  • 包含「概述」、「快速開始」、「功能說明」章節
  • 配置選項有完整說明
  • 連結到對應的 API 參考
  • 如有 ADR，加入連結
  • 更新 README.md 的模組列表

新增其他文檔時：

  • 確認分類正確
  • sidebar_position 不重複
  • 相關文檔有交叉引用

與 Diátaxis 的對應關係​

雖然不採用 Diátaxis 分類，但各目錄的內容性質可對應：

本架構分類Diátaxis 對應說明
quickstart/Tutorials學習導向，帶領完成目標
模組文檔（core/ 等）How-to + Reference 混合操作指南 + 規格說明
design/Explanation理解導向，解釋「為什麼」
examples/Tutorials（進階）完整範例
best-practices/Explanation經驗總結

權衡分析 (Trade-offs)​

我們獲得什麼 (Gains)​

  • ✅ 按模組查詢直覺
  • ✅ 與程式碼結構對應
  • ✅ 清晰的功能範圍展示
  • ✅ 模組文檔集中維護

我們放棄什麼 (Losses)​

  • ❌ 與 docs-web/guides 分類方式不一致
  • ❌ 跨模組主題需額外歸類

風險與緩解措施​

風險嚴重性機率緩解措施
新手不知從何開始中高README.md 提供學習路徑
模組過多時難以瀏覽低中按功能領域分組（core/data/auth/services）

相關文檔 (References)​

內部文檔​

外部資源​

變更歷史 (Change Log)​

日期變更內容變更者
2026-02-01初版，記錄現有架構設計Claude

文檔維護者: Development Team + AI Assistant 最後審閱: 2026-02-01