花店管理系統 - 軟體開發計畫

專案類型: 參考實作（Reference Implementation） 基於框架: @appfuse/appfuse-web 開發方法: Agile / Scrum Sprint 長度: 2 週

📋 目錄

專案概覽
開發階段規劃
Sprint 規劃
技術棧與架構
開發流程
測試策略
品質保證
部署策略
風險管理

專案概覽

專案目標

框架驗證 - 使用真實業務場景驗證 appfuse-web 框架的完整性
最佳實踐展示 - 提供完整的參考實作範例
框架改進 - 在實作過程中發現並改進框架不足

成功標準

✅ 完成 Epic 0-2 的核心功能實作
✅ 單元測試覆蓋率 > 80%
✅ E2E 測試覆蓋所有關鍵用戶流程
✅ 框架組件庫至少提取 10 個可復用組件
✅ 文檔完整（API、組件、使用指南）

專案範圍

Phase 1: MVP (最小可行產品)

Epic 0: 平台基礎設施（認證、權限、通知）
Epic 2: 訂單生命週期管理（核心流程）

Phase 2: 核心功能擴展

Epic 1: 產品與作品集管理
Epic 3: 客戶與企業帳戶系統

Phase 3: 進階功能

Epic 4: 發票與支付管理
Epic 5: 數位資產與簽收工作流程

開發階段規劃

Phase 1: MVP (第 1-5 週)

目標: 建立可運行的核心系統

Week 1-2: Epic 0 - 平台基礎設施

認證系統（JWT、登入/登出）
角色權限控制（RBAC）
基礎 Layout 與導航
通知系統（Toast、Email）

Week 3-4: Epic 2 - 訂單管理（核心）

US-201: 創建訂單
US-202: 確認訂單
US-203: 分配給設計師
US-206: 簽收上傳（簡化版）

Week 5: 整合測試與調整

E2E 測試（完整訂單流程）
效能優化
Bug 修復

Phase 2: 核心功能擴展 (第 6-11 週)

Week 6-7: Epic 1 - 產品管理

US-101: 創建產品
US-102: 上傳產品照片
US-103: 管理產品目錄

Week 8-9: Epic 3 - 客戶管理

US-301: 創建個人客戶
US-302: 創建企業客戶
US-303: 管理子帳戶

Week 10-11: Epic 2 - 訂單管理（進階）

US-207: 修改訂單
US-208: 取消訂單
US-209: 搜尋與過濾
US-212: 訂單通知

Week 12: 整合測試與調整

Phase 3: 進階功能 (第 13-19 週)

Week 13-14: Epic 4 - 支付管理

US-401: 記錄支付
US-402: 月結帳單

Week 15-16: Epic 5 - 數位資產

US-501: 作品照片管理
US-502: 簽收照片（完整版）

Week 17-19: 最終整合

完整 E2E 測試
效能優化
文檔完善

Sprint 規劃

Sprint 結構（2 週為一個 Sprint）

Sprint 1 (Week 1-2): 平台基礎 - 認證與權限

Sprint 目標: 完成用戶認證與角色權限系統

User Stories

US-001: 用戶登入 (5 點)
US-002: 角色權限控制 (8 點)
US-003: 基礎 Layout (5 點)

總 Story Points: 18 點

Sprint Backlog

任務	負責人	估時	狀態
實作 JWT 認證 API	Backend	1 天	📝 待處理
實作登入表單	Frontend	1 天	📝 待處理
實作 RBAC 中間件	Backend	2 天	📝 待處理
實作角色檢查 Hook	Frontend	1 天	📝 待處理
Layout 組件開發	Frontend	1.5 天	📝 待處理
導航選單組件	Frontend	1 天	📝 待處理
單元測試	All	1.5 天	📝 待處理
E2E 測試	QA	1 天	📝 待處理

Definition of Done

Sprint 2 (Week 3-4): 訂單管理核心

Sprint 目標: 完成訂單創建到簽收的核心流程

User Stories

US-201: 創建訂單 (5 點)
US-202: 訂單狀態流轉 (5 點)
US-203: 搜尋與過濾訂單 (3 點)

總 Story Points: 13 點

Sprint Backlog

任務	負責人	估時	狀態
訂單 API 實作	Backend	2 天	📝 待處理
訂單表單組件	Frontend	2 天	📝 待處理
狀態機實作	Backend	1 天	📝 待處理
訂單列表頁面	Frontend	1.5 天	📝 待處理
單元測試	All	1.5 天	📝 待處理
E2E 測試 (核心流程)	QA	1 天	📝 待處理

