accounting-engine

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Accounting Engine

会计引擎

Use When

适用场景

The product handles money, inventory value, payroll, tax, customer balances, supplier balances, assets, grants, donations, loans, refunds, wallet balances, or financial reporting.
A SaaS must replace routine bookkeeping in external products such as QuickBooks, Xero, Sage, Pastel, Tally, Zoho Books, or Wave.
You need architecture, schema, posting rules, tests, documentation, or review findings for ledger-backed business software.

产品涉及资金、库存价值、薪资、税务、客户余额、供应商余额、资产、拨款、捐赠、贷款、退款、钱包余额或财务报告。
SaaS产品需要替代QuickBooks、Xero、Sage、Pastel、Tally、Zoho Books或Wave等外部产品中的日常簿记工作。
你需要基于分类账的业务软件的架构、schema、过账规则、测试、文档或评审结果。

Do Not Use When

不适用场景

The task is only financial analysis or projections without software architecture; use
```
accounting-finance-controller
```
or the business-plan finance skills.
The system only displays imported accounting reports and does not create business events or postings.
A jurisdiction requires a licensed accountant, auditor, or tax practitioner to exercise professional judgement; design the system support, but do not claim the software replaces that judgement.

任务仅为财务分析或预测，不涉及软件架构；请使用
```
accounting-finance-controller
```
或商业计划财务相关技能。
系统仅展示导入的会计报表，不生成业务事件或过账记录。
司法管辖区要求持牌会计师、审计师或税务从业者行使专业判断；设计系统提供支持，但不得声称软件可替代该判断。

Hard Rules

硬性规则

NEVER let a business module write directly to
```
gl_entries
```
,
```
journal_lines
```
,
```
journal_entries
```
, or any ledger table.
ALWAYS write ledger records through one service:
```
LedgerPostingService::post(JournalEntry $entry)
```
or the project-equivalent single posting service.
NEVER update, delete, or soft-delete posted journal lines. Corrections are reversing journals linked to the original entry.
NEVER store authoritative balances that cannot be rebuilt from journal lines. Materialized balances are caches with a documented rebuild command.
NEVER hardcode account codes in business logic. Use account mappings resolved at posting time.
NEVER use LIFO for IFRS or IFRS for SMEs tenants.
MUST reject posting when required account mappings are missing, inactive, cross-tenant, or not valid for the source document.

绝对禁止业务模块直接写入
```
gl_entries
```
、
```
journal_lines
```
、
```
journal_entries
```
或任何分类账表。
必须通过单一服务写入分类账记录：
```
LedgerPostingService::post(JournalEntry $entry)
```
或项目等效的单一过账服务。
绝对禁止更新、删除或软删除已过账的日记账分录。更正需通过关联原分录的冲销日记账完成。
绝对禁止存储无法从日记账分录重建的权威余额。物化余额为缓存，并需附带可重建的文档化命令。
绝对禁止在业务逻辑中硬编码科目代码。使用过账时解析的科目映射。
对于采用IFRS或IFRS for SMEs的租户，绝对禁止使用LIFO（后进先出）法。
当所需科目映射缺失、失效、跨租户或对源文档无效时，必须拒绝过账。

Canonical Architecture

标准架构

Business modules emit events. A mapper turns events into balanced

JournalEntry

value objects. The posting service validates and writes the entry atomically. Reports, subledgers, balances, tax schedules, and dashboards are deterministic projections of the ledger.

text

Sales / Stock / Payroll / Assets / Payments / Grants
        -> business event
        -> account resolver and posting-rule mapper
        -> JournalEntry value object
        -> LedgerPostingService::post()
        -> append-only journal_entries + journal_lines
        -> reports, subledgers, tax schedules, dashboards

业务模块触发事件。映射器将事件转换为平衡的

JournalEntry

值对象。过账服务原子性地验证并写入该分录。报表、子分类账、余额、税表和仪表盘均为分类账的确定性投影。

text

Sales / Stock / Payroll / Assets / Payments / Grants
        -> business event
        -> account resolver and posting-rule mapper
        -> JournalEntry value object
        -> LedgerPostingService::post()
        -> append-only journal_entries + journal_lines
        -> reports, subledgers, tax schedules, dashboards

Required Model

必备模型

Core tables:

```
chart_of_accounts
```
```
account_mappings
```
```
journal_entries
```
```
journal_lines
```
```
accounting_periods
```
```
posting_rule_versions
```
```
accounting_integrity_runs
```
```
accounting_audit_log
```

Every accounting table MUST carry

tenant_id

, unless the product is explicitly single-tenant. If legacy files use

franchise_id

, treat it as a project-specific tenant alias and document the mapping.

核心表：

```
chart_of_accounts
```
```
account_mappings
```
```
journal_entries
```
```
journal_lines
```
```
accounting_periods
```
```
posting_rule_versions
```
```
accounting_integrity_runs
```
```
accounting_audit_log
```

除非产品明确为单租户，否则所有会计表必须包含

tenant_id

