Epic 0: 平台基礎設施與橫切關注點

業務目標 (Business Goal)

建立一個安全、可擴展、可審計的多租戶平台基礎設施，為所有業務功能提供統一的支撐服務。這是整個花店管理系統的基石，確保系統的安全性、可靠性與可維護性。

核心價值主張

安全第一 - 多租戶數據隔離、JWT 認證、RBAC 權限控制
用戶體驗 - 統一的 Layout、友好的錯誤提示、即時通知
可審計性 - 所有關鍵操作都有完整的審計日誌
開發效率 - 提供可復用的基礎組件，加速業務功能開發

成功指標 (Success Metrics)

指標	目標值	衡量方式
登入成功率	> 99%	成功登入 / 總登入嘗試
Token 刷新失敗率	< 0.1%	Token 刷新失敗次數 / 總刷新次數
未授權訪問攔截率	100%	成功攔截未授權請求 / 總未授權請求
通知送達率	> 95%	成功發送 / 總通知數
審計日誌完整性	100%	關鍵操作記錄覆蓋率
平均頁面載入時間	< 1.5 秒	使用 Lighthouse 測量

功能範疇 (Scope)

1. 認證與授權 (Authentication & Authorization)

1.1 用戶登入

員工登入: 使用 Email + 密碼
- 支援「記住我」功能（延長 Token 有效期）
- 登入失敗 5 次後鎖定帳號 15 分鐘
- 記錄登入歷史（IP 地址、裝置資訊）
客戶登入: 未來支援（Epic 3）
- 支援 Email + 密碼
- 支援社交登入（Google、Facebook）

1.2 JWT Token 管理

Access Token: 短期有效（15 分鐘），用於 API 請求
Refresh Token: 長期有效（7 天），用於刷新 Access Token

Token 內容:

{
  "userId": "uuid",
  "tenantId": "uuid",
  "email": "user@example.com",
  "roles": ["ROLE_STAFF"],
  "iat": 1234567890,
  "exp": 1234568790
}

Token 撤銷: 支援登出時撤銷 Refresh Token（使用 Redis 黑名單）

1.3 角色基礎訪問控制 (RBAC)

8 種用戶角色（參考 roadmap.md 第二節）:

系統管理員 (ROLE_ADMIN) - 跨租戶管理
店主/超級管理員 (ROLE_OWNER) - 完整權限
店長 (ROLE_MANAGER) - 管理日常營運
銷售人員 (ROLE_SALES) - 訂單、客戶管理
會計 (ROLE_ACCOUNTANT) - 財務報表
採購 (ROLE_PURCHASER) - 商品採購
設計師 (ROLE_FLORIST) - 查看分配訂單、上傳作品照片
送貨員 (ROLE_DELIVERY) - 查看配送訂單、上傳簽收照片

權限檢查層級:

API 層級: 每個 API 端點使用裝飾器檢查角色
UI 層級: 根據角色顯示/隱藏功能按鈕
數據層級: 查詢時自動過濾（僅返回有權限的數據）

2. 通知系統 (Notification System)

2.1 通知通道

站內訊息 (In-App Notification): 優先實作
- 右上角通知鈴鐺圖示
- 未讀數量提示
- 點擊後標記為已讀
電子郵件 (Email): Phase 2
- 使用 SMTP 服務（如 SendGrid、AWS SES）
- 支援 HTML 模板
簡訊 (SMS): Phase 3
- 整合 Twilio 或當地簡訊服務商
- 僅用於高優先級通知

2.2 通知類型

系統通知: 登入成功、密碼變更
訂單通知: 狀態變更、配送提醒（整合 Epic 2）
支付通知: 支付成功、月結帳單提醒（整合 Epic 4）
異常警報: 配送失敗、庫存不足

2.3 通知偏好設定

用戶可自定義：

接收哪些類型的通知
使用哪些通道（站內/Email/SMS）
通知時段（如「僅在工作時間接收」）

3. 審計日誌 (Audit Logging)

3.1 記錄範圍

關鍵操作記錄:

認證事件：登入成功/失敗、登出、Token 刷新
訂單操作：創建、修改、刪除、狀態變更、價格調整
支付操作：支付處理、退款、月結確認
權限變更：角色分配、權限修改
數據導出：下載客戶資料、訂單報表

3.2 日誌格式

{
  "id": "uuid",
  "tenantId": "uuid",
  "timestamp": "2025-10-31T10:30:00Z",
  "userId": "uuid",
  "userEmail": "staff@florist.com",
  "userRole": "ROLE_STAFF",
  "action": "ORDER_CREATED",
  "resourceType": "Order",
  "resourceId": "uuid",
  "status": "SUCCESS",
  "ipAddress": "192.168.1.100",
  "userAgent": "Mozilla/5.0...",
  "details": {
    "orderId": "ABC-20251031-0001",
    "customerId": "uuid",
    "totalAmount": 3000
  }
}

