架構概述

分層架構

iDempiere Mobile 是以 Flutter 打造的 iDempiere ERP 行動客戶端，透過 idempiere-rest 外掛提供的 OData REST API 與伺服器通訊。

應用程式圍繞 8 大業務循環（銷售、採購、財務、庫存、生產、總帳、資產、薪資）以及投資與工作管理，為 iDempiere 標準業務視窗提供增強的行動體驗。

┌──────────────────────────────────────────────┐
│              UI（畫面 / 小工具）                │  Flutter widgets, GoRouter
├──────────────────────────────────────────────┤
│          狀態管理（Riverpod Notifiers）         │  StateNotifier, AsyncNotifier
├──────────────────────────────────────────────┤
│             資料存取層（Repositories）           │  資料取得, OData 查詢
├──────────────────────────────────────────────┤
│           API 客戶端（Dio）                     │  HTTP, JWT 認證, 攔截器
├──────────────────────────────────────────────┤
│         iDempiere REST API                    │  OData 篩選, 展開, CRUD
└──────────────────────────────────────────────┘

資料由上而下流動（UI → 狀態 → Repository → API → iDempiere），狀態通知則透過 Riverpod providers 由下而上傳遞。

目錄結構

lib/
├── main.dart                          # 進入點, Firebase 初始化
├── app.dart                           # MaterialApp.router 設定
├── core/
│   ├── api/
│   │   ├── api_client.dart            # Dio 客戶端, 通用 CRUD, 使用者可見度
│   │   ├── auth_interceptor.dart      # JWT Bearer token + 自動刷新
│   │   ├── context_interceptor.dart   # AD_Language / 上下文標頭
│   │   ├── retry_interceptor.dart     # 網路錯誤自動重試
│   │   ├── token_storage.dart         # 安全 token 持久化
│   │   ├── workflow_api.dart          # 核准/駁回/轉發/確認
│   │   ├── attachment_api.dart        # 檔案附件
│   │   └── print_api.dart            # 列印格式取得
│   ├── config/
│   │   ├── enhanced_module_registry.dart  # 選單 → 功能路由對應
│   │   ├── dashboard_module.dart          # 儀表板卡片定義
│   │   ├── app_modules.dart               # 固定儀表板模組
│   │   ├── branding_config.dart           # 白牌設定 (AD_SysConfig)
│   │   └── base_url_storage.dart          # 伺服器 URL 持久化
│   ├── constants/
│   │   └── api_constants.dart         # API URL 模式, 表格名稱
│   ├── document_framework/            # ★ 設定驅動文件畫面
│   │   ├── config/
│   │   │   ├── document_config.dart      # 核心設定模型
│   │   │   ├── field_config.dart         # 欄位顯示類型
│   │   │   ├── filter_config.dart        # 狀態篩選, 額外篩選
│   │   │   ├── document_registry.dart    # 靜態登錄: find(action, targetId)
│   │   │   └── standard_configs.dart     # 啟動時註冊所有標準設定
│   │   ├── data/
│   │   │   └── document_repository.dart  # 通用 CRUD + OData
│   │   ├── domain/
│   │   │   └── document_list_notifier.dart  # 列表狀態管理
│   │   ├── presentation/
│   │   │   ├── document_list_screen.dart    # 通用列表畫面
│   │   │   ├── document_detail_screen.dart  # 通用詳情畫面
│   │   │   └── widgets/                     # 狀態標籤, 資訊列等
│   │   └── document_routes.dart       # 從 registry 自動產生路由
│   ├── router/
│   │   └── app_router.dart            # GoRouter: 認證轉導, 所有路由
│   ├── services/
│   │   └── fcm_service.dart           # Firebase Cloud Messaging
│   └── widgets/                       # 共用可重複使用元件
├── features/
│   ├── login/                         # 認證流程
│   ├── dashboard/                     # 主儀表板
│   ├── sales_order/                   # 設定驅動（1 個檔案）
│   ├── purchase_order/                # 設定驅動（1 個檔案）
│   ├── invoice/                       # 設定驅動（1 個檔案）
│   ├── payment/                       # 設定驅動（1 個檔案）
│   ├── requisition/                   # 自訂（表單編輯器）
│   ├── booking/                       # 自訂（日曆 UI）
│   ├── attendance_dashboard/          # 自訂（週/月儀表板）
│   ├── approval/                      # 工作流程核准
│   ├── chat/                          # 即時聊天（WebSocket）
│   ├── report/                        # 流程 / 報表檢視器
│   ├── info_window/                   # 資訊視窗檢視器
│   ├── window/                        # 通用視窗瀏覽器
│   └── ...
└── l10n/
    ├── app_zh_TW.arb                  # 範本 ARB（主要）
    ├── app_en.arb                     # 英文
    ├── app_zh.arb                     # 簡體中文
    └── app_ja.arb                     # 日文

