erpnext-analysis/ERPNext_Accounting_Structure.md

ERPNext 會計數據結構分析

日期: 2026-04-18 版本: ERPNext v17 (develop branch) 程式碼位置: /home/tony/erpnext-analysis/erpnext

---

目錄

1. 環境現狀
2. 核心會計數據模型
3. GL Entry 總帳分錄結構
4. 主要 Doctype 欄位詳解
5. 會計數據導入的 4 種方式
6. 基礎資料依賴
7. 自訂 API 開發架構
8. 關鍵程式邏輯
9. 下一步建議

---

環境現狀

項目	狀態
ERPNext 版本	v17 (develop branch)
程式碼位置	/home/tony/erpnext-analysis/erpnext、/home/tony/erpnext/erpnext
Frappe Core	❌ 未找到
Bench 環境	❌ 無 sites/、無 bench 目錄
執行中服務	❌ 無 ERPNext/Frappe 實例運行
可用資源	PostgreSQL (nexus_postgres:5432)、Qdrant (6333-6334)、Neo4j (7474/7687)
API 端口	8084 (本地 LLM)、8082 (Python 服務)

結論: 目前只能做靜態結構分析，要實際開發 API 需要部署 Frappe bench 環境。

---

核心會計數據模型

ERPNext 的會計數據透過 **Doctype（文件類型）**組織，核心流程是：

交易文件 (Invoice/Payment) → General Ledger (GL Entry) → 總帳/分類帳

層級關係圖

┌─────────────────────────────────────────────────────────────────┐
│                        主交易文件                                 │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐ │
│  │ Sales Invoice    │  │ Purchase Invoice │  │ Payment Entry │ │
│  │ (銷售發票)        │  │ (採購發票)        │  │ (付款/收款)    │ │
│  └────────┬─────────┘  └────────┬─────────┘  └───────┬───────┘ │
│           │                     │                     │          │
│  ┌────────┴─────────────────────┴─────────────────────┴───────┐ │
│  │  controller.py (accounts/doctype/...)                       │ │
│  │  自動生成 GL Entry + Payment Ledger Entry                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                        底層分錄                                  │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐  ┌──────────────────────────┐            │
│  │ GL Entry         │  │ Payment Ledger Entry     │            │
│  │ (總帳分錄)        │  │ (付款分類帳)              │            │
│  │ • 不可手動編輯    │  │ • 不可手動編輯            │            │
│  │ • 借貸平衡        │  │ • AR/AP 追蹤             │            │
│  └──────────────────┘  └──────────────────────────┘            │
└─────────────────────────────────────────────────────────────────┘

主要 Doctype 總覽

層級	Doctype	說明	關聯
主文件	sales_invoice	銷售發票	→ GL Entry
主文件	purchase_invoice	採購發票	→ GL Entry
主文件	payment_entry	付款/收款記錄	→ GL Entry + Payment Ledger
主文件	journal_entry	日記帳（手動過帳）	→ GL Entry
主文件	pos_invoice	POS 發票	→ GL Entry
子表	sales_invoice_item	發票明細（商品/收入帳戶）
子表	purchase_invoice_item	採購明細（費用帳戶）
子表	journal_entry_account	日記帳分录行
底層	gl_entry	總帳分錄（最終會計記錄）	不可手動編輯
底層	payment_ledger_entry	付款分類帳（AR/AP 追蹤）	不可手動編輯

---

GL Entry（總帳分錄）結構

⚠️ GL Entry 是 ERPNext 會計數據的終極歸宿，所有交易文件最終都會轉成 GL Entry 記錄。

完整欄位列表