3.3 查詢與合規

查詢功能: 管理者可按日期、用戶、操作類型查詢日誌
保留期限: 至少 3 年（符合財務審計需求）
導出功能: 支援導出為 CSV（用於審計報告）

4. 全域搜尋與過濾 (Global Search & Filtering)

4.1 搜尋範圍（Phase 2）

訂單：編號、客戶姓名、電話、地址
客戶：姓名、電話、Email、地址
商品：名稱、描述、類別

4.2 搜尋功能

即時搜尋: 輸入 3 個字元後開始搜尋
模糊匹配: 支援部分匹配（如搜尋「王」可找到「王小明」）
搜尋歷史: 記錄最近 10 次搜尋

5.1 Layout 結構

┌─────────────────────────────────────┐
│  Header (Logo, Search, User Menu)   │
├──────┬──────────────────────────────┤
│      │                              │
│ Side │                              │
│ Nav  │    Main Content Area         │
│      │                              │
│      │                              │
├──────┴──────────────────────────────┤
│  Footer (Copyright, Links)          │
└─────────────────────────────────────┘

5.2 Header 組件

Logo: 左上角，點擊回首頁
全域搜尋框: 中間（Phase 2）
通知鈴鐺: 右上角，顯示未讀數量
用戶選單: 右上角
- 用戶名稱 + 角色顯示
- 下拉選單：個人設定、登出

5.3 Application Launcher

Header 右側的 Grid3x3 圖示觸發 Modal 應用啟動器，根據角色動態顯示可用 Applet：

Applet	分類	所需角色
Home	other	所有角色
Orders	sales-marketing	`ROLE_SALES` 以上
Customers	sales-marketing	`ROLE_SALES` 以上
Products	operations	`ROLE_OWNER` 以上
Delivery	operations	`ROLE_DELIVERY` 以上
Reports	finance	`ROLE_OWNER` 以上
Settings	utilities	`ROLE_ADMIN`

功能特點：

搜尋：按名稱、描述、關鍵字搜尋
分類過濾：銷售行銷、營運管理、財務會計、工具程式、其他
角色權限：自動過濾無權限的 Applet

5.4 響應式設計

桌面版 (≥ 1024px): 完整 Header 工具列
平板版 (768px - 1023px): 自適應 Header
手機版 (< 768px): 精簡 Header + Hamburger 選單（輔助導航）

6. 錯誤處理與用戶反饋 (Error Handling & User Feedback)

6.1 Toast 通知

成功訊息: 綠色，3 秒後自動消失
錯誤訊息: 紅色，5 秒後消失（可手動關閉）
警告訊息: 黃色，4 秒後消失
資訊訊息: 藍色，3 秒後消失

6.2 表單驗證

即時驗證: 失去焦點時驗證單一欄位
提交驗證: 提交時驗證所有欄位
錯誤提示: 欄位下方顯示紅色文字

6.3 Loading 狀態

按鈕 Loading: 提交時顯示 spinner，禁用按鈕
頁面 Loading: 顯示骨架屏或 spinner
區塊 Loading: 部分區域載入時顯示 spinner

User Stories 列表

Sprint 1: 認證與基礎 Layout (P0 - 最高優先級)

Sprint 2+: 通知與審計 (P1 - 高優先級)

US-004: 站內通知系統（待建立）
US-005: 審計日誌記錄（待建立）
US-006: 通知偏好設定（待建立）

Phase 2: 進階功能 (P2 - 中優先級)

US-007: 全域搜尋功能（待建立）
US-008: 審計日誌查詢（待建立）
US-009: Email 通知（待建立）

Phase 3: 擴展功能 (P3 - 低優先級)

US-010: SMS 通知（待建立）
US-011: 登入歷史查詢（待建立）
US-012: 多因素認證 (MFA)（待建立）

技術依賴 (Technical Dependencies)

依賴對象	依賴內容	影響
後端 API	JWT 認證端點 (`/api/v1/auth/*`)	登入、Token 刷新
後端 API	用戶角色端點 (`/api/v1/users/me`)	獲取當前用戶資訊與角色
Redis	Token 黑名單	登出時撤銷 Token
SMTP 服務	SendGrid / AWS SES	Email 通知（Phase 2）
SMS 服務	Twilio	SMS 通知（Phase 3）
前端框架	React Router	路由保護 (Protected Routes)
前端狀態管理	Redux Toolkit	儲存用戶狀態與 Token

多租戶考量 (Multi-Tenancy Considerations)

1. 租戶識別

Token 中包含 tenantId: 所有 API 請求自動攜帶租戶資訊
中間件自動過濾: 後端自動將查詢限制在當前租戶

