--- id: CAP-ACC-BKS-002 title: Enable supported foreign currencies for a business unit feature: FEAT-ACC-BKS-01 product_area: accounting module: books revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: - CAP-ACC-CFG-002 source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#R1' - 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D2' - 'services-accounting:docs/architecture/accounting-2.0/02-decisions.md#P-3' purpose: >- A unit can accept foreign-currency work with explicit choices for rates and missing prices. outcomes: - >- Single-currency operation rejects foreign-currency work using the legacy treatment. - >- Enabled foreign currencies carry explicit sourcing and missing-price choices. - >- Existing account and rate dependencies protect their currencies from removal. concepts: - CON-ACC-BKS-001 actors: - ACT-ACC-001 - ACT-ACC-004 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: accounting.business-units.update where_checked: api scope: tenant - key: accounting.business-units.read where_checked: api scope: tenant rules: - id: BR-CAP-ACC-BKS-002-01 proved_by: [ATS-ACC-BKS-002-01, TST-ACC-BKS-074] statement: >- Multicurrency starts disabled; enabling it requires a supported currency, and the supported set takes effect only while the switch is enabled. kind: validation enforced_at: - api - service - console must_prove: true provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js#refuses Enable Multicurrency on a create with no supported currency, in Rhythm 1.0’s words origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#R1' - id: BR-CAP-ACC-BKS-002-02 proved_by: [ATS-ACC-BKS-002-02, TST-ACC-BKS-173] statement: >- A unit with multicurrency disabled refuses non-base currencies for accounts, prices, transactions and rates using the carried-forward refusal message. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-accounting:modules/books/tests/unit/rules/multi-currency-rules.spec.js#refuses a foreign currency when the flag is off, with 1.0’s sentence origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#R1' examples: negative: A conflicting configuration receives the stated refusal. - id: BR-CAP-ACC-BKS-002-03 proved_by: [ATS-ACC-BKS-002-03, ATS-ACC-BKS-002-10, TST-ACC-BKS-046, TST-ACC-BKS-074] statement: >- The supported set contains at most 200 offered currencies, without duplicates or the unit’s base currency. kind: validation enforced_at: - api - service - database must_prove: true provenance: test source: >- services-accounting:modules/books/tests/e2e/business-units.e2e.spec.js#answers 400 to a supported currency named twice, in Rhythm 1.0’s words origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D2' - id: BR-CAP-ACC-BKS-002-04 proved_by: [ATS-ACC-BKS-001-14, ATS-ACC-BKS-002-04, ATS-ACC-BKS-002-15, TST-ACC-BKS-053, TST-ACC-BKS-063, TST-ACC-BKS-074] statement: >- Each supported currency chooses table or provider rates and calculated or prohibited missing-price handling, defaulting to table and calculate; the base currency has neither setting. kind: policy enforced_at: - api - service - database must_prove: true provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js#answers each supported currency with its settings, the defaults for one that stated none, and the codes beside them origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D2' - id: BR-CAP-ACC-BKS-002-05 proved_by: [ATS-ACC-BKS-002-05, ATS-ACC-BKS-002-12, ATS-ACC-BKS-002-13, ATS-ACC-BKS-007-10, TST-ACC-BKS-005, TST-ACC-BKS-046, TST-ACC-BKS-067, TST-ACC-BKS-074] statement: >- Removing a supported currency or disabling multicurrency is refused while accounts or rates use it, with the unit, currency and dependent kinds identified; disabling an unused set clears it. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-accounting:modules/books/tests/e2e/business-units.e2e.spec.js#answers 409 naming the currency, the unit and the kinds of account that use it origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#R1' - id: BR-CAP-ACC-BKS-002-06 proved_by: [ATS-ACC-BKS-002-06, ATS-ACC-BKS-002-13, ATS-ACC-BKS-002-14, TST-ACC-BKS-005, TST-ACC-BKS-045, TST-ACC-BKS-055, TST-ACC-BKS-056] statement: >- GL, bank and merchant accounts accept only currencies enabled for their business unit. kind: validation enforced_at: - api - service - database must_prove: true provenance: test source: >- services-accounting:modules/books/tests/e2e/gl-accounts.e2e.spec.js#answers 400 to a currency the unit is not enabled for, in Rhythm 1.0’s words origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#D2' examples: negative: A conflicting configuration receives the stated refusal. - id: BR-CAP-ACC-BKS-002-07 proved_by: [] statement: >- When codes and detailed currency settings are both supplied, the codes define membership and the matching settings define each member’s behaviour. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js#lets the codes govern when both are sent (the console’s round trip), the settings applying to the codes they name origin: none - id: BR-CAP-ACC-BKS-002-08 proved_by: [ATS-ACC-BKS-002-07, TST-ACC-BKS-006] statement: >- An account creation and concurrent removal of its currency cannot both succeed with the account left in an unsupported currency. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0007.spec.ts#ACT-ACC-0007 origin: none - id: BR-CAP-ACC-BKS-002-09 proved_by: [] statement: >- The console displays supported currencies while multicurrency is enabled and asks for confirmation before disabling it and clearing the set. kind: policy enforced_at: - console must_prove: false provenance: documented source: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#R1' origin: 'services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md#R1' scenarios: - id: SC-CAP-ACC-BKS-002-01 given: A unit needs Canadian-dollar and euro trading. when: >- The controller enables both currencies and selects provider rates with prohibited base-price calculation for euros. then: >- A Canadian-dollar cash account can be saved, after which the currency cannot be removed while that account uses it. provenance: test source: >- react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0006.spec.ts#ACT-ACC-0006 - id: SC-CAP-ACC-BKS-002-02 given: Two administrators change the same unit concurrently. when: One drops euros as the other adds a euro account. then: One request succeeds and the refused request explains the conflict. provenance: test source: >- react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0007.spec.ts#ACT-ACC-0007 edge_cases: [] constraints: [] depends_on: - CAP-ACC-BKS-001 related: - CAP-ACC-BKS-004 - CAP-ACC-BKS-005 - CAP-ACC-BKS-007 journeys: - JNY-ACC-BKS-006 open_questions: [] evidence: - >- Verified source file: react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0006.spec.ts - >- Verified source file: react-console:acceptance/accounting/playwright/journeys/configuration/ACT-ACC-0007.spec.ts - 'Verified source file: services-accounting:aws/accounting.service.ts' - >- Verified source file: services-accounting:docs/architecture/accounting-2.0/02-decisions.md - >- Verified source file: services-accounting:docs/milestones/ACCT-M1-books-and-invoices.md - >- Verified source file: services-accounting:modules/books/db/business-unit-currencies.table.ts - >- Verified source file: services-accounting:modules/books/db/currencies.table.ts - >- Verified source file: services-accounting:modules/books/services/persistence/business-units.ts - >- Verified source file: services-accounting:modules/books/tests/e2e/bank-accounts.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/e2e/business-units.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/e2e/exchange-rates.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/e2e/gl-accounts.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/e2e/merchant-accounts.e2e.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/db/configuration-records.table.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/db/currency-catalog.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/db/exchange-rates.table.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/integration/services/persistence/currencies.queries.integration.spec.js - >- Verified source file: services-accounting:modules/books/tests/unit/rules/multi-currency-rules.spec.js controls: [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-002, 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] exercised_by: [FAS-ACC-BKS-01-01, FAS-ACC-BKS-01-02, FAS-ACC-BKS-01-03, FAS-ACC-BKS-01-04, FAS-ACC-BKS-01-05] suites: [TST-ACC-BKS-005, TST-ACC-BKS-006, TST-ACC-BKS-045, TST-ACC-BKS-046, TST-ACC-BKS-053, TST-ACC-BKS-055, TST-ACC-BKS-056, TST-ACC-BKS-063, TST-ACC-BKS-067, TST-ACC-BKS-074, TST-ACC-BKS-173] --- # Enable supported foreign currencies for a business unit ## Purpose A unit can accept foreign-currency work with explicit choices for rates and missing prices. ## How It Works The controller enables foreign-currency work on the chosen unit. They select the currencies the unit uses and review each currency’s pricing and rate choices. Account editors then use that configured context. Rate maintenance supplies the quotes needed for subsequent work. Switching a currency off can fail when existing accounts or rates depend on it. Staff remove those dependencies before trying again. Concurrent changes must preserve the same valid accounting context. ## Relationships Foreign-currency accounts and rate maintenance depend on this enabled set.