API 整合

iDempiere REST API 概述

iDempiere Mobile 透過 idempiere-rest 外掛的 OData REST API 與 iDempiere ERP 伺服器通訊。所有資料存取都使用標準的 HTTP 方法操作 REST 端點。

┌─────────────────────┐       HTTPS/JWT        ┌──────────────────────┐
│   Flutter App        │ <──────────────────►   │  iDempiere ERP       │
│   (iOS/Android/Web/  │   idempiere-rest API   │  + idempiere-rest    │
│    macOS)            │   /api/v1/...          │    plugin            │
└─────────────────────┘                         └──────────────────────┘

認證流程（兩步驟）

認證分為兩個步驟：先登入取得臨時 token 和可用角色列表，再選擇角色取得正式 session token。

步驟 1：登入

POST /api/v1/auth/tokens
Content-Type: application/json

{
  "userName": "your-username",
  "password": "your-password"
}

# 回應：
{
  "token": "jwt-temporary-token...",
  "clients": [
    {
      "id": 11,
      "name": "GardenWorld",
      "roles": [
        { "id": 102, "name": "GardenAdmin" }
      ]
    }
  ]
}

步驟 2：選擇角色

PUT /api/v1/auth/tokens
Authorization: Bearer jwt-temporary-token
Content-Type: application/json

{
  "clientId": 11,
  "roleId": 102,
  "organizationId": 11,
  "language": "zh_TW"
}

# 回應：
{
  "token": "jwt-session-token..."
}

• 步驟 1 回傳臨時 token 和可用的 client/role 列表
• 步驟 2 選擇工作的 client/role/org 並回傳正式 session token
• Token 儲存在 FlutterSecureStorage（iOS Keychain / Android EncryptedSharedPreferences）
• 後續所有請求由 AuthInterceptor 自動附加 Authorization: Bearer <token>

一步登入（已知所有 ID）

若已知 clientId、roleId、organizationId、warehouseId，可在一次 POST 中完成登入：

POST /api/v1/auth/tokens
{
  "userName": "X", "password": "Y",
  "parameters": {
    "clientId": 11, "roleId": 102,
    "organizationId": 11, "warehouseId": 103, "language": "zh_TW"
  }
}
// 回應：{ "token": "eyJ...", "refresh_token": "eyJ..." }

中間查詢端點

步驟 1 與步驟 2 之間，可查詢可用的角色、組織、倉庫：

GET /api/v1/auth/roles?client={clientId}
GET /api/v1/auth/organizations?client={clientId}&role={roleId}
GET /api/v1/auth/warehouses?client={clientId}&role={roleId}&organization={orgId}

Token 管理

CRUD 操作

所有資料存取使用 GET/POST/PUT/DELETE 操作 /api/v1/models/{tableName}：

Dart 程式碼範例

// ApiClient 封裝了所有 CRUD 操作
final api = ref.watch(apiClientProvider);

// 查詢列表（含篩選、排序、展開外鍵）
final data = await api.getRecords('C_Order',
  filter: "IsSOTrx eq true and DocStatus eq 'DR'",
  orderBy: 'DateOrdered desc',
  expand: 'C_BPartner_ID,C_DocType_ID',
  top: 20,
  skip: 0,
);

// 取得單筆記錄（含展開欄位）
final record = await api.getRecord('C_Order', 12345,
  expand: 'C_BPartner_ID,C_DocType_ID,M_Warehouse_ID',
);

// 新增記錄
final newRecord = await api.createRecord('C_Order', {
  'C_DocTypeTarget_ID': 132,
  'C_BPartner_ID': 118,
  'DateOrdered': '2026-02-17',
});

// 更新記錄
await api.updateRecord('C_Order', 12345, {
  'Description': 'Updated description',
});

// 刪除記錄
await api.deleteRecord('C_Order', 12345);

單欄位查詢

GET /api/v1/models/{TableName}/{id}/{ColumnName}

回應結構（集合）

{
  "page-count": 5,
  "records-size": 100,
  "skip-records": 0,
  "row-count": 450,
  "array-count": 100,
  "records": [...]
}

資料型別 — 讀取 vs 寫入

GET 回傳的型別與 POST/PUT 送出的型別不一定相同，這是常見錯誤來源：