。如果遗留文件使用

franchise_id

，需将其视为项目特定的租户别名，并记录映射关系。

Posting Service Contract

过账服务契约

php

<?php
declare(strict_types=1);

final readonly class JournalEntry
{
    public function __construct(
        public int $tenantId,
        public string $idempotencyKey,
        public DateTimeImmutable $entryDate,
        public string $sourceType,
        public string $sourceId,
        public string $description,
        /** @var list<JournalLine> */
        public array $lines,
        public ?int $reversesJournalId = null,
    ) {}
}

final readonly class JournalLine
{
    public function __construct(
        public int $accountId,
        public string $currency,
        public string $debitMinor,
        public string $creditMinor,
        public array $dimensions = [],
    ) {}
}

interface LedgerPostingService
{
    public function post(JournalEntry $entry): PostedJournal;
}

The service validates tenant scope, account status, open period, debit-credit equality, currency policy, idempotency, source document state, and mapping completeness before insert.

php

<?php
declare(strict_types=1);

final readonly class JournalEntry
{
    public function __construct(
        public int $tenantId,
        public string $idempotencyKey,
        public DateTimeImmutable $entryDate,
        public string $sourceType,
        public string $sourceId,
        public string $description,
        /** @var list<JournalLine> */
        public array $lines,
        public ?int $reversesJournalId = null,
    ) {}
}

final readonly class JournalLine
{
    public function __construct(
        public int $accountId,
        public string $currency,
        public string $debitMinor,
        public string $creditMinor,
        public array $dimensions = [],
    ) {}
}

interface LedgerPostingService
{
    public function post(JournalEntry $entry): PostedJournal;
}

该服务在插入前会验证租户范围、科目状态、期间是否开放、借贷相等性、货币政策、幂等性、源文档状态及映射完整性。

Integrity Checks

完整性检查

Run these per tenant and per accounting period from day one:

Debits equal credits per
```
journal_entry_id
```
.
Trial balance total debits equal total credits.
AR control account equals customer-tagged journal line balance.
AP control account equals supplier-tagged journal line balance.
Inventory control account equals stock-on-hand value by item/location/cost layer.
Fixed asset control account equals asset-register cost less disposals.
Payroll liability accounts equal unpaid statutory and employee deductions.
No journal exists in a locked period unless it is a permitted reopening workflow with approval evidence.
No ledger table has rows written outside the posting service.
Materialized balances rebuild to the same values as stored cache rows.

从项目启动第一天起，需按租户和会计周期运行以下检查：

每个
```
journal_entry_id
```
对应的借方等于贷方。
试算表总借方等于总贷方。
应收账款控制科目等于带客户标记的日记账分录余额。
应付账款控制科目等于带供应商标记的日记账分录余额。
库存控制科目等于按商品/位置/成本层计算的在手库存价值。
固定资产控制科目等于资产登记成本减去处置额。
薪资负债科目等于未支付的法定及员工扣款。
锁定期间内不得存在日记账，除非是经批准的重新开启流程并附有审批凭证。
所有分类账表的记录均需通过过账服务写入，不得直接写入。
物化余额重建后的值需与存储的缓存记录一致。

User Experience Principle

用户体验原则

Non-accountants record business actions:

Record Sale

Receive Payment

Buy Stock

Run Payroll

Record Asset Purchase

Receive Grant

Close Month

. The system posts accounting behind the scenes. Accountant-facing roles get journals, CoA, mappings, period close, manual journal, and report exports.

非会计人员记录业务操作：

记录销售

、

接收付款

、

采购库存

、

运行薪资

、

记录资产采购

、

接收拨款

、

月结

。系统在后台自动完成会计过账。面向会计人员的角色可查看日记账、CoA（科目表）、映射、期间结账、手动日记账及报表导出。

Companion Skills

配套技能

```
chart-of-accounts-templates
```
for IFRS-aligned industry templates.
```
inventory-costing
```
for IAS 2 stock valuation and COGS flows.
```
payroll-postings-uganda
```
for PAYE/NSSF/LST payroll journal shapes.
```
fixed-assets-and-depreciation
```
for IAS 16 asset lifecycle.
```
multicurrency-and-fx
```
for IAS 21 currency handling.

multi-tenant-saas-architecture

api-design-first

, and

advanced-testing-strategy

for platform integration.

```
chart-of-accounts-templates
```
：IFRS合规的行业模板。
```
inventory-costing
```
：IAS 2库存估值及销货成本流程。
```
payroll-postings-uganda
```
：PAYE/NSSF/LST薪资日记账格式。
```
fixed-assets-and-depreciation
```
：IAS 16资产生命周期管理。
```
multicurrency-and-fx
```
：IAS 21货币处理。

multi-tenant-saas-architecture

、

api-design-first

和

advanced-testing-strategy

：平台集成相关。

References

参考资料

```
references/posting-engine-contract.md
```
```
references/integrity-invariants.md
```

```
references/posting-engine-contract.md
```
```
references/integrity-invariants.md
```