欄位	類型	可空	說明
posting_date	Date	✅	入帳日期
transaction_date	Date	✅	交易日期
account	Link → Account	✅	會計科目
party_type	Link → DocType	✅	往來對象類型（Customer/Supplier/Employee 等）
party	Dynamic Link	✅	往來對象（動態引用 party_type 指向的 Doctype）
cost_center	Link → Cost Center	✅	成本中心
debit	Currency	✅	借方金額（公司幣）
credit	Currency	✅	貸方金額（公司幣）
account_currency	Link → Currency	✅	科目幣別
debit_in_account_currency	Currency	✅	科目幣別借方
credit_in_account_currency	Currency	✅	科目幣別貸方
against	Text	✅	對應科目（簡述）
against_voucher_type	Link → DocType	✅	對應憑證類型
against_voucher	Dynamic Link	✅	對應憑證編號
voucher_type	Link → DocType	✅	來源文件類型
voucher_no	Dynamic Link	✅	來源文件編號
voucher_detail_no	Data	✅	來源明細編號（子表行號）
project	Link → Project	✅	專案
remarks	Text	✅	備註
is_opening	Select	✅	是否為期初分錄
is_advance	Select	✅	是否為預付款
fiscal_year	Link → Fiscal Year	✅	會計年度
company	Link → Company	✅	公司
finance_book	Link → Finance Book	✅	財務簿
to_rename	Check	✅	待重新編號
due_date	Date	✅	到期日
is_cancelled	Check	✅	是否已取消
transaction_currency	Link → Currency	✅	交易幣別
transaction_exchange_rate	Float	✅	交易匯率
debit_in_transaction_currency	Currency	✅	交易幣別借方
credit_in_transaction_currency	Currency	✅	交易幣別貸方
voucher_subtype	Small Text	✅	憑證子類型
debit_in_reporting_currency	Currency	✅	報表幣別借方
credit_in_reporting_currency	Currency	✅	報表幣別貸方
reporting_currency_exchange_rate	Float	✅	報表幣別匯率

分錄結構要求

每筆分录: debit = credit（借貸必須平衡）
每筆交易: 所有 GL Entry 的 debit 總和 = credit 總和

---

主要 Doctype 欄位詳解

Sales Invoice（銷售發票）

Header（主文件）核心欄位

欄位	類型	必填	說明
naming_series	Select	✅	編號系列
customer	Link → Customer	✅	客戶
posting_date	Date	✅	入帳日期
posting_time	Time	✅	入帳時間
company	Link → Company	✅	公司
tax_category	Link → Tax Category	✅	稅務類別
taxes_and_charges	Link → Sales Taxes and Charges Template	✅	稅金模板
is_return	Check	✅	是否為退貨
return_against	Data	✅	退回原始發票
is_consolidated	Check	✅	是否為合併發票
is_discounted	Check	✅	是否為折讓發票
base_grand_total	Currency	✅	稅前總額（公司幣）
base_rounding_adjustment	Currency	✅	四捨五入調整（公司幣）
round_total	Check	✅	是否四捨五入
base_rounded_total	Currency	✅	四捨五入後總額（公司幣）
grand_total	Currency	✅	總額
rounded_total	Currency	✅	四捨五入後總額
total_taxes_and_charges	Currency	✅	總稅金
total_qty	Float	✅	總數量
status	Select	✅	狀態（Draft/Submitted/Cancelled/Paid）
is_pos	Check	✅	是否為 POS 發票
is_return	Check	✅	是否為退貨
update_stock	Check	✅	是否更新庫存
update_billed_amount_in_delivery_note	Check	✅	是否更新送貨單已計費金額
update_billed_amount_in_sales_order	Check	✅	是否更新訂單已計費金額
write_off_amount	Currency	✅	核銷金額
is_opening	Select	✅	是否為期初
amended_from	Link → Sales Invoice	✅	來源修改

Sales Invoice Item（明細子表）核心欄位