⚠️ GET 回傳的 FK/List 是物件 — 取值用 .id，顯示用 .identifier
⚠️ DateTime Z 後綴實為本地時間 — 解析時不要做 UTC 轉換

OData 查詢

idempiere-rest 支援 OData 風格的查詢參數：

OData 篩選注意事項

這是最常見的 bug 來源。Boolean 欄位和 Char 欄位的篩選語法不同：

例外：contains 等字串函式和 $context 必須用 'Y'/'N'（不是 true/false）：

contains(IsSOTrx,'Y')          ← 字串函式用 'Y'
$context=IsSOTrx:Y               ← context 用 Y（不加引號）

Document Framework 透過 StatusFilter.isBoolean 自動處理這個差異。

完整比較運算子

⚠️ ne 不支援，必須用 neq
⚠️ not (X eq Y) 不行，not 只能搭配函式

字串函式

contains(Name,'Garden')    startswith(Name,'Ga')    endswith(Name,'Co.')
tolower(Name) eq 'garden'  not contains(Name,'test')

$select 欄位選擇

GET /api/v1/models/M_Product?$select=Name,Value&$orderby=Name desc&$top=20&$skip=40

$expand — 展開關聯（進階用法）

# FK 展開（一對一）
?$expand=C_BPartner_ID

# 子表展開（一對多）
?$expand=C_OrderLine

# 帶過濾的子表（分號分隔參數）
?$expand=C_OrderLine($select=Line,LineNetAmt;$filter=LineNetAmt gt 1000;$orderby=Line)

# FK 欄位 $select
?$expand=M_Product_Category_ID($select=Name,IsDefault)

# 巢狀展開
?$expand=C_OrderLine($expand=C_OrderTax)

# 反向展開（自訂 join key）
?$expand=C_Order.SalesRep_ID($select=DocumentNo)

$valrule + $context — 套用驗證規則

直接在 server 端執行 AD_Val_Rule，不需手動轉 SQL → OData。搜尋參考欄位時，App 會自動將表單目前的欄位值作為 $context 傳送，確保驗證規則中的 @ColumnName@ 變數能正確解析：

GET /api/v1/models/C_DocType?$valrule=133&$context=IsSOTrx:Y

⚠️ $context 的 Boolean 用 Y/N（不是 true/false，跟 $filter 不同！）

載入狀態追蹤

參考欄位搜尋支援即時載入狀態追蹤。當使用者輸入搜尋關鍵字時：

1. 搜尋面板顯示載入指示器（shimmer 骨架動畫）
2. 若搜尋條件變更，前一次尚未完成的請求會自動取消
3. 載入完成後平滑過渡至結果列表
4. 錯誤時顯示重試按鈕，不影響已選取的值

文件工作流程

iDempiere 文件（如銷售訂單、付款等）遵循三步驟工作流程：

# 1. 建立文件標頭
POST /api/v1/models/C_Order
{
  "C_DocTypeTarget_ID": 132,
  "C_BPartner_ID": 118,
  "DateOrdered": "2026-02-17"
}
# 回傳: { "id": 12345, ... }

# 2. 建立明細行
POST /api/v1/models/C_OrderLine
{
  "C_Order_ID": 12345,
  "M_Product_ID": 456,
  "QtyOrdered": 10
}

# 3. 完成文件（透過 Process 端點）
POST /api/v1/processes/c_order-process
{
  "record-id": 12345,
  "table-id": 259
}

⚠️ 不要用 PUT 更新 DocAction 欄位，應使用 Process 端點。新單據預設 DocAction='CO'，POST Process 即觸發 Complete。

Document Process 對照表

常用 doc-action 代碼

攔截器

API 客戶端使用 Dio 攔截器處理橫切關注點：

認證攔截器流程

HTTP 請求
  │
  ▼
AuthInterceptor 附加 Bearer token
  │
  ▼
伺服器回應
  │
  ├── 200 OK → 正常回傳
  │
  └── 401 Unauthorized
       │
       ▼
  自動刷新 token（PUT /api/v1/auth/tokens）
       │
       ▼
  使用新 token 重新發送原始請求

附件上傳/下載

// 上傳附件
final attachmentApi = AttachmentApi(api.dio);
await attachmentApi.upload(
  tableName: 'C_Order',
  recordId: 12345,
  file: selectedFile,
);

