02 · Accounting — chart of accounts, periods, and general ledger

Layer Base(1). Depends on Common (currency, rate) and Organization (legal entity). Accounting owns the scalar EDT Money — most workspace models depend on Accounting only for that EDT, not for posting (see Links with other modules).

← General specification

Purpose#

Chart of accounts, fiscal calendar, manual posting (JournalEntry), and the general ledger (GL). Accounting does not post other documents by itself — every business document writes its own ledger legs into GL, the way a 1C document writes its own accounting-register records. Accounting provides the mechanics of a leg (IGeneralLedgerService.EntryAsync / PostForDocumentAsync: accounts by code, period by date, the three books); the document's owner model decides what and to which accounts. The full map is in Who writes the general ledger.

What is created (object map)#

Total: 4 dictionaries, 1 document, 1 table part, 1 register, 1 report view, 3 services, 1 job, 1 command, 2 analytics, 1 enum, 8 EDTs, 5 number sequences, and 7 integration tests.

Not documented as functionality: the OpsConsoleDemo form (a standard platform demo screen with charts; the data is PurchaseOrder/Country and it is not related to accounting) and the SalesRealization.Accounting extension (an orphaned descriptor without a handler). Both live in the model folder, but neither carries behaviour.

model.json#

Layer Base(1), version 2.0.0. Dependencies: Common (minVersion 1.10.0), Organization (minVersion 1.0.0). Nothing else — Accounting does not depend on Tax or on any application model.

Number sequences#

AccountingSettingsSeq, ChartOfAccountsSeq (starts at 1000), FiscalPeriodSeq (starts at 1000), FiscalYearSeq (starts at 1000), JournalEntrySeq (starts at 1000).

EDT#

Scalar EDTs: Money Decimal(18,2) — owned here; most models depend on Accounting only for it; Percent Decimal(9,4). Reference EDTs: RefAccount, RefChartOfAccounts, RefFiscalYear, RefFiscalPeriod, ChartOfAccountsParentRef (the same reference, but for the system ParentId of the hierarchy). Enumerable EDT: AccountTypeEdt (a wrapper over AccountType).

Dictionaries#

ChartOfAccounts#

Hierarchical (isHierarchical: true). ID (system), Code (String 32, required, unique), Name (String 160, required), AccountType (AccountTypeEdt → enum AccountType, required — a closed set of five values, not a free string), IsPostable (Boolean, optional), Currency (RefCurrency, optional — a currency account), ParentId (system, ChartOfAccountsParentRef).

ChartOfAccountsEventHandler.OnBeforeSaveAsync: a node with at least one child (query ParentId = '{MetaId}') cannot have IsPostable=true — Счёт «Name» — группа (N подчинённых): проводки принимают только конечные счета. The old separate check of allowed AccountType values is no longer needed — the enum type itself now enforces it.

Referenced by: analytic GL-Account (this register); RefAccount on JournalEntryLines.Account; all 16 fields of AccountingSettings (below); GeneralLedgerService.ResolveAccountAsync/AccountCodeProblemAsync.

FiscalYear / FiscalPeriod#

FiscalYear: Code (String 16, required, unique), StartDate/EndDate (required), IsClosed (Boolean). The handler is a pure template; every override only calls next(...).

A year is never closed by code. Neither year closing nor rolling Income/Expense to retained earnings is implemented in the workspace — IsClosed exists as a field, but no service reads or sets it. Do not plan year closing as ready functionality.

FiscalPeriod: ID, Code (String 16, required, not unique — the natural key is the date range, not the code), FiscalYear (RefFiscalYear, required), FromDate/ToDate (required), Status (plain string String 16, required).

On every save the handler checks: FromDate ≤ ToDate; the period range does not overlap any sibling (scanned regardless of Status); "close only in order" is checked only when leaving Open (an already closed period can be saved again without rechecking the order). Status = "Open" is compared case-insensitively; any other value, including a typo or a non-existent status, is silently read as "closed" — this is an intentional fail-safe in code ("unknown means closed, not open"), not a separate third Locked state. No such state exists in the implementation.

Referenced by: analytic GL-FiscalPeriod; JournalEntry.FiscalPeriod; FiscalPeriodService.ClosedReasonAsync (platform IFiscalCalendar).

AccountingSettings#

Singleton (isSingleton, isCached) — one record per tenant, and this is the centre of gravity of all posting: not a global constant, but a dictionary with 18 pairs of fields <Account>Account (Ref, RefChartOfAccounts, for UI) + <Account>AccountCode (String, hidden on the form — the actual runtime posting key), grouped on the form by subledger:

Plus AutoPostJournal (Boolean) and DefaultCurrency/DefaultCurrencyCode.

