Accounting Basics (BAS)

The bas submodule of acc owns the cross-cutting accounting reference data used by every other accounting submodule: the finance company a company is registered as, the financial year/period structure that gates posting, currency contracts and their per-day buying/selling rates, interest contracts and their per-day rates, and the finance-item-group that pins ledger accounts to a product item group. It depends on com.org for the underlying company, on sys.loc for currencies, and on acc.gld and acc.jrn for the ledger accounts and journals it points at.

Concepts

Finance Company: The accounting projection of a Company. Carries the contracts and the default journals used by document posting.
Financial Year: A named accounting year. Owns a fixed set of FinancialPeriod rows and tracks an aggregate biClosed flag.
Financial Period: A posting interval within a year. Once closed, no new postings are accepted for dates inside the period.
Currency Contract: A grouping of currency-conversion definitions concluded with a particular bank, all sharing the same internal currency.
Currency Conversion: A pair of currencies (internal + external) under a CurrencyContract with optional default buying/selling margins.
Currency Conversion Rate: A dated middle/buying/selling rate for one CurrencyConversion. Buying and selling rates are stored explicitly so they can deviate from the middle rate by their margin.
Currency Rate Type: Whether the conversion is for a buying scenario (purchase process) or a selling scenario (sales process). Decides which side of the conversion’s rate is used.
Interest Contract: A grouping of interest-rate definitions agreed with a particular bank.
Interest Contract Rate: A dated interest rate within an InterestContract.
Finance Item Group: The accounting projection of a product ItemGroup. Pins the ledger accounts used when the group’s items hit inventory, cost-of-goods-sold, accounts-payable/receivable, currency differences, and so on.

Entities

Finance Company (`FinanceCompany`)

The accounting projection of a Company.

Field Description

Field	Description
`company`	Owning `Company` (one-to-one, final field).
`currencyContract`	The currency contract used to convert foreign-currency amounts.
`interestContract`	The interest contract used to compute interest amounts.
`defaultBankJournal`	Default bank journal used for postings.
`defaultCashJournal`	Default cash journal.
`defaultPurchaseJournal`	Default purchase journal.
`defaultSalesJournal`	Default sales journal.
`defaultPaymentJournal`	Default payment journal.
`defaultGeneralJournal`	Default general journal.
`defaultTaxJournal`	Default tax journal.

company

Owning Company (one-to-one, final field).

currencyContract

The currency contract used to convert foreign-currency amounts.

interestContract

The interest contract used to compute interest amounts.

defaultBankJournal

Default bank journal used for postings.

defaultCashJournal

Default cash journal.

defaultPurchaseJournal

Default purchase journal.

defaultSalesJournal

Default sales journal.

defaultPaymentJournal

Default payment journal.

defaultGeneralJournal

Default general journal.

defaultTaxJournal

Default tax journal.

A validation rule enforces that the company’s internal currency matches the currency-contract’s internal currency.

Financial Year (`FinancialYear`)

A named accounting year.

Field Description

Field	Description
`periodYear`	Business key — the year identifier.
`financialPeriods`	The contained `FinancialPeriod` rows.
`biClosed`	Aggregate flag derived from the periods. Once closed, no postings are accepted.

periodYear

Business key — the year identifier.

financialPeriods

The contained FinancialPeriod rows.

biClosed

Aggregate flag derived from the periods. Once closed, no postings are accepted.

Financial Period (`FinancialPeriod`)

A posting interval within a year.

Field Description

Field	Description
`financialYear`	Owning year (composite business key with `periodNumber`).
`periodNumber`	Period sequence within the year.
`firstDate`	Inclusive first posting date.
`lastDate`	Inclusive last posting date.
`closed`	Whether the period is closed for posting.

financialYear

Owning year (composite business key with periodNumber).

periodNumber

Period sequence within the year.

firstDate

Inclusive first posting date.

lastDate

Inclusive last posting date.

closed

Whether the period is closed for posting.

Currency Contract (`CurrencyContract`)

A grouping of currency conversions concluded with a particular bank.

Field Description

Field	Description
`code`	Business key (a `ContractCode`).
`description`	Human-readable name.
`currencyInt`	Internal currency for every conversion under this contract.
`bank`	The bank the contract is concluded with.

code

Business key (a ContractCode).

description

Human-readable name.

currencyInt

Internal currency for every conversion under this contract.

bank

The bank the contract is concluded with.

