@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/src/modules/accounting/docs/commands/TechnicallyCompleteInternalOrder.md

@@ -0,0 +1,44 @@
+# TechnicallyCompleteInternalOrder
+
+## Overview
+
+technicallyCompleteInternalOrder transitions an internal order from RELEASED status to TECHNICALLY_COMPLETED status. This indicates that the activity tracked by the order is complete and no further cost postings are expected, though the order remains open for final review before closure.
+
+## Business Rules
+
+- Internal order must exist
+- Internal order must be in RELEASED status to be technically completed
+- Technically completing a CREATED, already TECHNICALLY_COMPLETED, or CLOSED order is rejected as an invalid state transition
+- Once technically completed, no further cost postings are accepted
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive technically complete internal order request] --> B{Internal order exists?}
+    B -->|No| C[Return error: INTERNAL_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is RELEASED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from RELEASED to TECHNICALLY_COMPLETED]
+    F --> G[Emit audit event]
+    G --> H[Return technically completed internal order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INTERNAL_ORDER_NOT_FOUND**: Internal order with the specified ID does not exist
+- **INVALID_STATE**: Internal order is not in RELEASED status
+
+## Test Cases
+
+- technically completes a RELEASED internal order transitioning it to TECHNICALLY_COMPLETED status
+- returns error when internal order does not exist
+- returns error when internal order is in CREATED status
+- returns error when internal order is already TECHNICALLY_COMPLETED
+- returns error when internal order is CLOSED
+- emits audit event recording the status transition and acting user

package/src/modules/accounting/docs/commands/UpdateAllocationCycle.md

@@ -0,0 +1,45 @@
+# UpdateAllocationCycle
+
+## Overview
+
+updateAllocationCycle modifies an existing allocation cycle. Updates are only permitted when the cycle is in DRAFT status. In the current implementation, only the cycle name can be updated while in DRAFT.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in DRAFT status to be updated
+- Updates to cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status are rejected
+- Only `name` can be updated
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update allocation cycle request] --> B{Allocation cycle exists?}
+    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Apply updates to allocation cycle]
+    F --> G[Emit audit event]
+    G --> H[Return updated allocation cycle]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: Allocation cycle with the specified ID does not exist
+- **INVALID_STATE**: Allocation cycle is not in DRAFT status
+
+## Test Cases
+
+- updates name on a DRAFT allocation cycle
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is in VALIDATED status
+- returns error when allocation cycle is in EXECUTED status
+- returns error when allocation cycle is in POSTED status
+- returns error when allocation cycle is in REVERSED status
+- emits audit event recording previous and new field values

package/src/modules/accounting/docs/commands/UpdateBudget.md

@@ -0,0 +1,47 @@
+# UpdateBudget
+
+## Overview
+
+updateBudget modifies fields on an existing budget. Updates are only permitted when the budget is in DRAFT status. Name, description, and budget holder can be updated while in DRAFT.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in DRAFT status to be updated
+- Name, description, and budget holder can be updated
+- Updates to budgets in SUBMITTED, APPROVED, ACTIVE, or CLOSED status are rejected
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update budget request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Apply updates to budget]
+    F --> G[Emit audit event]
+    G --> H[Return updated budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in DRAFT status
+
+## Test Cases
+
+- updates name on a DRAFT budget
+- updates description on a DRAFT budget
+- updates budget holder on a DRAFT budget
+- returns error when budget does not exist
+- returns error when budget is in SUBMITTED status
+- returns error when budget is in APPROVED status
+- returns error when budget is in ACTIVE status
+- returns error when budget is in CLOSED status
+- emits audit event recording previous and new field values

package/src/modules/accounting/docs/commands/UpdateCostCenter.md

@@ -0,0 +1,50 @@
+# UpdateCostCenter
+
+## Overview
+
+updateCostCenter modifies fields on an existing cost center. Name, description, category, responsible person, department, and validity period can be updated. The cost center code is fixed by the existing record and is not part of the update input.
+
+## Business Rules
+
+- Cost center must exist
+- Name, description, category, responsible person, and department can be updated
+- Category must be from the defined set: overhead, production, administration, sales, or research
+- When updating validTo, it must remain on or after validFrom
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update cost center request] --> B{Lookup by costCenterId}
+    B -->|Not found| C[Return error: COST_CENTER_NOT_FOUND]
+    B -->|Found| D{Valid name if provided?}
+    D -->|No| E[Return error: INVALID_NAME]
+    D -->|Yes| F{Valid category if changed?}
+    F -->|No| G[Return error: INVALID_CATEGORY]
+    F -->|Yes| H{validTo >= validFrom when both set?}
+    H -->|No| I[Return error: INVALID_VALIDITY_PERIOD]
+    H -->|Yes| J[Apply updates to cost center]
+    J --> K[Emit audit event]
+    K --> L[Return updated cost center]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_NOT_FOUND**: Cost center with the specified ID does not exist
+- **INVALID_NAME**: Name is empty or blank when provided
+- **INVALID_CATEGORY**: Category is not one of the recognized values (overhead, production, administration, sales, research)
+- **INVALID_VALIDITY_PERIOD**: validTo is before validFrom
+
+## Test Cases
+
+- returns error when cost center does not exist
+- returns error when name is empty string
+- returns error when category is invalid
+- returns error when validTo is before validFrom
+- updates cost center with valid fields
+- updates multiple fields at once

