iDempiere Data Dictionary 與 AD 體系深入解析

深入解析 iDempiere 的 Data Dictionary（資料字典）與 AD（Application Dictionary）體系架構，是每位 iDempiere 開發者必須掌握的核心知識。AD 體系採用元資料驅動（Metadata-Driven）設計，讓你無需撰寫程式碼，即可透過設定完成資料表、視窗、欄位與選單的定義。本文將從 AD_Table、AD_Column 到 AD_Window、AD_Menu，帶你完整理解這套強大機制的運作原理。

什麼是 Data Dictionary？

Data Dictionary（資料字典）是描述資料庫結構的「元資料」集合。在傳統開發中，我們需要手動撰寫 SQL 建立資料表，再寫程式碼產生 UI 畫面。但 iDempiere 採用了革命性的設計：一切皆由 AD 表定義。

資料字典包含以下資訊：

• 資料表結構：表名、欄位名稱、資料型態
• 欄位屬性：是否必填、預設值、驗證規則
• 關聯關係：Foreign Key、Reference 類型
• 顯示設定：視窗、頁籤、欄位順序
• 選單結構：如何在系統中存取

AD 體系總覽

AD（Application Dictionary）體系由多個相互關聯的資料表組成，形成完整的元資料架構：

┌─────────────┐
│   AD_Menu   │ ← 選單入口
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  AD_Window  │ ← 視窗容器
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   AD_Tab    │ ← 頁籤（綁定 Table）
└──────┬──────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│  AD_Field   │ ←── │  AD_Column  │ ← 欄位定義
└─────────────┘     └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  AD_Table   │ ← 資料表定義
                    └─────────────┘

AD_Table：資料表定義

AD_Table 定義系統中的每一張資料表。當你在 iDempiere 建立新表時，首先要在這裡註冊。

-- 查詢特定資料表定義
SELECT AD_Table_ID, TableName, Name, Description, 
       IsView, AccessLevel, EntityType
FROM AD_Table 
WHERE TableName = 'Z_BookLoan';

AD_Column：欄位定義

AD_Column 定義資料表中的每個欄位，包含資料型態、長度、是否為主鍵等資訊。

-- 查詢資料表的所有欄位
SELECT c.ColumnName, c.Name, c.AD_Reference_ID, 
       r.Name as ReferenceType, c.IsKey, c.IsMandatory
FROM AD_Column c
JOIN AD_Reference r ON c.AD_Reference_ID = r.AD_Reference_ID
WHERE c.AD_Table_ID = (SELECT AD_Table_ID FROM AD_Table WHERE TableName = 'Z_BookLoan')
ORDER BY c.SeqNo;

-- 查詢主鍵欄位
SELECT ColumnName, IsKey 
FROM AD_Column 
WHERE AD_Table_ID = (SELECT AD_Table_ID FROM AD_Table WHERE TableName = 'Z_BookLoan')
  AND IsKey = 'Y';

AD_Window：視窗定義

AD_Window 定義使用者操作的視窗容器。每個視窗可以包含多個頁籤（Tab）。

-- 查詢視窗定義
SELECT AD_Window_ID, Name, Description, WindowType, IsSOTrx
FROM AD_Window 
WHERE Name LIKE '%BookLoan%';

AD_Tab：頁籤定義

AD_Tab 將視窗與資料表連結。一個視窗可有多個頁籤，形成主從關係（Header-Line）。

-- 查詢視窗的所有頁籤
SELECT t.SeqNo, t.Name, t.TabLevel, tbl.TableName
FROM AD_Tab t
JOIN AD_Table tbl ON t.AD_Table_ID = tbl.AD_Table_ID
WHERE t.AD_Window_ID = (SELECT AD_Window_ID FROM AD_Window WHERE Name = '圖書借閱')
ORDER BY t.SeqNo;

AD_Field：欄位顯示定義

AD_Field 定義欄位在頁籤中如何顯示，包括順序、是否顯示、是否唯讀等。

-- 查詢頁籤中的欄位配置
SELECT f.SeqNo, f.Name, c.ColumnName, f.IsDisplayed, f.IsReadOnly
FROM AD_Field f
JOIN AD_Column c ON f.AD_Column_ID = c.AD_Column_ID
WHERE f.AD_Tab_ID = ?
ORDER BY f.SeqNo;

AD_Menu：選單定義

AD_Menu 定義系統選單結構，讓使用者可以存取視窗、報表或流程。

-- 查詢選單項目
SELECT m.Name, m.Action, w.Name as WindowName
FROM AD_Menu m
LEFT JOIN AD_Window w ON m.AD_Window_ID = w.AD_Window_ID
WHERE m.Action = 'W'
ORDER BY m.Name;

