Assign new documents to the appropriate batch stream

Purpose

Administrators configure predictable default placement for transactions that do not name a batch.

How It Works

An administrator opens a unit’s Batch Assignment settings. They choose a default stream and put more specific rules in priority order. Testing sample facts shows which rule wins without creating a document. Transaction callers gather those facts and ask for placement when no batch is supplied. The selected stream must provide a batch that accepts the document. Missing settings or an unavailable active batch produces a refusal that the caller must resolve.

Relationships

Prerequisite: Configure recurring batch streams, which addresses the connected batch work.
Related outcome: Place documents in eligible batches and protect posted work, which addresses the connected batch work.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

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

Outcomes: Default and ordered matching choices select recurring intake for applicable document facts.
Surfaces: consoleapi
Constraints: Transaction callers supply assignment facts and retain ownership of their documents.
Intent sources: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3

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-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-CRY-001 TC-DAT-001 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003

Permissions

Key	Checked at	Scope
`accounting.batch-assignment-settings.read`	api	tenant
`accounting.batch-assignment-settings.update`	api	tenant
`accounting.batch-assignment-settings.delete`	api	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	A unit has one assignment-settings record comprising a required default recurring configuration and no more than one hundred ordered rules. proved by `ATS-ACC-BAT-011-01`, `TST-ACC-BAT-056`, `TST-ACC-BAT-080`	validation	api, database	test services-accounting:modules/batches/tests/e2e/batch-assignment-settings.e2e.spec.js#answers 400 to 101 rules
`02`must prove Proposed	Saving replaces settings and their entire ordered rule list atomically, assigning positions from one and preserving the previous list if replacement fails. origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D3 proved by `ATS-ACC-BAT-011-02`	policy	service, database	test services-accounting:modules/batches/tests/integration/services/persistence/batch-assignment-settings.integration.spec.js#keeps the previous settings and rules after the database refused a rule the save had already replaced them with
`03`must prove Proposed	The first save creates settings, and later saves require the current version rather than a missing or stale version. proved by `ATS-ACC-BAT-011-03`, `TST-ACC-BAT-056`	validation	service	test services-accounting:modules/batches/tests/e2e/batch-assignment-settings.e2e.spec.js#answers 409 StaleObject to a save at the version first read
`04`must prove Proposed	Referenced recurring configurations and merchant or bank accounts must belong to the settings’ unit, with invalid rule references identified. proved by `ATS-ACC-BAT-011-04`, `TST-ACC-BAT-056`, `TST-ACC-BAT-080`	validation	service, database	test services-accounting:modules/batches/tests/e2e/batch-assignment-settings.e2e.spec.js#answers 400 to another unit’s recurring batch in a rule
`05`must prove Proposed	An assignment rule can select one merchant account or one bank account, but not both. proved by `ATS-ACC-BAT-011-05`, `TST-ACC-BAT-056`, `TST-ACC-BAT-066`, `TST-ACC-BAT-126`	validation	api, database	test services-accounting:modules/batches/tests/e2e/batch-assignment-settings.e2e.spec.js#answers 400 naming bank_account_id to a rule naming both a merchant and a bank account
`06`must prove Proposed	Transaction, payment and card criteria use the declared vocabulary without duplicates, and an omitted or empty criterion means unrestricted. proved by `ATS-ACC-BAT-011-05`, `ATS-ACC-BAT-011-13`, `TST-ACC-BAT-056`, `TST-ACC-BAT-066`, `TST-ACC-BAT-126`	validation	api, database	test services-accounting:modules/batches/tests/e2e/batch-assignment-settings.e2e.spec.js#answers 400 to a transaction type the vocabulary does not have
`07`must prove Proposed	Selection uses the first rule in position order matching every supplied criterion, including the exact bank account, and otherwise returns the default. proved by `ATS-ACC-BAT-011-06`, `TST-ACC-BAT-126`	calculation	service	test services-accounting:modules/batches/tests/unit/rules/batch-assignment-rules.spec.js#answers the first matching rule by position, whatever order the rules are listed in
`08`must prove Proposed	A transaction lacking a fact matches only an unrestricted criterion for that fact, while the contract delegates companion-payment and order facts to the caller. proved by `ATS-ACC-BAT-011-06`, `TST-ACC-BAT-126`	calculation	service	documented services-accounting:modules/batches/services/rules/batch-assignment-rules.ts (assignment contract in file header)
`09`must prove Proposed	The selected recurring configuration supplies an accepting active batch, and missing settings, a missing active batch or refused intake prevents default assignment even though inactive configuration can still supply an Open batch. proved by `ATS-ACC-BAT-007-09`, `ATS-ACC-BAT-011-07`, `ATS-ACC-BAT-011-11`, `TST-ACC-BAT-004`, `TST-ACC-BAT-074`	policy	service	test react-console:acceptance/accounting/playwright/journeys/batches-posting/ACT-ACC-0510.spec.ts#ACT-ACC-0510
`10`must prove Proposed	Evaluation accepts transaction facts and returns the selected recurring configuration and matching position, or no position for the default, without writing a transaction. proved by `ATS-ACC-BAT-011-08`, `TST-ACC-BAT-056`	calculation	api, service	test services-accounting:modules/batches/tests/e2e/batch-assignment-settings.e2e.spec.js#answers the first rule by position when two rules match
`11`must prove Proposed	Read permission covers settings and evaluation, update covers save and delete covers removal, which also removes owned rules and releases their recurring references. proved by `ATS-ACC-BAT-009-15`, `ATS-ACC-BAT-011-09`, `ATS-ACC-BAT-011-12`, `TST-ACC-BAT-056`, `TST-ACC-BAT-059`	permission	api, console	test services-accounting:modules/batches/tests/e2e/batches-security.e2e.spec.js#is refused the save 403 permission_missing
`12`must prove Proposed	Default selection returns no batch for pro forma work and prefers a referenced Open order batch before consulting assignment rules. proved by `ATS-ACC-BAT-011-10`	policy	service	observed services-accounting:modules/batches/services/rules/batch-rules.ts:defaultBatchOf

Scenarios

Id	Given	When	Then	Provenance
`01`	Checks use the default stream and the first rule selects the card merchant’s stream.	A card payment and a check arrive without batches.	Each document takes the accepting active batch chosen by its matching rule or default.	test react-console:acceptance/accounting/playwright/journeys/batches-posting/ACT-ACC-0510.spec.ts#ACT-ACC-0510
`02`	An assignment rule specifies the operating bank account.	An administrator evaluates a payment using a different bank account.	Selection uses the default rather than matching the different bank.	test services-accounting:modules/batches/tests/e2e/batch-assignment-settings.e2e.spec.js#REGRESSION — answers the default, not the bank account rule, for a payment into another bank account (legacy problem B)

Planning

Implementation

Assign new documents to the appropriate batch stream ​

Purpose ​

How It Works ​

Relationships ​