AccountingSettingsEventHandler: OnBeforeSaveAsync stamps all *Code values from the corresponding *Account references and stamps the currency, then for each non-empty code calls GeneralLedgerService.AccountCodeProblemAsync(code) — it rejects only a code that exists but is not IsPostable (a group). An empty code, or a code that does not resolve at all, is the valid state "not set up yet". OnAfterLoadAsync resolves DefaultCurrency back from DefaultCurrencyCode if the reference is empty — the same one-way pattern as CommonSettings.DefaultCurrency (Common).

There is no GlobalConstants account group here. There is no Accounting group with keys RetainedEarnings, RoundingAccount, OutputTaxAccount, InputTaxAccount, ArAccount, ApAccount, FxGainLoss. The source of posting accounts is this record, AccountingSettings, read through GeneralLedgerService.GetSettingsAsync().

Referenced by: every ledger leg of a business document (see Who writes the general ledger) — through IGeneralLedgerService.GetSettingsAsync(), not directly by field.

Documents#

JournalEntry#

Header: Circuits (String 32, optional, hidden — FIN,MGT,TAX..., empty means FIN,MGT; parsed line-by-line in GLPostingTx), Currency (RefCurrency, required), Description (String 256, optional), FiscalPeriod (RefFiscalPeriod, required), LegalEntity (RefLegalEntity, required), ExchangeRate (Decimal 18.8, optional — factor from the document currency to the legal entity functional currency, stamped on save). Subtypes: Draft → Posted (postOnSave: true, requiresPosting: true). Table part: Lines (JournalEntryLines).

JournalEntryEventHandler:

• OnBeforeCreateAsync: fills Currency/LegalEntity from IRecordDefaults.SeedAsync (Common).
• OnBeforeSaveAsync: stamps ExchangeRate on every save, not only on creation — because GLPostingTx is synchronous and cannot fetch the rate by itself. The private helper reads the legal entity functional currency and calls ICurrencyRateService.FactorAsync (Common): matching currencies or empty legal entity → 1; no rate window on the date → 0 (a signal value, not "the rate is irrelevant").
• OnBeforePostAsync: lines are not empty; no line carries both Debit and Credit; ΣDebit == ΣCredit; the period is not closed (IFiscalPeriodService.ClosedReasonAsync); ExchangeRate > 0 (otherwise it rejects with the date — this is exactly the signal 0 caught here).
• OnBeforeUnpostAsync: the same repeated "period is not closed" control.

JournalEntryLines (table part)#

Account (RefAccount → ChartOfAccounts, required), Debit/Credit (Money, optional), Description (String 256, optional). The handler is an empty template (fully commented out).

PostJournalEntry (command, only on Draft)#

Duplicates the document-handler checks to provide more precise UI messages: lines are not empty; the period is not closed (ClosedReasonAsync and a separate ResolvePeriodAsync existence check); no line carries both directions; AccountCodeProblemAsync for every line account; ΣDebit == ΣCredit — then sets Subtype = Posted and saves.

GLPostingTx — what is actually written on posting#

For each line there is one GL movement (not a pair), built by IGeneralLedgerService.Movement — the same layout the business documents' legs use: analytics Account/LegalEntity/FiscalPeriod, resources Debit/Credit (always, multiplied by fx), plus ManagementDebit/ManagementCredit (if the MGT circuit is active) and TaxDebit/TaxCredit (if TAX is explicitly specified). All six resources are always set, zeros included. fx = ExchangeRate ≤ 0 ? 1 : ExchangeRate — a safety floor that is unreachable in practice: OnBeforePostAsync would already reject a posting with ExchangeRate ≤ 0.

The ledger balance is guaranteed not by the register, but by the preceding document check (ΣDebit = ΣCredit) — movements in GL are one per line, and the register does not pair them (see GL about isDoubleEntry).

Circuits (Circuits): FIN is implicit and always active (resources Debit/Credit are written unconditionally); MGT is enabled by default if the field is empty; TAX only explicitly.

Example 1 — balanced posting entry#

Currency EUR, legal entity ACME GmbH, period 2026-08 (2026-08-01…2026-08-31, Open), accounts: Cash (1000, Asset, postable), Revenue (4000, Income, postable). Lines: Dr Cash 100 / Cr Revenue 100.

An unbalanced posting entry (Dr 100 / Cr 60) is saved as Draft with no check — the refusal comes only when trying to move to Posted.

Example 2 — rate and missing rate#

Rates on the date: EUR → base 45, USD → base 41 (the base is implicit, "the one whose rate is 1"; see Common · ExchangeRate).

Example 3 — boundary refusals#

