開發流程
本文檔說明花店管理系統的日常開發流程與最佳實踐。
開發環境啟動
每日開始
# 1. 更新程式碼
git pull origin main
# 2. 啟動前端（使用 Mock API，預設模式）
cd app-web
npm run dev
# 訪問 http://localhost:3000
前後端整合開發
需要測試真實後端 API 時：
# 1. 啟動後端
cd app-server
./gradlew bootRun
# 後端啟動於 http://localhost:8080/app-server
# 2. 修改前端配置，關閉 MSW
# 編輯 app-web/src/conf/config.ts
# 設定 app.msw.enabled = false
# 設定 app.baseURL = '/app-server'
# 3. 啟動前端
cd app-web
npm run dev
使用 Mock API 開發（預設）
前端預設啟用 MSW Mock API，可獨立開發不需啟動後端：
cd app-web
npm run dev
MSW 會在開發環境自動啟用，Console 會顯示
[MSW] Mock Service Worker started。
功能開發流程
1. 建立分支
# 從 develop 分支建立功能分支
git checkout develop
git pull
git checkout -b feature/US-101-product-list
命名規範
| 類型 | 格式 | 範例 |
|---|---|---|
| 功能 | feature/US-xxx-description | feature/US-101-product-list |
| 修復 | fix/issue-description | fix/login-redirect-error |
| 改善 | improve/description | improve/product-search-performance |
2. 開發功能
後端開發順序
- Entity - 定義資料模型
- Repository - 資料存取層
- Service - 業務邏輯
- Controller - REST API
- 測試 - 單元測試、整合測試
前端開發順序
- Mock API - 定義 API 回應格式
- Service - API 服務層
- Hook - 資料查詢/變更 hook
- Component - UI 組件
- Page - 頁面整合
- 測試 - 組件測試
3. 提交變更
# 查看變更
git status
git diff
# 暫存變更
git add .
# 提交（遵循 Conventional Commits）
git commit -m "feat(product): 新增商品列表頁面
- 實作商品列表 API 整合
- 新增搜尋與篩選功能
- 支援分頁"
Commit Message 規範
<type>(<scope>): <subject>
<body>
| Type | 說明 |
|---|---|
feat | 新功能 |
fix | 修復 bug |
docs | 文檔更新 |
style | 程式碼風格調整 |
refactor | 重構 |
test | 測試 |
chore | 雜項維護 |
4. 推送與建立 PR
# 推送分支
git push -u origin feature/US-101-product-list
# 建立 Pull Request（使用 GitHub CLI）
gh pr create --title "feat(product): 新增商品列表頁面" \
--body "## 變更內容
- 實作商品列表 API
- 新增搜尋與篩選功能
## 測試
- [ ] 單元測試通過
- [ ] 手動測試通過"
5. Code Review
- 至少一位團隊成員 review
- CI 檢查通過
- 解決所有 review 意見
6. 合併
# 合併到 develop
gh pr merge --squash
程式碼品質
執行 Lint 與格式化
# 前端 Lint 檢查
cd app-web
npm run lint
# 前端程式碼格式化
npm run format
# 檢查格式（不修改）
npm run format:check
執行測試
# 前端測試
cd app-web
npm run test
# 前端測試覆蓋率
npm run coverage
# 後端測試
cd app-server
./gradlew test
建置檢查
# 前端建置（含型別檢查）
cd app-web
npm run build
# 後端建置
cd app-server
./gradlew build
常見任務
新增 API 端點
- 定義 Entity（繼承
AuditableTenantEntity） - 新增 Repository（使用
EntityManager+TupleQueryBuilder） - 實作 Service 邏輯（
@Transactional） - 新增 Controller 端點（
@PreAuthorize權限控制） - 撰寫測試
新增前端頁面
- 新增 Mock Handler（
app-web/src/mocks/handlers/） - 新增 Service 方法（
app-web/src/services/） - 新增 React Query Hook
- 建立頁面組件
- 設定路由（
app-web/src/routes/） - 撰寫測試
資料庫變更
專案使用 Hibernate auto DDL（ddl-auto: update），Entity 變更會自動同步到資料庫：
- 修改或新增 Entity
- 重新啟動後端
- Hibernate 自動更新資料庫 Schema
注意：此模式適合開發環境。生產環境建議使用 Flyway 管理遷移。
疑難排解
相依性問題
# 前端
rm -rf node_modules package-lock.json
npm install
# 後端
./gradlew clean build --refresh-dependencies
資料庫狀態不一致
H2 資料庫重置：
# 刪除 H2 資料庫檔案（會清除所有資料）
rm -rf ~/Project/appfuse/var/data/app-server/appdb.*
# 重新啟動後端，Hibernate 會重建 Schema
./gradlew bootRun
快取問題
# 清除 Gradle 快取
./gradlew clean
# 清除 Vite 快取
rm -rf node_modules/.vite
MSW 未正常運作
# 確認 mockServiceWorker.js 存在
ls app-web/public/mockServiceWorker.js
# 如果不存在，重新生成
cd app-web
npx msw init public --save