文件畫面框架（Document Screen Framework）

這是應用程式的核心架構模式。它透過「設定取代程式碼」的方式，消除每個功能的重複樣板程式碼。

框架前後對比

運作原理

1. 設定 (Config)           2. 登錄 (Registry)         3. 畫面 (Screens)
┌─────────────────┐    ┌───────────────────┐    ┌──────────────────────┐
│ DocumentConfig   │───►│ DocumentRegistry   │───►│ DocumentListScreen   │
│ - tableName      │    │ find(action, id)  │    │ DocumentDetailScreen │
│ - fields         │    │ register(config)  │    │ （從 config 讀取）     │
│ - filters        │    └───────────────────┘    └──────────────────────┘
│ - actions        │              │
│ - routes         │              ▼
└─────────────────┘    ┌───────────────────────────┐
                       │ generateDocumentRoutes()   │
                       │ → 每個 config 產生 GoRoute  │
                       └───────────────────────────┘

1. Config（DocumentConfig）— 宣告所有資訊：表格名稱、欄位、篩選、動作、路由
2. Registry（DocumentRegistry）— 儲存所有 config，以 (action, targetId) 查詢
3. 通用畫面（DocumentListScreen、DocumentDetailScreen）— 根據 config 渲染
4. 自動路由（generateDocumentRoutes()）— 從所有已註冊的 config 建立 GoRoute

Config 註冊流程

// 在應用程式啟動時（main.dart）：
registerStandardConfigs();  // 註冊 23 個 DocumentConfig

// 每個 config 是一個頂層變數：
// lib/features/sales_order/sales_order_config.dart
final salesOrderConfig = DocumentConfig(
  targetId: 143,          // AD_Window_ID
  tableName: 'C_Order',
  title: (l10n) => l10n.salesOrderTitle,
  ...
);

選單解析流程

當使用者點擊 iDempiere 選單項目時，應用程式依序解析要顯示哪個畫面：

使用者點擊選單項目 (action='W', targetId=143)
       │
       ▼
findEnhancedModule(action, targetId)
       │
       ├──► 1. DocumentRegistry.find()    → 設定驅動畫面（23 個功能）
       │
       ├──► 2. enhancedModuleRegistry[]   → 舊版自訂畫面（7 個功能）
       │
       └──► 3. 通用視窗瀏覽器             → 未對應視窗的後備方案

設定驅動 vs 自訂功能

通用視窗的 Slug 解析

通用視窗模組（/dashboard/window/:slug/:recordId）使用 slug（URL 友善名稱）來識別視窗，而非數字的 AD_Window_ID。WindowRepository.resolveSlug() 處理兩種格式：

1. 非數字字串 → 視為 slug，直接回傳
2. 數字字串 → 先嘗試作為 AD_Window_ID 查詢，再作為數字 slug 的後備方案

這種兩步驟解析之所以必要，是因為某些 iDempiere 視窗擁有純數字的 slug（例如 "7005"），否則會被誤判為 Window ID。簽核模組的「跳轉至原始文件」功能使用 resolveWindowSlugForTable(tableName)，透過 AD_Table → AD_Tab → AD_Window_ID → slug 的鏈路解析後，再以 slug 進行導航。

狀態管理

Riverpod Providers

• apiClientProvider — 單例 Dio 客戶端，含認證攔截器
• tokenStorageProvider — JWT token 持久化
• brandingConfigProvider — 伺服器端品牌設定（FutureProvider）
• 設定驅動功能 — 每個 config 一個 DocumentListNotifier（auto-dispose）
• 自訂功能 — 各功能自有 StateNotifier / AsyncNotifier

列表畫面模式

