Rhythm 2.0 Specifications

Appearance

CAP-ACC-TRX-005Prepare and deliver invoice documents

Markdown

CAP-ACC-TRX-005

Prepare and deliver invoice documents

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationPartially observed

Planning

Feature
FEAT-ACC-TRX-01
Exercised by
FAS-ACC-TRX-01-01, FAS-ACC-TRX-01-02, FAS-ACC-TRX-01-04
Key concepts
CON-ACC-TRX-001
Actors
ACT-ACC-012, ACT-ACC-002, ACT-ACC-021
Journeys
JNY-ACC-TRX-001
Depends on
CAP-ACC-TRX-001
Related
CAP-ACC-TRX-002
Proved by
ATS-ACC-TRX-005

Implementation

Executable suites
TST-ACC-TRX-007, TST-ACC-TRX-051, TST-ACC-TRX-060

KindCapabilityProduct areaAccountingModuleTransactionsRevision1

Read atservices-accounting f47cb263react-console baf6dae3

Prepare and deliver invoice documents ​

Purpose ​

Staff and Commerce give customers a readable account of their billed charges.

How It Works ​

A reader requests the rendered invoice using its applicable template. Accounting produces the current HTML document when requested. Sending is an explicit operation with its own authority and retry identity. Staff can select recipients when the bill-to contact’s primary address is unsuitable or unavailable. Communication submission and its event commit together. A failed submission leaves no misleading delivery record. The product should expose document delivery on the staff invoice page.

Relationships ​

  • Issue customer bills and numbered quotes supplies or continues the related financial work.
  • Correct issued bills before posting 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 and Commerce give customers a readable account of their billed charges.A failed submission leaves no misleading delivery record. The product should expose document delivery on the staff invoice page.
Surfaces
api
Intent sources
services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-10services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-11services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M1-7

Controls

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

Permissions

KeyChecked atScope
accounting.invoices.readapitenant
accounting.invoices.emailapitenant

Business Rules

7 rules, 7 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.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Rendering selects the invoice template, then the unit template, then the built-in design; a missing, inactive or inappropriate named template is refused.
origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D12
proved by ATS-ACC-TRX-005-01, TST-ACC-TRX-060
policyservicetest
services-accounting:modules/transactions/tests/integration/services/invoices/render-invoice.integration.spec.js#it is the invoice’s own template over its unit’s
02must prove
Proposed
Each rendering produces fresh HTML from the invoice without retaining a rendered copy.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-10
proved by ATS-ACC-TRX-001-17, ATS-ACC-TRX-005-02, ATS-ACC-TRX-005-07, TST-ACC-TRX-007
policyservicetest
services-accounting:modules/transactions/tests/e2e/invoice-documents.e2e.spec.js#it refuses a format other than html: 400
03must prove
Proposed
E-mail delivery rejects drafts and requires an invoice that has been issued.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M1-7
proved by ATS-ACC-TRX-005-03, TST-ACC-TRX-051
validationservicetest
services-accounting:modules/transactions/tests/integration/services/invoices/email-invoice.integration.spec.js#it refuses a draft: it has no number and no receivable
04must prove
Proposed
Delivery uses the contact’s primary address unless the sender provides up to ten valid recipients; absent recipients prevent sending, including an organization with no explicit recipients.
origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D12
proved by ATS-ACC-TRX-005-03, ATS-ACC-TRX-005-08, TST-ACC-TRX-051
validationapi, servicetest
services-accounting:modules/transactions/tests/integration/services/invoices/email-invoice.integration.spec.js#it refuses more than ten addresses: 400
05must prove
Proposed
Sending requires a distinct retry key, repeats only once under that key and occurs separately from invoice creation.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-11
proved by ATS-ACC-TRX-005-04, ATS-ACC-TRX-005-07, TST-ACC-TRX-051
policyapi, servicetest
services-accounting:modules/transactions/tests/integration/services/invoices/email-invoice.integration.spec.js#it refuses an e-mail without an idempotency key: 400 idempotency_key_required
06must prove
Proposed
The communication submission and delivery event commit together, with a failed submission leaving neither record.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#M1-7
proved by ATS-ACC-TRX-001-17, ATS-ACC-TRX-005-05, ATS-ACC-TRX-005-07, TST-ACC-TRX-051
invariantservicetest
services-accounting:modules/transactions/tests/integration/services/invoices/email-invoice.integration.spec.js#it writes nothing, not even the event, when the sender’s statement fails: the command’s transaction rolls back
07must prove
Proposed
Read authority permits document viewing, while e-mail authority is separately required for sending.
origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D12
proved by ATS-ACC-TRX-005-06, TST-ACC-TRX-007
permissionapitest
services-accounting:modules/transactions/tests/e2e/invoice-documents.e2e.spec.js#it refuses the e-mail to a principal holding only accounting.invoices.read: 403, submitting nothing

Scenarios

IdGivenWhenThenProvenance
01A billed contact has a primary e-mail address.Send the issued invoice without explicit recipients.A communication is submitted for that address with template content and an attachment, and a delivery event is recorded.test
services-accounting:modules/transactions/tests/integration/services/invoices/email-invoice.integration.spec.js#it goes to the bill-to contact’s primary address, from the template, with the document attached, in the transaction
02An amendment advanced the invoice to revision two.Send its e-mail document.The subject identifies the second revision.test
services-accounting:modules/transactions/tests/e2e/invoices.e2e.spec.js#it amends an issued, unposted invoice (POST .../amend): a line added, the revision 2, the e-mail subject saying so

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