@tailor-platform/erp-kit 0.6.0 → 0.8.0

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

@@ -0,0 +1,83 @@
+# GenerateVarianceReport
+
+## Overview
+
+generateVarianceReport creates a variance report in DRAFT status for a specific cost object and accounting period. The command collects actual amounts from posted journal entries in finance-ledger, retrieves planned amounts from budget line items, calculates variance per cost element, categorizes variance direction (FAVORABLE or UNFAVORABLE based on account type), and computes variance percentages. Division by zero is handled gracefully when the planned amount is zero.
+
+## Business Rules
+
+- Requires a valid `companyId` referencing an ACTIVE company
+- Requires a valid `accountingPeriodId` referencing an existing accounting period
+- Requires a valid cost object reference (cost center, profit center, or internal order)
+- Report is created in DRAFT status
+- Actual amounts are sourced exclusively from POSTED journal entries in finance-ledger (DRAFT entries are excluded)
+- Actual amounts are aggregated by cost element, cost object, and accounting period
+- Planned amounts are sourced from budget line items, matched by cost element
+- Variance amount per cost element is calculated as actual minus planned
+- Variance percentage is calculated as (actual - planned) / planned * 100
+- When planned amount is zero and actual is non-zero, variance percentage is handled gracefully (not division by zero)
+- For cost/expense elements: FAVORABLE when actual < planned, UNFAVORABLE when actual > planned
+- For revenue elements: FAVORABLE when actual > planned, UNFAVORABLE when actual < planned
+- When actual equals planned, variance is zero and direction is FAVORABLE
+- A VarianceReportLine is created for each cost element with either a planned or actual amount (or both)
+- A cost element with actual postings but no budget line item generates a line with zero planned amount
+- Summary totals (total planned, total actual, total variance) are computed from the sum of detail lines
+- Budget line items must exist for the specified cost object and period
+- Regenerating for the same cost object and period replaces an existing DRAFT report
+- A FINAL report is not overwritten; a new DRAFT is created alongside it
+- Emits an audit event recording the report generation and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive generate variance report request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Accounting period exists?}
+    D -->|No| E[Return error: ACCOUNTING_PERIOD_NOT_FOUND]
+    D -->|Yes| F{Cost object exists?}
+    F -->|No| G[Return error: COST_OBJECT_NOT_FOUND]
+    F -->|Yes| H{Budget line items exist for cost object and period?}
+    H -->|No| I[Return error: NO_BUDGET_DATA]
+    H -->|Yes| J[Collect actual amounts from POSTED journal entries]
+    J --> K[Collect planned amounts from budget line items]
+    K --> L[Calculate variance per cost element: actual - planned]
+    L --> M[Calculate variance percentage per cost element]
+    M --> N[Categorize direction: FAVORABLE or UNFAVORABLE]
+    N --> O[Create VarianceReportLine per cost element]
+    O --> P[Compute summary totals from detail lines]
+    P --> Q[Create VarianceReport in DRAFT status]
+    Q --> R[Emit audit event]
+    R --> S[Return generated variance report]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the referenced accounting period exists
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **COST_OBJECT_NOT_FOUND**: Referenced cost object (cost center, profit center, or internal order) does not exist
+- **NO_BUDGET_DATA**: No budget line items exist for the specified cost object and period
+
+## Test Cases
+
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when accounting period does not exist
+- returns error when cost object does not exist
+- returns error when no budget line items exist for the cost object and period
+- generates a variance report in DRAFT status for a cost center
+- calculates variance as actual minus planned per cost element
+- handles division by zero when planned amount is zero
+- sets variance direction to FAVORABLE when actual equals planned
+- categorizes cost/expense variance as FAVORABLE when actual is less than planned
+- categorizes revenue variance as FAVORABLE when actual is greater than planned
+- creates a line for actual postings without a matching budget line item
+- computes summary totals from the sum of detail lines
+- replaces existing DRAFT report when regenerating for same cost object and period
+- does not overwrite a FINAL report when regenerating
+- emits audit event recording the report generation and acting user

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

