花店管理系統規格文檔
📌 關於本目錄
本目錄包含 花店管理系統（多租戶 SaaS） 的完整產品規格文檔。
這是 AppFuse 框架的 參考實作規格，供以下模組共同使用：
模組 角色 使用方式 appfuse-web/src框架驗證 讀取規格，驗證框架功能 app-web-mockupPrototype 讀取規格，開發 UI 原型 app-web前端生產 讀取規格，實作前端功能 app-server後端生產 讀取並更新規格，實作 API 為什麼規格放在這裡？
- 共享真相來源 - 所有模組都能平等存取規格文件
- 雙向更新 - app-server 開發時可以直接更新 api-specs、data-models
- 變更追蹤 - Git 可清楚追蹤規格變更影響哪些模組
- 職責分離 - 框架文件（appfuse-web/docs）與應用規格分開管理
📂 文檔層級架構
specs/florist/
├── README.md # 本文檔（規格架構說明）
├── roadmap.md # 產品路線圖（戰略層級）
├── development-plan.md # 軟體開發計畫（執行層級）
│
├── epics/ # Epic 層級文檔
│ ├── README.md # Epic 索引與概覽
│ ├── epic-0-platform-infrastructure.md
│ ├── epic-1-product-management.md
│ ├── epic-2-order-lifecycle.md
│ ├── epic-3-customer-crm.md
│ ├── epic-4-invoicing-payment.md
│ └── epic-5-digital-assets.md
│
├── user-stories/ # User Story 層級文檔
│ ├── README.md # User Story 索引與模板
│ └── epic-{N}/ # 按 Epic 分組
│ └── US-{NNN}-{name}.md # 各 User Story 文檔
│
├── sbe/ # 實例化規格 (Specification by Example)
│ ├── README.md # SBE 概覽與模板
│ └── epic-{N}/ # 按 Epic 分組
│ └── US-{NNN}/ # 按 User Story 分組
│ └── scenario-{N}-{description}.md
│
├── api-specs/ # API 規格文檔
│ ├── README.md
│ ├── authentication.md # 認證相關 API
│ ├── products.md # 產品管理 API
│ ├── orders.md # 訂單管理 API
│ ├── customers.md # 客戶管理 API
│ └── payments.md # 支付管理 API
│
├── data-models/ # 數據模型文檔
│ ├── README.md
│ └── {entity}.md # 各 Entity 定義
│
├── decision-records/ # 應用架構決策記錄 (ADR)
│ ├── README.md
│ ├── 001-multi-tenancy-strategy.md
│ ├── 002-state-machine-for-orders.md
│ ├── 003-payment-gateway-selection.md
│ └── 004-image-storage-strategy.md
│
├── testing/ # 測試文檔
│ ├── README.md
│ └── US-{NNN}-manual-testing-guide.md
│
├── progress/ # 進度追蹤
│ ├── README.md
│ └── sprints/
│ └── sprint-{N}.md
│
├── design-reference/ # 設計參考
│ └── *.html # UI 設計稿
│
└── examples/ # 範例文檔
└── *.md
📚 各層級文檔說明
1. 📍 roadmap.md - 產品路線圖（戰略層級）
讀者: 產品經理、技術主管、利害關係人
內容:
- 產品願景與戰略主題
- Now-Next-Later 時間框架
- 關鍵成功指標 (KPIs)
- 用戶角色與權限矩陣
- 核心 Epics 概覽
- 非功能性需求
更新頻率: 每季度審視一次
2. 📋 development-plan.md - 軟體開發計畫（執行層級）
讀者: 開發團隊、Tech Lead、Scrum Master、QA
內容:
- 專案概覽與成功標準
- 開發階段規劃
- Sprint 規劃與 Backlog
- 技術棧與應用架構
- Git 工作流程與分支策略
- 測試策略
- CI/CD Pipeline
- 部署策略與回滾計畫
更新頻率: 每個 Sprint 檢視並調整
3. 📦 epics/ - Epic 層級文檔
讀者: 產品經理、技術架構師、Team Lead
內容: 從 roadmap 拆分出的詳細 Epic 描述
4. 📝 user-stories/ - User Story 層級文檔
讀者: 開發人員、測試人員、產品經理
內容: 使用者故事（遵循 INVEST 原則）
5. 🧪 sbe/ - 實例化規格 (Specification by Example)
讀者: 開發人員、測試人員
內容: 具體的測試場景與範例數據
6. 🔌 api-specs/ - API 規格文檔
讀者: 前端開發者、後端開發者
內容: REST API 端點詳細規格
維護者: 後端團隊主導，app-server 開發時產出/修改
7. 🗄️ data-models/ - 數據模型文檔
讀者: 後端開發者、DBA
內容: Entity 定義、關聯關係、欄位說明
維護者: 後端團隊主導，app-server 開發時產出/修改
8. 📋 decision-records/ - 應用架構決策記錄 (ADR)
讀者: 技術主管、架構師、資深開發者
內容: 花店管理系統特定的架構決策
注意: 框架層級的 ADR（如 AppletShell、Application Launcher）請參閱 appfuse-web/docs/decision-records/
🔄 文件維護職責
| 文件類型 | 主要維護者 | 說明 |
|---|---|---|
roadmap.md | 產品經理 | 產品願景與戰略 |
development-plan.md | Scrum Master | Sprint 規劃 |
epics/ | 產品經理 | 需求階段定義 |
user-stories/ | 產品經理 + 開發 | Three Amigos 協作 |
sbe/ | 前後端共同 | 規格變更需雙方同意 |
api-specs/ | 後端主導 | 後端開發時產出/修改 |
data-models/ | 後端主導 | 後端開發時產出/修改 |
decision-records/ | 前後端共同 | 重要技術決策 |
testing/ | QA 團隊 | 測試文檔 |
progress/ | Scrum Master | 進度追蹤 |
🔗 規格變更流程
後端需要修改規格時
後端發現需要修改規格（如 API 設計調整）
↓
更新 specs/florist/api-specs/ 或 sbe/
↓
Git commit 說明變更原因
↓
通知前端團隊
↓
前端根據變更更新 app-web（或 app-web-mockup）
↓
必要時更新 decision-records/ 記錄決策
規格變更檢查清單
- 更新對應的 API 規格文檔
- 更新對應的 SBE 場景
- 通知受影響的團隊成員
- Git commit message 清楚說明變更
- 重大變更需記錄在 decision-records/
📖 相關資源
開發方法論
框架文件
- UX 設計指南 - 互動設計原則（參閱 appfuse-web/docs/ux-guidelines.md）
- 框架架構決策 - Application Launcher、AppletShell 等（參閱 appfuse-web/docs/decision-records/）
參考文檔
- User Story Mapping - Jeff Patton
- Specification by Example - Gojko Adzic
- INVEST in Good Stories - Bill Wake
最後更新: 2024-12-23