DocumentListNotifier (StateNotifier<DocumentListState>)
  ├── records: List<Map<String, dynamic>>
  ├── isLoading: bool
  ├── filter: String          （搜尋文字）
  ├── statusFilter: String    （DocStatus 篩選標籤）
  ├── extraFilters: Map       （額外篩選）
  ├── page / hasMore          （分頁）
  └── methods: refresh(), fetchNextPage(), setFilter(), setStatusFilter()

詳情畫面模式

FutureProvider.autoDispose<Map<String, dynamic>>  // 標頭記錄
FutureProvider.autoDispose<List<Map>>              // 明細行項目

路由

使用 GoRouter，在 /dashboard 下使用巢狀路由：

/login                          → LoginScreen
/dashboard                      → DashboardScreen (ShellRoute)
  /dashboard/sales-order        → DocumentListScreen（自動產生）
  /dashboard/sales-order/:id    → DocumentDetailScreen（自動產生）
  /dashboard/requisition        → RequisitionListScreen（手動）
  /dashboard/requisition/new    → RequisitionFormScreen（手動）
  /dashboard/booking            → BookingScreen（手動）
  /dashboard/window/:id         → GenericWindowScreen（後備方案）

設定驅動的路由由 generateDocumentRoutes() 自動產生。自訂功能則在 app_router.dart 中手動註冊路由。

權限模型

權限完全由伺服器驅動 — Flutter 應用程式不執行存取控制。

iDempiere 伺服器
  └── 角色 (Role)
       ├── AD_Window_Access    → 角色可存取的視窗
       ├── AD_Process_Access   → 可執行的流程/報表
       └── AD_Form_Access      → 可使用的表單
            │
            ▼
       選單樹 API (/api/v1/menus/{treeId})
            │
            ▼
       Flutter 僅接收已授權的選單項目
            │
            ▼
       findEnhancedModule() 對應到 Flutter 路由

應用程式只顯示伺服器篩選後的選單樹所回傳的項目，不需要客戶端的權限檢查。

本地化

支援 4 種語言：zh_TW（範本）、en、zh、ja。

• 範本 ARB：lib/l10n/app_zh_TW.arb — 先在此新增 key
• 產生的類別：S（AppLocalizations 的別名）
• 使用方式：S.of(context).myKey 或 l10n.myKey
• 設定驅動功能使用延遲求值：title: (l10n) => l10n.featureTitle

關鍵設計決策

為何用設定驅動而非程式碼產生？

Config 物件是執行時期值 — 無需建置步驟、無產生的檔案、可立即 hot reload。開發者新增一個檔案即可讓功能運作。程式碼產生會增加複雜度（build_runner、模板維護），卻得到相同的結果。

為何使用 Map<String, dynamic> 而非型別化模型？

iDempiere 有 800+ 張表格。為每張表格產生 Freezed 模型並不實際。通用的 Map<String, dynamic> 搭配 DisplayField.resolve() 能統一處理所有表格。$expand 指令回傳含有 id、identifier、model-name 的巢狀 Map — DisplayField.lookup() 會自動處理。

為何選擇 Riverpod 而非 Bloc/Provider？

Riverpod 提供：auto-dispose（導航時無記憶體洩漏）、ref.watch 實現響應式更新、family providers 支援參數化、以及 repository 中無需 BuildContext 依賴。

Freezed sealed class（不可變模型）

認證狀態使用 Freezed sealed class（AuthState），啟用 4 種認證狀態（unauthenticated、loading、roleSelection、authenticated）的窮盡模式匹配。編譯器會強制處理所有狀態分支，避免遺漏。

Repository 模式

Repository 封裝所有 API 呼叫與資料映射，讓 Notifier 專注於業務邏輯。這使得單元測試可以輕鬆 mock Repository，不需啟動 HTTP 伺服器。

通用 ApiClient

單一 API 客戶端透過表格名稱處理所有 iDempiere CRUD 操作，避免為每個實體建立獨立的 endpoint 類別。搭配 OData 篩選語法，一個方法即可查詢任何表格。

ODataFilter / ODataExpand 建構器

型別安全的建構器在編譯期強制正確的 OData 篩選語法。boolEq() 處理布林欄位（避免 IsActive eq 'Y' 錯誤）、neq() 強制正確運算子（iDempiere 使用 neq 而非標準 OData 的 ne）。單引號自動轉義。

M_Movement 單據工作流程