@@ -0,0 +1,45 @@
+# InvalidateAllocationCycle
+
+## Overview
+
+invalidateAllocationCycle transitions an allocation cycle from VALIDATED status back to DRAFT status, allowing further editing of allocation rules. This enables corrections before execution.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in VALIDATED status to be invalidated
+- Invalidating a cycle in any other status is rejected as an invalid state transition
+- Upon invalidation, rules can be added, modified, or removed again
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive invalidate allocation cycle request] --> B{Allocation cycle exists?}
+    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
+    B -->|Yes| D{Status is VALIDATED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from VALIDATED to DRAFT]
+    F --> G[Emit audit event]
+    G --> H[Return invalidated 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 VALIDATED status
+
+## Test Cases
+
+- invalidates a VALIDATED allocation cycle transitioning it to DRAFT status
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is in DRAFT 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 the status transition and acting user

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

@@ -0,0 +1,51 @@
+# MoveCostCenterHierarchyNode
+
+## Overview
+
+moveCostCenterHierarchyNode relocates an existing node to a different parent within the same cost center hierarchy. The move must not introduce a circular reference in the hierarchy tree structure. This enables reorganization of the cost center grouping structure without recreating nodes.
+
+## Business Rules
+
+- Node must exist
+- New parent node must exist within the same hierarchy
+- Node cannot be moved to itself as parent (no self-referencing)
+- Move must not create a circular reference (the new parent cannot be a descendant of the node being moved)
+- All child nodes and assigned cost centers move with the node
+- Emits an audit event recording the move and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive move hierarchy node request] --> B{Node exists?}
+    B -->|No| C[Return error: NODE_NOT_FOUND]
+    B -->|Yes| D{New parent node exists?}
+    D -->|No| E[Return error: PARENT_NODE_NOT_FOUND]
+    D -->|Yes| F{Self-referencing?}
+    F -->|Yes| G[Return error: SELF_REFERENCE]
+    F -->|No| H{Circular reference?}
+    H -->|Yes| I[Return error: CIRCULAR_REFERENCE]
+    H -->|No| J[Move node to new parent]
+    J --> K[Emit audit event]
+    K --> L[Return moved node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Hierarchy node with the specified ID does not exist
+- **PARENT_NODE_NOT_FOUND**: New parent node does not exist within the hierarchy
+- **SELF_REFERENCE**: Node cannot be moved to itself as parent
+- **CIRCULAR_REFERENCE**: Moving the node would introduce a circular reference (new parent is a descendant of the node)
+
+## Test Cases
+
+- returns error for self-reference
+- returns error when node does not exist
+- returns error when new parent is not in same hierarchy
+- returns error for circular reference (moving parent under its child)
+- moves node to new parent successfully
+- updates level based on new parent level

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

@@ -0,0 +1,58 @@
+# PostAllocationCycle
+
+## Overview
+
+postAllocationCycle transitions an allocation cycle from EXECUTED to POSTED status by creating journal entries through the finance-ledger module. For ASSESSMENT type allocations, journal entries use secondary cost elements. For DISTRIBUTION type allocations, journal entries preserve the original primary cost elements. The accounting period must be in OPEN or FUTURE_ENTERABLE status.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in EXECUTED status to be posted
+- Posting creates journal entries through the finance-ledger subledger integration
+- Assessment-type allocations use secondary cost elements in generated journal entries
+- Distribution-type allocations preserve original primary cost elements in generated journal entries
+- The accounting period must be in OPEN or FUTURE_ENTERABLE status
+- Posting to a CLOSED or PERMANENTLY_CLOSED period is rejected
+- Journal entries reference the allocation cycle as the source document
+- Transitions status from EXECUTED to POSTED
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive post allocation cycle request] --> B{Allocation cycle exists?}
+    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
+    B -->|Yes| D{Status is EXECUTED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Accounting period is OPEN or FUTURE_ENTERABLE?}
+    F -->|No| G[Return error: PERIOD_NOT_OPEN]
+    F -->|Yes| H{Allocation type?}
+    H -->|ASSESSMENT| I[Create journal entries with secondary cost elements]
+    H -->|DISTRIBUTION| J[Create journal entries with primary cost elements]
+    I --> K[Post journal entries via finance-ledger]
+    J --> K
+    K --> L[Transition status from EXECUTED to POSTED]
+    L --> M[Emit audit event]
+    M --> N[Return posted allocation cycle]
+```
+
+## External Dependencies
+
+- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the accounting period is in OPEN or FUTURE_ENTERABLE status
+- [finance-ledger::createJournalEntry](../../../finance-ledger/docs/commands/CreateJournalEntry.md) — Creates journal entries for the allocation postings
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: Allocation cycle with the specified ID does not exist
+- **INVALID_STATE**: Allocation cycle is not in EXECUTED status
+- **PERIOD_NOT_OPEN**: Accounting period is not in OPEN or FUTURE_ENTERABLE status (e.g., CLOSED or PERMANENTLY_CLOSED)
+
+## Test Cases
+
+- posts an EXECUTED allocation cycle transitioning it to POSTED status
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in EXECUTED status
+- returns error when accounting period is CLOSED
+- returns error when accounting period is PERMANENTLY_CLOSED
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,43 @@
+# ReactivateCostElement
+
+## Overview
+
+reactivateCostElement transitions a cost element from INACTIVE status back to ACTIVE status, making it available again for cost postings and allocations. Only cost elements currently in INACTIVE status can be reactivated.
+
+## Business Rules
+
+- Cost element must exist
+- Cost element must be in INACTIVE status to be reactivated
+- Reactivating a DRAFT or already ACTIVE cost element is rejected as an invalid state transition
+- Upon reactivation, the cost element becomes available for cost postings and allocations again
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate cost element request] --> B{Cost element exists?}
+    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from INACTIVE to ACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return reactivated cost element]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_ELEMENT_NOT_FOUND**: Cost element with the specified ID does not exist
+- **INVALID_STATE**: Cost element is not in INACTIVE status (e.g., DRAFT or already ACTIVE)
+
+## Test Cases
+
+- reactivates an INACTIVE cost element transitioning it to ACTIVE status
+- returns error when cost element does not exist
+- returns error when cost element is in DRAFT status
+- returns error when cost element is already ACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,43 @@
+# ReactivateProfitCenter
+
+## Overview
+
+reactivateProfitCenter transitions a profit center from INACTIVE status back to ACTIVE status, making it available again for transaction assignments and profitability reporting. Only profit centers currently in INACTIVE status can be reactivated.
+
+## Business Rules
+
+- Profit center must exist
+- Profit center must be in INACTIVE status to be reactivated
+- Reactivating a DRAFT or already ACTIVE profit center is rejected as an invalid state transition
+- Upon reactivation, the profit center becomes available for transaction assignments again
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate profit center request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from INACTIVE to ACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return reactivated 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 not in INACTIVE status (e.g., DRAFT or already ACTIVE)
+
+## Test Cases
+
+- reactivates an INACTIVE profit center transitioning it to ACTIVE status
+- returns error when profit center does not exist
+- returns error when profit center is in DRAFT status
+- returns error when profit center is already ACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,60 @@
+# RecordCommitment
+
+## Overview
+
+recordCommitment records a purchase order commitment against a specific cost element, cost object, and accounting period. Commitments reduce budget availability by reserving funds for outstanding purchase orders that have not yet been invoiced. This is triggered when a purchase order confirmation event is received.
+
+## Business Rules
+
+- Requires a valid cost element reference
+- Requires a valid cost object reference (cost center, profit center, or internal order)
+- Requires a valid accounting period reference
+- Requires a positive commitment amount
+- Commitment reduces budget availability using the formula: Available = Budget - (Actual + Commitments + Encumbrances)
+- Commitment is associated with a purchase order reference for traceability
+- An ACTIVE budget must exist for the cost object to record commitments against
+- Emits an audit event recording the commitment and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive record commitment request] --> B{Cost element exists?}
+    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
+    B -->|Yes| D{Cost object exists?}
+    D -->|No| E[Return error: COST_OBJECT_NOT_FOUND]
+    D -->|Yes| F{Accounting period exists?}
+    F -->|No| G[Return error: ACCOUNTING_PERIOD_NOT_FOUND]
+    F -->|Yes| H{Commitment amount positive?}
+    H -->|No| I[Return error: INVALID_COMMITMENT_AMOUNT]
+    H -->|Yes| J{Active budget exists for cost object?}
+    J -->|No| K[Return error: NO_ACTIVE_BUDGET]
+    J -->|Yes| L[Record commitment amount]
+    L --> M[Reduce budget availability]
+    M --> N[Emit audit event]
+    N --> O[Return recorded commitment]
+```
+
+## External Dependencies
+
+- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the referenced accounting period exists
+
+## Error Scenarios
+
+- **COST_ELEMENT_NOT_FOUND**: Referenced cost element does not exist
+- **COST_OBJECT_NOT_FOUND**: Referenced cost object does not exist
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **INVALID_COMMITMENT_AMOUNT**: Commitment amount is not positive
+- **NO_ACTIVE_BUDGET**: No active budget exists for the specified cost object
+
+## Test Cases
+
+- records a commitment against a cost element, cost object, and period
+- reduces budget availability by the commitment amount
+- returns error when cost element does not exist
+- returns error when cost object does not exist
+- returns error when accounting period does not exist
+- returns error when commitment amount is zero or negative
+- returns error when no active budget exists for the cost object
+- associates commitment with purchase order reference
+- emits audit event recording the commitment and acting user

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

