Rhythm 2.0 Specifications

Appearance

CAP-ACC-BKS-004Maintain dated exchange rates for a unit

Markdown

CAP-ACC-BKS-004

Maintain dated exchange rates for a unit

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationPartially observed

Planning

Feature
FEAT-ACC-BKS-01
Exercised by
FAS-ACC-BKS-01-02
Key concepts
CON-ACC-BKS-001
Actors
ACT-ACC-001, ACT-ACC-002, ACT-ACC-004
Journeys
JNY-ACC-BKS-006
Depends on
CAP-ACC-BKS-002
Related
CAP-ACC-BKS-001
Proved by
ATS-ACC-BKS-004

Implementation

Executable suites
TST-ACC-BKS-053, TST-ACC-BKS-084, TST-ACC-BKS-085, TST-ACC-BKS-172

KindCapabilityProduct areaAccountingModuleBooks, Business Units and Chart of AccountsRevision1

Read atservices-accounting f47cb263react-console baf6dae3

Maintain dated exchange rates for a unit ​

Purpose ​

Finance staff maintain precise foreign-currency quotes and resolve the rate applicable to a date.

How It Works ​

The controller selects a unit and a foreign currency in Exchange Rates. They enter a dated manual quote or ask the provider to fill eligible missing quotes. Stored rates preserve decimal precision. Later pricing and accounting work resolves the quote applicable to its date. A provider failure leaves the configuration unchanged. An existing quote keeps its identifying choices during correction. Provider quotes require a different correction path from manually entered quotes.

Relationships ​

The unit’s supported-currency settings govern rate entry, provider filling and missing-price treatment.

The Formal Contract

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

Outcomes
Dated resolution selects the latest eligible quote.Provider quote correction uses removal and refilling rather than manual editing.Commerce and Accounting share the same resolved quote.
Surfaces
consoleapi
Intent sources
services-accounting:docs/milestones/plans/ACCT-M1-plan.md#2. Scopeservices-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D4services-accounting:docs/architecture/accounting-2.0/02-decisions.md#P-3services-accounting:docs/architecture/accounting-2.0/02-decisions.md#P-4services-accounting:docs/architecture/accounting-2.0/02-decisions.md#P-5

Controls

27 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-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
accounting.exchange-rates.readapitenant
accounting.exchange-rates.createapitenant
accounting.exchange-rates.updateapitenant
accounting.exchange-rates.deleteapitenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
A rate is positive decimal text with no more than eight integer and ten fractional digits for a supported non-base currency on a valid date; numeric input is refused to preserve precision.
✓ A valid configuration completes the stated operation.✗ A conflicting configuration receives the stated refusal.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#P-5
proved by ATS-ACC-BKS-004-01, ATS-ACC-BKS-004-09, TST-ACC-BKS-053, TST-ACC-BKS-172
validationapi, service, databasetest
services-accounting:modules/books/tests/unit/rules/exchange-rate-rules.spec.js#refuses a number (digits would be lost), zero, a negative, more than ten places, nine integer digits and a word
02must prove
Confirmed
A unit has at most one rate for each currency and date, and a saved rate cannot change its unit, currency, date or source.
origin: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D4
proved by ATS-ACC-BKS-002-12, ATS-ACC-BKS-004-02, TST-ACC-BKS-084
invariantservice, databasetest
services-accounting:modules/books/tests/integration/services/persistence/exchange-rates.integration.spec.js#refuses changing the unit, the currency or the day: a rate’s identity is write-once
03must prove
Confirmed
Rate resolution returns the latest quote on or before the requested date, defaulting to the workspace’s current date, with source and pricing settings or no quote; Commerce uses the same database answer.
proved by ATS-ACC-BKS-004-03, ATS-ACC-BKS-004-11, TST-ACC-BKS-053, TST-ACC-BKS-085
calculationservice, databasetest
services-accounting:modules/books/tests/integration/services/persistence/exchange-rates.queries.integration.spec.js#answers the latest rate on or before the day with the currency’s settings
04must prove
Confirmed
Provider rates cannot be edited manually; deletion is permitted, so correction requires deletion followed by another fill.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#P-4
proved by ATS-ACC-BKS-004-07
policyserviceobserved
services-accounting:modules/books/services/persistence/exchange-rates.ts:updateExchangeRate
05must prove
Confirmed
Provider filling makes one request outside the database transaction for missing quotes among selected provider currencies, skips existing dated quotes, reports unpriced currencies and stores quotes on the provider’s date.
origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#P-4
proved by ATS-ACC-BKS-004-04, TST-ACC-BKS-084
calculationservicetest
services-accounting:modules/books/tests/integration/services/persistence/exchange-rates.integration.spec.js#skips a currency whose day already holds a rate, reports one the provider did not price, and stores a quote on the provider’s own earlier day
06must prove
Confirmed
Filling refuses table-sourced or unsupported currencies and units without provider currencies, and writes nothing when the provider is unavailable or declines.
proved by ATS-ACC-BKS-004-05, TST-ACC-BKS-053, TST-ACC-BKS-084
validationservicetest
services-accounting:modules/books/tests/integration/services/persistence/exchange-rates.integration.spec.js#refuses provider_unavailable and provider_declined, writing nothing
07must prove
Confirmed
Conversion rounds half away from zero at the target currency’s precision, while reciprocal rates round half up to ten decimal places.
proved by ATS-ACC-BKS-004-06, TST-ACC-BKS-172
calculationservicetest
services-accounting:modules/books/tests/unit/rules/exchange-rate-rules.spec.js#applies the target currency’s exponent exactly: 100.00 USD at 149.37 is 14937 yen
08
Confirmed
Rate lists order by unit, currency and descending date, support unit, currency and inclusive date filters, and provider filling requires rate-create permission.
policyapi, servicetest
services-accounting:modules/books/tests/integration/services/persistence/exchange-rates.queries.integration.spec.js#lists the tenant’s rates by unit, currency, newest day first

Scenarios

IdGivenWhenThenProvenance
01The unit maintains Canadian-dollar quotes manually.Staff enter today’s and last week’s quotes and resolve yesterday’s rate.Resolution returns last week’s quote together with table sourcing and calculated-price handling.test
react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0030.spec.ts#ACT-ACC-0030
02The development workspace has no available provider connection.The controller requests a provider fill.The request reports provider unavailability without saving a quote.test
services-accounting:modules/books/tests/e2e/exchange-rates.e2e.spec.js#refuses the fill 409 provider_unavailable while no platform client exists, writing nothing

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