// 下載附件
final bytes = await attachmentApi.download(
  tableName: 'C_Order',
  recordId: 12345,
  attachmentId: 67890,
);

選單樹 API

// 取得角色的選單樹
final menuTree = await api.getMenuTree(treeId);
// 回傳巢狀選單項目，每個項目含有：
// - action: 'W' (Window), 'P' (Process), 'R' (Report), 'X' (Form)
// - targetId: AD_Window_ID / AD_Process_ID / AD_Form_ID
// - name, description

表格對應參考

Application Dictionary (AD) 查詢

iDempiere 的表單結構是 metadata-driven，欄位定義在 AD_Window → AD_Tab → AD_Field → AD_Column。

查詢 Tab 的欄位定義

GET /api/v1/models/AD_Field?$filter=AD_Tab_ID eq {tabId} and IsActive eq true and IsDisplayed eq true
  &$select=AD_Field_ID,Name,SeqNo,IsReadOnly,AD_FieldGroup_ID,AD_Column_ID&$orderby=SeqNo&$top=200

查詢欄位的 Column 屬性

GET /api/v1/models/AD_Column/{columnId}
  ?$select=ColumnName,AD_Reference_ID,AD_Reference_Value_ID,FieldLength,IsMandatory,DefaultValue,IsUpdateable,AD_Val_Rule_ID

AD_Reference_ID → 元件類型

FK Table Name 解析邏輯

Ref 19/31 (TableDirect/Locator):
  column name 去掉 _ID → table name (M_Warehouse_ID → M_Warehouse)

Ref 18/30 (Table/Search) + 有 AD_Reference_Value_ID:
  AD_Ref_Table → AD_Table → TableName

Ref 18/30 (Table/Search) + 無 AD_Reference_Value_ID:
  fallback: column name 去掉 _ID → table name
  (大量核心欄位如 C_BPartner_ID, C_Order_ID 都是這種情況)

List 參照選項 (Ref 17)

GET /api/v1/models/AD_Ref_List?$filter=AD_Reference_ID eq {referenceValueId} and IsActive eq true
  &$select=Value,Name&$orderby=Name

Identifier Column（FK 顯示欄位）

GET /api/v1/models/AD_Column?$filter=AD_Table_ID eq {tableId} and IsIdentifier eq true and IsActive eq true
  &$select=ColumnName,SeqNo&$orderby=SeqNo&$top=1

必填欄位查詢

GET /api/v1/models/AD_Column?$filter=AD_Table_ID eq {tableId} and IsMandatory eq true and IsActive eq true
  &$select=ColumnName,DefaultValue,AD_Reference_ID

AD_Val_Rule 驗證規則

GET /api/v1/models/AD_Val_Rule/{ruleId}?$select=Code
# 回傳: { "Code": "C_DocType.DocBaseType IN ('SOO','POO') AND ..." }

優先用 $valrule 參數讓 server 端執行，避免手動轉 SQL → OData。

DefaultValue 解析規則

Processes / Reports

POST /api/v1/processes/{slug}
{ "record-id": 123, "table-id": 208, "params": { "DateFrom": "2025-01-01" } }

其他功能

# 顯示生成的 SQL（debug 用）
GET /api/v1/models/C_Order/100?showsql
GET /api/v1/models/C_Order/100?showsql=nodata

# REST Views（自訂視圖）
GET /api/v1/views/{viewName}

# 建立記錄連同子記錄（單次 POST）
POST /api/v1/models/C_Order
{ "C_BPartner_ID": 119,
  "C_OrderLine": [{ "M_Product_ID": 122, "QtyOrdered": 10 }] }

label / showlabel — 標籤篩選

透過 AD_Label 標籤篩選和查詢記錄：

# 篩選有 #Customer 標籤的商業夥伴（# 需 URL encode 為 %23）
GET /api/v1/models/C_BPartner?label=Name eq '%23Customer'

# 查詢單筆記錄的標籤（回傳完整標籤資訊）
GET /api/v1/models/C_BPartner/119?showlabel&$select=Name,IsCustomer,IsVendor
# 回傳: "assigned-labels": [{"Name":"#Customer","Description":"Customers"}]