從 Table 到 Menu 的完整流程

建立一個新功能模組時，AD 體系的設定流程如下：

1️⃣ 建立 AD_Table
     ↓
2️⃣ 建立 AD_Column（每個欄位）
     ↓
3️⃣ 同步資料庫（Synchronize Column）
     ↓
4️⃣ 建立 AD_Window
     ↓
5️⃣ 建立 AD_Tab（連結 Table）
     ↓
6️⃣ 建立 AD_Field（從 Column 自動產生）
     ↓
7️⃣ 建立 AD_Menu（加入選單）
     ↓
✅ 完成！可以透過選單存取新視窗

Reference 與 Foreign Key 的關係

iDempiere 使用 AD_Reference 來定義欄位的「顯示類型」與「驗證規則」，這與資料庫的 Foreign Key 有密切關係但並非完全相同。

常用 Reference 類型

Table Direct vs Table Reference

-- 查詢 Reference 類型定義
SELECT AD_Reference_ID, Name, ValidationType
FROM AD_Reference
WHERE IsActive = 'Y'
ORDER BY AD_Reference_ID;

-- 查詢 Table Reference 的設定（使用 AD_Ref_Table）
SELECT rt.AD_Table_ID, t.TableName, rt.AD_Key, rt.AD_Display
FROM AD_Ref_Table rt
JOIN AD_Table t ON rt.AD_Table_ID = t.AD_Table_ID
WHERE rt.AD_Reference_ID = ?;

實際範例：查詢 AD 體系 SQL

以下提供一個完整的查詢範例，從資料表追溯到選單：

-- 完整追溯：Table → Column → Tab → Field → Window → Menu

-- Step 1: 取得 Table 資訊
SELECT AD_Table_ID, TableName, Name 
FROM AD_Table 
WHERE TableName = 'Z_BookLoan';
-- 假設 AD_Table_ID = 1000000

-- Step 2: 查詢該表的所有欄位
SELECT ColumnName, Name, AD_Reference_ID, IsKey, IsMandatory, IsIdentifier
FROM AD_Column 
WHERE AD_Table_ID = 1000000
ORDER BY SeqNo;

-- Step 3: 查詢使用該表的 Tab
SELECT t.AD_Tab_ID, t.Name, t.TabLevel, w.Name as WindowName, w.AD_Window_ID
FROM AD_Tab t
JOIN AD_Window w ON t.AD_Window_ID = w.AD_Window_ID
WHERE t.AD_Table_ID = 1000000;

-- Step 4: 查詢 Tab 的欄位配置
SELECT f.SeqNo, f.Name, c.ColumnName, f.IsDisplayed, f.IsSameLine
FROM AD_Field f
JOIN AD_Column c ON f.AD_Column_ID = c.AD_Column_ID
WHERE f.AD_Tab_ID = ?
ORDER BY f.SeqNo;

-- Step 5: 查詢對應的選單項目
SELECT m.Name, m.Action, m.IsSummary
FROM AD_Menu m
WHERE m.AD_Window_ID = ?;

一次性完整查詢

-- 從 Table 一路查到 Menu 的完整關聯
SELECT 
    tbl.TableName,
    tbl.Name as TableDisplayName,
    tab.Name as TabName,
    tab.TabLevel,
    win.Name as WindowName,
    win.WindowType,
    menu.Name as MenuName
FROM AD_Table tbl
JOIN AD_Tab tab ON tbl.AD_Table_ID = tab.AD_Table_ID
JOIN AD_Window win ON tab.AD_Window_ID = win.AD_Window_ID
LEFT JOIN AD_Menu menu ON win.AD_Window_ID = menu.AD_Window_ID
WHERE tbl.TableName = 'Z_BookLoan';

常見 AD 表對照

以下整理開發時最常使用的 AD 系統表：

總結

iDempiere 的 AD 體系是其元資料驅動架構的核心。理解 AD_Table → AD_Column → AD_Window → AD_Tab → AD_Field → AD_Menu 的關聯，能讓你：

• 快速建立新的功能模組而無需撰寫 UI 程式碼
• 透過 SQL 查詢理解現有功能的結構
• 進行客製化開發時精準定位修改點
• 排查問題時追溯設定來源

下一篇文章，我們將實際操作建立自訂資料表與視窗，將這些理論付諸實踐！

📖 iDempiere 開發者系列文章 (3/10) |
關鍵字：iDempiere, Data Dictionary, AD體系, AD_Table, AD_Column, AD_Window, 元資料驅動, ERP開發