Rhythm 2.0 Specifications

Appearance

CAP-ACC-TRX-008Allocate and relocate received money

Markdown

CAP-ACC-TRX-008

Allocate and relocate received money

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-ACC-TRX-03
Exercised by
FAS-ACC-TRX-03-01, FAS-ACC-TRX-03-02, FAS-ACC-TRX-03-03, FAS-ACC-TRX-03-04, JNY-ACC-TRX-003
Key concepts
CON-ACC-TRX-003, CON-ACC-TRX-001
Actors
ACT-ACC-012, ACT-ACC-021
Journeys
JNY-ACC-TRX-002
Depends on
CAP-ACC-TRX-006
Related
CAP-ACC-TRX-007, CAP-ACC-TRX-009, CAP-ACC-TRX-011
Proved by
ATS-ACC-TRX-008

Implementation

Executable suites
TST-ACC-TRX-070, TST-ACC-TRX-072, TST-ACC-TRX-081, TST-ACC-TRX-242, TST-ACC-TRX-256

KindCapabilityProduct areaAccountingModuleTransactionsRevision1

Read atservices-accounting f47cb263react-console baf6dae3

Allocate and relocate received money ​

Purpose ​

Staff put held receipts against the correct customer debt while retaining earlier allocation history.

How It Works ​

Staff choose invoice or line targets for available receipt value. Accounting restricts targets to the applicable customer and financial context. Invoice targets distribute value according to line priority. An application that would overspend either side is refused. Reallocation writes opposite entries for selected old applications before placing the available value again. Both changes commit together. A first payment can recognize a previously unconverted quote.

Relationships ​

  • Record receipts collected outside Rhythm supplies or continues the related financial work.
  • Collect processor payments and resolve uncertainty supplies or continues the related financial work.
  • Complete invoice settlement with credit and money supplies or continues the related financial work.
  • Provide and spend customer credit supplies or continues the related financial work.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Staff put held receipts against the correct customer debt while retaining earlier allocation history.Both changes commit together. A first payment can recognize a previously unconverted quote.
Surfaces
consoleapi
Constraints
One allocation request names at most five hundred targets.
Intent sources
services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D1services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D2services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D4services-accounting:docs/milestones/plans/ACCT-M2-plan.md#D6services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M2-9

Controls

24 controls apply, from the corpus control catalogue.

TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
accounting.payments.updateapitenant
accounting.payments.readapitenant

Business Rules

9 rules, 8 to be proved before approval. A rule's product intent is derived from its origin: 1 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Allocations target issued eligible invoice lines in the payment’s unit and currency; drafts and void invoices cannot receive money.
proved by ATS-ACC-TRX-004-07, ATS-ACC-TRX-008-01, ATS-ACC-TRX-010-07, TST-ACC-TRX-081
validationservice, databasetest
services-accounting:modules/transactions/tests/integration/services/payments/receive-offline.integration.spec.js#it refuses an invoice of another unit (business_unit_mismatch)
02must prove
Proposed
Every allocation path restricts payment to the receipt’s own customer until a later multi-customer model is implemented.
proved by ATS-ACC-TRX-008-02, ATS-ACC-TRX-010-07, TST-ACC-TRX-072
policyservicetest
services-accounting:modules/transactions/tests/integration/services/payments/customer-guard.integration.spec.js#it refuses allocating unapplied money to another customer’s invoice, leaving the payment unapplied
03must prove
Proposed
A line target receives its stated amount, while an invoice target distributes the amount by line payment priority up to each outstanding balance.
proved by ATS-ACC-TRX-008-03, TST-ACC-TRX-070, TST-ACC-TRX-081
calculationservicetest
services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it spreads the invoice target by pay priority: the second invoice’s first line takes 5000
04must prove
Proposed
Allocation cannot exceed either a line’s balance or the payment’s available money, including concurrent attempts protected by database constraints.
proved by ATS-ACC-TRX-003-12, ATS-ACC-TRX-004-07, ATS-ACC-TRX-006-10, ATS-ACC-TRX-007-12, ATS-ACC-TRX-008-04, ATS-ACC-TRX-008-09, ATS-ACC-TRX-009-12, ATS-ACC-TRX-020-09, TST-ACC-TRX-070, TST-ACC-TRX-256
invariantservice, databasetest
services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it serialize, and the second is refused by the database’s balance CHECK, not by code
05must prove
Confirmed
Allocation history accepts additions only; taking money away requires an opposite entry referring to the original.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-01
proved by ATS-ACC-TRX-008-05, ATS-ACC-TRX-008-09, TST-ACC-TRX-070
invariantdatabasetest
services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it refuses an UPDATE of an allocation row
06must prove
Proposed
Reallocation negates selected live applications and applies the resulting available money to new targets atomically; an already reversed application is ineligible.
proved by ATS-ACC-TRX-003-12, ATS-ACC-TRX-006-10, ATS-ACC-TRX-008-06, ATS-ACC-TRX-008-09, TST-ACC-TRX-070, TST-ACC-TRX-242
lifecycleservicetest
services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it writes a reversing row for the 5000 and a new row for the 4000, the original marked reversed in full
07must prove
Proposed
Only live payments can be allocated; voided, returned and charged-back receipts have no usable money.
proved by ATS-ACC-TRX-007-12, ATS-ACC-TRX-008-07, TST-ACC-TRX-070
validationservice, databasetest
services-accounting:modules/transactions/tests/integration/services/payments/allocate.integration.spec.js#it refuses allocating a voided payment (payment_not_live)
08must prove
Proposed
The first payment against an issued pro forma recognizes it as a real invoice within the same operation.
proved by ATS-ACC-TRX-008-08, TST-ACC-TRX-081
lifecycleservicetest
services-accounting:modules/transactions/tests/integration/services/payments/receive-offline.integration.spec.js#it converts an unconverted pro forma the first payment names, in the payment’s batch, and pays it (Commerce’s first payment makes it real)
09
Proposed
Later allocation chooses the requested batch, otherwise the payment’s still-open batch, otherwise the unit’s assigned batch.
policyservicedocumented
services-accounting:docs/accounting/payments.md#Routes

Scenarios

IdGivenWhenThenProvenance
01A receipt paid the wrong invoice.Move its allocation from the payment record.The original and opposing entries remain alongside the replacement, which settles the intended invoice.test
react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0304.spec.ts#ACT-ACC-0304
02Only 10.00 remains available on one receipt.Two staff submit applications simultaneously.Database protection permits one spend and rejects the competing request.test
react-console:acceptance/accounting/playwright/journeys/payments/ACT-ACC-0321.spec.ts#ACT-ACC-0321

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software