# 只回傳標籤名稱
GET /api/v1/models/C_BPartner/119?showlabel=Name
# 回傳: "assigned-labels": ["#Customer","#Vendor"]

label 也支援在 $expand 內巢狀使用。

常見陷阱速查 ⚠️

常用查詢範例

# 客戶列表
GET /api/v1/models/C_BPartner?$filter=IsCustomer eq true and IsActive eq true&$orderby=Name&$top=50

# 搜尋產品
GET /api/v1/models/M_Product?$filter=contains(Name,'玻尿酸') and IsActive eq true&$select=Name,Value

# 訂單 + 明細
GET /api/v1/models/C_Order/100?$expand=C_OrderLine($orderby=Line)

# 單據類型（銷售）
GET /api/v1/models/C_DocType?$valrule=133&$context=IsSOTrx:Y&$select=Name

# BOM 產品
GET /api/v1/models/M_Product?$filter=IsBOM eq true and IsVerified eq true

# 完成訂單
POST /api/v1/processes/c_order-process  { "record-id": 100, "table-id": 259 }

# 依標籤篩選
GET /api/v1/models/C_BPartner?label=Name eq '%23Customer'&$select=Name,Value

ODataFilter / ODataExpand Builder 工具

專案提供了型別安全的 ODataFilter 建構器（lib/core/utils/odata_filter_builder.dart），用於產生正確的 filter 語法：

import 'package:idempiere_app/core/utils/odata_filter_builder.dart';

// Boolean 欄位 — 產生: IsActive eq true
ODataFilter().boolEq('IsActive', true)

// String 欄位 — 產生: DocStatus eq 'CO'
ODataFilter().eq('DocStatus', 'CO')

// 不等於 — 產生: Status neq 'CO'（永遠用 neq，不是 ne）
ODataFilter().neq('Status', 'CO')

// 組合條件 — 產生:
// IsVendor eq true and IsActive eq true and (contains(Name,'acme') or contains(Value,'acme'))
ODataFilter()
    .boolEq('IsVendor', true)
    .boolEq('IsActive', true)
    .or_(["contains(Name,'acme')", "contains(Value,'acme')"])
    .build()

⚠️ 字串值中的單引號會自動跳脫（O'Brien → O''Brien）。

ODataExpand Builder

ODataExpand 建構器（lib/core/utils/odata_expand_builder.dart）支援 $expand 搭配子篩選：

import 'package:idempiere_app/core/utils/odata_expand_builder.dart';

// 簡單展開: C_BPartner_ID
ODataExpand('C_BPartner_ID').build()

// 帶子篩選: C_OrderLine($select=Line,Amt;$filter=Amt gt 100;$orderby=Line)
ODataExpand('C_OrderLine')
    .select('Line,Amt')
    .filter('Amt gt 100')
    .orderBy('Line')
    .build()

// 多重展開
buildExpands([ODataExpand('C_BPartner_ID'), ODataExpand('C_OrderLine').select('Line')])

Builder 方法速查

SQL 預設值解析（Default Value Resolution）

新增或複製記錄時，系統自動解析 AD_Column.DefaultValue，將預設值填入表單。特別是 @SQL=SELECT... 格式的預設值，需要伺服器端執行查詢。

相關檔案

支援的預設值模式

Context 變數替換

SQL 預設值中的 @ColumnName@ 變數替換順序：

1. 優先從表單目前欄位值取得（已填入的欄位）
2. 再從登入 Context 取得（AD_Client_ID、AD_Org_ID、#Date 等）
3. 若仍無法解析，保留原始 @Variable@（由伺服器端處理）

API 呼叫方式

SQL 預設值透過 OData 查詢端點執行，將 @SQL=SELECT... 中的 SQL 轉換為 OData 格式：

# 例：取得下一行行號
GET /api/v1/models/C_OrderLine?$filter=C_Order_ID eq 12345&$select=Line&$orderby=Line desc&$top=1

API 回應處理

伺服器回傳預設值後，系統依欄位的 AD_Reference_ID 自動轉型：

• FK 欄位（18/19/30）：數字 ID → 查詢 identifier 後組成 {"id": N, "identifier": "..."}
• Boolean 欄位（20）："Y"/"N" → true/false
• 日期欄位（15/16）：字串 → ISO 格式日期
• 數字欄位（11/12/22/29）：字串 → 數字