Sprint 3 (Week 5-6): 角色工作台

Sprint 目標: 完成三個角色工作台，實現訂單處理分工

User Stories

US-204: 店員工作台 (3 點)
US-205: 設計師工作台 (5 點)
US-206: 配送員工作台 (5 點)

總 Story Points: 13 點

Sprint Backlog

任務	負責人	估時	狀態
共用組件開發 (TaskCard, TaskGroup)	Frontend	1.5 天	📝 待處理
AppletShell 統一外殼	Frontend	1 天	📝 待處理
店員工作台 (SalesApplet)	Frontend	1 天	📝 待處理
設計師工作台 (DesignApplet)	Frontend	1.5 天	📝 待處理
配送員工作台 (DeliveryApplet)	Frontend	1.5 天	📝 待處理
照片上傳功能 (PhotoUploadDialog)	Frontend	1 天	📝 待處理
狀態更新 API 整合	Frontend	0.5 天	📝 待處理
單元測試	All	1 天	📝 待處理
E2E 測試 (工作台流程)	QA	1 天	📝 待處理

技術棧與架構

前端技術棧

後端技術棧（Mock API）

應用架構

導航架構

採用 macOS Launchpad 風格的 Application Launcher 作為主導航入口（參見 ADR-005）。

關鍵組件:

ApplicationLauncher: 全螢幕網格式應用選單
AppletRegistry: 集中式應用配置 (src/config/applet-registry.ts)
AppletShell: 統一外殼組件（參見 ADR-006）

角色工作台架構

訂單流程透過三個專用工作台實現角色分工：

工作台	角色	路徑	處理狀態	原始碼
店員工作台	ROLE_SALES	`/sales`	`pending_confirmation`	`src/applets/sales-applet/`
設計師工作台	ROLE_FLORIST	`/design`	`confirmed`, `in_production`	`src/applets/design-applet/`
配送員工作台	ROLE_DELIVERY	`/delivery`	`ready_for_delivery`, `out_for_delivery`	`src/applets/delivery-applet/`

共用組件架構

工作台共用組件位於 src/applets/shared/：

組件	用途	位置
`TaskCard`	任務卡片，顯示訂單摘要與操作按鈕	`src/applets/shared/task-card.tsx`
`TaskGroup`	任務分組，按狀態分類任務卡片	`src/applets/shared/task-group.tsx`
`OrderDetailDrawer`	訂單詳情抽屜	`src/applets/shared/order-detail-drawer.tsx`
`PhotoUploadDialog`	照片上傳對話框	`src/applets/order-applet/components/photo-upload-dialog.tsx`

TaskConfig 模式:

interface TaskConfig {
  status: OrderStatus;
  groupLabel: string;
  action: { label: string; nextStatus: OrderStatus };
  requiresPhoto?: boolean;
}

開發流程

Git Workflow

分支策略

main: 生產環境（僅包含穩定版本）
develop: 開發主線（整合所有功能）
feature/{US-ID}: 功能分支（如 feature/US-201）
hotfix/{issue}: 緊急修復分支

提交規範

使用 Conventional Commits：

<type>(<scope>): <subject>

<body>

<footer>

Type:

feat: 新功能
fix: Bug 修復
docs: 文檔更新
style: 格式調整
refactor: 重構
test: 測試相關
chore: 建置工具或輔助工具

範例:

feat(order): implement order creation form

- Add OrderForm component with validation
- Integrate with order API
- Add unit tests for form validation

Closes US-201

Code Review 流程

Code Review 檢查清單

功能性

符合 User Story 的驗收標準
處理所有錯誤場景
多租戶隔離正確

代碼品質

遵循專案編碼規範
無 TypeScript 錯誤或警告
無 ESLint 錯誤
無重複代碼

測試

單元測試覆蓋率 > 80%
關鍵路徑有 E2E 測試
測試案例涵蓋邊界條件

文檔

API 變更已更新文檔
組件有 Storybook Stories
README 或 CLAUDE.md 已更新（如需要）

性能

無明顯性能問題
圖片已優化
無記憶體洩漏

測試策略

測試金字塔

測試類型與工具

測試類型	工具	範圍	執行時機
單元測試	Jest + RTL	組件、Hooks、Utils	每次 commit
整合測試	Jest + MSW	API + 組件整合	每次 PR
E2E 測試	Cypress	完整用戶流程	每日 + 部署前
視覺回歸測試	Storybook + Chromatic	UI 組件	每次 PR
性能測試	Lighthouse	頁面載入效能	每週

