ADR-001: docs-guides 文檔架構
ADR 編號: 001 狀態: 已接受 (Accepted) 決策日期: 2026-02-01 決策者: Development Team
摘要
採用「開發生命週期導向」架構組織 docs-guides/ 文檔，結合開發階段（入門→開發→測試→部署）與技能領域（前端/後端）兩個維度。
背景 (Context)
問題陳述
docs-guides 是 AppFuse 文檔站的主要入口，需要服務以下讀者：
- 新加入的開發者：需要快速上手專案
- 前端開發者：需要了解如何使用 appfuse-web 開發業務功能
- 後端開發者：需要了解如何使用 appfuse-server 開發 API
- DevOps 人員：需要了解部署與監控
與框架文檔的區別
| 面向 | docs-guides | docs-server / docs-web |
|---|---|---|
| 對象 | 應用開發者 | 框架使用者/貢獻者 |
| 內容 | 如何用框架建構應用 | 框架本身的功能與 API |
| 視角 | 業務開發者視角 | 框架開發者視角 |
| 範例 | 「如何在專案中使用 Cache」 | 「Cache 模組的所有功能」 |
限制條件
- 需作為文檔站的主要入口
- 需同時服務前端與後端開發者
- 需涵蓋從入門到部署的完整流程
- 需與框架文檔（docs-server、docs-web）互補
考量的方案 (Options Considered)
方案 A: Diátaxis 框架
說明: 採用 tutorials/how-to/concepts/reference 分類
優點:
- ✅ 有明確的分類標準
- ✅ 與 docs-web/guides 一致
缺點:
- ❌ 前後端內容會混在一起
- ❌ 開發者習慣按技能領域查詢
- ❌ 不符合「入門→開發→部署」的學習順序
評分: 2/5
方案 B: 純技能領域分類
說明: 按 frontend/backend/devops 等技能領域劃分
優點:
- ✅ 符合開發者身份認同
- ✅ 易於找到對應內容
缺點:
- ❌ 跨領域內容難以歸類
- ❌ 入門指南不屬於任何領域
- ❌ 缺乏學習順序引導
評分: 3/5
方案 C: 開發生命週期導向
說明: 結合開發階段與技能領域，形成矩陣結構
優點:
- ✅ 有明確的學習路徑（入門→開發→測試→部署）
- ✅ 開發階段內再按技能領域細分
- ✅ 新手可循序漸進，老手可直接跳到對應章節
- ✅ 與實際開發流程對應
缺點:
- ❌ 需同時維護階段與領域兩個維度
- ❌ 部分內容可能跨多個階段
評分: 4/5
決策 (Decision)
選擇方案: C - 開發生命週期導向
核心理由:
- 提供清晰的學習路徑，新手知道從哪開始
- 按技能領域細分，開發者能快速定位
- 與實際開發流程對應，符合直覺
目標結構
docs-guides/
├── README.md # 導覽頁（含學習路徑）
│
├── getting-started/ # 🚀 入門階段
│ ├── README.md
│ ├── setup.md # 環境設定
│ ├── local-development.md # 本地運行
│ └── development-workflow.md # 開發流程
│
├── concepts/ # 💡 核心概念
│ ├── README.md
│ ├── architecture.md # 系統架構
│ ├── project-structure.md # 專案結構
│ ├── environments.md # 環境配置
│ └── mock-to-real-api.md # Mock → 真實 API
│
├── frontend/ # 🎨 前端開發
│ ├── README.md
│ ├── appfuse-usage.md # 框架使用
│ ├── applet-development.md # Applet 開發
│ ├── form-handling.md # 表單處理
│ ├── state-management.md # 狀態管理
│ └── project-patterns.md # 專案模式
│
├── backend/ # ⚙️ 後端開發
│ ├── README.md
│ ├── appfuse-usage.md # 框架使用
│ ├── entity-design.md # Entity 設計
│ ├── database-migration.md # 資料庫遷移
│ └── project-patterns.md # 專案模式
│
├── testing/ # 🧪 測試階段
│ ├── README.md
│ ├── overview.md # 測試總覽
│ ├── frontend-testing.md # 前端測試
│ ├── backend-testing.md # 後端測試
│ └── e2e-testing.md # E2E 測試
│
├── deployment/ # 🚢 部署階段
│ ├── README.md
│ ├── overview.md # 部署總覽
│ ├── local.md # 本地部署
│ ├── staging.md # 暫存環境
│ ├── production.md # 生產環境
│ ├── unified-deployment.md # 統一部署
│ ├── monitoring.md # 監控
│ └── troubleshooting.md # 故障排除
│
├── reference/ # 📖 參考資料
│ ├── README.md
│ ├── project-initialization.md # 專案初始化
│ ├── versioning.md # 版本規範
│ └── contributing.md # 貢獻指南
│
└── decision-records/ # 📋 架構決策記錄
├── README.md
└── 001-guides-documentation-structure.md
分類定義
開發階段分類
| 階段 | 目錄 | 讀者狀態 | 內容類型 |
|---|---|---|---|
| 入門 | getting-started/ | 「我剛加入專案」 | 環境設定、第一次運行 |
| 理解 | concepts/ | 「我想了解系統」 | 架構、設計決策 |
| 開發 | frontend/ backend/ | 「我要寫程式」 | 實作指南、模式 |
| 測試 | testing/ | 「我要確保品質」 | 測試策略、工具 |
| 部署 | deployment/ | 「我要上線」 | 部署流程、監控 |
| 參考 | reference/ | 「我需要查資料」 | 規範、貢獻指南 |
| 決策 | decision-records/ | 「我想了解為什麼」 | 架構決策記錄 |
技能領域分類
| 領域 | 適用目錄 | 說明 |
|---|---|---|
| 前端 | frontend/、testing/frontend-* | React、Applet、表單 |
| 後端 | backend/、testing/backend-* | Spring Boot、Entity、API |
| 全端 | getting-started/、concepts/、deployment/ | 通用知識 |
實作指南 (Implementation Guidelines)
新增文檔時的判斷流程
這份文檔的主題是什麼？
│
├─ 環境設定、首次運行
│ └─ → getting-started/
│
├─ 架構設計、系統概念
│ └─ → concepts/
│
├─ 前端實作相關
│ └─ → frontend/
│
├─ 後端實作相關
│ └─ → backend/
│
├─ 測試相關
│ ├─ 前端測試 → testing/frontend-*
│ ├─ 後端測試 → testing/backend-*
│ └─ 通用測試 → testing/
│
├─ 部署、監控、維運
│ └─ → deployment/
│
└─ 規範、指南、參考
└─ → reference/
必須遵守的規則
- 開發階段優先：先判斷屬於哪個開發階段，再判斷技能領域
- 避免重複：與框架文檔互補，不重複框架 API 說明
- 連結框架文檔：涉及框架功能時，連結到 docs-server 或 docs-web
- 學習路徑：README.md 需維護學習路徑建議
命名慣例
| 目錄 | 命名規則 | 範例 |
|---|---|---|
| getting-started/ | 名詞或動名詞 | setup.md、local-development.md |
| concepts/ | 名詞 | architecture.md、environments.md |
| frontend/ backend/ | 名詞-動詞或功能名 | entity-design.md、form-handling.md |
| testing/ | 領域-testing | frontend-testing.md、e2e-testing.md |
| deployment/ | 環境名或動詞 | staging.md、monitoring.md |
檢查清單
新增文檔時：
- 確認屬於正確的開發階段
- 確認 sidebar_position 不重複
- 涉及框架功能時，連結到對應框架文檔
- 更新該目錄的 README.md（如需要）
- 如為重要入口，更新主 README.md 的學習路徑
與其他實例的關係
內容邊界
讀者問題 → 應該去哪裡找？
─────────────────────────────────────────────────────
「如何設定開發環境？」 → docs-guides/getting-started/
「Cache 模組有哪些功能？」 → docs-server/guides/core/cache
「如何在專案中使用 Cache？」 → docs-guides/backend/
「Applet 的設計理念是什麼？」 → docs-web/guides/concepts/
「如何開發一個 Applet？」 → docs-guides/frontend/applet-development
「如何部署到生產環境？」 → docs-guides/deployment/production
交叉引用原則
| 從 | 到 | 連結方式 |
|---|---|---|
| docs-guides | docs-server | 「詳細 API 請參閱 Cache 模組」 |
| docs-guides | docs-web | 「元件規格請參閱 元件庫」 |
| docs-guides | docs-methodology | 「開發流程詳見 開發方法論」 |
| docs-guides | docs-specs | 「完整範例請參閱 花店管理系統」 |
權衡分析 (Trade-offs)
我們獲得什麼 (Gains)
- ✅ 清晰的學習路徑
- ✅ 按技能領域快速定位
- ✅ 與實際開發流程對應
- ✅ 新手友善的入口設計
我們放棄什麼 (Losses)
- ❌ 與 docs-web/guides 的 Diátaxis 分類不一致
- ❌ 部分跨階段內容需決定主要歸屬
風險與緩解措施
| 風險 | 嚴重性 | 機率 | 緩解措施 |
|---|---|---|---|
| 與框架文檔內容重複 | 中 | 中 | 明確邊界：應用層 vs 框架層 |
| 跨階段內容歸類困難 | 低 | 中 | 以「主要用途」判斷，輔以交叉連結 |
相關文檔 (References)
內部文檔
- ADR-000: 文檔站整體架構 →
decision-records/000-documentation-site-architecture.md - docs-server ADR-004: 功能模組導向
- docs-web ADR-001: Diátaxis 結構
設計理念對照
| 實例 | 分類方式 | 理由 |
|---|---|---|
| docs-guides | 開發生命週期 | 應用層入口，需學習路徑 |
| docs-server | 功能模組導向 | 工具集框架，按模組查詢 |
| docs-web | Diátaxis | 應用框架，按情境查詢 |
變更歷史 (Change Log)
| 日期 | 變更內容 | 變更者 |
|---|---|---|
| 2026-02-01 | 初版，記錄現有架構設計 | Claude |
| 2026-02-01 | 新增 decision-records/ 目錄至目標結構 | Claude |
文檔維護者: Development Team + AI Assistant 最後審閱: 2026-02-01