圖片欄位顯示（Image Field Display）

支援 AD_Reference_ID 為 32（Image）和 33（Image URL）的欄位顯示。圖片以 base64 內嵌方式傳輸，無需額外的檔案伺服器。

JSON 結構

// GET 回傳的圖片欄位值
{
  "Logo_ID": {
    "id": 12345,
    "identifier": "company-logo.png",
    "model-name": "ad_image"
  }
}

// 取得圖片內容
GET /api/v1/models/AD_Image/12345
// 回傳:
{
  "BinaryData": "iVBORw0KGgo...",   // base64 encoded
  "Name": "company-logo.png"
}

顯示邏輯（4 步驟）

1. 偵測圖片欄位：判斷 AD_Reference_ID 為 32 或 33
2. 載入圖片資料：透過 AD_Image 表取得 base64 編碼的 BinaryData
3. 預覽顯示：在記錄詳情中以縮圖呈現（最大寬度 120px），載入中顯示骨架動畫
4. 全螢幕檢視：點擊縮圖開啟全螢幕畫面，支援雙指縮放（pinch-to-zoom）與拖曳平移

注意事項

• 圖片資料快取於記憶體中，同一 session 不重複下載
• 若 BinaryData 為空或解碼失敗，顯示破損圖片圖示
• 編輯模式下圖片欄位為唯讀（不支援從 App 上傳圖片）

Callout API（欄位變更觸發）

提供伺服器端欄位變更觸發（Callout）功能，與 iDempiere WebUI 的 Callout 行為一致。

API 端點

POST /api/v1/callout/{windowSlug}/{tabSlug}

Request Body

{
  "columnName": "C_BPartner_ID",
  "value": {"id": 123, "identifier": "Joe Block", "model-name": "c_bpartner"},
  "record": {
    "C_DocType_ID": {"id": 132},
    "DateOrdered": "2026-02-21",
    "C_BPartner_ID": {"id": 123}
  },
  "recordId": 0
}

Response Body

{
  "changedFields": {
    "Bill_BPartner_ID": {"id": 123, "identifier": "Joe Block"},
    "C_PaymentTerm_ID": {"id": 105, "identifier": "Immediate"},
    "M_PriceList_ID": {"id": 101, "identifier": "Standard"}
  }
}

changedFields 僅包含被 Callout 修改的欄位。若無欄位被變更，回傳空物件 {}。

Callout 來源類型

兩種 Callout 來源均支援——不管你的 Callout 是在 Application Dictionary 裡設定的，還是用 Java 寫的 Factory，通通能觸發：

• AD_Column.Callout：在 Application Dictionary 中設定的 Callout class 名稱
• IColumnCalloutFactory / IColumnCallout：透過 OSGi 註冊的 Callout Factory（如 HRMCalloutFactory）

架構圖

Flutter App                        iDempiere Server
─────────────                      ────────────────
onChanged(field, value)
    │
    ▼
fireCallout() ──POST──►  /api/v1/callout/{windowSlug}/{tabSlug}
                                    │
                                    ▼
                          CalloutResourceImpl.fireCallout()
                                    │
                          ┌─────────┴──────────┐
                          │  1. Resolve window  │
                          │  2. Create GridTab  │
                          │  3. Load/new record │
                          │  4. Set all fields  │
                          │  5. Set trigger col │
                          │     (fires callout) │
                          │  6. Diff before/after│
                          │  7. Return changes  │
                          │  8. Discard (no save)│
                          └─────────┬──────────┘
                                    │
fireCallout() ◄──response──  {"changedFields":{...}}
    │
    ▼
setState(() => formData.addAll(changed))

伺服器端處理流程（Java 程式碼）

// 1. 解析 Window/Tab（透過 slug）
MWindow window = new Query(ctx, MWindow.Table_Name, "slugify(name)=?", null)
    .setParameters(windowSlug).first();
GridWindowVO vo = GridWindowVO.create(ctx, 1, window.getAD_Window_ID());
GridWindow gridWindow = new GridWindow(vo, true);

// 2. 初始化 GridTab
GridTab targetTab = gridWindow.getTab(tabIndex);
targetTab.initTab(false);
targetTab.getTableModel().setImportingMode(false, null);