package/src/modules/accounting/docs/commands/UpdateCostElement.md

@@ -0,0 +1,82 @@
+# UpdateCostElement
+
+## Overview
+
+updateCostElement modifies fields on an existing cost element that is in DRAFT or ACTIVE status. Description and name can be updated in both DRAFT and ACTIVE status. Category and GL account reference changes are only permitted while the element is in DRAFT status. Type changes are never permitted. The command enforces field-level mutability rules based on the current lifecycle status to preserve referential integrity of downstream cost postings and allocations.
+
+## Business Rules
+
+- Cost element must exist and be in DRAFT or ACTIVE status
+- Description can be updated in both DRAFT and ACTIVE status
+- Name can be updated in both DRAFT and ACTIVE status
+- Category change is not permitted when the cost element is in ACTIVE status
+- GL account reference change is not permitted after activation (only updatable in DRAFT)
+- Type change (PRIMARY to SECONDARY or vice versa) is never permitted
+- When updating category, the new category must still match the element's type
+- When updating GL account reference on a DRAFT PRIMARY element, the new GL account must be active in an active CoA
+- When updating GL account reference, no other PRIMARY element in the same company may reference the new GL account
+- When updating validFrom/validTo, validFrom must be less than or equal to validTo when both are set
+- INACTIVE cost elements cannot be updated
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update cost element request] --> B{Cost element exists?}
+    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT or ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Type change attempted?}
+    F -->|Yes| G[Return error: TYPE_CHANGE_NOT_ALLOWED]
+    F -->|No| H{Status is ACTIVE and category change attempted?}
+    H -->|Yes| I[Return error: CATEGORY_CHANGE_NOT_ALLOWED]
+    H -->|No| J{Status is ACTIVE and GL account change attempted?}
+    J -->|Yes| K[Return error: GL_ACCOUNT_CHANGE_NOT_ALLOWED]
+    J -->|No| L{Category matches type if changed?}
+    L -->|No| M[Return error: INVALID_CATEGORY_FOR_TYPE]
+    L -->|Yes| N{GL account valid if changed?}
+    N -->|No| O[Return error: GL_ACCOUNT_NOT_FOUND]
+    N -->|Yes| P{Duplicate GL account reference?}
+    P -->|Yes| Q[Return error: DUPLICATE_GL_ACCOUNT_REFERENCE]
+    P -->|No| R{validFrom <= validTo when both set?}
+    R -->|No| S[Return error: INVALID_VALIDITY_PERIOD]
+    R -->|Yes| T[Apply updates to cost element]
+    T --> U[Emit audit event]
+    U --> V[Return updated cost element]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) — Validates updated GL account reference if changed
+
+## Error Scenarios
+
+- **COST_ELEMENT_NOT_FOUND**: Cost element with the specified ID does not exist
+- **INVALID_STATE**: Cost element is in INACTIVE status and cannot be updated
+- **TYPE_CHANGE_NOT_ALLOWED**: Changing the type (PRIMARY/SECONDARY) is never permitted
+- **CATEGORY_CHANGE_NOT_ALLOWED**: Category cannot be changed when the cost element is in ACTIVE status
+- **GL_ACCOUNT_CHANGE_NOT_ALLOWED**: GL account reference cannot be changed after activation
+- **INVALID_CATEGORY_FOR_TYPE**: New category does not match the cost element type
+- **GL_ACCOUNT_NOT_FOUND**: Updated GL account does not exist or is not active in an active Chart of Accounts
+- **DUPLICATE_GL_ACCOUNT_REFERENCE**: Another PRIMARY cost element in the same company already references the specified GL account
+- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo
+
+## Test Cases
+
+- updates description on a DRAFT cost element
+- updates description on an ACTIVE cost element
+- updates name on a DRAFT cost element
+- updates name on an ACTIVE cost element
+- updates category on a DRAFT cost element
+- returns error when changing category on an ACTIVE cost element
+- returns error when changing type on any cost element
+- returns error when changing GL account on an ACTIVE cost element
+- updates GL account on a DRAFT PRIMARY cost element
+- returns error when updated GL account does not exist
+- returns error when updated GL account is already referenced by another PRIMARY element
+- returns error when new category does not match the element type
+- returns error when cost element does not exist
+- returns error when cost element is INACTIVE
+- returns error when validFrom is after validTo
+- emits audit event recording previous and new field values

