--- id: DOM-ACC-BKS-001 title: Business Unit realises: CON-ACC-BKS-001 product_area: accounting module: books revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-ACC-BKS-books readable_by: - SVC-ACC-BKS-maintenance lifecycle: STATE-ACC-BKS-001 custom_fields: none identity: >- Each workspace identifies a unit with an immutable configuration code. The caller supplies it or the service derives it from the name; queries use the same code, while staff can correct the display name. attributes: - name: identifier kind: text required: true computed: false notes: The configuration code is supplied or derived at creation and stays fixed. - name: name kind: text required: true computed: false notes: Surrounding spaces are removed; an all-space name is missing. - name: description kind: text required: false computed: false notes: Optional descriptive wording. - name: priority kind: number required: false computed: false notes: >- Ascending priority puts unranked units last and influences the working-unit fallback. - name: active kind: enum required: true computed: false notes: A stored flag controls whether active-only selectors offer the unit. - name: base currency kind: reference required: true computed: false notes: An offered ISO currency selected at creation and fixed thereafter. - name: fiscal start month kind: number required: true computed: false notes: A fixed month from January through December defines the calendar boundary. - name: multicurrency enabled kind: enum required: true computed: false notes: Defaults off; enabling it requires a nonempty supported set. - name: supported currencies kind: collection required: false computed: false notes: >- An owned list of at most two hundred foreign currencies stores table or provider sourcing and calculate or prohibit handling for missing prices. - name: dated exchange rates kind: collection required: false computed: false notes: >- Dated currency quotes retain their manual or provider origin; provider rows also retain quote and integration references. - name: accounting method kind: enum required: true computed: false notes: >- Defaults to accrual; a requested switch checks posted or downloaded batches in the current open period. - name: inventory costing method kind: enum required: true computed: false notes: Defaults to no costing; FIFO and LIFO are the other choices. - name: write-off method and direct write-off treatment kind: enum required: true computed: false notes: >- The default is direct write-off with bad-debt expense treatment; posting reads the current policy. - name: tender fee rule and default fee policy kind: collection required: false computed: false notes: >- A fee product, percentage, fixed and minimum amounts, electronic-check flag and invoice fee policy form a group preserved when wholly omitted. - name: download detail and financial software package kind: enum required: true computed: false notes: >- Summary and Other are the defaults used to choose built-in download behavior. - name: receivable project inheritance kind: enum required: true computed: false notes: Defaults off and controls project inheritance during posting. - name: document template choices kind: reference required: false computed: false notes: >- Four optional choices cover invoices, payment receipts, refund receipts and downloads; omission on replacement restores built-in selection. - name: lock and version kind: computed required: true computed: true notes: >- The version advances on mutation; a stored lock can protect deletion or both update and deletion. relationships: - to: DOM-ACC-BKS-002 cardinality: >- Each unit has multiple chart records, purpose assignments, receiving destinations and classifications ownership: >- Books maintains the unit’s chart; accounts and projects must be removed before deleting the unit. cross_service: false - to: DOM-ACC-BKS-003 cardinality: Each unit owns multiple fiscal years ownership: >- The calendar is created for the unit and cascades when an eligible unit is deleted. cross_service: false - to: DOM-ACC-BKS-004 cardinality: A template can serve multiple units; a unit selects at most one per kind ownership: The unit holds a choice of shared content without owning that content. cross_service: false - to: DOM-ACC-BKS-006 cardinality: A workspace contains multiple units ownership: >- Workspace definitions govern the unit but are maintained independently of it. cross_service: false invariants: - id: INV-DOM-ACC-BKS-001-01 statement: >- After insertion, the service and database refuse changes to a unit’s base currency or fiscal starting month. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/books/db/business-units.table.ts:business_units_freeze_trigger - id: INV-DOM-ACC-BKS-001-02 statement: >- A unit’s creation commits the base currency, supported set and first two fiscal years atomically; permitted later year deletion can remove that initial coverage. enforced_at: - service provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/fiscal-years.integration.spec.js#gives the new unit exactly its two years, the one containing today and the next - id: INV-DOM-ACC-BKS-001-03 statement: >- A request’s supported set contains at most two hundred distinct offered currencies and excludes the base currency. enforced_at: - api - service - database 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 - id: INV-DOM-ACC-BKS-001-04 statement: >- An enabled currency remains in the unit while an account or dated rate references its currency row. enforced_at: - service - database 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 - id: INV-DOM-ACC-BKS-001-05 statement: >- Only one quote is stored for a unit, currency and date, and its unit, currency, date and origin remain fixed. enforced_at: - service - database provenance: test source: >- 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 - id: INV-DOM-ACC-BKS-001-06 statement: >- A fee rule is either complete or absent; a request naming a product checks that it is active and belongs to the unit, without preserving that condition through a database reference. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/books/services/persistence/business-units.ts:assertCardFeeRule; services-accounting:modules/books/db/business-units.table.ts:business_units_card_fee_rule_check - id: INV-DOM-ACC-BKS-001-07 statement: >- A stored document choice is empty or references an active customer template in the same workspace for the required document kind. enforced_at: - database provenance: observed source: >- services-accounting:modules/books/db/business-units.table.ts:business_units_template_references_trigger - id: INV-DOM-ACC-BKS-001-08 statement: >- Deletion is refused while the unit retains GL, bank or merchant accounts or accounting projects. enforced_at: - service - database provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js#refuses a unit with GL, bank and merchant accounts, naming all three physical: - accounting.business_units - accounting.business_unit_currencies - accounting.exchange_rates - accounting.business_units_v - accounting.currencies (global vocabulary) evidence: - >- services-accounting at f47cb263: modules/books/db/business-units.table.ts, business-unit-currencies.table.ts, exchange-rates.table.ts, business-units.view.ts, currencies.table.ts - >- services-accounting at f47cb263: modules/books/services/persistence/business-units.ts, exchange-rates.ts; services/rules/configuration-rules.ts, card-fee-rules.ts, multi-currency rules - >- services-accounting at f47cb263: modules/books/metadata/business-units.object.ts; queries/business-units.query.ts - >- react-console at baf6dae3: components/configuration/resources/accounting-business-units.tsx --- # Business Unit ## What It Models A business unit gives the customer a separate accounting context. Its base currency and fiscal boundary establish how money and dates are interpreted. Currency permissions, accounting policies, document choices and tender-fee settings provide the configuration financial workflows consume. ## Identity and Attributes The configuration code identifies the unit within its workspace. Creation can derive that code from the name; subsequent edits preserve it. Name, description, priority and availability can change. The base currency and fiscal starting month are fixed. Currency rows and dated quotes are owned collections. The remaining policies govern posting, fees, downloads and document selection. Fee settings and direct write-off treatment survive an older client’s save when omitted, while an omitted document choice returns to built-in selection. ## Relationships Each unit supplies a chart, receiving destinations, reporting dimensions and calendar. Shared templates and workspace definitions are referenced separately. Restricting references from financial work can prevent removal of the unit or of records its deletion would cascade. ## Invariants Creation is one atomic write of the unit, currency setup and two fiscal years. This is a creation guarantee: permitted later calendar deletion can remove those years. Currency references and fixed founding values receive database protection. A fee-product check runs when the request names the product; it does not prevent later product changes. ## How It Is Stored and Shared Books provides ordinary configuration maintenance. Other Accounting modules use its shared tables and helpers within their own work. Maintenance reads the configuration for lifecycle operations and can remove it during workspace erasure. A read-only business-unit query exposes the agreed identifying fields. The registered unit has no custom-field capability. Customer rows use forced row-level security. Configuration retains the current version and last-modified details rather than a revision history or change-event stream. ## Open Design Questions Product still needs to settle merchant fee overrides and configuration history. The console exposes neither tender-fee settings nor direct write-off treatment. The accounting-method check can miss a concurrently posted batch.