Skip to main content
ShumoulShumoul Developer Portalplatform.shumoul.com
Version: Latest

5. Cash / Bank / Account Logic

5.1 What CashAccountId actually points to​

CashierAppsSettings.CashAccountId (and UserCashierSetting.CashAccountId) is a Guid? referencing dbo.CashAccounts.Id — a standalone operational "cash box" record (Shumoul.Domain.Entities.Financial.Setup.CashAccount: Name, FName, Cachier, Mobile, Phone, Fax, Email, Reference + audit fields). It carries no CurrencyId and no GL AccountId directly — those live in a separate, optional join table, CashAccountCurrency (CashAccountId, AccountId, CurrencyId + audit fields). The same shape applies to BankAccount/BankAccountCurrency.

Practical consequence: a CashAccount/BankAccount row can be created and immediately referenced by CashierAppsSettings.CashAccountId/BankAccountId with zero accounting entitlement, zero currency setup, and zero chart-of-accounts dependency. CashAccountService.CreateAsync (BackEnd) confirms this — a plain single-row insert, no transaction even required for a lone create.

The task's own guidance was to prefer resolving a GL account from AccountingChartTemplateMappings (which does carry MappingKey values CashOnHand and BankAccount — see Subscription Packages & Entitlements, Chapter 5A) rather than inventing new GL-resolution logic. Investigation found:

  • The existing accounting-chart-template mapping apply flow (Phase 5B.2) only currently wires 4 of the 12 seeded MappingKey values into InventoryAccountCategory fields — CashOnHand and BankAccount are not yet consumed anywhere in the tenant database. There is no reliable way today to ask "what is this tenant's CashOnHand GL account" from BackEnd — the mapping exists in the SaaS seed data but has no landing spot in the tenant's own schema yet.
  • The tenant-side Account entity created by AccountingChartTemplateAccountApplyService carries no MappingKey column at all (confirmed by reading MapToAccount) — so even a direct query against dbo.Accounts cannot recover which account corresponds to which mapping key after the fact.

Decision: this phase creates CashAccount/BankAccount as bare operational records only — no CashAccountCurrency/BankAccountCurrency row, no GL account resolution or creation of any kind. This is explicitly not a workaround or a shortcut: extending the accounting-mapping-apply system to resolve CashOnHand/BankAccount into a real tenant GL account is a real, separate piece of work with its own design questions (which currency? which account if the chart wasn't applied yet? what happens on a chart re-apply?) and is out of scope for this phase. See Chapter 10 §10.4 for this as a tracked remaining gap.

5.3 Can a POS-only tenant have a usable cash box without AccountManagement?​

Yes, unconditionally — per §5.1, the entity itself has no GL/currency requirement. CashAccount is entitled by Features.PointofSalesApp OR Features.AccountManagement (either one is sufficient) — a Shumoul Starter/POS tenant gets a cash box exactly as readily as a Finance tenant does, matching the task's own instruction: "If POS packages need a cash box but not full accounting, document whether CashAccountId can safely be null or must wait for AccountManagement" — it never needs to be null or wait; it is safe immediately.

BankAccount, by contrast, is gated on Features.AccountManagement only — banking is treated as an accounting concept a POS-only tenant does not need by default, matching §6 of the original task ("do not create advanced accounting/bank defaults unless required and safe" for Starter/POS).

5.4 Update — this gap is now closed​

§5.2 above is retained for historical context, but the GL/currency-resolution gap it describes was closed by a later phase — see Cash/Bank GL-Currency Linking. In short: the accounting-chart-template mapping-apply flow (Phase 5B.2) was extended so CashOnHand/BankAccount mapping keys resolve to real CashAccountCurrency/BankAccountCurrency rows, once both a chart template is applied (giving BackEnd a dbo.Accounts.Code to resolve) and this phase's default CashAccount/ BankAccount exist (giving it something to link). Neither this phase's CashAccount/BankAccount creation logic nor its entitlement rules changed.