package/src/modules/accounting/docs/commands/UpdateInternalOrder.md

@@ -0,0 +1,62 @@
+# UpdateInternalOrder
+
+## Overview
+
+updateInternalOrder modifies fields on an existing internal order. Updates are permitted when the order is in CREATED or RELEASED status. Orders in TECHNICALLY_COMPLETED or CLOSED status cannot be updated. The order type cannot be changed after the order has been released.
+
+## Business Rules
+
+- Internal order must exist
+- Internal order must be in CREATED or RELEASED status
+- Description, responsible person, cost center, and validity dates can be updated in CREATED or RELEASED status
+- Order type cannot be changed after the order is released
+- Orders in TECHNICALLY_COMPLETED or CLOSED status cannot be updated
+- When updating validity dates, validFrom must precede validTo when both are set
+- Updated cost center must belong to the same company
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update internal order request] --> B{Internal order exists?}
+    B -->|No| C[Return error: INTERNAL_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is CREATED or RELEASED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Order type change attempted after release?}
+    F -->|Yes| G[Return error: ORDER_TYPE_CHANGE_NOT_ALLOWED]
+    F -->|No| H{Cost center valid if changed?}
+    H -->|No| I[Return error: COST_CENTER_NOT_FOUND]
+    H -->|Yes| J{validFrom <= validTo when both set?}
+    J -->|No| K[Return error: INVALID_VALIDITY_PERIOD]
+    J -->|Yes| L[Apply updates to internal order]
+    L --> M[Emit audit event]
+    M --> N[Return updated internal order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INTERNAL_ORDER_NOT_FOUND**: Internal order with the specified ID does not exist
+- **INVALID_STATE**: Internal order is in TECHNICALLY_COMPLETED or CLOSED status and cannot be updated
+- **ORDER_TYPE_CHANGE_NOT_ALLOWED**: Order type cannot be changed after the order is released
+- **COST_CENTER_NOT_FOUND**: Updated cost center does not exist or does not belong to the same company
+- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo
+
+## Test Cases
+
+- updates description on a CREATED internal order
+- updates description on a RELEASED internal order
+- updates responsible person on a CREATED internal order
+- updates cost center on a CREATED internal order
+- updates validity dates on a CREATED internal order
+- returns error when internal order does not exist
+- returns error when internal order is TECHNICALLY_COMPLETED
+- returns error when internal order is CLOSED
+- returns error when changing order type after release
+- returns error when updated cost center does not exist
+- returns error when validFrom is after validTo
+- emits audit event recording previous and new field values

package/src/modules/accounting/docs/commands/UpdateProfitCenter.md

@@ -0,0 +1,56 @@
+# UpdateProfitCenter
+
+## Overview
+
+updateProfitCenter modifies fields on an existing profit center. In DRAFT status, all mutable fields can be updated. In ACTIVE status, only limited fields (description, responsible person) can be updated. INACTIVE profit centers cannot be updated.
+
+## Business Rules
+
+- Profit center must exist
+- Profit center must be in DRAFT or ACTIVE status
+- In DRAFT status: name, description, responsible person, validFrom, validTo can be updated
+- In ACTIVE status: only description and responsible person can be updated
+- When updating validTo, it must remain on or after validFrom
+- INACTIVE profit centers cannot be updated
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update profit center request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT or ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Status is ACTIVE and restricted field change?}
+    F -->|Yes| G[Return error: FIELD_NOT_UPDATABLE]
+    F -->|No| H{validTo >= validFrom when both set?}
+    H -->|No| I[Return error: INVALID_VALIDITY_PERIOD]
+    H -->|Yes| J[Apply updates to profit center]
+    J --> K[Emit audit event]
+    K --> L[Return updated profit center]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PROFIT_CENTER_NOT_FOUND**: Profit center with the specified ID does not exist
+- **INVALID_STATE**: Profit center is in INACTIVE status and cannot be updated
+- **FIELD_NOT_UPDATABLE**: Attempted to change a field that is not updatable in ACTIVE status
+- **INVALID_VALIDITY_PERIOD**: validTo is before validFrom
+
+## Test Cases
+
+- updates name on a DRAFT profit center
+- updates description on a DRAFT profit center
+- updates description on an ACTIVE profit center
+- updates responsible person on a DRAFT profit center
+- updates responsible person on an ACTIVE profit center
+- returns error when changing restricted fields on an ACTIVE profit center
+- returns error when profit center does not exist
+- returns error when profit center is INACTIVE
+- returns error when validTo is before validFrom
+- emits audit event recording previous and new field values