Currency Conversion (`CurrencyConversion`)

A pair of currencies (internal + external) within a contract.

Field Description

Field	Description
`currencyContract`	Owning contract (composite business key with `currencyExt`).
`currencyExt`	The external currency.
`defaultBuyingMargin`	Optional default buying margin (percentage) used as the seed when entering a new rate.
`defaultSellingMargin`	Optional default selling margin.

currencyContract

Owning contract (composite business key with currencyExt).

currencyExt

The external currency.

defaultBuyingMargin

Optional default buying margin (percentage) used as the seed when entering a new rate.

defaultSellingMargin

Optional default selling margin.

Currency Conversion Rate (`CurrencyConversionRate`)

A dated rate snapshot for a conversion.

Field Description

Field	Description
`currencyConversion`	Owning conversion (composite business key with `validFrom`).
`validFrom`	First date the rate is valid.
`rate`	The middle rate.
`buyingMargin`	Optional buying margin in effect on this snapshot.
`buyingRate`	The buying rate (used in purchase scenarios).
`sellingMargin`	Optional selling margin in effect on this snapshot.
`sellingRate`	The selling rate (used in sales scenarios).

currencyConversion

Owning conversion (composite business key with validFrom).

validFrom

First date the rate is valid.

rate

The middle rate.

buyingMargin

Optional buying margin in effect on this snapshot.

buyingRate

The buying rate (used in purchase scenarios).

sellingMargin

Optional selling margin in effect on this snapshot.

sellingRate

The selling rate (used in sales scenarios).

Currency Rate Type (`CurrencyRateType`)

Internal enum used by callers of the conversion service to pick the buying or selling rate.

Value Used by

Value	Used by
`RATE_WHEN_BUYING_CURRENCY`	Purchase processes (`forPurchaseProcess()`).
`RATE_WHEN_SELLING_CURRENCY`	Sales processes (`forSalesProcess()`).

RATE_WHEN_BUYING_CURRENCY

Purchase processes (forPurchaseProcess()).

RATE_WHEN_SELLING_CURRENCY

Sales processes (forSalesProcess()).

Interest Contract (`InterestContract`)

A grouping of interest rates concluded with a bank.

Field Description

Field	Description
`code`	Business key (a `ContractCode`).
`description`	Human-readable name.
`bank`	The bank the contract is concluded with.

code

Business key (a ContractCode).

description

Human-readable name.

bank

The bank the contract is concluded with.

Interest Contract Rate (`InterestContractRate`)

A dated interest-rate snapshot under an interest contract.

Field Description

Field	Description
`interestContract`	Owning contract (composite business key with `validFrom`).
`validFrom`	First date the rate applies.
`rate`	The interest rate.

interestContract

Owning contract (composite business key with validFrom).

validFrom

First date the rate applies.

rate

The interest rate.

Interest Calculation Type (`InterestCalculationType`)

Code Name Meaning

Code	Name	Meaning
`S`	Simple	Simple interest.
`C`	Compound	Compound interest.

S

Simple

Simple interest.

C

Compound

Compound interest.

Finance Item Group (`FinanceItemGroup`)

The accounting projection of a product ItemGroup. Pins the ledger accounts used by every posting that touches items of the group.

Field Description

Field	Description
`itemGroup`	The product item group (one-to-one).
`accountInvoicesToReceive`	Account hit when an invoice is expected but not yet received.
`accountCost`	Cost account.
`accountInventory`	Inventory account.
`accountInventorySuspense`	Inventory suspense account (in-flight inventory adjustments).
`accountWorkOrderResult`	Work order result account.
`accountMaterialCoverage`	Material coverage account.
`accountLabourCoverage`	Labour coverage account.
`accountAccountsReceivable`	Accounts receivable account.
`accountUninvoicedReceivables`	Receivables that have not been invoiced yet.
`accountRevenue`	Revenue account.
`accountDeferredRevenue`	Deferred revenue account.
`accountCostOfGoodsSold`	Cost-of-goods-sold account.
`accountAccountsPayable`	Accounts payable account.
`accountGoodsReceivedNotInvoiced`	Goods received but not yet invoiced.
`accountPrepaidInventory`	Pre-paid inventory account.
`accountCurrencyDifferenceRevenue`	Currency difference (revenue side).
`accountCurrencyDifferenceCost`	Currency difference (cost side).

itemGroup

The product item group (one-to-one).