Overlapping FiscalPeriod windows are rejected on save; adjacent non-overlapping windows are accepted. Closing periods out of order (closing 2026-09 while 2026-08 is open) is rejected with an "earlier" message; strict chronological order is accepted, and an already closed period can be saved again without rechecking the order. GeneralLedgerService.EntryAsync into a closed period silently returns no leg (no exception — a ledger leg is best-effort; the platform itself refuses to post a document into a closed period); in an open period it returns the pair. A leg to a non-postable (group) account is not built; to a postable leaf it is. Saving AccountingSettings with a group-account code in any of the 16 fields is rejected through AccountCodeProblemAsync.

Example 4 — account reference and code as a pair#

Setting ArAccount (reference) automatically stamps ArAccountCode (string) on save. A bare string code without a set reference also saves successfully — the reference is UI convenience, and the code is the only runtime-authoritative key. Selecting a non-postable account is rejected the same way through the reference and through the bare code — validation is symmetrical regardless of input path.

Registers#

GL#

registerEngineType: Standard, isDoubleEntry: false (single movements, not pairs — the document guarantees balance, not the register), allowNegativeBalance: true, useBalanceTable: true.

Resources: Debit, Credit, ManagementDebit, ManagementCredit, TaxDebit, TaxCredit (all Money).

Analytics (all isRequired: true): GL-Account (owned here, on ChartOfAccounts), GL-FiscalPeriod (owned here, on FiscalPeriod), GL-LegalEntity — declared not here, but in Organization · Analytics, and reused by this register without a separate dependency declared in model.json (the dependency on Organization is already declared for the LegalEntity dictionary). The same analytic slices TaxLedger in Tax — a shared platform dimension, not Accounting-private.

GlByLegalEntityAccount#

Report view over GL: grouping by LegalEntity and Account, columns Opening/Income/Outcome/Closing for Debit and for Credit.

Services#

GeneralLedgerService (IGeneralLedgerService)#

Best-effort. No profile, an empty or unknown code, a group account, no period on the date, a closed period, a non-positive amount — no leg, no exception: incomplete account setup must not bring down document posting.

Two doors, one layout. A leg whose amount is known before posting (revenue, payments, payroll, VAT) is built in the document's transaction script with EntryAsync: it joins the posting chain, is compared on re-save and is reversed with the document. A leg whose amount is a fact of the posting itself — cost the CostingIssue driver takes off FIFO/AVG layers — cannot be known in the synchronous GetTransactions, which runs before the drivers. Such a leg is written from the document's OnAfterPost with PostForDocumentAsync, still as the document's own movement, so the platform reverses it on unpost like any other. The after-post event can run twice in one posting; the legKey (stored as the movement's ScriptMetaId) keeps the second run from writing the leg again.

There is no PostAsync (or any method) that creates a JournalEntry for a business document. Business documents write their own GL legs; a separate journal would outlive the source document's unpost and stay in the book.

AutoJournalMigrationService (IAutoJournalMigrationService)#

DetachAsync(apply) — for tenants that still have automatic journals from before ledger legs moved into the models that own the documents. A posted JournalEntry whose description starts with one of the old automatic prefixes (Sales invoice <id>, Cost of sales <id>, Vendor payment <id>, …) and that has the source → journal link hands its GL movements to the source document (same accounts, amounts, books and date) and is deleted. The ledger does not change by a cent; from then on unposting the source document takes its leg back. Journals in a closed period are left alone. The DetachAutoJournals job runs it nightly; with nothing left, a run does nothing.

FiscalPeriodService (IFiscalCalendar)#

ClosedReasonAsync(date): no period covers the date → null (this is not a refusal — operationally, the period is "open by default" and posting goes through). A period is found but its Status is not Open → a message with the period code and dates. More than one period covers one date → InvalidOperationException (master data is considered damaged and cannot be resolved automatically).

Business logic and invariants#

Posting entries only use leaf accounts. A node with children cannot be IsPostable — the check is at ChartOfAccounts level, not at JournalEntry level.

The year is not closed. FiscalYear.IsClosed is a field without behaviour; there is no code that rolls income/expenses to retained earnings.

FiscalPeriod.Status has two states, not three. Only "Open" (case-insensitive) is read as open; any other value, known or unknown, is closed. There is no separate handling for "Locked" to plan against — that state does not exist.

The posting rate is stamped on every save, not only on creation — this is the only point where synchronous GLPostingTx can receive a ready number computed by asynchronous CurrencyRateService.

A document owns its ledger legs. Every GL movement belongs to the document that produced it — a business document or a manual JournalEntry — and is reversed with it on unpost, subtype change or re-post. There is no separate journal per business operation. The ledger balance of a business leg is guaranteed by construction (EntryAsync always returns a Dr/Cr pair of the same amount); of a manual journal — by its OnBeforePostAsync check.