測試覆蓋率目標

整體覆蓋率: > 80%
關鍵業務邏輯: 100%
UI 組件: > 80%
工具函數: 100%

測試執行策略

本地開發

# 單元測試 (Watch 模式)
npm run test:watch

# E2E 測試 (開發模式)
npm run cypress:open

CI/CD Pipeline

# 所有測試
npm run test:ci

# E2E 測試 (Headless)
npm run cypress:run

# 覆蓋率報告
npm run test:coverage

E2E 測試場景

關鍵用戶流程（必須覆蓋）

測試案例:

完整訂單流程（Happy Path）
店員工作台確認訂單流程
設計師工作台設計完成流程（含照片上傳）
配送員工作台簽收流程（含照片上傳）
訂單修改流程
訂單取消流程
多租戶隔離驗證
角色權限控制驗證（工作台存取限制）

品質保證

代碼品質檢查

Pre-commit Hooks (使用 Husky)

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

CI/CD Pipeline

GitHub Actions 配置範例

name: CI/CD Pipeline

on:
  push:
    branches: [develop, main]
  pull_request:
    branches: [develop]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Lint check
        run: npm run lint

      - name: Type check
        run: npm run type-check

      - name: Unit tests
        run: npm run test:ci

      - name: Build
        run: npm run build

      - name: E2E tests
        run: npm run cypress:run

      - name: Upload coverage
        uses: codecov/codecov-action@v3

性能監控

指標	目標	工具
首次內容繪製 (FCP)	< 1.5s	Lighthouse
最大內容繪製 (LCP)	< 2.5s	Lighthouse
首次輸入延遲 (FID)	< 100ms	Lighthouse
累積版面配置位移 (CLS)	< 0.1	Lighthouse
Bundle Size	< 500KB	Bundlesize

部署策略

環境配置

環境	用途	部署時機	URL
Local	本地開發	隨時	`localhost:5173`
Development	開發整合	每次 merge 到 develop	`dev.ROLE_FLORIST.example.com`
Staging	預生產測試	每次 PR 到 main	`staging.ROLE_FLORIST.example.com`
Production	正式環境	Release 後手動部署	`ROLE_FLORIST.example.com`

部署流程

回滾策略

若部署後發現嚴重問題：

風險管理

已識別風險

風險	影響	機率	緩解措施	負責人
框架 API 不足	高	中	邊開發邊擴展框架	Tech Lead
Mock API 與真實 API 不一致	中	中	提前定義 API 規格	Backend Lead
測試覆蓋率不足	中	低	強制 Pre-commit 檢查	QA Lead
時程延誤	高	中	每週檢討進度、調整範圍	PM
多租戶隔離漏洞	高	低	安全性審查、專項測試	Security Lead

風險監控

附錄

A. 開發環境設定

必要工具

Node.js 20+
npm 10+
Git 2.40+
VS Code (推薦)

VS Code 擴展

ESLint
Prettier
TypeScript Vue Plugin
Tailwind CSS IntelliSense
GitLens

首次設定

# 安裝依賴
npm install

# 啟動開發伺服器
npm run dev

# 運行測試
npm test

# 打開 Storybook
npm run storybook

B. 命名規範

檔案命名

組件: PascalCase.tsx (如 OrderForm.tsx)
Hooks: camelCase.ts (如 useOrder.ts)
Utils: camelCase.ts (如 formatDate.ts)
Tests: *.test.tsx 或 *.spec.tsx

變數命名

React 組件: PascalCase
函數: camelCase
常數: UPPER_SNAKE_CASE
類型: PascalCase

C. 參考資源

產品路線圖
Epic 文檔
User Stories
SBE 場景
API 規格
架構決策記錄 (ADR)
appfuse-web 框架文檔（參閱 appfuse-web/CLAUDE.md）

D. 相關架構決策

ADR	標題	說明
ADR-005	Application Launcher 導航架構	主導航入口設計
ADR-006	AppletShell 統一外殼架構	Applet 共用外殼組件

E. 角色工作台 User Stories

User Story	角色	說明
US-204	店員	確認待處理訂單
US-205	設計師	設計與照片上傳
US-206	配送員	配送與簽收

最後更新: 2025-12-19 維護者: Development Team

📋 目錄​

專案概覽​

專案目標​

成功標準​

