⚡ 開發工作流程

本文檔說明 Valo 專案的日常開發工作流程、最佳實踐和團隊協作規範。

🔄 日常開發流程

1. 開始新功能開發

創建分支

# 從 develop 分支創建新功能分支
git checkout develop
git pull origin develop
git checkout -b feature/功能名稱

# 例如：
git checkout -b feature/add-friend-request-notification

分支命名規範

feature/功能名稱 - 新功能開發
bugfix/問題描述 - 錯誤修復
hotfix/緊急修復 - 生產環境緊急修復
refactor/重構內容 - 代碼重構
docs/文檔更新 - 文檔相關更新

2. 開發過程

代碼開發

# 確保依賴最新
flutter pub get

# 如果修改了自動生成的文件，運行代碼生成
flutter packages pub run build_runner build --delete-conflicting-outputs

# 開始開發
flutter run --dart-define=ENV=dev

定期檢查

# 代碼分析
flutter analyze

# 運行測試
flutter test

# 格式化代碼
flutter format .

3. 提交代碼

提交信息規範

使用語義化提交信息：

# 格式：類型(範圍): 描述
# 類型：feat, fix, docs, style, refactor, test, chore

# 例如：
git commit -m "feat(chat): 添加好友請求通知功能"
git commit -m "fix(auth): 修復Token過期後無法自動重新登入問題"
git commit -m "docs(setup): 更新開發環境設置指南"

提交前檢查清單

[ ] 代碼格式化完成 (flutter format .)
[ ] 沒有分析錯誤 (flutter analyze)
[ ] 相關測試通過 (flutter test)
[ ] 功能在多個設備上測試過
[ ] 添加或更新了必要的文檔
[ ] 遵循專案編碼標準

4. 推送和創建 PR

# 推送分支
git push origin feature/功能名稱

# 在 GitHub/GitLab 上創建 Pull Request
# 請求將 feature/功能名稱 合併到 develop

📝 代碼審查流程

PR 創建規範

PR 標題

使用清晰描述性的標題
包含影響範圍和主要變更

PR 描述模板

## 📋 變更摘要
<!-- 簡要描述這個 PR 做了什麼 -->

## 🎯 相關 Issue
<!-- 如果有相關 Issue，請連結 -->
Closes #123

## ✨ 主要變更
- [ ] 新增功能：描述新功能
- [ ] 錯誤修復：描述修復的問題
- [ ] 重構：描述重構內容
- [ ] 文檔：描述文檔變更

## 🧪 測試情況
- [ ] 在 Android 設備/模擬器上測試
- [ ] 在 iOS 設備/模擬器上測試（如適用）
- [ ] 添加/更新了相關單元測試
- [ ] 手動測試了相關功能

## 📱 測試設備
- Android: API 等級，設備型號
- iOS: iOS 版本，設備型號

## 📸 截圖（如適用）
<!-- 添加相關截圖 -->

## ⚠️ 注意事項
<!-- 任何需要特別注意的事項 -->

審查者檢查清單

代碼品質

[ ] 代碼遵循專案編碼標準
[ ] 沒有明顯的性能問題
[ ] 錯誤處理適當
[ ] 沒有安全漏洞

功能性

[ ] 功能按預期工作
[ ] 邊緣情況得到處理
[ ] UI/UX 符合設計規範
[ ] 多語言支持正常

測試

[ ] 適當的測試覆蓋
[ ] 測試通過
[ ] 手動測試確認

文檔

[ ] 代碼注釋充分
[ ] API 文檔更新
[ ] 使用者文檔更新

🚀 發布流程

版本號規範

使用語義化版本號：主版本.次版本.修訂版本

主版本: 不兼容的 API 變更
次版本: 向下兼容的功能新增
修訂版本: 向下兼容的錯誤修復

發布步驟

1. 準備發布

# 切換到 develop 分支
git checkout develop
git pull origin develop

# 創建發布分支
git checkout -b release/v1.2.0

# 更新版本號（pubspec.yaml）
# 更新 CHANGELOG.md

2. 測試發布候選

# 建制測試版本
flutter build apk --dart-define=ENV=test
flutter build ios --dart-define=ENV=test

# 內部測試
# 修復發現的問題

3. 完成發布

# 合併到 main
git checkout main
git merge release/v1.2.0

# 創建標籤
git tag -a v1.2.0 -m "Release version 1.2.0"

# 合併回 develop
git checkout develop
git merge main

# 推送所有變更
git push origin main develop --tags

4. 建制生產版本

# 建制生產版本
flutter build appbundle --dart-define=ENV=prod --release  # Android
flutter build ios --dart-define=ENV=prod --release        # iOS

🔧 代碼生成

何時運行代碼生成

當修改以下文件時需要運行：

app_router.dart (auto_route)
API service 介面 (retrofit)
Model 類別 (json_serializable)

生成命令

# 生成所有
flutter packages pub run build_runner build --delete-conflicting-outputs

# 僅生成特定類型
flutter packages pub run build_runner build --build-filter="*.g.dart"
flutter packages pub run build_runner build --build-filter="*.gr.dart"

🧪 測試策略

測試層次

1. 單元測試

# 運行所有單元測試
flutter test

# 運行特定測試文件
flutter test test/unit/utils/time_util_test.dart

# 運行測試組合
flutter test test/test_runner.dart

2. 整合測試

# 運行整合測試
flutter test test/integration/

# 運行 Widget 測試
flutter test test/widget/

測試覆蓋率

# 生成覆蓋率報告
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

🐛 除錯和問題解決

常見問題快速修復

建制問題

# 清理建制快取
flutter clean
flutter pub get
cd ios && pod install && cd ..

# Android Gradle 問題
cd android && ./gradlew clean && cd ..

狀態管理問題

檢查 Provider 註冊
確認 Consumer/Selector 使用正確
使用 Provider DevTools 調試

路由問題

重新生成路由文件
檢查路由守護配置
確認深度連結設定

效能調優

一般建議

使用 const 建構函數
避免在 build 方法中進行重計算
使用 Selector 而非 Consumer
合理使用 ListView.builder

記憶體優化

及時取消事件監聽器
避免記憶體洩漏
使用 dispose 方法清理資源

📊 監控和日誌

開發環境日誌

// 使用統一的日誌工具
import 'package:logger/logger.dart';

final logger = Logger();

logger.d('Debug message');
logger.i('Info message');
logger.w('Warning message');
logger.e('Error message');

崩潰報告

集成 Firebase Crashlytics
收集崩潰日誌
定期檢查錯誤報告

🤝 團隊協作

溝通規範

重要變更提前溝通
使用 Issue 追蹤問題
PR 中詳細描述變更

衝突解決

# 解決合併衝突
git checkout develop
git pull origin develop
git checkout feature/your-feature
git rebase develop

# 解決衝突後
git add .
git rebase --continue
git push --force-with-lease origin feature/your-feature

知識分享

定期技術分享會議
文檔更新和維護
代碼審查中的學習

📋 檢查清單模板

功能開發完成檢查

[ ] 功能按需求實現
[ ] 代碼遵循專案標準
[ ] 添加適當測試
[ ] 多設備測試通過
[ ] 性能表現良好
[ ] 文檔更新完成
[ ] 無安全漏洞
[ ] 多語言支持正常

PR 提交前檢查

[ ] 分支名稱符合規範
[ ] 提交信息清晰
[ ] 代碼格式化
[ ] 分析通過
[ ] 測試通過
[ ] 截圖/說明完整

最後更新: 2025-08-07