accountInvoicesToReceive

Account hit when an invoice is expected but not yet received.

accountCost

Cost account.

accountInventory

Inventory account.

accountInventorySuspense

Inventory suspense account (in-flight inventory adjustments).

accountWorkOrderResult

Work order result account.

accountMaterialCoverage

Material coverage account.

accountLabourCoverage

Labour coverage account.

accountAccountsReceivable

Accounts receivable account.

accountUninvoicedReceivables

Receivables that have not been invoiced yet.

accountRevenue

Revenue account.

accountDeferredRevenue

Deferred revenue account.

accountCostOfGoodsSold

Cost-of-goods-sold account.

accountAccountsPayable

Accounts payable account.

accountGoodsReceivedNotInvoiced

Goods received but not yet invoiced.

accountPrepaidInventory

Pre-paid inventory account.

accountCurrencyDifferenceRevenue

Currency difference (revenue side).

accountCurrencyDifferenceCost

Currency difference (cost side).

Functionality

Financial-period gating

FinancialPeriodReaderService.assertFinancialPeriodIsOpen raises a business exception when either the financial year is closed or the named period is closed; postings call this before persisting. getFinancialPeriod(postingDate) returns the (single) period that contains the date — multiple matches are an error. getOpenFinancialPeriod(postingDate) is the same, but additionally fails if the matching period is closed.

Period close / undo

The closePeriod and closePeriodUndo write actions on FinancialPeriod flip the period’s closed flag. FinancialPeriodActionWriter is the action handler that the framework dispatches to.

Currency conversion

CurrencyRateReaderService.convertAmountToCurrency converts an amount from one currency to another using the rate effective on a given RateDate under the supplied CurrencyContract, picking buying or selling rate based on the supplied CurrencyRateType. The service also exposes getCurrencyRate for callers that want the rate without applying it. (Several home-currency convenience methods are stubbed out — listed in the source but not active.)

Public API

`ACC_BAS_QueryApi`

Read-side facade.

Method Description

Method	Description
`assertFinancialPeriodIsOpen(PeriodYear, PeriodNumber)`	Raises if the year or period is closed.
`getOpenFinancialPeriod(PostingDate)`	The period containing the date; raises if closed.
`getFinancialPeriod(PostingDate)`	The period containing the date (open or closed).

assertFinancialPeriodIsOpen(PeriodYear, PeriodNumber)

Raises if the year or period is closed.

getOpenFinancialPeriod(PostingDate)

The period containing the date; raises if closed.

getFinancialPeriod(PostingDate)

The period containing the date (open or closed).

`ACC_BAS_CommandApi`

This submodule does not provide a command API class. Period close/open is performed through the entity action handler, not a cross-module write seam.

ViewModel actions

Action User-visible effect

Action	User-visible effect
`closePeriod` (on Financial Period)	Closes the period so no further postings are accepted.
`closePeriodUndo` (on Financial Period)	Re-opens a closed period.

closePeriod (on Financial Period)

Closes the period so no further postings are accepted.

closePeriodUndo (on Financial Period)

Re-opens a closed period.

Accounting Basics (BAS)

Concepts

Entities

Finance Company (FinanceCompany)

Financial Year (FinancialYear)

Financial Period (FinancialPeriod)

Currency Contract (CurrencyContract)

Currency Conversion (CurrencyConversion)

Currency Conversion Rate (CurrencyConversionRate)

Currency Rate Type (CurrencyRateType)

Interest Contract (InterestContract)

Interest Contract Rate (InterestContractRate)

Interest Calculation Type (InterestCalculationType)

Finance Item Group (FinanceItemGroup)

Functionality

Financial-period gating

Period close / undo

Currency conversion

Public API

ACC_BAS_QueryApi

ACC_BAS_CommandApi

ViewModel actions

Finance Company (`FinanceCompany`)

Financial Year (`FinancialYear`)

Financial Period (`FinancialPeriod`)

Currency Contract (`CurrencyContract`)

Currency Conversion (`CurrencyConversion`)

Currency Conversion Rate (`CurrencyConversionRate`)

Currency Rate Type (`CurrencyRateType`)

Interest Contract (`InterestContract`)

Interest Contract Rate (`InterestContractRate`)

Interest Calculation Type (`InterestCalculationType`)

Finance Item Group (`FinanceItemGroup`)

`ACC_BAS_QueryApi`

`ACC_BAS_CommandApi`