跳至主要内容

架構決策記錄 (ADRs)

Architecture Decision Records for AppFuse Server

本目錄記錄 AppFuse Server 框架的重要架構決策。每個 ADR 記錄一個特定的架構決策，包括背景、考量的方案、決策理由、權衡分析和影響。

📚 ADR 索引​

編號標題狀態決策日期主題
ADR-000ADR 模板模板-參考模板
ADR-001多租戶數據隔離策略✅ 已接受2025-12-23多租戶、數據隔離
ADR-002JSON 欄位處理策略⤴️ 已被取代（→ ADR-027）2025-12-22JSON、資料庫
ADR-003Entity 關聯設計策略⤴️ 已被取代（→ ADR-028）2025-12-23Entity、關聯設計
ADR-004guides 文檔架構✅ 已接受2026-02-01文檔結構
ADR-005檔案儲存與資料庫交易一致性✅ 已接受2026-06-22檔案儲存、交易一致性
ADR-006CacheManager 層記憶體預算管制⤴️ 部分取代（byte-heap → ADR-011）2026-06-22快取、記憶體管理
ADR-007CacheManager 層快取啟用開關（disableAll／狀態上提）✅ 已接受2026-06-22快取、除錯／測試
ADR-008Word 文件產生模組（隔離式、handle-based）✅ 已接受2026-06-23文件產生
ADR-009認證授權架構——雙模式資源伺服器✅ 已接受2026-06-24認證授權、安全性
ADR-010事件驅動通知子系統✅ 已接受2026-06-26通知、事件驅動
ADR-011Cache 記憶體預算改以 offheap 承擔 byte 封頂✅ 已接受2026-06-28快取、記憶體管理、JDK 25
ADR-012營業行事曆與日期可選性契約（BusinessCalendar）✅ 已接受2026-07-04行事曆、日期輸入、跨端契約
ADR-013代理與模擬——ActingContext 框架能力🟡 提議中2026-07-08認證授權、代理、模擬、稽核
ADR-014框架能力與參考接線碼的對偶（capability ↔ core slice）✅ 已接受2026-07-10框架設計、參考實作、SPI
ADR-015Reference Data 多語系（i18n）策略🟡 提議中2026-07-10Reference Data、i18n
ADR-016租戶隔離改採 Hibernate 原生 @TenantId✅ 已接受2026-07-15多租戶、數據隔離、安全性
ADR-017框架 jar 不擁有 @Entity——判準零的反向套用✅ 已接受2026-07-15框架設計、Entity、多租戶、中性
ADR-018auth 身分模型——Account 降為應用宣告的 seam 實體✅ 已接受2026-07-19認證授權、Entity、參考實作、中性
ADR-019通知主旨 env 前綴上收框架✅ 已接受2026-07-20通知、環境標示
ADR-020auth-admin optional feature（帳號／角色管理端點收編）⤴️ 已被取代（→ ADR-022）2026-07-20認證授權、feature
ADR-021模擬三路放行格架與 consent-based impersonation✅ 已接受2026-07-21認證授權、模擬、稽核
ADR-022auth-admin 降級為業務層參考實作✅ 已接受2026-07-22認證授權、參考實作
ADR-023auth 登入引擎上收框架 capability（契約驅動）✅ 已接受2026-07-22認證授權、框架設計、SPI
ADR-024capability／feature／參考實作三層定位；auth 資源實作降級業務層✅ 已接受2026-07-22框架設計、認證授權、參考實作
ADR-025M2M 憑證發放上收 auth capability；線格式對齊 RFC 6749；api-key 為第二憑證呈遞✅ 已接受2026-07-23認證授權、M2M、框架設計
ADR-026固定 application adapter 歸 Feature 所有✅ 已接受2026-07-25框架設計、Feature、Actuator
ADR-027JSON 欄位處理策略✅ 已接受2026-07-29JSON、資料庫可攜性
ADR-028Entity 關聯設計策略✅ 已接受2026-07-29Entity、關聯設計
ADR-029Headless 報表引擎與中介文件模型✅ 已接受2026-08-06報表、PDF、文件渲染
ADR-030互動式 Session 生命週期、Refresh Rotation 與錯誤契約🟡 提議中2026-08-11認證授權、Session、Refresh Token
ADR-031風險導向的 API Capability、資料範圍與稽核✅ 已接受2026-08-14認證授權、API、稽核

🔍 按主題檢索​

框架設計 / 參考實作 (Framework Design)​

快取 / 記憶體管理 (Cache / Memory)​

認證授權 / 安全 (Auth / Security)​

多租戶 (Multi-Tenancy)​

資料層設計 (Data Layer)​

Entity 設計 (Entity Design)​

檔案儲存 (File Storage)​

報表 / 文件產生 (Reporting / Document Generation)​

文檔結構 (Documentation)​

📖 如何閱讀 ADR​

對於新成員​

  1. 了解核心決策（必讀）:

  2. 實作指南:

    • 每個 ADR 的「實作指南」章節提供具體的檢查清單和程式碼範例

  3. 相關文檔:

    • ADR 記錄「為什麼」(Why)
    • 設計文檔（docs/design-guidelines/）記錄「怎麼做」(How)

對於 AI 助手​

  1. 快速查詢:

    • 使用上方的「按主題檢索」快速找到相關 ADR
    • 每個 ADR 都有「檢查清單」章節供驗證

  2. 理解脈絡:

    • ADR 的「背景」章節說明決策的前因後果
    • 「權衡分析」章節說明取捨

✍️ 如何撰寫 ADR​

何時需要 ADR？​

當面臨以下情況時，應該撰寫 ADR：

  • ✅ 重大架構決策: 影響整體架構或未來擴展性
  • ✅ 技術選型: 選擇框架、資料庫、儲存方案等
  • ✅ 設計模式: 採用特定的設計模式或實作方式
  • ✅ 權衡取捨: 需要在多個方案間做出選擇
  • ✅ 打破慣例: 不遵循常見做法或業界標準

撰寫步驟​

  1. 複製模板:

    cp 000-template.md 00X-your-decision.md

  2. 填寫內容:

    • 清楚描述問題背景
    • 列出所有考量的方案
    • 說明選擇的理由
    • 分析權衡與影響

  3. 審閱:

    • 團隊成員審閱
    • 確認決策合理性

  4. 更新索引:

    • 在本文檔（README.md）加入新的 ADR

📊 ADR 狀態說明​

狀態說明
提議中 (Proposed)正在討論中，尚未定案
已接受 (Accepted)已接受並實施
已棄用 (Deprecated)不再推薦，但尚未被取代
已取代 (Superseded)已被新的 ADR 取代

🔗 相關文檔​

設計文檔（How - 實作指南）​

📝 ADR 編號規則​

  • 000: 模板
  • 001-099: 基礎架構決策（多租戶、資料層、安全性）
  • 100-199: 功能模組決策（訂單、客戶、產品）
  • 200-299: 整合與部署決策（CI/CD、監控）

文檔維護者: Development Team + AI Assistant 最後更新: 2026-08-06