@@ -0,0 +1,49 @@
+# RejectBudget
+
+## Overview
+
+rejectBudget transitions a budget from SUBMITTED status back to DRAFT status, allowing the submitter to revise and resubmit. A rejection reason text is required to communicate the basis for rejection.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in SUBMITTED status to be rejected
+- Requires a `reason` text explaining the basis for rejection
+- Transitions status from SUBMITTED back to DRAFT
+- Upon rejection, the budget can be updated and resubmitted
+- Emits an audit event recording the status transition, reason, and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reject budget request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is SUBMITTED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Reason text provided?}
+    F -->|No| G[Return error: REASON_REQUIRED]
+    F -->|Yes| H[Transition status from SUBMITTED to DRAFT]
+    H --> I[Emit audit event]
+    I --> J[Return rejected budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in SUBMITTED status
+- **REASON_REQUIRED**: Rejection reason text is missing or empty
+
+## Test Cases
+
+- rejects a SUBMITTED budget transitioning it to DRAFT status with reason
+- returns error when budget does not exist
+- returns error when budget is not in SUBMITTED status
+- returns error when reason text is missing
+- reason is persisted to the budget
+- rejected budget can be updated and resubmitted
+- emits audit event recording the status transition, reason, and acting user

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

@@ -0,0 +1,45 @@
+# ReleaseCommitment
+
+## Overview
+
+releaseCommitment releases a commitment back to available budget when a purchase order is cancelled. This restores budget availability by removing the reserved commitment amount. The full remaining commitment amount is released.
+
+## Business Rules
+
+- Commitment must exist for the specified cost element, cost object, and period
+- Releases the full remaining commitment amount back to available budget
+- Budget availability increases by the released amount
+- Commitment is associated with a purchase order cancellation event
+- Emits an audit event recording the release and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive release commitment request] --> B{Commitment exists?}
+    B -->|No| C[Return error: COMMITMENT_NOT_FOUND]
+    B -->|Yes| D{Remaining commitment amount > 0?}
+    D -->|No| E[Return error: NO_COMMITMENT_TO_RELEASE]
+    D -->|Yes| F[Release remaining commitment amount]
+    F --> G[Increase budget availability]
+    G --> H[Emit audit event]
+    H --> I[Return released commitment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMMITMENT_NOT_FOUND**: No commitment exists for the specified cost element, cost object, and period
+- **NO_COMMITMENT_TO_RELEASE**: Commitment has already been fully consumed or released (remaining amount is zero)
+
+## Test Cases
+
+- releases remaining commitment amount back to available budget
+- increases budget availability by the released amount
+- returns error when commitment does not exist
+- returns error when commitment has already been fully consumed
+- releases a partially consumed commitment (only remaining portion)
+- emits audit event recording the release and acting user

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

@@ -0,0 +1,44 @@
+# ReleaseInternalOrder
+
+## Overview
+
+releaseInternalOrder transitions an internal order from CREATED status to RELEASED status. Once released, the order is enabled for cost postings. Only orders in CREATED status can be released.
+
+## Business Rules
+
+- Internal order must exist
+- Internal order must be in CREATED status to be released
+- Releasing a RELEASED, TECHNICALLY_COMPLETED, or CLOSED order is rejected as an invalid state transition
+- Upon release, cost postings against the order are enabled
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive release internal order request] --> B{Internal order exists?}
+    B -->|No| C[Return error: INTERNAL_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is CREATED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from CREATED to RELEASED]
+    F --> G[Emit audit event]
+    G --> H[Return released 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 CREATED status
+
+## Test Cases
+
+- releases a CREATED internal order transitioning it to RELEASED status
+- returns error when internal order does not exist
+- returns error when internal order is already RELEASED
+- returns error when internal order is 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/ReverseAllocationCycle.md

@@ -0,0 +1,55 @@
+# ReverseAllocationCycle
+
+## Overview
+
+reverseAllocationCycle transitions an allocation cycle from POSTED to REVERSED status by creating reversal journal entries with inverted amounts. This offsets the original allocation postings to zero. An already REVERSED cycle cannot be reversed again. The reversal period must be in OPEN or FUTURE_ENTERABLE status.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in POSTED status to be reversed
+- Reversing an already REVERSED cycle is rejected
+- Creates reversal journal entries with inverted (negated) amounts
+- Reversal journal entries must target a period that is in OPEN or FUTURE_ENTERABLE status
+- Transitions status from POSTED to REVERSED
+- Original allocation postings remain in the ledger for auditability
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reverse allocation cycle request] --> B{Allocation cycle exists?}
+    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
+    B -->|Yes| D{Status is POSTED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Reversal period is OPEN or FUTURE_ENTERABLE?}
+    F -->|No| G[Return error: PERIOD_NOT_OPEN]
+    F -->|Yes| H[Create reversal journal entries with inverted amounts]
+    H --> I[Post reversal entries via finance-ledger]
+    I --> J[Transition status from POSTED to REVERSED]
+    J --> K[Emit audit event]
+    K --> L[Return reversed allocation cycle]
+```
+
+## External Dependencies
+
+- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the reversal period is in OPEN or FUTURE_ENTERABLE status
+- [finance-ledger::createJournalEntry](../../../finance-ledger/docs/commands/CreateJournalEntry.md) — Creates reversal journal entries
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: Allocation cycle with the specified ID does not exist
+- **INVALID_STATE**: Allocation cycle is not in POSTED status (e.g., DRAFT, VALIDATED, EXECUTED, or already REVERSED)
+- **PERIOD_NOT_OPEN**: Reversal period is not in OPEN or FUTURE_ENTERABLE status
+
+## Test Cases
+
+- reverses a POSTED allocation cycle transitioning it to REVERSED status
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in POSTED status
+- returns error when allocation cycle is already REVERSED
+- returns error when reversal period is not OPEN or FUTURE_ENTERABLE
+- returns error when allocation cycle is in DRAFT status
+- returns error when allocation cycle is in VALIDATED status
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,47 @@
+# SubmitBudget
+
+## Overview
+
+submitBudget transitions a budget from DRAFT status to SUBMITTED status, initiating the approval workflow. The budget must have at least one line item before it can be submitted.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in DRAFT status to be submitted
+- Budget must have at least one line item
+- Submitting a budget without line items is rejected
+- Transitions status from DRAFT to SUBMITTED
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive submit 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{Has at least one line item?}
+    F -->|No| G[Return error: NO_LINE_ITEMS]
+    F -->|Yes| H[Transition status from DRAFT to SUBMITTED]
+    H --> I[Emit audit event]
+    I --> J[Return submitted 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
+- **NO_LINE_ITEMS**: Budget has no line items and cannot be submitted
+
+## Test Cases
+
+- submits a DRAFT budget with line items transitioning it to SUBMITTED status
+- returns error when budget does not exist
+- returns error when budget is not in DRAFT status
+- returns error when budget has no line items
+- emits audit event recording the status transition and acting user