開發環境設定

環境需求

安裝步驟

# 1. 複製專案
git clone https://github.com/anthropics/idempiere-mobile.git
cd idempiere-mobile

# 2. 安裝相依套件
flutter pub get

# 3. 產生程式碼（Freezed + json_serializable）
dart run build_runner build --delete-conflicting-outputs

# 4. 靜態分析（確認無錯誤）
flutter analyze

# 5. 執行測試
flutter test

執行應用程式

# Web（Chrome）
flutter run -d chrome

# macOS（需要 Xcode）
flutter run -d macos

# iOS（需要 Xcode + 裝置 / 模擬器）
flutter run -d ios

# Android（需要 Android Studio + 裝置 / 模擬器）
flutter run -d android

# Windows
flutter run -d windows

新增平台支援

如果專案缺少某個平台的設定，可以產生它：

flutter create --platforms=ios,android,macos,web .

程式碼產生

專案使用 Freezed（不可變模型）和 json_serializable（JSON 序列化）進行程式碼產生。修改任何標記 @freezed 或 @JsonSerializable 的模型後，必須重新執行：

# 一次性建置
dart run build_runner build --delete-conflicting-outputs

# 開發期間的監聽模式（持續監控檔案變更）
dart run build_runner watch --delete-conflicting-outputs

何時需要重新執行？

• 修改任何 @freezed 類別後
• 修改任何 @JsonSerializable 類別後
• 新增或修改模型類別後
• 看到「Generated files missing」錯誤時

注意：模型類別 Locator 與 state_notifier 套件（由 flutter_riverpod 重新匯出）的 Locator 名稱衝突。需要同時匯入兩者的檔案必須使用 hide Locator：

import 'package:flutter_riverpod/flutter_riverpod.dart' hide Locator;
import '../../../core/models/locator.dart';

專案結構說明

lib/
  core/                    # 共用框架
    api/                   #   Dio HTTP 客戶端, 認證, 攔截器
    config/                #   品牌設定, 模組登錄, 儀表板
    constants/             #   API URL 模式
    document_framework/    #   設定驅動文件畫面（核心）
    router/                #   GoRouter + 認證轉導
    services/              #   FCM, 通知服務
    widgets/               #   共用小工具（列印按鈕等）
  features/                # 每個功能一個目錄
    sales_order/           #   設定驅動：1 個檔案 (sales_order_config.dart)
    requisition/           #   自訂：data/ + domain/ + presentation/
    booking/               #   自訂：日曆 UI
    ...
  l10n/                    # 本地化（ARB 檔案, 4 種語言）

伺服器設定

應用程式透過 REST API 連接 iDempiere。首次啟動時：

1. 輸入 iDempiere 伺服器 URL（例如 https://your-server/api）
2. 使用 iDempiere 帳號密碼登入
3. 選擇 Client、Role、Organization

Firebase（選用）

推播通知需要 Firebase 設定。應用程式在沒有 Firebase 設定的情況下仍可正常運作 — FCM 功能在缺少設定時會優雅地停用。

開發工作流程

1. 從 main 建立功能分支：git checkout -b feat/your-feature main
2. 進行開發 — 遵循程式碼慣例
3. 提交前執行檢查：

   flutter analyze
   flutter test

4. 使用 Conventional Commits 格式提交
5. 對 main 發起 Pull Request

Commit 慣例

測試

# 執行所有測試
flutter test

# 執行特定測試檔案
flutter test test/core/api/api_client_test.dart

# 含覆蓋率報告
flutter test --coverage

程式碼慣例

• flutter analyze 必須零問題通過
• 盡可能使用 const 建構子
• 優先使用 final 變數；已知型別時避免 var
• 3 個以上參數的建構子使用命名參數
• 設定檔命名：lib/features/<feature>/<feature>_config.dart
• 自訂功能：lib/features/<feature>/{data,domain,presentation}/
• 路由：/dashboard/<feature-name>（kebab-case）

git clone https://github.com/anthropics/idempiere-mobile.git
cd idempiere-mobile
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter analyze
flutter test

flutter run -d chrome      # Web
flutter run -d macos        # macOS
flutter run -d ios          # iOS
flutter run -d android      # Android
flutter run -d windows      # Windows

dart run build_runner build --delete-conflicting-outputs

# Watch mode:
dart run build_runner watch --delete-conflicting-outputs

flutter test                    # All tests
flutter test test/path/file.dart  # Specific file
flutter test --coverage          # With coverage