本篇文章更新時間：2026/06/03
如有資訊過時或語誤之處，歡迎使用 Contact 功能通知或向一介資男的 LINE 社群反應。
如果本站內容對你有幫助，歡迎贊助支持 。
內容目錄
前言：ERP 客製化的學習曲線問題
iDempiere 是一套功能完整的企業級 ERP，但它的客製化開發有著陡峭的學習曲線。要寫一個 Plugin，你需要同時掌握：OSGi bundle 架構、iDempiere 的 Application Dictionary 機制、ZK Web UI 框架、Java 後端模式、REST API 的限制與慣例。
這些知識散落在 wiki、論壇貼文、原始碼註解中，沒有統一的教學路徑。即使是有經驗的 Java 開發者，面對「建立一個 Annotation-based Process」或「正確地透過 REST API 完成一張銷售訂單」這類任務，也常常需要花大量時間查文件、看範例、踩坑。
我的解法是：把這些領域知識封裝成 AI 開發助手的技能包，讓 AI Coding Agent 直接具備 iDempiere 的開發知識，而不是每次都從零開始。
目前我開源了兩個專案，分別針對兩個主流的 AI 編碼工具：
- idempiere-api — Claude Code 插件，專注 REST API 操作與測試
- idempiere-skills — Gemini CLI 技能包，專注 Plugin 程式碼生成
idempiere-api：Claude Code 的 iDempiere REST API 助手
這是什麼
一個 Claude Code 插件（Plugin），安裝後讓 Claude Code 具備 iDempiere REST API 的完整知識。涵蓋 34 個功能模組、159 個測試案例，以及我從實戰中整理的五大原則和錯誤診斷指南。
安裝
# 在 Claude Code 中執行
/plugin marketplace add nczz/idempiere-api
/plugin install idempiere-api@nczz/idempiere-api
可用命令
| 命令 | 說明 |
|---|---|
/idempiere-api:test <module> |
執行指定模組的 API 測試 |
/idempiere-api:create <doctype> |
單據建立指導（含五大原則） |
/idempiere-api:debug |
顯示錯誤診斷指南 |
/idempiere-api:modules |
列出所有測試模組 |
五大原則
透過 REST API 建立 iDempiere 單據時，有五個必須確認的面向。這些原則是我從無數次踩坑中歸納的：
- WHO — Token 的 User 必須屬於目標租戶，且 Context（Client/Org/Role/Warehouse）正確設定。
- WHAT — 確認必填欄位和正確的 DocType（C_DocTypeTarget_ID vs C_DocType_ID 依表不同）。
- FILL — 盡可能填寫完整資訊，避免系統預設值造成的非預期行為。
- WHERE — 關聯主檔（BPartner、Product、Price List）優先查詢確認存在，再建立單據。
- WHEN — 完成、作廢等動作必須用 Process API（POST /processes/{slug}），不能用 PUT 改 DocAction 欄位。
支援的模組（部分列舉）
- 認證與授權（auth）
- 業務夥伴（bpartner）
- 銷售訂單（order）
- 採購訂單（purchase）
- 發票管理（invoice）
- 付款管理（payment）
- 出入庫（inout）
- 庫存（inventory）
- ...共 34 個模組
使用場景
當你在 Claude Code 中對 iDempiere 做 REST API 開發或整合測試時，這個插件讓 AI 具備：
- 知道每個單據的正確建立順序和必填欄位
- 知道常見的錯誤原因和解法（如 Cross-Tenant 錯誤、QtyEntered 漏填）
- 可以直接執行測試腳本驗證 API 是否正常運作
idempiere-skills：Gemini CLI 的 iDempiere 開發技能包
這是什麼
一組 Gemini CLI 的技能（Skills），涵蓋 iDempiere Plugin 開發中最常見的 11 種模式。每個 Skill 包含完整的程式碼模板和工作流程指引，讓 Gemini 可以按照正確的模式生成 iDempiere 程式碼。
安裝
# 前置：安裝 Gemini CLI
npm install -g @google/gemini-cli
# 安裝個別技能
gemini skills install https://github.com/nczz/idempiere-skills.git --path idempiere-annotation-process
gemini skills install https://github.com/nczz/idempiere-skills.git --path idempiere-callout-generator
# ... 依需要安裝
可用技能
| Skill | 用途 |
|---|---|
| idempiere-annotation-process | 建立 Annotation-based Process + ProcessFactory |
| idempiere-mapped-process | 建立 IMappedProcessFactory 的 Process |
| idempiere-callout-generator | 建立欄位 Callout + CalloutFactory |
| idempiere-event-annotation | 建立 Annotation-based Event Manager + Delegate |
| idempiere-osgi-event-handler | 建立 OSGi component-based Event Handler |
| idempiere-rest-resource | 建立 REST ResourceExtension（自訂 API） |
| idempiere-window-validator | 建立 WindowValidator（視窗驗證邏輯） |
| idempiere-zul-form | 建立自訂 ZK Form（IMappedFormFactory） |
| idempiere-grouped-listbox | 建立 Grouped Listbox Form |
| idempiere-wlistbox-custom-editor | 自訂 WListbox 欄位編輯器 |
| idempiere-mapped-model-factory-service | 使用 IMappedModelFactory 掃描 Model |
每個 Skill 的結構
每個技能包含：
- SKILL.md：工作流程描述，告訴 AI「建立這種元件需要哪些步驟」
- assets/：程式碼模板（.java），包含正確的 annotation、OSGi 宣告、interface 實作
例如 idempiere-annotation-process 的工作流程：
- 確認 Process 的 package 位置
- 用模板建立 AnnotationBasedProcessFactory（OSGi @Component）
- 用模板建立 Process class（@Process + @Parameter annotations）
- 確保 Factory 的 getPackages() 包含 Process 所在的 package
使用場景
當你對 Gemini 說「幫我建立一個 C_Order.DateOrdered 的 Callout，設定 DatePromised 為今天」，安裝了 idempiere-callout-generator 技能的 Gemini 會：
- 用正確的 @Callout annotation template
- 設定正確的 tableName 和 columnName（用 I_C_Order interface 常數）
- 在 start() 中正確使用 mTab.setValue()
- 如果 Factory 不存在，同時建立 Factory class
不需要你記住所有的 annotation 格式、interface 名稱、OSGi 宣告方式。
兩個工具的互補關係
| 面向 | idempiere-api（Claude Code） | idempiere-skills（Gemini CLI） |
|---|---|---|
| 階段 | Runtime（執行期） | Development（開發期） |
| 用途 | REST API 測試、單據操作、除錯 | Plugin 程式碼生成 |
| 輸出 | API 呼叫結果、診斷報告 | Java 原始碼檔案 |
| 適合誰 | 整合開發者、QA、顧問 | Plugin 開發者 |
| 知識來源 | 34 模組測試 + 五大原則 + 錯誤診斷 | 11 種開發模式 + 程式碼模板 |
一個典型的開發流程可能是：
- 用 idempiere-skills + Gemini 生成 Plugin 骨架（Process、Callout、Event Handler）
- 部署到測試環境
- 用 idempiere-api + Claude Code 測試 REST API 行為是否符合預期
為什麼要封裝領域知識給 AI
你可能會問：直接問 AI 不行嗎？為什麼要做成 plugin / skill？
差別在於精確度和一致性：
- 沒有領域知識：AI 可能用 PUT 改 DocAction（錯誤）、可能忘記 QtyEntered（錯誤）、可能用錯 C_DocType_ID vs C_DocTypeTarget_ID（錯誤）。這些都是 iDempiere 特有的陷阱，通用 AI 模型不會知道。
- 有領域知識：AI 知道必須用 Process API 完成單據、知道每個表的必填欄位、知道正確的 Annotation 格式。產出的程式碼直接可用，不需要 debug。
本質上，這是把「資深 iDempiere 開發者的經驗」編碼化（codified），讓任何開發者都能透過 AI 存取這些經驗。
授權
- idempiere-api：MIT License
- idempiere-skills：依 iDempiere 社群慣例
延伸閱讀
本站 iDempiere 開發相關：
- [iDempiere] Plugin 開發入門：用 OSGi 擴充 iDempiere
- [iDempiere] 開源看板外掛：Kanban 管理 R_Request
- [iDempiere] 開源預約管理外掛：Google Calendar 風格行事曆
- [iDempiere] 多語系全域搜尋外掛：跨語言找選單
如果你的團隊正在用 iDempiere，想加速客製化開發或需要顧問協助，歡迎透過聯絡我們洽詢。