跳至主要内容

開發流程指南

本文檔定義從 Prototype 到生產整合的完整開發流程，涵蓋 SCRUM 方法論與各模組的協作方式。

實際案例參考: specs/florist/ 包含花店管理系統的產品規格，展示本流程的具體應用。

流程概述​

┌─────────────────────────────────────────────────────────────────────────────┐
│                              開發流程總覽                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Step 1: Prototype 開發                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  app-web-mockup + Mock API (MSW)                                    │   │
│  │                                                                     │   │
│  │  Product Roadmap → Epic → User Stories → SBE → Sprint → Tasks       │   │
│  │                                                                     │   │
│  │  產出：需求確認的 Prototype、SBE 規格文件                              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      ↓ 同步程式碼                           │
│  Step 2: 前端生產環境準備                                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  app-web + Mock API                                                 │   │
│  │                                                                     │   │
│  │  確保同步的程式碼可正常運作                                            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      ↓ 平行開發                            │
│  Step 3: 後端開發 + 漸進式整合                                              │
│  ┌──────────────────────────┐    ┌──────────────────────────┐              │
│  │       app-web            │←──→│      app-server          │              │
│  │    逐步切換真實 API       │    │    實作 RESTful API       │              │
│  └──────────────────────────┘    └──────────────────────────┘              │
│                                      ↓                                     │
│  Step 4: 完全整合與生產部署                                                  │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  app-web + app-server + app-web-host                                │   │
│  │                                                                     │   │
│  │  整合測試、WAR 封裝、部署準備                                         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

各階段產出物​

階段主要產出物存放位置
Step 1Epic、User Stories、SBE 規格、Prototype{project}/docs/、app-web-mockup/
Step 2生產前端程式碼app-web/
Step 3RESTful API、整合測試app-server/
Step 4可部署的 WAR 檔案app-server.war、app-web-host.war

實際案例: 花店管理系統的規格存放在 specs/florist/

US 開發階段​

每個 User Story 在 Sprint 內經歷四個階段閘門（stage gate），從 Prototype 驗證到整合交付。此模型讓 Sprint 看板能精確反映每個 US 的真實進度，而非僅有「In Progress / Done」兩種狀態。

四階段定義​

階段代碼環境驗證方式通過標準
Prototype E2EP.E2Eapp-web-mockup + MSWPlaywright 自動化測試所有 E2E 測試通過
Prototype 驗收P.UATapp-web-mockup + MSW/test-plan 手動測試指南PO 手動測試簽收
整合 E2EI.E2Eapp-web + app-serverPlaywright 自動化測試所有 E2E 測試通過（真實 API）
整合驗收I.UATapp-web + app-server手動測試指南最終手動測試簽收

階段流程​

🔲 待開發
 ↓
P.E2E ─── Prototype E2E 測試通過（app-web-mockup + MSW）
 ↓
P.UAT ─── PO 手動驗收 Prototype
 ↓
I.E2E ─── 整合 E2E 測試通過（app-web + app-server）
 ↓
 ✅  ──── I.UAT 通過，US 完成

與 Step 1–4 的對應關係​

四階段閘門對應到專案層級的 Step 1–4 開發流程：

US 階段對應 Step說明
P.E2E → P.UATStep 1: Prototype 開發在 app-web-mockup 中完成 UI 與 Mock API
I.E2EStep 2–3: 同步 + 後端整合程式碼同步至 app-web，後端 API 實作完成
I.UAT → ✅Step 3–4: 整合驗收前後端整合測試通過，PO 最終簽收

注意：並非所有 US 都會在同一個 Sprint 內走完四個階段。Prototype 階段（P.E2E / P.UAT）可在一個 Sprint 完成，整合階段（I.E2E / I.UAT）在後續 Sprint 進行。

Sprint Backlog 追蹤方式​

Sprint Backlog 表格以「目標」和「階段」兩個欄位追蹤每個 US 的進度：

  • 目標 — Sprint Planning 時決定，表示本 Sprint 預期將 US 推進到哪個階段
  • 階段 — Sprint 進行中即時更新，表示 US 目前的實際狀態
| # | US | 標題 | SP | 目標 | 階段 |
|---|-----|------|----|------|------|
| 1 | US-301 | 客戶基本資料管理 | 8 | P.UAT | P.E2E |
| 2 | US-302 | 客戶列表與搜尋 | 5 | P.UAT | 🔲 |
| 3 | US-201 | 創建訂單 | 13 | ✅ | I.E2E |

上例中：US-301 和 US-302 本 Sprint 只做到 Prototype 驗收；US-201 是從前一個 Sprint 延續的整合工作，目標是完成。

階段符號說明：

  • 🔲 — 待開發
  • P.E2E — Prototype E2E 測試通過
  • P.UAT — Prototype 驗收通過
  • I.E2E — 整合 E2E 測試通過
  • ✅ — 整合驗收通過（US 完成）

Step 1: Prototype 開發（app-web-mockup）​

產品規劃流程​

Prototype 開發前需完成產品規劃，產出需求規格文檔：

Product Roadmap → Epic → User Stories → SBE → Sprint Planning → Tasks

各文檔的撰寫規範與範本請參閱 規格撰寫指南，Sprint 規劃使用 /sprint Skill。

實際案例: 花店管理系統規格

SCRUM 迭代​

