---
id: STATE-ACC-PRD-003
title: Accounting setup lifecycle
object: DOM-ACC-PRD-004
product_area: accounting
module: products
revision: 3
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
- name: not set up
  meaning: No product-specific setup exists; reads return no summary and the console warns about documented
    fallback to unit defaults.
- name: set up
  meaning: A setup supplies account and recognition configuration for future posting.
transitions:
- from: not set up
  to: set up
  trigger: Save the first setup through single or bulk replacement.
  guard: The workspace product must exist and be locked, and all setup checks must pass; retired products are
    admitted.
  side_effects:
  - Fill the product's financial summary on reads
  - Exclude the product from missing-setup results
  who: A caller with product-accounting update authority
  provenance: test
  source: services-accounting:modules/products/tests/integration/services/persistence/product-accounting-setups.integration.spec.js#gives
    the product its accounting summary
- from: set up
  to: set up
  trigger: Replace the existing setup at its read version.
  guard: Its version matches and price-based validation passes, with any combined setup lock explicitly reduced.
  side_effects:
  - Advance setup version and modification stamps
  - Replace all four collections
  - Clear omitted optional values without modifying posted entries
  who: A caller with product-accounting update authority
  provenance: test
  source: services-accounting:modules/products/tests/integration/services/persistence/product-accounting-setups.integration.spec.js#answers
    the replaced setup at version 2, its cleared fields left out and every collection replaced
- from: set up
  to: not set up
  trigger: Remove the setup through its delete operation.
  guard: No setup lock may prevent deletion.
  side_effects:
  - Delete the setup and its children
  - Keep the product with no accounting summary
  who: A caller with product-accounting delete authority; no console action invokes it
  provenance: test
  source: services-accounting:modules/products/tests/integration/services/persistence/product-accounting-setups.integration.spec.js#unlocks
    a setup locked against updates when the replacement states sys_locked null, then deletes it
invalid:
- from: set up
  to: set up
  why: An existing setup requires its current read version for replacement; absent or stale versions fail.
- from: not set up
  to: not set up
  why: Removing an absent setup returns not found.
concurrency: Setup operations lock the product before the setup. Bulk saving acquires products in key order.
  This holds prices stable for validation but does not make later product edits validate existing shares again.
invariants:
- INV-DOM-ACC-PRD-004-01
- INV-DOM-ACC-PRD-004-09
- INV-DOM-ACC-PRD-004-13
evidence:
- 'services-accounting at f47cb263: modules/products/services/persistence/product-accounting-setups.ts (replaceProductAccounting,
  replaceProductAccountings, deleteProductAccounting); services/persistence/products.ts (lockProductForAccounting,
  lockProductsInIdOrder); docs/accounting/products.md (Accounting setup, Products without a setup).'
- 'react-console at baf6dae3: components/accounting-config/products/products-page.tsx (AccountingCell); lib/accounting/configuration/client.ts
  (removeAccounting, unused by screens).'
---

# Accounting setup lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> not_set_up: create product
  not_set_up --> set_up: save first setup
  set_up --> set_up: replace setup
  set_up --> not_set_up: remove setup
  set_up --> [*]: remove product
  not_set_up --> [*]: remove product
```

## Transitions Explained

A product has no setup until finance supplies one through single or bulk saving. An absent setup is inserted; an existing setup is replaced at its current version. Deleting only the setup leaves the product available with no financial summary. Product deletion also removes the setup unless its deletion lock blocks the operation.

## What Cannot Happen

A setup cannot change its product or business unit. Refused local writes leave the committed row and collections intact. The documented posting boundary keeps earlier posted accounts outside later setup edits.

## Concurrency and Timing

The setup writer locks the product before reading prices and locking the setup. Bulk writes acquire product locks in identity order. A first setup write does not reject a supplied version merely because the setup is absent. Retirement does not prevent setup saving; explicit product authority for that difference remains missing.