入庫與出庫均使用相同的 3 步驟模式（建立表頭 → 建立明細行 → 以 doc-action: CO 完成），對應 iDempiere 的標準單據處理流程。這確保了業務邏輯的一致性，也簡化了程式碼結構。

為何有 enhanced_module_registry 和 DocumentRegistry 兩套系統？

這是歷史遷移路徑留下的產物——說白了就是「祖宗之法不可廢，但可以慢慢架空」。enhancedModuleRegistry 是最早的靜態 Map，負責把選單項目對應到自訂功能畫面。後來引入了更強大的 DocumentRegistry，以設定驅動的方式處理標準功能。

findEnhancedModule() 的查詢順序是：先問 DocumentRegistry，再問舊版 Map。這意味著只要把功能的 config 註冊到 DocumentRegistry，舊版 Map 裡的對應條目就自動失效——漸進式遷移，不需要一次大爆炸重構。最終目標是讓舊版 Map 只剩下那些真正需要自訂 UI 的功能（表單編輯器、日曆、儀表板等），標準的列表→詳情流程全部由 DocumentRegistry 接管。

Slug 生成邏輯（Server 端）

iDempiere REST plugin 使用 TypeConverterUtils.slugify() 將 Window/Tab/Process 名稱轉為 URL-friendly slug。關鍵：slug 來源永遠是英文原始名稱，跟使用者登入的語系完全無關。（所以別問「為什麼我的中文視窗名稱變成空的」——這不是 bug，這是 feature。）

// 呼叫 window.getName() → get_Value("Name") → 讀取 AD_Window.Name 欄位
// 不是 get_Translation("Name")，所以永遠是英文原始名稱
jsonObject.addProperty("slug", TypeConverterUtils.slugify(window.getName()));

Slugify 演算法（5 步驟）：

1. 空白與標點符號 → 替換為 -
2. Unicode NFD 正規化（拆解重音字母，如 é → e + combining accent）
3. 移除所有非 ASCII 字母數字（[^\w_-] 使用 ASCII 模式）
4. 全部轉小寫
5. 合併重複的 -

注意事項：

• getName() 讀取的是 AD_Window.Name（英文原始欄位），不是 AD_Window_Trl.Name（翻譯欄位），所以 slug 永遠從英文名稱生成。
• 如果你的 iDempiere 有 custom window 且 AD_Window.Name 用中文命名（沒有走翻譯表），slug 會變成空字串，REST API 呼叫就會爆炸。
• 最佳實踐：自訂 Window/Tab/Process 的 Name 欄位務必使用英文，中文名稱放在 AD_Window_Trl 翻譯表。這是鐵律，不是建議。

┌──────────────────────────────────────────────┐
│              UI (Screens/Widgets)             │  Flutter widgets, GoRouter
├──────────────────────────────────────────────┤
│          State (Riverpod Notifiers)          │  StateNotifier, AsyncNotifier
├──────────────────────────────────────────────┤
│             Repositories                      │  Data fetching, OData queries
├──────────────────────────────────────────────┤
│           API Client (Dio)                    │  HTTP, JWT auth, interceptors
├──────────────────────────────────────────────┤
│         iDempiere REST API                    │  OData filters, expand, CRUD
└──────────────────────────────────────────────┘

// Calls window.getName() → get_Value("Name") → reads AD_Window.Name field
// NOT get_Translation("Name"), so it's always the English base name
jsonObject.addProperty("slug", TypeConverterUtils.slugify(window.getName()));

┌──────────────────────────────────────────────┐
│              UI（画面 / ウィジェット）          │  Flutter widgets, GoRouter
├──────────────────────────────────────────────┤
│          状態管理（Riverpod Notifiers）        │  StateNotifier, AsyncNotifier
├──────────────────────────────────────────────┤
│             リポジトリ層                       │  データ取得, OData クエリ
├──────────────────────────────────────────────┤
│           API クライアント（Dio）              │  HTTP, JWT 認証, インターセプター
├──────────────────────────────────────────────┤
│         iDempiere REST API                    │  OData フィルタ, 展開, CRUD
└──────────────────────────────────────────────┘

// window.getName() → get_Value("Name") → AD_Window.Name フィールドを読み取り
// get_Translation("Name") ではないため、常に英語の元の名前
jsonObject.addProperty("slug", TypeConverterUtils.slugify(window.getName()));