[iDempiere] 開源看板外掛：用 Kanban 管理 R_Request，拖拉、甘特圖、即時推送全搞定

小編 2026/06/02 發佈留言

本篇文章更新時間：2026/06/02
如有資訊過時或語誤之處，歡迎使用 Contact 功能通知或向一介資男的 LINE 社群反應。
如果本站內容對你有幫助，歡迎贊助支持。

前言：為什麼 iDempiere 需要一個看板

iDempiere 的 R_Request（需求工單）是系統內建的任務管理機制。舉凡客訴追蹤、IT 工單、售後服務、內部任務分派，都可以用 R_Request 來管理。它和 ERP 的核心資料深度整合 — 一張工單可以直接關聯到訂單、發票、付款、專案、業務夥伴等等。

問題是：原生的 R_Request 介面極度難用。

在 iDempiere 預設的 UI 中，R_Request 就是一個表格式的清單視窗。要看全局進度？你得一筆一筆點開看狀態。想知道哪些工單卡住了？沒有視覺提示。想拖一張工單到下個階段？不好意思，請打開表單、找到狀態欄位、從下拉選單選一個新狀態、儲存。

這個體驗在 2026 年是不能接受的。任何用過 Trello、Jira、Linear 的人都會問同一個問題：「有沒有看板？」

我寫了一個。

idempiere-kanban 是我開發的開源 iDempiere 外掛，把 R_Request 的管理體驗升級為現代化的視覺看板。拖拉卡片切換狀態、甘特圖看時程、指標儀表板看效率，全部整合在 iDempiere 裡面，不需要額外的第三方工具。

這篇文章是這個外掛的完整介紹。我會從架構設計的思考、功能細節、技術實作到安裝部署全面涵蓋，作為終極指南。

R_Request 的資料模型：為什麼天然適合看板

在介紹外掛功能之前，先理解一下為什麼 R_Request 的底層架構天然適合做成看板。

核心關聯鏈

R_RequestType → R_StatusCategory_ID → R_StatusCategory
R_Status → R_StatusCategory_ID → R_StatusCategory
R_Request → R_RequestType_ID + R_Status_ID

翻譯成白話：

R_RequestType（需求類型）：定義「這是什麼類型的工單」，例如「客訴」「IT 支援」「開發任務」。每個類型指向一個狀態類別。
R_StatusCategory（狀態類別）：一組狀態的容器。
R_Status（狀態）：看板上的每一欄。每個狀態有 SeqNo（排序）、IsOpen（開放中）、IsClosed（已結案）、IsFinalClose（最終結案，不可重開）等旗標。
R_Request（需求工單）：就是看板上的卡片。

看到了嗎？R_Request 的狀態系統本身就是「一列有序狀態 + 卡片在狀態之間流動」的模型 — 這正是看板。iDempiere 的資料結構已經替我們做好了 80% 的工作，差的只是一個現代化的視覺介面。

R_Request 的 ERP 整合深度

R_Request 不只是一個獨立的任務管理工具。它和 iDempiere 的核心商業資料有 10 個 FK（外鍵）關聯：

關聯欄位	關聯表	用途
C_BPartner_ID	業務夥伴	這張工單是哪個客戶/供應商的
M_Product_ID	產品	跟哪個產品有關
C_Order_ID	訂單	關聯到哪張訂單
C_Invoice_ID	發票	關聯到哪張發票
C_Payment_ID	付款	關聯到哪筆付款
C_Project_ID	專案	屬於哪個專案
C_Campaign_ID	行銷活動	屬於哪個行銷活動
A_Asset_ID	資產	跟哪個資產有關
C_Activity_ID	活動	成本歸屬到哪個活動
SalesRep_ID	負責人	誰負責處理

這代表每一張看板卡片都可以直接跳轉（Zoom）到 iDempiere 對應的訂單、發票、客戶資料。不像外部看板工具只是一張便利貼，這裡的每張卡片背後都是 ERP 的活資料。

功能全覽

看板操作