欄位	類型	必填	說明
item_code	Link → Item	✅	商品
item_name	Data	✅	商品名稱
uom	Link → UOM	✅	計量單位
conversion_factor	Float	✅	單位換算係數
qty	Float	✅	數量
stock_qty	Float	✅	庫存單位數量
rate	Currency	✅	單價
amount	Currency	✅	金額
base_rate	Currency	✅	公司幣單價
base_amount	Currency	✅	公司幣金額
income_account	Link → Account	✅	收入科目
expense_account	Link → Account	❌	費用科目
cost_center	Link → Cost Center	✅	成本中心
item_tax_template	Link → Item Tax Template	✅	商品稅金模板
warehouse	Link → Warehouse	✅	倉庫
delivery_note	Link → Delivery Note	❌	送貨單
sales_order	Link → Sales Order	❌	銷售訂單
project	Link → Project	❌	專案
is_fixed_asset	Check	❌	是否為固定資產
asset	Link → Asset	❌	資產編號
enable_deferred_revenue	Check	❌	是否啟用遞延收入
service_start_date	Date	❌	服務開始日期
service_end_date	Date	❌	服務結束日期

---

Purchase Invoice（採購發票）

Header 核心欄位（與 Sales Invoice 類似）

欄位	類型	必填	說明
supplier	Link → Supplier	✅	供應商
posting_date	Date	✅	入帳日期
company	Link → Company	✅	公司
taxes_and_charges	Link → Purchase Taxes and Charges Template	✅	稅金模板
is_return	Check	✅	是否為退貨
return_against	Data	✅	退回原始發票
grand_total	Currency	✅	總額
base_grand_total	Currency	✅	公司幣總額
update_stock	Check	✅	是否更新庫存
is_paid	Check	✅	是否為即期付款
status	Select	✅	狀態

Purchase Invoice Item 核心欄位

欄位	類型	必填	說明
item_code	Link → Item	✅	商品
qty	Float	✅	接收數量
rejected_qty	Float	❌	拒收數量
stock_qty	Float	✅	庫存單位數量
rate	Currency	✅	單價
amount	Currency	✅	金額
expense_account	Link → Account	✅	費用科目
cost_center	Link → Cost Center	✅	成本中心
warehouse	Link → Warehouse	❌	接收倉庫
rejected_warehouse	Link → Warehouse	❌	拒收倉庫
item_tax_template	Link → Item Tax Template	✅	商品稅金模板
purchase_order	Link → Purchase Order	❌	採購訂單
purchase_receipt	Link → Purchase Receipt	❌	採購收據
project	Link → Project	❌	專案
is_fixed_asset	Check	❌	是否為固定資產
asset_location	Link → Asset Location	❌	資產位置

---

Payment Entry（付款/收款）

Header 核心欄位

欄位	類型	必填	說明
payment_type	Select	✅	付款類型（Receive/Pay/Internal Transfer）
posting_date	Date	✅	入帳日期
company	Link → Company	✅	公司
party_type	Link → DocType	✅	對象類型（Customer/Supplier）
party_name	Data	✅	對象名稱
paid_from	Link → Account	✅	付款科目（借方）
paid_from_account_currency	Link → Currency	✅	付款科目幣別
paid_to	Link → Account	✅	收款科目（貸方）
paid_to_account_currency	Link → Currency	✅	收款科目幣別
paid_amount	Currency	✅	支付金額
base_paid_amount	Currency	✅	公司幣支付金額
received_amount	Currency	✅	收到金額
base_received_amount	Currency	✅	公司幣收到金額
source_exchange_rate	Float	✅	來源匯率
target_exchange_rate	Float	✅	目標匯率
reference_no	Data	❌	支票/參考編號
reference_date	Date	❌	支票日期
clearance_date	Date	❌	清償日期
mode_of_payment	Link → Mode of Payment	❌	付款方式
bank_account	Link → Company Bank Account	❌	公司銀行帳戶
party_bank_account	Link → Party Bank Account	❌	對方銀行帳戶
status	Select	✅	狀態
amended_from	Link → Payment Entry	❌	來源修改

Payment Entry Reference（明細子表）

欄位	類型	必填	說明
reference_doctype	Link → DocType	✅	引用文件類型
reference_name	Data	✅	引用文件編號
total_amount	Currency	✅	總金額
outstanding_amount	Currency	✅	未清金額
allocated_amount	Currency	✅	已分配金額
payment_term	Data	❌	付款條件