專案範圍​

Phase 1: MVP (最小可行產品)​

Phase 2: 核心功能擴展​

Phase 3: 進階功能​

開發階段規劃​

Phase 1: MVP (第 1-5 週)​

Week 1-2: Epic 0 - 平台基礎設施​

Week 3-4: Epic 2 - 訂單管理（核心）​

Week 5: 整合測試與調整​

Phase 2: 核心功能擴展 (第 6-11 週)​

Week 6-7: Epic 1 - 產品管理​

Week 8-9: Epic 3 - 客戶管理​

Week 10-11: Epic 2 - 訂單管理（進階）​

Week 12: 整合測試與調整​

Phase 3: 進階功能 (第 13-19 週)​

Week 13-14: Epic 4 - 支付管理​

Week 15-16: Epic 5 - 數位資產​

Week 17-19: 最終整合​

Sprint 規劃​

Sprint 結構（2 週為一個 Sprint）​

Sprint 1 (Week 1-2): 平台基礎 - 認證與權限​

User Stories​

Sprint Backlog​

Definition of Done​

Sprint 2 (Week 3-4): 訂單管理核心​

User Stories​

Sprint Backlog​

Sprint 3 (Week 5-6): 角色工作台​

User Stories​

Sprint Backlog​

技術棧與架構​

前端技術棧​

後端技術棧（Mock API）​

應用架構​

導航架構​

角色工作台架構​

共用組件架構​

開發流程​

Git Workflow​

分支策略​

提交規範​

Code Review 流程​

Code Review 檢查清單​

測試策略​

測試金字塔​

測試類型與工具​

測試覆蓋率目標​

測試執行策略​

本地開發​

CI/CD Pipeline​

E2E 測試場景​

關鍵用戶流程（必須覆蓋）​

品質保證​

代碼品質檢查​

Pre-commit Hooks (使用 Husky)​

CI/CD Pipeline​

GitHub Actions 配置範例​

性能監控​

部署策略​

環境配置​

部署流程​

回滾策略​

風險管理​

已識別風險​

風險監控​

附錄​

A. 開發環境設定​

必要工具​

VS Code 擴展​

首次設定​

B. 命名規範​

檔案命名​

變數命名​

C. 參考資源​

D. 相關架構決策​

E. 角色工作台 User Stories​

📋 目錄

專案概覽

專案目標

成功標準

專案範圍

Phase 1: MVP (最小可行產品)

Phase 2: 核心功能擴展

Phase 3: 進階功能

開發階段規劃

Phase 1: MVP (第 1-5 週)

Week 1-2: Epic 0 - 平台基礎設施

Week 3-4: Epic 2 - 訂單管理（核心）

Week 5: 整合測試與調整

Phase 2: 核心功能擴展 (第 6-11 週)

Week 6-7: Epic 1 - 產品管理

Week 8-9: Epic 3 - 客戶管理

Week 10-11: Epic 2 - 訂單管理（進階）

Week 12: 整合測試與調整

Phase 3: 進階功能 (第 13-19 週)

Week 13-14: Epic 4 - 支付管理

Week 15-16: Epic 5 - 數位資產

Week 17-19: 最終整合

Sprint 規劃

Sprint 結構（2 週為一個 Sprint）

Sprint 1 (Week 1-2): 平台基礎 - 認證與權限

User Stories

Sprint Backlog

Definition of Done

Sprint 2 (Week 3-4): 訂單管理核心

User Stories

Sprint Backlog

Sprint 3 (Week 5-6): 角色工作台

User Stories

Sprint Backlog

技術棧與架構

前端技術棧

後端技術棧（Mock API）

應用架構

導航架構

角色工作台架構

共用組件架構

開發流程

Git Workflow

分支策略

提交規範

Code Review 流程

Code Review 檢查清單

測試策略

測試金字塔

測試類型與工具

測試覆蓋率目標

測試執行策略

本地開發

CI/CD Pipeline

E2E 測試場景

關鍵用戶流程（必須覆蓋）

品質保證

代碼品質檢查

Pre-commit Hooks (使用 Husky)

CI/CD Pipeline

GitHub Actions 配置範例

性能監控

部署策略

環境配置

部署流程

回滾策略

風險管理

已識別風險

風險監控

附錄

A. 開發環境設定

必要工具

VS Code 擴展

首次設定

B. 命名規範

檔案命名

變數命名

C. 參考資源

D. 相關架構決策

E. 角色工作台 User Stories