// 3. 載入或新增記錄
if (recordId > 0) {
    MQuery query = new MQuery(tableName);
    query.addRestriction(keyColumn, "=", recordId);
    targetTab.setQuery(query);
    targetTab.query(false);
} else {
    targetTab.dataNew(false);
}

// 4. 設定所有欄位（觸發欄位最後設定）
for (field : record.entrySet()) {
    if (!field.equals(columnName)) {
        gridTab.setValue(gridField, convertedValue);
    }
}

// 5. 設定觸發欄位 → 觸發 Callout
gridTab.setValue(triggerField, triggerValue);
gridTab.processFieldChange(triggerField);  // fires both AD_Column.Callout & IColumnCallout

// 6. 比較前後差異，回傳 changedFields
// 7. 丟棄（不儲存）
targetTab.dataIgnore();

Flutter 客戶端整合

修改檔案

fireCallout() 方法

Future<Map<String, dynamic>?> fireCallout({
  required String windowSlug,
  required String tabSlug,
  required String columnName,
  required dynamic value,
  required Map<String, dynamic> formData,
  required int recordId,
}) async {
  final response = await _api.dio.post(
    '${ApiConstants.apiPrefix}/callout/$windowSlug/$tabSlug',
    data: {
      'columnName': columnName,
      'value': value,
      'record': formData,
      'recordId': recordId,
    },
  );
  // parse changedFields, return if non-empty
}

UI 整合

Future<void> _fireCallout(String columnName, dynamic value) async {
  final changed = await repo.fireCallout(
    windowSlug: widget.windowSlug,
    tabSlug: headerTab.slug,
    columnName: columnName,
    value: value,
    formData: _formData,
    recordId: _currentRecordId,
  );
  if (changed != null && changed.isNotEmpty && mounted) {
    setState(() { _formData.addAll(changed); });
  }
}

每個可編輯欄位的 onChanged 回呼中：

1. 更新 _formData[columnName] = value
2. 呼叫 _fireCallout(columnName, value)
3. 回傳的 changedFields 合併至 _formData，觸發 UI 重繪

ApplicationV1 動態載入程式碼

public class ApplicationV1 extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        final Set<Class<?>> classes = new HashSet<>();

        // 1. 硬編碼核心 resource
        classes.add(AuthServiceImpl.class);
        classes.add(ModelResourceImpl.class);
        classes.add(WindowResourceImpl.class);
        // ... 共 15 個 ...

        // 2. 動態發現外部 plugin 的 resource
        IServicesHolder<ResourceExtension> list =
            Service.locator().list(ResourceExtension.class);
        for (IServiceReferenceHolder<ResourceExtension> holder
                : list.getServiceReferences()) {
            ResourceExtension service = holder.getService();
            if (service != null) {
                classes.addAll(service.getResourceClasses());
            }
        }

        return classes;
    }
}

要點：getClasses() 在 Jersey servlet 初始化時呼叫一次（非每次請求）。Service.locator() 底層使用 OSGi ServiceTracker，所有 ResourceExtension 實作的 resource class 與核心 class 合併成同一個路由表。

部署步驟

完整部署四步走——比泡麵還簡單（好吧，至少跟泡麵一樣簡單）：

1. 匯入 Eclipse workspace：將 tw.idempiere.rest 專案匯入你的 Eclipse workspace
2. 加入 Launch Config：在 server.product.launch 的 selected_workspace_bundles 加入 tw.idempiere.rest@default:default
3. 重啟 iDempiere Server：重啟後 Jersey 會在初始化時自動發現新的 ResourceExtension
4. 驗證部署：在 OSGi console 執行 ss tw.idempiere.rest，確認狀態為 ACTIVE

伺服器插件架構（tw.idempiere.rest）

OSGi Bundle 架構與路由機制

tw.idempiere.rest 是獨立 OSGi Bundle，不是 Fragment Bundle：

兩個 Bundle 透過 OSGi Service Registry 連結，非 fragment 注入。idempiere-rest 核心匯出 ResourceExtension 介面，tw.idempiere.rest 實作該介面並註冊為 OSGi Service。各自獨立運行，擁有獨立的 classloader 與生命週期。

HTTP 請求路由鏈