---

Journal Entry（日記帳）

Header 核心欄位

欄位	類型	必填	說明
voucher_type	Select	✅	分录類型
naming_series	Select	✅	編號系列
posting_date	Date	✅	入帳日期
company	Link → Company	✅	公司
cheque_no	Data	❌	支票號碼
cheque_date	Date	❌	支票日期
total_debit	Currency	✅	總借方
total_credit	Currency	✅	總貸方
difference	Currency	✅	差額
user_remark	Small Text	❌	使用者備註
multi_currency	Check	❌	是否多幣別
clearance_date	Date	❌	清償日期
is_opening	Select	❌	是否為期初
amended_from	Link → Journal Entry	❌	來源修改

Journal Entry Account（分录子表）核心欄位

欄位	類型	必填	說明
account	Link → Account	✅	會計科目
account_currency	Link → Currency	✅	科目幣別
exchange_rate	Float	✅	匯率
debit_in_account_currency	Currency	❌	科目幣別借方
credit_in_account_currency	Currency	❌	科目幣別貸方
debit	Currency	❌	公司幣借方
credit	Currency	❌	公司幣貸方
cost_center	Link → Cost Center	❌	成本中心
is_advance	Select	❌	是否為預付款
party_type	Link → DocType	❌	對象類型
party	Dynamic Link	❌	對象
project	Link → Project	❌	專案
reference_type	Link → DocType	❌	參考文件類型
reference_name	Data	❌	參考文件編號

---

Payment Ledger Entry（付款分類帳）

Payment Ledger Entry 追蹤 AR/AP 的餘額變化，由 ERPNext 自動生成。

欄位	類型	說明
posting_date	Date	入帳日期
account_type	Select	科目類型
account	Link → Account	會計科目
party_type	Link → DocType	對象類型
party	Dynamic Link	對象
voucher_type	Link → DocType	來源文件類型
voucher_no	Dynamic Link	來源文件編號
against_voucher_type	Link → DocType	對應憑證類型
against_voucher_no	Dynamic Link	對應憑證編號
amount	Currency	金額
account_currency	Link → Currency	科目幣別
amount_in_account_currency	Currency	科目幣別金額
delinked	Check	是否已解綁
company	Link → Company	公司
cost_center	Link → Cost Center	成本中心
project	Link → Project	專案
due_date	Date	到期日
finance_book	Link → Finance Book	財務簿
remarks	Text	備註
voucher_detail_no	Data	明細編號

---

會計數據導入的 4 種方式

方式 A: API 創建交易文件（推薦 ⭐）

直接創建 sales_invoice、purchase_invoice、payment_entry 或 journal_entry。 ERPNext 的 controller 會自動生成 GL Entry。

優點:

• 自動化程度高
• 觸發完整業務邏輯（庫存、AR/AP、稅務）
• 可追溯來源文件

缺點:

• 需要遵循 ERPNext 的表單結構
• 外幣交易需要處理匯率

API 示例:

# 創建 Sales Invoice
curl -X POST \
  -H "Authorization: token <api_key>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "Customer Name",
    "posting_date": "2026-04-18",
    "company": "Company Name",
    "items": [
      {
        "item_code": "Item Code",
        "qty": 1,
        "rate": 100,
        "income_account": "Revenue - Company",
        "cost_center": "Main - Company"
      }
    ],
    "taxes": [...]
  }' \
  https://<your-erpnext-host>/api/resource/Sales%20Invoice

# 提交（Submit）
curl -X POST \
  -H "Authorization: token <api_key>:<secret>" \
  https://<your-erpnext-host>/api/method/frappe.desk.form.submit/submit?doclist=%5B%22INV-00001%22%5D

---

方式 B: API 直接創建 Journal Entry（最靈活）

手動建立日記帳分录，適合批次導入。

優點:

• 完全控制借貸分录
• 適合複雜的會計調整
• 不受業務流程限制

缺點:

• 不會自動更新 AR/AP
• 不會觸發庫存變動
• 需要手動處理 Payment Ledger Entry

API 示例:

curl -X POST \
  -H "Authorization: token <api_key>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Company Name",
    "posting_date": "2026-04-18",
    "accounts": [
      {
        "account": "Revenue - Company",
        "credit_in_account_currency": 1000,
        "debit_in_account_currency": 0,
        "cost_center": "Main - Company"
      },
      {
        "account": "Cash - Company",
        "debit_in_account_currency": 1000,
        "credit_in_account_currency": 0,
        "cost_center": "Main - Company"
      }
    ]
  }' \
  https://<your-erpnext-host>/api/resource/Journal%20Entry

---

方式 C: Data Import（內建工具）

ERPNext 內建 Data Import 功能，支援 CSV/JSON 批量導入。

優點:

• 無需寫程式碼
• 支援映射模板
• 適合歷史數據導入

缺點:

• 無法自訂業務邏輯
• 外幣交易處理較複雜
• 錯誤處理較弱

---

方式 D: 自訂 API Endpoint

在 hooks.py 註冊自訂 API，處理特定業務邏輯。

優點:

• 完全控制業務邏輯
• 可處理複雜轉換
• 可與外部系統整合

缺點:

• 需要維護自訂程式碼
• 更新 ERPNext 版本時可能衝突

---

基礎資料依賴

在導入會計數據前，以下 Doctype 必須先存在：

基礎資料	Doctype	用途
公司	company	所有分录的歸屬
會計科目	account	借貸方科目
成本中心	cost_center	成本歸屬
客戶	customer	往來對象
供應商	supplier	往來對象
商品	item	商品/服務
會計年度	fiscal_year	年度設定
幣別	currency	外幣交易
銀行帳戶	bank_account	付款來源
倉庫	warehouse	庫存管理
計量單位	uom	商品單位
稅金模板	taxes_and_charges_template	稅務計算
專案	project	專案管理
財務簿	finance_book	財務簿設定

科目表結構（Chart of Accounts）

ERPNext 的科目表是階層式結構，類似樹狀：

資產 (Asset)
├── 流動資產 (Current Asset)
│   ├── 現金 (Cash)
│   │   ├── 現金 - 公司 (Cash - Company)
│   │   └── 銀行存款 - 公司 (Bank - Company)
│   └── 應收帳款 (Accounts Receivable)
│       └── 應收帳款 - 公司 (Debtors - Company)
└── 固定資產 (Fixed Asset)
    └── 設備 - 公司 (Equipment - Company)

負債 (Liability)
├── 流動負債 (Current Liability)
│   └── 應付帳款 (Accounts Payable)
│       └── 應付帳款 - 公司 (Creditors - Company)
└── 長期負債 (Long Term Liability)

權益 (Equity)
└── 業主權益 (Capital)
    └── 資本 - 公司 (Capital - Company)

收入 (Income)
└── 營業收入 (Operating Income)
    └── 銷售收入 - 公司 (Sales - Company)

支出 (Expense)
└── 營業支出 (Operating Expense)
    └── 商品成本 - 公司 (Cost of Goods Sold - Company)

---

自訂 API 開發架構

目錄結構

/home/tony/erpnext-analysis/
├── erpnext/
│   └── accounts/
│       ├── api/
│       │   ├── __init__.py
│       │   ├── v1/
│       │   │   ├── __init__.py
│       │   │   ├── imports.py        # 導入 API
│       │   │   ├── reconciliation.py # 對帳 API
│       │   │   └── reports.py        # 報表 API
│       │   └── utils.py              # 公用函數
│       ├── doctype/
│       │   ├── gl_entry/
│       │   ├── sales_invoice/
│       │   └── purchase_invoice/
│       ├── general_ledger.py         # 核心 GL 邏輯
│       └── utils.py                  # 公用函數
└── ERPNext_Accounting_Structure.md   # 本文件

hooks.py 註冊自訂 API

# erpnext/hooks.py 中加入

