跳至主要内容

貢獻指南

感謝你對花店管理系統的貢獻！本指南說明開發規範與協作流程。

開發流程​

本專案遵循 AppFuse 開發方法論，採用 Prototype → 生產實作 的漸進式開發流程：

階段說明​

階段模組說明
1. 需求分析-撰寫 User Story 與 SBE
2. Prototype 開發app-web-mockup使用 Mock API 快速驗證 UI/UX
3. 需求確認-與 stakeholder 確認 Prototype 符合需求
4. 生產實作app-web + app-server前端同步 mockup 程式碼，後端實作 API
5. 測試所有模組單元測試、整合測試
6. Review-Code Review 與 PR 合併

詳細流程請參閱 AppFuse 開發流程指南。

本地開發環境​

快速開始（Prototype 模式）​

cd app-web-mockup
npm install
npm run dev
# 開啟 http://localhost:3001

前後端分離開發​

# Terminal 1: 啟動後端
cd app-server
./gradlew bootRun
# API: http://localhost:8080/app-server

# Terminal 2: 啟動前端
cd app-web
npm install
npm run dev
# 開啟 http://localhost:3000

使用 Mock API（app-web）​

app-web 在開發環境自動啟用 MSW Mock API：

cd app-web
npm run dev  # MSW 自動啟用

詳細說明請參閱「Mock → 真實 API 漸進切換」

分支策略​

main                    # 生產環境
├── develop             # 開發整合
│   ├── feature/US-xxx  # 功能開發
│   ├── bugfix/xxx      # Bug 修復
│   └── hotfix/xxx      # 緊急修復

Commit Message 規範​

遵循 Conventional Commits 規範，使用繁體中文：

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

<body>

Type 類型​

Type說明
feat新增功能
fix修復 bug
docs文檔更新
refactor程式碼重構
test測試相關
chore雜項維護

範例​

feat(order): 新增訂單建立功能

實作 US-201 訂單建立功能：
- 新增 OrderController 與相關 API
- 實作訂單驗證邏輯
- 整合客戶查詢

程式碼同步指引​

app-web 的程式碼從 app-web-mockup 同步，確保設計一致性。

同步範圍​

目錄/檔案是否同步說明
applets/✅ 同步業務邏輯組件
components/✅ 同步應用程式組件
features/✅ 同步Redux slices
mocks/✅ 同步MSW mock handlers
services/✅ 同步API 服務層
routes/✅ 同步路由配置
playground/❌ 不同步框架驗證專用
__tests__/❌ 不同步測試檔案各自維護

同步流程​

# 1. 在 app-web-mockup 開發完成後
cd app-web-mockup
npm run build  # 確認無編譯錯誤

# 2. 同步到 app-web
cd ../app-web
# 手動複製或使用 diff 工具同步變更

# 3. 確認同步結果
npm run build  # 確認無編譯錯誤
Import 路徑相容

兩個專案的 import 路徑設計為相容，程式碼可直接複製，不需修改 import 路徑。

程式碼規範​

Java (app-server)​

  • 遵循 Google Java Style Guide
  • 使用 Lombok 減少樣板程式碼
  • Service 層方法需加上 @Transactional
  • 註解使用繁體中文

TypeScript (app-web, app-web-mockup)​

  • 使用 ESLint + Prettier 格式化
  • 組件使用函數式組件 + Hooks
  • 狀態管理使用 Redux Toolkit
  • 註解使用繁體中文

Code Review 檢查項目​

  • 功能是否符合 User Story 描述
  • 是否有對應的測試案例
  • 程式碼風格是否一致
  • 是否有安全性問題
  • API 是否符合 RESTful 規範

測試要求​

app-server（後端）​

  • Service 層單元測試覆蓋率 > 80%
  • Controller 層使用 MockMvc 測試
  • API 文檔使用 Spring REST Docs 生成

app-web（生產前端）​

  • 關鍵業務邏輯需有測試
  • 使用 Vitest + React Testing Library
  • Mock API 整合測試

app-web-mockup（Prototype）​

  • 以快速驗證為主，測試要求較低
  • 確保 Mock API handlers 完整覆蓋 API 規格

相關資源​