跳至主要内容

開發流程

本文檔說明使用 AppFuse 框架的日常開發流程，聚焦一個功能從分支建立到合併的完整工作流。

啟動方式與 API 模式切換請參閱快速開始與本地運行。

功能開發流程​

1. 建立分支​

git checkout main
git pull
git checkout -b feature/US-101-product-list

分支命名規範​

類型格式範例
功能feature/US-xxx-descriptionfeature/US-101-product-list
修復fix/issue-descriptionfix/login-redirect-error
改善improve/descriptionimprove/product-search-performance

2. 開發功能​

後端開發順序​

  1. Entity — 定義資料模型
  2. Repository — 資料存取層
  3. Service — 業務邏輯
  4. Controller — REST API
  5. 測試 — 單元測試、整合測試

前端開發順序​

  1. Mock Handler — 定義 API 回應格式（src/mocks/handlers/）
  2. Service + Query Hook — API 服務層與 React Query Hook（src/services/）
  3. Component — UI 組件
  4. Applet 或 Page — 功能整合
    • Applet：CRUD 業務模組，包含 Finder/Editor/Detail（src/applets/）
    • Page：獨立頁面，如 Login、Dashboard 等（src/pages/）
  5. 測試 — 組件測試

各層的實作細節請參閱前端開發指南與後端開發指南。

3. 提交前檢查​

提交前確認以下檢查通過：

檢查項目前端指令後端指令
Lintnpm run lint—
格式化npm run format:check—
測試npm run test./gradlew test
建置npm run build./gradlew build

4. 提交變更​

遵循 Conventional Commits 規範，以繁體中文撰寫：

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

<body>
Type說明
feat新功能
fix修復 bug
docs文檔更新
style程式碼風格調整
refactor重構
test測試
chore雜項維護

範例：

git add .
git commit -m "feat(product): 新增商品列表頁面

- 實作商品列表 API 整合
- 新增搜尋與篩選功能
- 支援分頁"

5. 推送與建立 PR​

git push -u origin feature/US-101-product-list

gh pr create --title "feat(product): 新增商品列表頁面" \
  --body "## 變更內容
- 實作商品列表 API
- 新增搜尋與篩選功能

## 測試
- [ ] 單元測試通過
- [ ] 手動測試通過"

6. Code Review 與合併​

  1. 至少一位團隊成員 Review
  2. 若已設定 CI，確認 CI 檢查通過
  3. 解決所有 Review 意見
  4. 合併：gh pr merge --squash

疑難排解​

資料庫狀態不一致​

H2 資料庫重置（會清除所有資料）：

rm -rf $APP_HOME/var/data/myapp-server/myappdb.*

# 重新啟動後端，Hibernate 會重建 Schema
cd myapp-server
./gradlew bootRun

$APP_HOME 的預設值與設定方式請參閱環境設定 — APP_HOME。

快取問題​

# 清除 Gradle 快取
cd myapp-server
./gradlew clean

# 清除 Vite 快取
rm -rf myapp-office/node_modules/.vite

更多故障排除請參閱本地運行 — 故障排除。

下一步​