2. 數據隔離

用戶表: 每個用戶屬於一個租戶（tenantId 外鍵）
角色表: 角色在租戶層級定義（不同租戶可有不同角色配置）
審計日誌: 所有日誌與 tenantId 綁定

3. 跨租戶訪問保護

API 層級: 檢查請求的資源是否屬於當前租戶
錯誤響應: 返回 404 Not Found（而非 403，避免資訊洩漏）

4. 租戶配置

不同租戶可自定義：

Logo 與品牌顏色
訂單編號格式（如 ABC- 前綴）
通知偏好（預設開啟哪些通知）
稅率設定（如 5% 或 10%）

安全性考量 (Security Considerations)

1. 密碼安全

加密演算法: bcrypt（成本因子 12）
密碼強度要求:
- 最少 8 個字元
- 至少 1 個大寫字母
- 至少 1 個小寫字母
- 至少 1 個數字
- 至少 1 個特殊字元
密碼歷史: 不可重複使用最近 5 次的密碼

2. Token 安全

傳輸加密: 僅透過 HTTPS 傳輸 Token
儲存位置:
- Access Token: Memory (Redux Store)
- Refresh Token: HttpOnly Cookie（防止 XSS）
Token 簽名: 使用 RS256（非對稱加密）

3. API 安全

Rate Limiting:
- 登入端點: 5 次/分鐘/IP
- 一般 API: 100 次/分鐘/用戶
CSRF 保護: 使用 CSRF Token（針對 Cookie-based 認證）
XSS 防護: 所有輸出都進行 HTML 編碼

4. 審計與監控

異常登入偵測:
- 來自新 IP 的登入 → 發送通知
- 登入失敗 5 次 → 鎖定帳號
異常操作偵測:
- 短時間內大量 API 請求 → 觸發警報
- 嘗試訪問未授權資源 → 記錄到安全日誌

非功能性需求 (Non-Functional Requirements)

效能需求

登入 API 響應時間 < 300ms
Token 刷新響應時間 < 200ms
權限檢查響應時間 < 50ms
首頁載入時間 < 1.5 秒（使用 Lighthouse 測量）

可用性需求

認證服務可用性 > 99.9%（允許 43 分鐘/月停機）
Token 刷新失敗時自動重試（最多 3 次）
登入失敗時提供清晰的錯誤訊息

擴展性需求

支援同時 1000 個用戶在線
支援 100 個租戶（每個租戶 10-50 個用戶）
審計日誌支援每日 10 萬筆記錄寫入

可維護性需求

權限配置使用聲明式定義（YAML 或 JSON）
通知模板可視化編輯（未來功能）
審計日誌支援導出與分析

參考資料 (References)

產品路線圖 - Epic 0
用戶角色與權限設計
開發計畫 - Sprint 1
架構決策記錄 - JWT 認證策略 (待創建)

最後更新: 2025-12-20 撰寫者: Development Team

業務目標 (Business Goal)​

核心價值主張​

成功指標 (Success Metrics)​

功能範疇 (Scope)​

1. 認證與授權 (Authentication & Authorization)​

1.1 用戶登入​

1.2 JWT Token 管理​

1.3 角色基礎訪問控制 (RBAC)​

2. 通知系統 (Notification System)​

2.1 通知通道​

2.2 通知類型​

2.3 通知偏好設定​

3. 審計日誌 (Audit Logging)​

3.1 記錄範圍​

3.2 日誌格式​

3.3 查詢與合規​

4. 全域搜尋與過濾 (Global Search & Filtering)​

4.1 搜尋範圍（Phase 2）​

4.2 搜尋功能​

5. 基礎 Layout 與導航 (Layout & Navigation)​

5.1 Layout 結構​

5.2 Header 組件​

5.3 Application Launcher​

5.4 響應式設計​

6. 錯誤處理與用戶反饋 (Error Handling & User Feedback)​

6.1 Toast 通知​

6.2 表單驗證​

6.3 Loading 狀態​

User Stories 列表​

Sprint 1: 認證與基礎 Layout (P0 - 最高優先級)​

Sprint 2+: 通知與審計 (P1 - 高優先級)​

Phase 2: 進階功能 (P2 - 中優先級)​

Phase 3: 擴展功能 (P3 - 低優先級)​

技術依賴 (Technical Dependencies)​

多租戶考量 (Multi-Tenancy Considerations)​

1. 租戶識別​

2. 數據隔離​

3. 跨租戶訪問保護​

4. 租戶配置​

安全性考量 (Security Considerations)​

1. 密碼安全​

2. Token 安全​

3. API 安全​

4. 審計與監控​

非功能性需求 (Non-Functional Requirements)​

效能需求​

可用性需求​

擴展性需求​

可維護性需求​

參考資料 (References)​