拖拉切換狀態：把卡片從「待辦」拖到「進行中」，背後自動更新 R_Request.R_Status_ID。
欄內排序：同一欄內的卡片可以拖曳調整順序，存到自訂欄位 X_KanbanSeqNo。
泳道分組：依專案 / 負責人 / 業務夥伴 / 優先級分組顯示，快速聚焦。
WIP 限制：每個狀態欄位可設定在製品上限（Work-In-Progress limit），超過時視覺警告，避免過度承載。
阻塞標記：卡片被標記為阻塞（IsEscalated）時顯示 🚫，一眼識別卡住的工單。
過期指示：3 天未動的卡片顯示黃色、7 天未動顯示紅色，督促跟進。
最終結案確認：拖到 FinalClose 狀態時會跳出確認對話框，因為結案後不可重開（Processed='Y'）。
組織篩選：依登入者的角色權限（AD_Role_OrgAccess）篩選可見的組織。
範圍篩選：「我的卡片」/「我的團隊」/「全部」三種視角切換。

多視圖

除了看板，還有兩個互補的視圖，共享同一個資料來源和篩選條件：

甘特圖（Gantt Chart）：以 StartDate 和 EndTime 繪製時間軸，適合看專案排程和重疊。
指標（Metrics）：Cycle Time（各狀態停留時間）和 Throughput（每週完成數量）圖表，量化團隊效率。

卡片管理

新建卡片：指定狀態、組織、需求類型，一鍵建立新的 R_Request。
編輯所有欄位：10 個可搜尋的 ERP 下拉欄位（業務夥伴、產品、訂單、發票、付款、專案、行銷活動、資產、活動、負責人），直接在卡片內搜尋和關聯。
留言與 @mention：留言存到 R_RequestUpdate 表。支援 @mention 自動完成，被 mention 的人自動加入觀察者並收到通知。
檔案附件：上傳、下載、刪除附件，存到 iDempiere 原生的 AD_Attachment。
活動時間軸：整合狀態變更記錄（RK_Card_Move_Log）、留言（R_RequestUpdate）和欄位變更（AD_ChangeLog），完整呈現卡片的生命歷程。

通知系統

觀察/取消觀察：建立者和負責人自動成為觀察者。任何人可以手動 Watch/Unwatch。
觸發時機：狀態變更、新留言、負責人變更 → 通知所有觀察者。
通知管道：iDempiere 原生的 AD_Note（站內通知）+ HTML Email。
多語系模板：通知內容依收件者的 AD_Language 翻譯，中文使用者收到中文通知、英文使用者收到英文通知。

排程提醒（每日自動執行）

透過 AD_Scheduler 每日跑一次 KanbanReminderProcess：

條件	動作
明天到期 / 今天到期	通知觀察者
逾期 1 天	通知觀察者
逾期 3 天	升級通知主管（Supervisor）
逾期 7 天	自動標記阻塞（IsEscalated='Y'）
明天開始	通知負責人

可透過 AD_SysConfig KANBAN_REMINDER_ENABLED 開關。

設定功能

Board 來源：每個使用者可以選擇要看哪個 R_RequestType 的看板。支援重新命名、新建類型、以及直接跳轉（🔗）到 iDempiere 的 RequestType 設定視窗。
狀態管理：▲▼ 排序、偵測共用狀態類別（多個 RequestType 共用同一組狀態）、一鍵建立獨立副本。
WIP 限制：每個狀態欄位的在製品上限。
優先級顏色：自訂各優先級的顯示顏色。

技術架構深入

整體架構圖