每個 Sprint 週期建議為 1–2 週，迭代流程：

Sprint Planning → Tasks → Daily Scrum → Sprint Review → Sprint Retrospective

Sprint 內每個 US 的進度以 US 開發階段（🔲 → P.E2E → P.UAT → ...）追蹤。

Prototype 開發環境​

模組用途
app-web-mockup前端 Prototype（快速迭代）
MSW (Mock Service Worker)Mock API，不依賴後端

開發過程中，前端 UI 與 Mock API 在 app-web-mockup 中同步推進，PO 可隨時驗收 Prototype。

Step 2: 程式碼同步（app-web-mockup → app-web）​

同步時機​

當 Prototype 達到以下條件時進行同步：

  1. Sprint 目標完成
  2. 需求已確認（Product Owner 驗收）
  3. Mock API 規格已穩定

同步範圍​

目錄/檔案是否同步
applets/、components/、config/同步
features/、hooks/、layouts/同步
mocks/、nls/、routes/同步
services/、store/、types/、utils/同步
App.tsx同步
main.tsx謹慎同步
tailwind.css特殊處理（保留 import）
playground/、__tests__/不同步

同步步驟​

# 1. 確認 app-web-mockup 可正常建置
cd app-web-mockup
npm run build

# 2. 執行同步（手動或使用腳本）
# 複製需同步的目錄到 app-web/src/

# 3. 處理 tailwind.css
# 確保包含 @source 指令掃描元件庫原始碼

# 4. 驗證 app-web 可正常建置
cd app-web
npm run build

同步檢查清單​

  • 新增的目錄已複製
  • 修改的檔案已更新
  • 刪除的檔案已移除
  • tailwind.css 保留了框架 CSS import
  • npm run build 無錯誤
  • Mock API 可正常運作

Step 3: 後端開發 + 漸進式整合​

開發流程​

┌─────────────────────────────────────────────────────────────────┐
│                        平行開發                                  │
├─────────────────────────────┬───────────────────────────────────┤
│         app-web             │          app-server               │
├─────────────────────────────┼───────────────────────────────────┤
│  1. 使用 Mock API 開發      │  1. 依 SBE 設計 API               │
│  2. 逐步切換真實 API        │  2. 實作 Controller/Service       │
│  3. 處理整合問題            │  3. 撰寫單元/整合測試             │
└─────────────────────────────┴───────────────────────────────────┘

3.1 app-server 開發​

依據 SBE 規格開發​

SBE 中的 API 規格是 app-server 開發的依據：

docs/specs/sbe/epic-2/US-201-create-order/
    ↓ API 規格（Request/Response 範例）
app-server/src/main/java/.../controller/OrderController.java
app-server/src/main/java/.../service/OrderService.java
app-server/src/main/java/.../repository/OrderRepository.java

API 開發檢查清單​

  • Endpoint 路徑符合 SBE 定義
  • Request/Response 格式符合 SBE 定義
  • 錯誤碼符合 SBE 定義
  • 單元測試涵蓋 SBE 中的所有 Scenario
  • API 文檔已更新（Swagger/OpenAPI）

3.2 漸進式切換策略​

app-web 支援逐個 API 切換，確保整合過程可控。

MSW 控制機制​

MSW 透過 config.app.msw.enabled 控制，根據 Vite 環境自動判斷：

// src/conf/config.ts
export const config: AppEnvironConfig = {
  app: {
    msw: {
      enabled: import.meta.env.DEV, // 開發環境自動啟用
    },
  },
}
環境MSW 狀態說明
開發環境（npm run dev）自動啟用所有 API 由 MSW 處理
生產環境（npm run build）預設關閉所有 API 連接真實後端

逐模組切換​

MSW 設定 onUnhandledRequest: 'bypass'，未匹配的請求自動轉發到真實後端。

// src/mocks/handlers/index.ts
export const handlers = [
  // 移除已完成的 handler，讓請求走真實伺服器
  // ...authHandlers,    // 認證 API → 真實後端
  // ...orderHandlers,   // 訂單 API → 真實後端
  ...customerHandlers,   // 客戶 API → 繼續使用 Mock
];

3.3 整合測試​

測試策略​

測試類型工具說明
API 單元測試JUnitapp-server 內部測試
API 整合測試Spring Test測試完整 API 流程
E2E 測試Playwrightapp-web 對接真實 API

整合測試環境​

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    app-web      │───→│   app-server    │───→│    Database     │
│  (dev server)   │    │ (test profile)  │    │   (H2/Docker)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Step 4: 完全整合與生產部署​

生產環境必要模組​

模組用途產出物
app-web前端 SPAdist/（靜態檔案）
app-server後端 RESTful APIapp-server.war
app-web-host前端托管層（將 dist/ 封裝成 WAR）app-web-host.war

生產環境建置時，MSW 預設關閉（import.meta.env.DEV = false），所有 API 連接真實後端。

部署檢查清單​

  • 所有 MSW handler 已移除，API 完全切換至真實後端
  • E2E 測試通過（整合環境）
  • 環境變數已正確配置
  • 部署文檔已更新

建置指令、環境配置、部署架構等細節請參閱 部署指南。

相關文檔​

文檔說明
規格撰寫指南各類文檔的撰寫規範與範本
Claude Code Skills 總覽/sprint、/e2e、/test-plan 等開發相關 Skill
部署指南生產環境部署說明