package/src/modules/accounting/docs/commands/ValidateAllocationCycle.md

@@ -0,0 +1,57 @@
+# ValidateAllocationCycle
+
+## Overview
+
+validateAllocationCycle transitions an allocation cycle from DRAFT status to VALIDATED status. Validation verifies that the cycle has at least one allocation rule and that receiver percentages sum to exactly 100% for each sender. Only DRAFT cycles can be validated.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in DRAFT status to be validated
+- Cycle must have at least one allocation rule
+- Allocation rule percentages for each sender must sum to exactly 100%
+- Percentage values must be positive (greater than zero)
+- Upon validation, the cycle becomes eligible for execution
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive validate allocation cycle request] --> B{Allocation cycle exists?}
+    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Has at least one allocation rule?}
+    F -->|No| G[Return error: NO_ALLOCATION_RULES]
+    F -->|Yes| P{All percentages positive?}
+    P -->|No| Q[Return error: INVALID_PERCENTAGE]
+    P -->|Yes| H{Percentages sum to 100% per sender?}
+    H -->|No| I[Return error: INVALID_PERCENTAGE_SUM]
+    H -->|Yes| J[Transition status from DRAFT to VALIDATED]
+    J --> K[Emit audit event]
+    K --> L[Return validated allocation cycle]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: Allocation cycle with the specified ID does not exist
+- **INVALID_STATE**: Allocation cycle is not in DRAFT status
+- **NO_ALLOCATION_RULES**: Cycle has no allocation rules defined
+- **INVALID_PERCENTAGE**: One or more percentage values are zero or negative
+- **INVALID_PERCENTAGE_SUM**: Allocation rule percentages for one or more senders do not sum to exactly 100%
+
+## Test Cases
+
+- validates a DRAFT allocation cycle with valid rules transitioning it to VALIDATED status
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in DRAFT status
+- returns error when cycle has no allocation rules
+- returns error when any percentage is zero or negative
+- returns error when percentages do not sum to 100% for a sender
+- validates with multiple senders each summing to 100%
+- emits audit event recording the status transition and acting user

package/src/modules/accounting/docs/features/budget-management.md

