Rhythm 2.0 Specifications

Appearance

CAP-ACC-REC-010Document processor deductions and corrections

Markdown

CAP-ACC-REC-010

Document processor deductions and corrections

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-ACC-REC-02
Exercised by
FAS-ACC-REC-02-01, FAS-ACC-REC-02-02, FAS-ACC-REC-02-03, FAS-ACC-REC-02-04, FAS-ACC-REC-02-05
Key concepts
CON-ACC-REC-003, CON-ACC-REC-002
Actors
ACT-ACC-017
Journeys
JNY-ACC-REC-001
Depends on
CAP-ACC-REC-008
Related
CAP-ACC-REC-009, CAP-ACC-REC-011, CAP-ACC-REC-014
Proved by
ATS-ACC-REC-010
Executed by
TST-ACC-REC-006

Implementation

Executable suites
TST-ACC-REC-016, TST-ACC-REC-027, TST-ACC-REC-028, TST-ACC-REC-036, TST-ACC-REC-039, TST-ACC-REC-047, TST-ACC-REC-059

KindCapabilityProduct areaAccountingModuleReconciliationRevision2

Read atservices-accounting f47cb263react-console baf6dae3

Document processor deductions and corrections ​

Purpose ​

Preparers need to explain processor effects that payment records do not contain.

How It Works ​

The preparer chooses a fee, reserve movement or adjustment and enters its signed amount. A note or supporting evidence gives the approver a basis for review. Rhythm creates the financial item and associates it with the open explanation. Removing a mistaken entry withdraws it without pretending it never existed. Missing documentation, invalid accounts or limits stop entry, and console evidence upload remains incomplete.

Relationships ​

The matching workspace contains entries, finalization creates their recognition and operational posting writes the requested accounting.

The Formal Contract

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

Outcomes
Processor adjustments retain their supporting documentation.Fee-only and zero bank movements remain explainable.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: hand-entered fees, reserves and corrections with their accounts)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U4, U5, U6, U9)services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-18, INV-19)

Controls

25 controls apply, from the corpus control catalogue.

TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-IAM-006 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-004 TC-LOG-005 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
accounting.reconciliation-batches.updateapitenant
accounting.reconciliation-batches.updateconsoletenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Manual entries are restricted to fees, fee refunds, reserve holds or releases and adjustments with the required sign, reporting invalid kind, sign and documentation together.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U4, U6)
proved by ATS-ACC-REC-010-01, TST-ACC-REC-059
validationapi, service, databasetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses a manual item without a note or evidence, of a kind not entered by hand, and of the wrong sign, all at once; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses a capture entered by hand with 400
02must prove
Confirmed
Each manual entry needs a note or evidence at commit, and its final evidence cannot be removed without a note remaining.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-18)
proved by ATS-ACC-REC-010-02, TST-ACC-REC-039
validationdatabasetest
services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#refuses at commit a manual fee with neither a note nor an evidence file (RHF34); services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#commits a manual fee written with an evidence file in the same transaction; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#commits a manual fee that carries a note and no evidence file; services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#refuses at commit the removal of the only evidence file of a manual fee without a note (RHF34); services-accounting:modules/reconciliation/tests/integration/db/reconciliation-evidence-files.table.integration.spec.js#lets a manual fee’s evidence file go once the fee carries a note
03must prove
Confirmed
An adjustment selects a ledger account in the reconciliation’s business unit, while fee and reserve recognition uses that unit’s default accounts at finalization.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U5: “other” also names a GL account)
proved by ATS-ACC-REC-010-03, TST-ACC-REC-047, TST-ACC-REC-059
validationservice, databasetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses an adjustment without a GL account, or with another unit’s, with 400; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#enters an adjustment booked to a GL account of the unit; services-accounting:modules/reconciliation/tests/integration/db/settlement-items.table.integration.spec.js#refuses an adjustment without its GL account
04must prove
Confirmed
Adding a manual entry creates a settlement item already claimed by its reconciliation and updates totals and version.
proved by ATS-ACC-REC-008-13, ATS-ACC-REC-010-04, ATS-ACC-REC-010-12, TST-ACC-REC-059
lifecycleservicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#writes the fee as a manual item of the batch, claimed by it; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#counts the manual item and its claim in the batch, one version on; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#records batch.manual-item-added with the item and its idempotency key; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#answers a repeat of the same key and body with the first answer, entering nothing more; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses the same key with another body with 409 idempotency-key-reused
05must prove
Confirmed
A manual entry’s occurrence is local midnight on the earliest linked payout’s accounting day.
proved by ATS-ACC-REC-010-05
calculationserviceobserved
services-accounting:modules/reconciliation/services/persistence/reconciliation-allocations.ts:addManualItem
06must prove
Confirmed
Manual addition replays the first entry for an identical request key and body, and rejects a different body under that key.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: idempotency of every money command)
proved by ATS-ACC-REC-008-13, ATS-ACC-REC-010-04, ATS-ACC-REC-010-12, TST-ACC-REC-059
validationapi, servicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#answers a repeat of the same key and body with the first answer, entering nothing more; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#writes the fee as a manual item of the batch, claimed by it; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#counts the manual item and its claim in the batch, one version on; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#records batch.manual-item-added with the item and its idempotency key; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses the same key with another body with 409 idempotency-key-reused
07must prove
Confirmed
Removal withdraws the manual item, identifies its reconciliation, updates current totals and version but retains the lifetime manual-entry count; repeating removal finds no active entry.
proved by ATS-ACC-REC-009-11, ATS-ACC-REC-010-06, ATS-ACC-REC-010-11, TST-ACC-REC-027, TST-ACC-REC-059
lifecycleservicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#resolves the item withdrawn, naming the batch; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#takes it out of the batch’s items and totals, one version on, keeping the count of items entered; services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#refuses to remove it again with 404; services-accounting:modules/reconciliation/tests/e2e/reconciliation-matching.e2e.spec.js#leaves the removed fee withdrawn
08must prove
Confirmed
The lifetime manual-entry limit is two hundred per reconciliation.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§4: the architecture §6 invariants hold; INV-19)
proved by ATS-ACC-REC-010-07, TST-ACC-REC-036
invariantdatabasetest
services-accounting:modules/reconciliation/tests/integration/db/reconciliation-batches.table.integration.spec.js#refuses a 201st manual item
09must prove
Confirmed
Manual entries can explain a negative fee-only deposit or help reconcile a deposit whose net amount is zero.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U9)
proved by ATS-ACC-REC-010-08, TST-ACC-REC-028, TST-ACC-REC-059
calculationservicetest
services-accounting:modules/reconciliation/tests/integration/services/persistence/reconciliation-allocations.integration.spec.js#balances the negative payout with the two manual items; services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 14: reconciles and finalizes a zero payout whose fee took the whole capture
10
Confirmed
The adjustment dialog leaves the amount for staff to enter, explains its sign, requests kind and note plus an adjustment account when needed, and has no working evidence upload.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D6 (architecture §3.4 U5, U6)
policyconsoleobserved
react-console:components/accounting/reconciliation/workspace/adjustments.tsx:AddAdjustment
11must prove
Confirmed
Reconciliation update permission is required to add or remove manual entries.
origin: services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D10 (§2: permissions)
proved by ATS-ACC-REC-010-09, TST-ACC-REC-016
permissionapiobserved
services-accounting:modules/reconciliation/aws/api/matching.routes.ts:addReconciliationManualItem

Scenarios

IdGivenWhenThenProvenance
01Ten thousand dollars of claimed money explains a $9,725.00 deposit before deductions.Add the documented two-hundred-twenty-five-dollar fee and fifty-dollar reserve hold.The open explanation becomes Balanced at zero difference.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 6: balances to a difference of 0 with the fee and the reserve hold, and shows Balanced
02The processor debits fifteen dollars for fees alone.Enter the negative-fifteen-dollar fee.The explanation balances for approval.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 14: reconciles and finalizes a negative payout of −1500 made of fees only

Edge Cases

IdGivenWhenThenProvenance
03A three-hundred-fifty-dollar capture is entirely consumed by its fee, producing a zero payout.Claim the capture and add its negative fee.Approval recognizes the fee without a bank transfer.test
services-accounting:modules/reconciliation/tests/e2e/reconciliation-scenario.e2e.spec.js#step 14: reconciles and finalizes a zero payout whose fee took the whole capture

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