get_api_versions = lambda: [
    {
        "version": "v1",
        "path": "/api/method/accounts.api.v1.*"
    }
]

自訂 API 模組範例

# accounts/api/v1/imports.py
import frappe
from frappe import _
from frappe.utils import nowdate

@frappe.whitelist()
def import_sales_invoice(data):
    """
    批量導入銷售發票
    :param data: JSON 格式的發票數據
    """
    invoices = frappe.parse_json(data)
    results = []
    
    for inv_data in invoices:
        try:
            invoice = frappe.get_doc({
                "doctype": "Sales Invoice",
                "customer": inv_data.get("customer"),
                "posting_date": inv_data.get("posting_date") or nowdate(),
                "company": inv_data.get("company"),
                "items": [
                    {
                        "item_code": item.get("item_code"),
                        "qty": item.get("qty", 1),
                        "rate": item.get("rate"),
                        "income_account": item.get("income_account"),
                        "cost_center": item.get("cost_center")
                    }
                    for item in inv_data.get("items", [])
                ]
            })
            invoice.insert()
            invoice.submit()  # 提交（生成 GL Entry）
            results.append({
                "name": invoice.name,
                "status": "success"
            })
        except Exception as e:
            results.append({
                "customer": inv_data.get("customer"),
                "status": "error",
                "message": str(e)
            })
    
    return {"results": results}

---

關鍵程式邏輯

general_ledger.py 核心函數

函數	行號	說明
make_gl_entries()	L28	創建 GL Entry
process_gl_map()	L189	處理分錄映射
save_entries()	L407	保存分錄
make_entry()	L425	創建單筆分錄
process_debit_credit_difference()	L472	處理借貸差額
make_round_off_gle()	L550	創建四捨五入分錄
make_reverse_gl_entries()	L682	創建反向分錄（取消）
check_freezing_date()	L794	檢查會計凍結日期
validate_against_pcv()	L818	驗證與期間關閉憑證

accounts/utils.py 核心函數

函數	行號	說明
get_fiscal_year()	L63	獲取會計年度
get_balance_on()	L202	獲取科目餘額
get_account_name()	L1321	獲取科目名稱
get_company_default()	L1158	獲取公司預設值
reconcile_against_document()	L509	文件對帳
update_gl_entries_after()	L1652	更新之後的分錄
get_voucherwise_gl_entries()	L1796	獲取憑證相關分錄
get_stock_accounts()	L1853	獲取庫存科目
create_payment_ledger_entry()	L2135	創建付款分類帳
update_voucher_outstanding()	L2158	更新憑證未清金額
run_ledger_health_checks()	L2608	執行分類帳健康檢查

---

下一步建議

目前狀態

你目前沒有運行中的 ERPNext 實例，要開發 API 需要：

1. 部署環境: 建立 Frappe bench（需要 Python 3.10+, PostgreSQL, Redis）
2. 安裝 ERPNext: bench get-app erpnext
3. 建立公司與會計科目: 設定 Chart of Accounts
4. 開發 API: 在自訂 app 或 ERPNext 目錄下寫自訂 API

可選方向

• (A) 繼續靜態分析其他 Doctype 結構（如 Payment Entry 的 reference 機制）
• (B) 規劃 ERPNext bench 部署的步驟和 Docker 設定
• (C) 分析特定場景的導入流程（例如：批量導入發票 → 自動生成 GL Entry）

推薦做法

對於導入會計數據的需求，建議優先考慮：

1. 少量數據 → 使用方式 A（API 創建交易文件）
2. 大量歷史數據 → 使用方式 C（Data Import）
3. 特殊業務邏輯 → 使用方式 D（自訂 API Endpoint）
4. 複雜調整分录 → 使用方式 B（Journal Entry）

---

參考資源

• ERPNext 官方文件: https://docs.erpnext.com/
• GitHub 原始碼: https://github.com/frappe/erpnext
• Frappe 框架文件: https://frappeframework.com/docs

---

Generated by Nexus | 2026-04-18