@@ -0,0 +1,147 @@
+# Budget Management
+
+## Overview
+
+Budget Management provides the planning and control capabilities of the accounting module, enabling organizations to create budgets with line items per cost element, manage approval workflows, track multiple budget versions, and compare budgeted amounts against actual postings from finance-ledger. A budget entity carries a name, budget holder, fiscal year, period range, total amount, status, version type, and a cost object reference (cost center, profit center, or internal order). Each budget contains one or more BudgetLineItem records that specify a cost element, planned amount, and accounting period. The corresponding GL account for each line item is derived automatically from the primary cost element's one-to-one GL account mapping defined in cost-element-management, ensuring a single authoritative planning axis while preserving traceability to the general ledger. A PlanVersion entity (BUDGET, FORECAST, or SIMULATION) supports multi-version planning so organizations can maintain an approved operating budget alongside rolling forecasts and what-if simulations.
+
+Budgets follow a five-stage lifecycle — DRAFT, SUBMITTED, APPROVED, ACTIVE, CLOSED — enforcing segregation of duties between budget creation, approval, and cost posting. Budgetary control (funds check) provides real-time validation that prevents transactions from exceeding approved budget amounts, using the BudgetAvailability formula: `Available = Budget - (Actual + Commitments + Encumbrances)`. Actual amounts are sourced from posted journal entries in finance-ledger. Commitments represent outstanding purchase order amounts received from the purchase module via commitment events; encumbrances represent purchase requisition amounts (future extension). This three-bucket model aligns with SAP availability control and Oracle budgetary control patterns. Budget periods reference finance-ledger FiscalYear and AccountingPeriod entities for period alignment, and budget lock at period-end integrates with finance-ledger period close. All budgets are scoped to a Company.
+
+## Business Purpose
+
+Organizations need a structured budgeting process to plan expenditures, control costs, and measure financial performance against targets:
+
+- **Expenditure planning**: Budgets translate strategic objectives into quantified financial plans by allocating planned amounts to cost elements across accounting periods, providing a financial roadmap for the fiscal year. The corresponding GL account is derived from each primary cost element's GL mapping, ensuring consistency between management and financial accounting without requiring dual-axis maintenance
+- **Approval workflow enforcement**: The DRAFT to SUBMITTED to APPROVED progression ensures budgets are reviewed and authorized before activation, enforcing segregation of duties required by SOX and internal control frameworks — budget approval must be separate from budget creation and cost posting
+- **Multi-version planning**: PlanVersion support (BUDGET, FORECAST, SIMULATION) allows organizations to maintain an approved operating budget alongside rolling forecasts and what-if simulations, enabling agile financial planning without altering the baseline commitment
+- **Budgetary control (funds check)**: Real-time validation prevents transactions from exceeding available budget using the formula `Available = Budget - (Actual + Commitments + Encumbrances)`. This three-bucket availability check catches overspend at entry time, including amounts committed via purchase orders that have not yet been invoiced, preventing the common failure mode where PO-committed funds are double-spent
+- **Commitment tracking**: Outstanding purchase order amounts are tracked as commitments that reduce available budget. When the purchase module confirms, receives, or invoices a PO, commitment amounts are consumed and reclassified as actuals. This integration requires consuming commitment events from the purchase module (PO confirmed, goods received, invoice matched)
+- **Budget vs. actual comparison**: Comparing budgeted amounts against actual postings from finance-ledger journal entries surfaces variances early, enabling corrective action before period close
+- **Cost object alignment**: Budgets reference cost centers, profit centers, or internal orders, linking financial plans to the organizational and project structures managed by the accounting module
+- **Period alignment with finance-ledger**: Budget periods reference FiscalYear and AccountingPeriod from finance-ledger, ensuring budget and actual data share the same temporal boundaries for accurate variance analysis
+- **Budget lock at period-end**: Closing a budget period prevents further modifications to planned amounts, integrating with finance-ledger period close to produce a frozen baseline for reporting and audit
+- **Audit trail**: Every lifecycle transition — creation, submission, approval, activation, closure — is recorded with the acting user and timestamp, supporting internal and external audit requirements
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createBudget
+    Draft --> Draft: updateBudget / addLineItem / removeLineItem
+    Draft --> Submitted: submitBudget
+    Submitted --> Approved: approveBudget
+    Submitted --> Draft: rejectBudget
+    Approved --> Active: activateBudget
+    Active --> Closed: closeBudget
+    Draft --> [*]: deleteBudget
+```
+
+```mermaid
+flowchart TD
+    A[Define budget scope: fiscal year, cost object, version type] --> B[Create Budget in DRAFT with header fields]
+    B --> C[Add BudgetLineItem records per cost element and period]
+    C --> D{All periods and cost elements covered?}
+    D -- No --> C
+    D -- Yes --> E[Submit budget for approval]
+    E --> F{Approver reviews budget}
+    F -- Reject --> G[Return to DRAFT with rejection reason]
+    G --> C
+    F -- Approve --> H[Budget status set to APPROVED]
+    H --> I[Activate budget for budgetary control]
+    I --> J[Funds check enabled: transactions validated against budget]
+    J --> K{Period-end reached?}
+    K -- No --> J
+    K -- Yes --> L[Lock budget period and run variance analysis]
+    L --> M{All periods complete?}
+    M -- No --> K
+    M -- Yes --> N[Close budget]
+```
+
+```mermaid
+flowchart TD
+    A[Transaction submitted against cost element] --> B{Budget exists and ACTIVE for cost object?}
+    B -- No --> C[Transaction proceeds without funds check]
+    B -- Yes --> D[Compute BudgetAvailability]
+    D --> D1[Available = Budget - Actual + Commitments + Encumbrances]
+    D1 --> E{Available >= transaction amount?}
+    E -- Yes --> F[Transaction passes funds check]
+    E -- No --> G[Transaction rejected: budget exceeded]
+```
+
+```mermaid
+flowchart TD
+    A[Purchase Order confirmed in purchase module] --> B[Commitment event received by accounting]
+    B --> C[Record commitment amount against cost element + cost object + period]
+    C --> D[BudgetAvailability reduced by commitment amount]
+    D --> E{Goods receipt or invoice posted?}
+    E -- Goods Receipt --> F[Reduce commitment, increase actual by received amount]
+    E -- Invoice Matched --> G[Reduce remaining commitment, actual reflects invoiced amount]
+    E -- PO Cancelled --> H[Release commitment amount back to available budget]
+```
+
+## Scenario Patterns
+
+- **Annual Operating Budget Creation**: A finance manager creates a new budget for fiscal year 2026 scoped to a cost center, adds line items for each cost element (salaries, travel, office supplies) distributed across twelve monthly periods, submits for department head approval, and activates upon approval to enable funds checking
+- **Rolling Forecast Update**: A financial analyst creates a FORECAST plan version based on the approved BUDGET version, adjusts planned amounts for Q3 and Q4 to reflect revised revenue projections, and submits the forecast for review — the original BUDGET version remains unchanged as the committed baseline
+- **What-If Simulation**: A planning team creates a SIMULATION plan version to model the financial impact of opening a new office, copying the current budget as a base and adding incremental line items for rent, staffing, and equipment — the simulation is never activated but serves as decision support
+- **Budget Rejection and Revision**: A department submits a budget that exceeds the company-wide allocation. The finance director rejects it with a note to reduce travel expenses by 15%. The budget returns to DRAFT, the submitter adjusts the travel line items, and resubmits for approval
+- **Funds Check Blocking an Overspend**: An employee submits a purchase order for office furniture. The funds check computes BudgetAvailability as `Budget - (Actual + Commitments + Encumbrances)` for the office supplies cost element in the current period. The available budget is insufficient after accounting for existing PO commitments, and the transaction is rejected with a budget exceeded error
+- **Commitment Tracking from Purchase Orders**: A department issues a PO for consulting services worth $50,000. The purchase module emits a commitment event, and accounting records a $50,000 commitment against the consulting cost element budget. When the first invoice for $20,000 is matched, the commitment reduces by $20,000 and actual increases by $20,000, keeping BudgetAvailability unchanged. When the PO is fully invoiced, the commitment reaches zero
+- **Mid-Year Budget Transfer**: A budget holder reallocates planned amounts between cost elements within the same budget (e.g., moving unused travel budget to training) by updating line items while the budget is ACTIVE, subject to approval controls
+- **Budget vs. Actual Variance Report**: At month-end, a controller compares budgeted amounts against actual postings from finance-ledger journal entries for each cost element and period. The comparison highlights a 20% overrun in consulting expenses, triggering a management review
+- **Period-End Budget Lock**: As the finance-ledger accounting period for January is closed, the corresponding budget period is locked, freezing planned amounts for January and preventing retroactive adjustments to the baseline
+- **Multi-Cost-Object Budgeting**: A company creates separate budgets for three profit centers within the same fiscal year, each with its own line items and approval chain, enabling decentralized budget ownership while maintaining company-level consolidation
+
+## Test Cases
+
+- Budget lifecycle follows DRAFT -> SUBMITTED -> APPROVED -> ACTIVE -> CLOSED state machine
+- Budget can only be created in DRAFT status
+- Budget requires a valid companyId; the company must be in ACTIVE status
+- Budget requires a valid fiscal year reference from finance-ledger
+- Budget requires a name, budget holder, and cost object reference (cost center, profit center, or internal order)
+- Budget must reference a valid PlanVersion (BUDGET, FORECAST, or SIMULATION)
+- A DRAFT budget can be updated (name, description, budget holder, line items)
+- A DRAFT budget can be deleted; deletion removes all associated line items
+- Submitting a budget transitions status from DRAFT to SUBMITTED
+- A budget with no line items cannot be submitted
+- Only a user different from the budget creator can approve the budget (segregation of duties)
+- Approving a budget transitions status from SUBMITTED to APPROVED
+- Rejecting a budget transitions status from SUBMITTED back to DRAFT
+- Rejection requires a reason text
+- Activating an APPROVED budget transitions status to ACTIVE and enables funds checking
+- Only one ACTIVE budget of type BUDGET can exist per cost object per fiscal year
+- Multiple FORECAST or SIMULATION versions can coexist for the same cost object and fiscal year
+- Closing an ACTIVE budget transitions status to CLOSED; no further modifications are permitted
+- A CLOSED budget cannot be reopened
+- BudgetLineItem requires a valid cost element reference; the cost element must be a PRIMARY type in ACTIVE status
+- BudgetLineItem derives its GL account automatically from the referenced primary cost element's GL account mapping; no separate GL account field is required
+- BudgetLineItem requires a valid accounting period reference from finance-ledger
+- BudgetLineItem planned amount must be a positive value
+- Line items can be added to or removed from a DRAFT budget
+- Line items cannot be added to or removed from a SUBMITTED, APPROVED, or CLOSED budget
+- Duplicate line items (same account and period) within a single budget are rejected
+- Funds check computes BudgetAvailability as `Budget - (Actual + Commitments + Encumbrances)` for the target cost element, period, and cost object
+- A transaction that exceeds BudgetAvailability is rejected with a budget exceeded error when budgetary control is active
+- A transaction against a cost element with no corresponding budget line item is flagged as unbudgeted
+- Commitment amounts are recorded when a purchase order confirmation event is received from the purchase module
+- Commitment amounts are reduced and actual amounts are increased when a goods receipt or invoice match event is received from the purchase module
+- Commitment amounts are fully released when a purchase order cancellation event is received from the purchase module
+- Encumbrances (purchase requisition amounts) are tracked as a future extension; the availability formula reserves the field but the initial implementation treats encumbrances as zero
+- Budget vs. actual comparison retrieves actual amounts from finance-ledger posted journal entries matching the budget's cost object, cost element, and period
+- Variance is computed as planned amount minus actual amount; positive variance indicates underspend, negative indicates overspend
+- Budget periods align with finance-ledger AccountingPeriod boundaries; misaligned periods are rejected
+- Locking a budget period prevents further modifications to planned amounts for that period
+- Budget lock integrates with finance-ledger period close; closing an accounting period triggers the corresponding budget period lock
+- PlanVersion of type FORECAST or SIMULATION can reference a base version from which line items are copied
+- Creating a budget emits an audit event recording the acting user, timestamp, and initial field values
+- Submitting, approving, rejecting, activating, and closing a budget each emit audit events recording the status transition and acting user
+- Budgets are scoped to a company; budgets from different companies are fully isolated
+- Only users with appropriate permissions can create, submit, approve, activate, or close budgets
+- Unauthorized users receive a permission denied error when attempting budget operations
+
+## Reference Links
+
+- [SAP S/4HANA Budget Management and Availability Control](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/4dbfa293944e410aa3ca0e0905bda494/d0b843994f0d1014a585e2078de58ced.html)
+- [Oracle Fusion Financials Budgetary Control](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/budgetary-control.html)
+- [Odoo Budget Management](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/budget.html)
+- [NetSuite Budgets Overview](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N2169498.html)
+- [Sage Intacct Budgeting and Planning](https://www.sage.com/en-us/sage-business-cloud/intacct/features/budgeting-and-planning/)