架構決策記錄 (ADRs)

Architecture Decision Records for AppFuse Web Documentation

本目錄記錄 AppFuse Web 文檔的架構決策。

ADR 索引

編號	標題	狀態	決策日期
ADR-001	docs-web/guides 文檔架構	提議中	2026-02-01
ADR-005	Application Launcher 導航架構	已接受	2025-12-19
ADR-006	AppletShell 統一外殼架構	已接受	2025-12-19
ADR-007	Role + Authority 雙層權限模型	已接受	2025-12-19
ADR-008	表單部分更新策略	已接受	2025-12-21

編號說明：ADR-001 為 docs 結構決策；ADR-005~008 為框架設計決策。編號跳號為遷移前的歷史原因，保留原編號以維持引用連續性。

何時建立 ADR？

在此建立 ADR 當決策 影響框架設計 或 可被其他應用複用：

✅ UI 組件架構（如 AppletShell）
✅ 導航架構（如 Application Launcher）
✅ 權限模型設計
✅ 表單處理策略
✅ 通用的 UX 模式
✅ 文檔結構決策（如 Diátaxis 分類）

不在此建立：應用特定決策（多租戶策略、訂單狀態機、支付閘道等）請在該應用的 decision-records/ 目錄建立，例如花店範例見 specs/decision-records/。

ADR 文檔模板

使用 MADR (Markdown Any Decision Records) 格式：

# ADR-XXX: {決策標題}

## 狀態
{已提議 | 已接受 | 已棄用 | 已取代 by ADR-YYY} ({日期})

## 背景 (Context)
（為什麼需要做這個決策？遇到什麼問題？）

### 問題陳述
（用簡潔的語言描述要解決的問題）

### 限制條件
- 限制 1
- 限制 2

---

## 決策 (Decision)
### 選擇的方案
方案 X：{簡述}

### 實施細節
1. 步驟 1
2. 步驟 2

---

## 考慮的替代方案 (Alternatives Considered)

### 方案 A: {方案名稱}
**描述**: （簡述）
**優點**: ...
**缺點**: ...
**為何未採用**: ...

---

## 決策後果 (Consequences)

### 正面影響
- ✅ ...

### 負面影響
- ⚠️ ...（以及如何緩解）

### 風險
- 🚨 ...（機率: 低/中/高，影響: 低/中/高）

---

## 參考資料 (References)
- [...](URL)

命名規範

格式：XXX-{kebab-case-描述}.md
XXX 為三位數編號（001 起）
依時間順序遞增，不重用編號（即使 ADR 被取代）

撰寫指南

應建立 ADR 的情況：

架構選擇、技術棧選擇、設計模式選擇、API 設計、UX 模式標準化、重大程式碼結構變更

不需要 ADR 的情況：

日常功能實作、bug 修復、小型重構、配置變更

撰寫原則：

背景要充分（問題、限制、利害關係人）
至少列出 2-3 個替代方案與優缺點
後果要誠實（正面、負面、風險、緩解）
保持簡潔（不是教學，專注決策本身）

參考資源

對於 AI 助手

新增或修改 guides/ 文檔前：
- 必讀 ADR-001 了解 Diátaxis 分類標準
- 使用 ADR 中的「判斷流程」決定文檔歸屬
快速參考：
- tutorials/：帶讀者從零學會
- how-to/：解決特定問題
- concepts/：解釋為什麼
- reference/：規格資訊查詢

ADR 索引​

何時建立 ADR？​

ADR 文檔模板​

命名規範​

撰寫指南​

參考資源​

對於 AI 助手​