ZK Desktop → KanbanFormController（@Form）
  → JWT from ZK session（JwtUtil, HS512, KANBAN_TOKEN_SECRET）
  → iframe loads React SPA
    → Board（+ Swimlanes）/ Gantt / Metrics views
    → /init, /cards/*, /gantt, /metrics, /lookup, /attachments/*, /config
    → postMessage bridge（zoom, token refresh, server push）

KanbanReminderProcess（AD_Scheduler, daily）
  → scans due/overdue/starting cards
  → AD_Note + HTML Email via NotificationHelper

為什麼選擇 ZK Form + iframe + React？

iDempiere 的 Web UI 是基於 Apache ZK 框架。ZK 很適合表單式的企業應用，但要做拖拉看板這種高度互動的 UI 就力不從心了。直接在 ZK 裡面寫看板不是不行，但開發體驗和效能都不理想。

我選擇的架構是：

KanbanFormController：一個標準的 iDempiere Form（OSGi 註冊），負責從 ZK session 取得使用者身份。
JWT Token：Controller 用 ZK session 的 AD_Session_ID 簽發一個短期 JWT token（HS512），傳給前端。這讓前端 SPA 可以獨立呼叫後端 API，不依賴 ZK session 的 cookie。
React SPA：iframe 內載入獨立的 React 應用程式。所有 UI 互動、拖拉、圖表都在這裡處理。
postMessage bridge：SPA 和 ZK 之間透過 window.postMessage 溝通。用於：Zoom 跳轉到 iDempiere 視窗、Token 過期時重新取得、Server Push 觸發重整。

這個架構的好處：前端可以用現代工具鏈（React 18 + TypeScript + Vite + Tailwind）開發，不受 ZK 框架的限制；同時又保持了和 iDempiere 的無縫整合 — 從使用者的角度看，它就是 iDempiere 裡面的一個選單項目。

即時推送：OSGi EventAdmin + ZK Server Push

當使用者 A 把卡片從「待辦」拖到「進行中」時，使用者 B 的看板需要即時更新。這在傳統的 HTTP request-response 模型中做不到。

解法是 iDempiere 的 ZK Server Push 機制：

使用者 A 的操作觸發 Servlet → 更新資料庫後，透過 EventManager.getInstance().sendEvent() 發布一個 OSGi 事件。
所有在線使用者的 KanbanFormController 都註冊了 EventHandler，收到事件後：
- 檢查 desktop.isAlive()（Desktop 是否還活著）
- 檢查 AD_Client_ID（多租戶隔離）
- 透過 Executions.schedule(desktop, ...) 排入 ZK Server Push 佇列
- 注入 JavaScript：iframe.contentWindow.postMessage({type:'refresh'}, '*')
SPA 收到 refresh 訊息後，TanStack Query 自動重新抓取資料並更新 UI。

延遲：ZK CE 的 Server Push 是 Polling 模式，延遲約 1~15 秒，不是即時的。但對於看板場景已經夠用 — 你不需要毫秒級同步，幾秒內看到同事的操作就足夠了。

多租戶與多組織

iDempiere 是原生多租戶（Multi-Tenant）架構。每個 Client（租戶）的資料完全隔離。在看板外掛中：

Client 隔離：所有 R_Request 查詢都帶 AD_Client_ID = :clientId，不同租戶絕對看不到彼此的資料。
Org 篩選：同一個租戶內可能有多個組織（分公司、部門）。看板依登入者的角色權限（AD_Role_OrgAccess）決定可見的組織，並提供 Org filter 切換。
使用者偏好：每個使用者選擇的 Board 來源存在 AD_Preference（per-user），不影響其他人。
組織級設定：WIP 限制、優先級顏色存在 AD_SysConfig（per-client），整個租戶共用。

多語系（i18n）

外掛的所有 UI 文字都走 iDempiere 標準的翻譯機制：

120+ 個 AD_Message key，首次安裝時自動建立 en_US 和 zh_TW 翻譯。
後端 InitServlet 在使用者登入時，依 AD_Language 查詢對應翻譯，回傳 JSON 給前端。
前端用 t('KanbanSummary') 函數取得翻譯文字，有 fallback 到英文。
通知信件也依收件者的語言切換模板。

如果你的 iDempiere 環境有其他語系（如 ja_JP），只需要執行 i18n/ja_JP.sql 即可擴充，架構本身不限語言數量。

技術堆疊總覽

層面	技術
後端	WAB（Web Application Bundle）with 9 Servlets + 1 Scheduler Process（18 Java classes）
前端	React 18 + TypeScript + @dnd-kit/core + TanStack Query + Tailwind CSS
認證	JWT（HS512），橋接 ZK session，獨立於 REST API
即時推送	OSGi EventAdmin + ZK Server Push（polling）
資料儲存	R_Request（原生）+ RK_Card_Move_Log/RK_Card_Member/RK_Request_Type_Config（自建）
設定儲存	AD_Preference（per-user）+ AD_SysConfig（per-client）
通知	AD_Note + HTML Email，per-user i18n 模板
建置	Maven/Tycho 4.0.8 + Vite 6，`build.sh` 統一入口

看板欄位與 iDempiere 的對照

每一張看板卡片的欄位，都直接對應到 R_Request 表的真實資料。這不是一個「看起來像看板的獨立資料庫」，而是 iDempiere 原生資料的視覺化呈現。

卡片主要欄位

看板欄位	DB 欄位	說明
單據編號	R_Request.DocumentNo	自動編號，前綴 REQ
摘要	R_Request.Summary	卡片標題（最多 2000 字元）
狀態	R_Request.R_Status_ID	看板的哪一欄
優先級	R_Request.Priority	1=緊急 3=高 5=中 7=低 9=次要
阻塞	R_Request.IsEscalated	🚫 標記
負責人	R_Request.SalesRep_ID	誰負責處理
到期日	R_Request.DateNextAction	下次動作日 / 到期日
開始日	R_Request.StartDate	甘特圖起始（移入 Open 狀態時自動設定）
結束日	R_Request.EndTime	甘特圖結束
卡片排序	R_Request.X_KanbanSeqNo	自訂欄位，欄內拖曳排序用

留言與附件

功能	DB 表	說明
留言	R_RequestUpdate	Result 欄位存內容，CreatedBy + Created 記錄誰/何時
附件	AD_Attachment	AD_Table_ID=417（R_Request），Record_ID=卡片 ID
欄位變更	AD_ChangeLog	外掛自動啟用 R_Request 的 IsChangeLog

安裝與部署

系統需求

iDempiere v11 ~ v14（已測試）
JDK 17+
Maven 3.9+（建置時需要）
PostgreSQL

建置

git clone https://github.com/nczz/idempiere-kanban.git
cd idempiere-kanban
bash build.sh

build.sh 統一處理 Maven/Tycho 後端建置和 Vite 前端建置，一個指令搞定。

部署方式 A：update-prd.sh（建議）

cd /opt/idempiere
./update-prd.sh file:///path/to/tw.mxp.idempiere.kanban.p2/target/repository tw.mxp.idempiere.kanban

重啟 iDempiere 即完成。

部署方式 B：Docker 手動複製

JAR=tw.mxp.idempiere.kanban/target/tw.mxp.idempiere.kanban-14.0.0-SNAPSHOT.jar
docker cp $JAR <container>:/opt/idempiere/plugins/
docker exec <container> bash -c "
  echo 'tw.mxp.idempiere.kanban,14.0.0,plugins/$(basename $JAR),4,false' >> \
  /opt/idempiere/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info
"
docker restart <container>

首次啟動自動建立

安裝後第一次啟動，外掛自動完成所有初始化：

建立 3 張自建表（RK_Card_Move_Log、RK_Card_Member、RK_Request_Type_Config）
建立 AD_Form + AD_Menu + 翻譯記錄 + 角色權限
建立預設看板（Backlog → To Do → In Progress → Review → Done → Archived）
建立 120+ i18n 訊息（en_US + zh_TW）
設定 DocumentNo 前綴 REQ
啟用 R_Request 的 Change Log
建立 AD_Process + AD_Scheduler（每日提醒）
建立 AD_SysConfig KANBAN_REMINDER_ENABLED=Y

不需要手動執行任何 SQL，不需要手動設定任何東西。

語系擴充

如果你在安裝外掛之後才啟用新語系：

psql -U adempiere -d idempiere -f i18n/zh_TW.sql

適用場景

任何用 R_Request 管理工作流程的場景都適用：

IT 服務台：內部 IT 工單追蹤，從報修到結案的完整流程。
客訴處理：客戶投訴從受理、調查、處理到回覆的進度管理。
售後服務：產品售後問題追蹤，可直接關聯到訂單和產品。
專案任務：開發任務、設計任務的看板管理，搭配甘特圖看排程。
業務跟進：業務機會的階段管理，每張卡片關聯到業務夥伴和報價。

授權

GPL v2 — 和 iDempiere 本身相同。完全開源，自由使用。

需要導入協助？

如果你的組織正在使用 iDempiere，或正在評估導入，需要看板外掛的客製化、部署協助、或更廣泛的 iDempiere 顧問服務，歡迎透過聯絡我們頁面洽詢，或參閱服務與商品頁面了解費用。

取消回覆

文章

文章