POST /api/v1/callout/sales-order/order
      │
      ▼
  Jetty Web Server
      │  (Web-ContextPath: /api → idempiere-rest MANIFEST.MF)
      ▼
  Jersey ServletContainer (web.xml url-pattern: /*)
      │
      ▼
  ApplicationV1.getClasses() — JAX-RS Application，啟動時呼叫一次
      │
      ├── 硬編碼 15 個核心 resource class
      │   ├── AuthServiceImpl        → @Path("v1/auth")
      │   ├── ModelResourceImpl      → @Path("v1/models")
      │   ├── WindowResourceImpl     → @Path("v1/windows")
      │   └── ...
      │
      └── 動態發現 ResourceExtension（OSGi 服務）
          │  Service.locator().list(ResourceExtension.class)
          │       ↓
          │  DynamicServiceLocator → OSGi ServiceTracker
          │       ↓
          └── CalloutResourceExtension.getResourceClasses()
              → 返回 {CalloutResourceImpl.class}
      │
      ▼
  Jersey 統一路由表：
      v1/auth/**       → AuthServiceImpl        (idempiere-rest)
      v1/models/**     → ModelResourceImpl       (idempiere-rest)
      v1/callout/**    → CalloutResourceImpl     (tw.idempiere.rest)

ApplicationV1 動態載入機制

public class ApplicationV1 extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        final Set<Class<?>> classes = new HashSet<>();
        // 1. 硬編碼核心 resource（15 個）
        classes.add(AuthServiceImpl.class);
        classes.add(ModelResourceImpl.class);
        // ...
        // 2. 動態發現外部 plugin 的 resource
        IServicesHolder<ResourceExtension> list =
            Service.locator().list(ResourceExtension.class);
        for (IServiceReferenceHolder<ResourceExtension> holder
                : list.getServiceReferences()) {
            ResourceExtension service = holder.getService();
            if (service != null) {
                classes.addAll(service.getResourceClasses());
            }
        }
        return classes;
    }
}

要點：getClasses() 在 Jersey servlet 初始化時呼叫一次，非每次請求。所有 ResourceExtension 實作的 class 與核心 class 合併成同一個路由表，Jersey 根據 @Path 註解區分路由。

新增 REST 端點的模式

若未來需要擴充更多端點，只需在 tw.idempiere.rest 中：

1. 建立新的 @Path("v1/xxx") resource class
2. 在 CalloutResourceExtension.getResourceClasses() 中加入該 class
3. 重啟 iDempiere — Jersey 重新初始化時會自動發現

無需修改 idempiere-rest 核心插件的任何程式碼。

Flutter 客戶端整合

// window_repository.dart
Future<Map<String, dynamic>?> fireCallout({
  required String windowSlug,
  required String tabSlug,
  required String columnName,
  required dynamic value,
  required Map<String, dynamic> formData,
  required int recordId,
}) async {
  final response = await _api.dio.post(
    '${ApiConstants.apiPrefix}/callout/$windowSlug/$tabSlug',
    data: {
      'columnName': columnName,
      'value': value,
      'record': formData,
      'recordId': recordId,
    },
  );
  // parse changedFields, return if non-empty
}

// record_detail_screen.dart / record_form_screen.dart
Future<void> _fireCallout(String columnName, dynamic value) async {
  final changed = await repo.fireCallout(
    windowSlug: widget.windowSlug,
    tabSlug: headerTab.slug,
    columnName: columnName,
    value: value,
    formData: _formData,
    recordId: _currentRecordId,
  );
  if (changed != null && changed.isNotEmpty && mounted) {
    setState(() { _formData.addAll(changed); });
  }
}

每個可編輯欄位的 onChanged 回呼中：更新 _formData、呼叫 _fireCallout()、回傳的 changedFields 合併至 _formData 觸發 UI 重繪。

POST /api/v1/callout/{windowSlug}/{tabSlug}

{
  "columnName": "C_BPartner_ID",
  "value": {"id": 123, "identifier": "Joe Block", "model-name": "c_bpartner"},
  "record": {
    "C_DocType_ID": {"id": 132},
    "DateOrdered": "2026-02-21",
    "C_BPartner_ID": {"id": 123}
  },
  "recordId": 0
}

{
  "changedFields": {
    "Bill_BPartner_ID": {"id": 123, "identifier": "Joe Block"},
    "C_PaymentTerm_ID": {"id": 105, "identifier": "Immediate"},
    "M_PriceList_ID": {"id": 101, "identifier": "Standard"}
  }
}

Flutter App                        iDempiere Server
─────────────                      ────────────────
onChanged(field, value)
    │
    ▼
fireCallout() ──POST──►  /api/v1/callout/{windowSlug}/{tabSlug}
                                    │
                                    ▼
                          CalloutResourceImpl.fireCallout()
                          (resolve → GridTab → set fields → trigger → diff → discard)
                                    │
fireCallout() ◄──response──  {"changedFields":{...}}
    │
    ▼
setState(() => formData.addAll(changed))

// 1. Resolve Window/Tab via slug
MWindow window = new Query(ctx, MWindow.Table_Name, "slugify(name)=?", null)
    .setParameters(windowSlug).first();

// 2. Initialize GridTab
GridTab targetTab = gridWindow.getTab(tabIndex);
targetTab.initTab(false);

// 3. Load or create record
if (recordId > 0) { targetTab.query(false); }
else { targetTab.dataNew(false); }

// 4. Set all fields (trigger column last)
// 5. gridTab.processFieldChange(triggerField) — fires callouts
// 6. Diff before/after → return changedFields
// 7. Discard (no save)
targetTab.dataIgnore();

Future<Map<String, dynamic>?> fireCallout({
  required String windowSlug, required String tabSlug,
  required String columnName, required dynamic value,
  required Map<String, dynamic> formData, required int recordId,
}) async {
  final response = await _api.dio.post(
    '${ApiConstants.apiPrefix}/callout/$windowSlug/$tabSlug',
    data: {'columnName': columnName, 'value': value,
           'record': formData, 'recordId': recordId},
  );
  // parse changedFields, return if non-empty
}

POST /api/v1/callout/{windowSlug}/{tabSlug}

{
  "columnName": "C_BPartner_ID",
  "value": {"id": 123, "identifier": "Joe Block", "model-name": "c_bpartner"},
  "record": {
    "C_DocType_ID": {"id": 132},
    "DateOrdered": "2026-02-21",
    "C_BPartner_ID": {"id": 123}
  },
  "recordId": 0
}

{
  "changedFields": {
    "Bill_BPartner_ID": {"id": 123, "identifier": "Joe Block"},
    "C_PaymentTerm_ID": {"id": 105, "identifier": "Immediate"},
    "M_PriceList_ID": {"id": 101, "identifier": "Standard"}
  }
}

Flutter App                        iDempiere Server
─────────────                      ────────────────
onChanged(field, value)
    │
    ▼
fireCallout() ──POST──►  /api/v1/callout/{windowSlug}/{tabSlug}
                                    │
                                    ▼
                          CalloutResourceImpl.fireCallout()
                          (解決 → GridTab → フィールド設定 → トリガー → 差分 → 破棄)
                                    │
fireCallout() ◄──response──  {"changedFields":{...}}
    │
    ▼
setState(() => formData.addAll(changed))

// 1. slug で Window/Tab を解決
MWindow window = new Query(ctx, MWindow.Table_Name, "slugify(name)=?", null)
    .setParameters(windowSlug).first();

// 2. GridTab を初期化
GridTab targetTab = gridWindow.getTab(tabIndex);
targetTab.initTab(false);

// 3. レコードの読み込みまたは新規作成
if (recordId > 0) { targetTab.query(false); }
else { targetTab.dataNew(false); }

// 4. 全フィールド設定（トリガーカラムは最後）
// 5. gridTab.processFieldChange(triggerField) — Callout を起動
// 6. 前後を比較 → changedFields を返却
// 7. 破棄（保存しない）
targetTab.dataIgnore();

Future<Map<String, dynamic>?> fireCallout({
  required String windowSlug, required String tabSlug,
  required String columnName, required dynamic value,
  required Map<String, dynamic> formData, required int recordId,
}) async {
  final response = await _api.dio.post(
    '${ApiConstants.apiPrefix}/callout/$windowSlug/$tabSlug',
    data: {'columnName': columnName, 'value': value,
           'record': formData, 'recordId': recordId},
  );
  // changedFields をパースし、空でなければ返却
}