Who writes the general ledger#

Each leg lives in the model that owns the document; the accounts are codes from AccountingSettings. "Tx" — a transaction script of the document; "after post" — OnAfterPost through PostForDocumentAsync (the amount is the cost fact in ItemCostFifo of Costing).

The legal entity of a leg: the document header (SalesRealization, CustomerPayment, VendorPayment, TaxCalculation, TaxPayment), the cell's chain Cell → Zone → Store → Division → LegalEntity (IStoreCellService: receipts, returns, stock documents, production), or Division → LegalEntity (HR). The date is the document date (StockCount — CountDate): it picks the fiscal period.

Amounts are in the legal entity's currency. A sales document under a contract in another currency, or a purchase document from a supplier whose card names another currency, stamps ExchangeRate (that currency to the entity's, on its date), and its legs are line amounts × that rate. A JournalEntry converts the same way through its own ExchangeRate.

Production on Finished posts no material leg. Moving Released → Finished reverses all the order's movements, the WIP leg included. Materials out and the product in are value-neutral on the one inventory account (raw materials and finished goods share it), so only labour — which makes the output layer dearer than the materials — goes to the books.

A mixed stock adjustment posts both legs in full. The shortage is the issued cost, the surplus the cost of the new lot; one is not netted against the other.

Example — a sale and its cancellation#

Inventory 10 × 7 received (Dr Inventory 70 / Cr Payable 70 — the receipt's own movements). Invoice: 4 × 20, issued.

Unposting the invoice reverses its own GL movements. There is no leftover journal that would keep the 80 / 80 / 28 / 28 in the book.

Menu#

The Accounting group → Dictionaries (AccountingSettings, ChartOfAccounts, FiscalYear, FiscalPeriod) · Documents (JournalEntry) · Registers (GL) · Settings (AccountingSettings).

Links with other modules#

• Outgoing: Common — currency, ExchangeRate, rate; Organization — LegalEntity and analytic GL-LegalEntity (declared there, reused here).
• Incoming: Sales, Purchasing, HR, Tax, Costing and Production write their own ledger legs through IGeneralLedgerService (see Who writes the general ledger); Inventory depends on Accounting only for the EDT Money. Accounting knows none of them.

Objects#

Generated from workspace metadata by node tools/gen-reference.mjs; edit the metadata, not this block.

Dictionaries#

AccountingSettings — Accounting settings

Singleton posting profile: pick ChartOfAccounts leaves; string *AccountCode fields are the posting key and are stamped from the refs on save.

Bank — Banks

A bank directory entry. Banks can be arranged in a hierarchy and referenced by bank accounts.

BankAccount — Bank accounts

A current account of a legal entity at a bank: one currency, optionally its own ledger account. Payments and transfers through it move its BankBalance.

CashDesk — Cash desks

A cash desk (till): one currency, optionally its own ledger cash account. Spending from a desk lowers its CashBalance.

ChartOfAccounts — Chart of accounts

Hierarchical chart of accounts; postings hit leaf postable accounts

CostArticle — Cost articles

What an expense is spent on. The expense account is set on an article or inherited from its group.

FiscalPeriod — Fiscal periods

Posting periods within a fiscal year; Open/Closed/Locked control postings

FiscalYear — Fiscal years

Accounting years; closing rolls income/expense into retained earnings

Documents#

CashExpense — Cash expense

Money paid out of a cash desk on cost articles. Posting lowers the desk balance and debits each article expense account against the desk cash account.

Header fields:

Subtypes:

Commands:

CashIncome — Other income

Money received into a cash desk or a bank account that settles no customer debt: other income, refunds, found cash. Posting raises the desk or account balance and debits its ledger account against the income account of the document.

Header fields:

Subtypes:

Commands:

JournalEntry — Journal entry

Header fields:

Subtypes:

Commands:

MoneyTransfer — Money transfer

Moves money between the company's own cash desks and bank accounts: cash paid into the bank, cash taken from the bank, a transfer between two bank accounts. Posting lowers the source balance, raises the target one and debits the target ledger account against the source one.

Header fields:

Subtypes:

Commands:

Registers#

BankBalance — Bank balance

Money on each bank account, in the account currency. Payments and transfers through the account move it.

Dimensions:

Resources:

CashBalance — Cash balance

Cash held in each desk, in the desk currency. Expense documents lower it.

Dimensions:

Resources:

GL — General ledger

Double-entry general ledger; every posted journal entry balances (ΣDebit = ΣCredit, enforced on the document)

Resources:

Analytics:

Table parts#

CashExpenseLines — Lines

Used by: CashExpense.

JournalEntryLines — Lines

Used by: JournalEntry.