@tailor-platform/erp-kit 0.7.0 → 0.9.0

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

@@ -0,0 +1,43 @@
+# DeactivateCostElement
+
+## Overview
+
+deactivateCostElement transitions a cost element from ACTIVE status to INACTIVE status. Once inactive, the cost element can no longer be used for new cost postings or allocations. Historical postings referencing this element remain intact.
+
+## Business Rules
+
+- Cost element must exist
+- Cost element must be in ACTIVE status to be deactivated
+- Deactivating a DRAFT or already INACTIVE cost element is rejected as an invalid state transition
+- Existing historical postings referencing this cost element are not affected
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate cost element request] --> B{Cost element exists?}
+    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from ACTIVE to INACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return deactivated 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 ACTIVE status (e.g., DRAFT or already INACTIVE)
+
+## Test Cases
+
+- deactivates an ACTIVE cost element transitioning it to INACTIVE 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 INACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,44 @@
+# DeactivateProfitCenter
+
+## Overview
+
+deactivateProfitCenter transitions a profit center from ACTIVE status to INACTIVE status. Once inactive, the profit center can no longer receive new transaction assignments. Historical transactions referencing this profit center remain intact. Only ACTIVE profit centers can be deactivated; deactivating a DRAFT profit center is not permitted.
+
+## Business Rules
+
+- Profit center must exist
+- Profit center must be in ACTIVE status to be deactivated
+- Deactivating a DRAFT profit center is rejected as an invalid state transition
+- Deactivating an already INACTIVE profit center is rejected as an invalid state transition
+- Existing historical transactions referencing this profit center are not affected
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate profit center request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from ACTIVE to INACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return deactivated 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 ACTIVE status (e.g., DRAFT or already INACTIVE)
+
+## Test Cases
+
+- deactivates an ACTIVE profit center transitioning it to INACTIVE 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 INACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,46 @@
+# DeleteAllocationCycle
+
+## Overview
+
+deleteAllocationCycle permanently removes an allocation cycle that is in DRAFT status. Cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status cannot be deleted.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Only DRAFT allocation cycles can be deleted
+- Cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status cannot be deleted
+- Deletion removes the cycle and all associated allocation rules
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete 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[Delete allocation cycle and associated rules]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## 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
+
+- deletes a DRAFT allocation cycle successfully
+- deletes a DRAFT allocation cycle and removes associated rules
+- 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 the deletion and acting user

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

@@ -0,0 +1,45 @@
+# DeleteAllocationRule
+
+## Overview
+
+deleteAllocationRule removes an allocation rule from an allocation cycle. Rules can only be removed when the cycle is in DRAFT status.
+
+## Business Rules
+
+- Allocation rule must exist
+- Parent allocation cycle must be in DRAFT status
+- Rules cannot be removed from cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status
+- Deletion permanently removes the rule from the cycle
+- Emits an audit event recording the rule deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete allocation rule request] --> B{Allocation rule exists?}
+    B -->|No| C[Return error: ALLOCATION_RULE_NOT_FOUND]
+    B -->|Yes| D{Parent cycle status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Delete allocation rule]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ALLOCATION_RULE_NOT_FOUND**: Allocation rule with the specified ID does not exist
+- **INVALID_STATE**: Parent allocation cycle is not in DRAFT status
+
+## Test Cases
+
+- deletes an allocation rule from a DRAFT allocation cycle
+- returns error when allocation rule does not exist
+- returns error when parent cycle is in VALIDATED status
+- returns error when parent cycle is in EXECUTED status
+- returns error when parent cycle is in POSTED status
+- returns error when parent cycle is in REVERSED status
+- emits audit event recording the rule deletion and acting user

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

@@ -0,0 +1,46 @@
+# DeleteBudget
+
+## Overview
+
+deleteBudget permanently removes a budget that is in DRAFT status. Deletion also removes all associated line items. Budgets in SUBMITTED, APPROVED, ACTIVE, or CLOSED status cannot be deleted.
+
+## Business Rules
+
+- Budget must exist
+- Only DRAFT budgets can be deleted
+- Budgets in SUBMITTED, APPROVED, ACTIVE, or CLOSED status cannot be deleted
+- Deletion removes the budget and all associated line items
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete 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[Delete budget and all associated line items]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## 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
+
+- deletes a DRAFT budget successfully
+- deletes a DRAFT budget and removes all associated line items
+- 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 the deletion and acting user

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

@@ -0,0 +1,45 @@
+# DeleteBudgetLineItem
+
+## Overview
+
+deleteBudgetLineItem removes a line item from a budget. Line items can only be removed when the parent budget is in DRAFT status.
+
+## Business Rules
+
+- Budget line item must exist
+- Parent budget must be in DRAFT status
+- Line items cannot be removed from budgets in SUBMITTED, APPROVED, ACTIVE, or CLOSED status
+- Deletion permanently removes the line item from the budget
+- Emits an audit event recording the line item deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete budget line item request] --> B{Budget line item exists?}
+    B -->|No| C[Return error: BUDGET_LINE_ITEM_NOT_FOUND]
+    B -->|Yes| D{Parent budget status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Delete budget line item]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_LINE_ITEM_NOT_FOUND**: Budget line item with the specified ID does not exist
+- **INVALID_STATE**: Parent budget is not in DRAFT status
+
+## Test Cases
+
+- deletes a line item from a DRAFT budget
+- returns error when budget line item does not exist
+- returns error when parent budget is in SUBMITTED status
+- returns error when parent budget is in APPROVED status
+- returns error when parent budget is in ACTIVE status
+- returns error when parent budget is in CLOSED status
+- emits audit event recording the line item deletion and acting user

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

@@ -0,0 +1,50 @@
+# DeleteCostCenter
+
+## Overview
+
+deleteCostCenter permanently removes a cost center. A cost center can only be deleted if it has no associated cost postings, budget line items, or allocation rules referencing it. This prevents orphaning of financial records and ensures data integrity.
+
+## Business Rules
+
+- Cost center must exist
+- Cost center must have no associated cost postings
+- Cost center must have no associated budget line items
+- Cost center must have no associated allocation rules referencing it
+- Deletion permanently removes the cost center record
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete cost center request] --> B{Cost center exists?}
+    B -->|No| C[Return error: COST_CENTER_NOT_FOUND]
+    B -->|Yes| D{Has associated cost postings?}
+    D -->|Yes| E[Return error: COST_CENTER_HAS_POSTINGS]
+    D -->|No| F{Has associated budget line items?}
+    F -->|Yes| G[Return error: COST_CENTER_HAS_BUDGET_ITEMS]
+    F -->|No| H{Has associated allocation rules?}
+    H -->|Yes| I[Return error: COST_CENTER_HAS_ALLOCATION_RULES]
+    H -->|No| J[Delete cost center]
+    J --> K[Emit audit event]
+    K --> L[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_NOT_FOUND**: Cost center with the specified ID does not exist
+- **COST_CENTER_HAS_POSTINGS**: Cost center has associated cost postings and cannot be deleted
+- **COST_CENTER_HAS_BUDGET_ITEMS**: Cost center has associated budget line items and cannot be deleted
+- **COST_CENTER_HAS_ALLOCATION_RULES**: Cost center is referenced by allocation rules and cannot be deleted
+
+## Test Cases
+
+- returns error when cost center does not exist
+- returns error when cost center has postings
+- returns error when cost center has budget items
+- returns error when cost center has allocation rules
+- deletes cost center when no dependencies exist

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

@@ -0,0 +1,45 @@
+# DeleteCostCenterHierarchyNode
+
+## Overview
+
+deleteCostCenterHierarchyNode removes a node from a cost center hierarchy. A node can only be deleted if it has no child nodes and no cost centers assigned to it. This prevents orphaning of child structures and ensures data integrity.
+
+## Business Rules
+
+- Hierarchy node must exist
+- Node must have no child nodes; nodes with children cannot be deleted
+- Node must have no cost centers assigned to it; nodes with assigned cost centers cannot be deleted
+- Deletion permanently removes the node from the hierarchy
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete hierarchy node request] --> B{Node exists?}
+    B -->|No| C[Return error: NODE_NOT_FOUND]
+    B -->|Yes| D{Node has child nodes?}
+    D -->|Yes| E[Return error: NODE_HAS_CHILDREN]
+    D -->|No| F{Node has assigned cost centers?}
+    F -->|Yes| G[Return error: NODE_HAS_ASSIGNED_COST_CENTERS]
+    F -->|No| H[Delete hierarchy node]
+    H --> I[Emit audit event]
+    I --> J[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Hierarchy node with the specified ID does not exist
+- **NODE_HAS_CHILDREN**: Node has child nodes that must be reassigned or removed first
+- **NODE_HAS_ASSIGNED_COST_CENTERS**: Node has cost centers assigned that must be reassigned first
+
+## Test Cases
+
+- returns error when node does not exist
+- returns error when node has children
+- returns error when node has assigned cost centers
+- deletes node when it has no children and no assigned cost centers

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

@@ -0,0 +1,43 @@
+# DeleteCostElement
+
+## Overview
+
+deleteCostElement permanently removes a cost element that is in DRAFT status. Cost elements in ACTIVE or INACTIVE status cannot be deleted because they may be referenced by existing cost postings, allocations, or budget line items.
+
+## Business Rules
+
+- Cost element must exist
+- Only DRAFT cost elements can be deleted
+- ACTIVE and INACTIVE cost elements cannot be deleted
+- Deletion permanently removes the cost element record
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete cost element request] --> B{Cost element exists?}
+    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Delete cost element]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## 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 DRAFT status (ACTIVE or INACTIVE elements cannot be deleted)
+
+## Test Cases
+
+- deletes a DRAFT cost element successfully
+- returns error when cost element does not exist
+- returns error when cost element is in ACTIVE status
+- returns error when cost element is in INACTIVE status
+- emits audit event recording the deletion and acting user

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

@@ -0,0 +1,45 @@
+# DeleteInternalOrder
+
+## Overview
+
+deleteInternalOrder permanently removes an internal order that is in CREATED status. Orders in RELEASED, TECHNICALLY_COMPLETED, or CLOSED status cannot be deleted because they may have associated cost postings or budget assignments.
+
+## Business Rules
+
+- Internal order must exist
+- Only CREATED orders can be deleted
+- RELEASED, TECHNICALLY_COMPLETED, and CLOSED orders cannot be deleted
+- Deletion removes the order and any associated budget assignment
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete 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[Delete internal order and associated budget assignment]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## 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 (RELEASED, TECHNICALLY_COMPLETED, or CLOSED orders cannot be deleted)
+
+## Test Cases
+
+- deletes a CREATED internal order successfully
+- deletes a CREATED internal order and removes associated budget assignment
+- returns error when internal order does not exist
+- returns error when internal order is in RELEASED status
+- returns error when internal order is in TECHNICALLY_COMPLETED status
+- returns error when internal order is in CLOSED status
+- emits audit event recording the deletion and acting user

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

@@ -0,0 +1,46 @@
+# DeleteProfitCenter
+
+## Overview
+
+deleteProfitCenter permanently removes a profit center that is in DRAFT status. ACTIVE and INACTIVE profit centers cannot be deleted. Deletion also removes any hierarchy assignment associated with the profit center.
+
+## Business Rules
+
+- Profit center must exist
+- Only DRAFT profit centers can be deleted
+- ACTIVE profit centers cannot be deleted; they must be deactivated first
+- INACTIVE profit centers cannot be deleted
+- Deletion removes the profit center and its hierarchy assignment
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete profit center request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Remove hierarchy assignment]
+    F --> G[Delete profit center]
+    G --> H[Emit audit event]
+    H --> I[Return success]
+```
+
+## 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 DRAFT status (ACTIVE or INACTIVE profit centers cannot be deleted)
+
+## Test Cases
+
+- deletes a DRAFT profit center successfully
+- deletes a DRAFT profit center and removes its hierarchy assignment
+- returns error when profit center does not exist
+- returns error when profit center is in ACTIVE status
+- returns error when profit center is in INACTIVE status
+- emits audit event recording the deletion and acting user

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

@@ -0,0 +1,46 @@
+# DeleteProfitCenterHierarchyNode
+
+## Overview
+
+deleteProfitCenterHierarchyNode removes a node from a profit center hierarchy. A node can only be deleted if it has no child nodes and no profit centers assigned to it. This prevents orphaning of child structures and ensures data integrity.
+
+## Business Rules
+
+- Hierarchy node must exist
+- Node must have no child nodes; nodes with children cannot be deleted
+- Node must have no profit centers assigned to it; nodes with assigned profit centers cannot be deleted
+- Deletion permanently removes the node from the hierarchy
+- Emits an audit event recording the deletion and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete hierarchy node request] --> B{Node exists?}
+    B -->|No| C[Return error: NODE_NOT_FOUND]
+    B -->|Yes| D{Node has child nodes?}
+    D -->|Yes| E[Return error: NODE_HAS_CHILDREN]
+    D -->|No| F{Node has assigned profit centers?}
+    F -->|Yes| G[Return error: NODE_HAS_ASSIGNED_PROFIT_CENTERS]
+    F -->|No| H[Delete hierarchy node]
+    H --> I[Emit audit event]
+    I --> J[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Hierarchy node with the specified ID does not exist
+- **NODE_HAS_CHILDREN**: Node has child nodes that must be reassigned or removed first
+- **NODE_HAS_ASSIGNED_PROFIT_CENTERS**: Node has profit centers assigned that must be reassigned first
+
+## Test Cases
+
+- deletes a leaf node with no children and no assigned profit centers
+- returns error when node does not exist
+- returns error when node has child nodes
+- returns error when node has assigned profit centers
+- emits audit event recording the deletion and acting user

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

@@ -0,0 +1,54 @@
+# ExecuteAllocationCycle
+
+## Overview
+
+executeAllocationCycle runs the allocation calculations for a VALIDATED cycle. In ACTUAL mode, it transitions the cycle from VALIDATED to EXECUTED and creates immutable AllocationResult records for each sender-receiver-amount combination. In TEST_RUN mode, it generates preview results without changing the cycle status, allowing controllers to review projected allocations before committing.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in VALIDATED status to be executed
+- Supports two execution modes: ACTUAL and TEST_RUN
+- ACTUAL mode transitions status from VALIDATED to EXECUTED
+- ACTUAL mode creates immutable AllocationResult records for each sender-receiver-amount combination
+- AllocationResult records cannot be modified or deleted after creation
+- Each AllocationResult references the allocation cycle, sender, receiver, allocated amount, and cost element
+- TEST_RUN mode generates preview results without changing cycle status
+- Emits an audit event recording the execution and acting user (ACTUAL mode only)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive execute 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{Execution mode?}
+    F -->|TEST_RUN| G[Calculate allocation amounts]
+    G --> H[Return preview results without status change]
+    F -->|ACTUAL| I[Calculate allocation amounts]
+    I --> J[Create immutable AllocationResult records]
+    J --> K[Transition status from VALIDATED to EXECUTED]
+    K --> L[Emit audit event]
+    L --> M[Return execution results]
+```
+
+## 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
+
+- executes a VALIDATED allocation cycle in ACTUAL mode transitioning it to EXECUTED status
+- creates AllocationResult records in ACTUAL mode
+- executes in TEST_RUN mode returning preview results without status change
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in VALIDATED status
+- each AllocationResult references cycle, sender, receiver, amount, and cost element
+- emits audit event recording the execution and acting user

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

@@ -0,0 +1,44 @@
+# FinalizeVarianceReport
+
+## Overview
+
+finalizeVarianceReport transitions a variance report from DRAFT status to FINAL status. Once finalized, the report cannot be modified or transitioned back to DRAFT. This locks the variance analysis results for distribution to management.
+
+## Business Rules
+
+- Variance report must exist
+- Variance report must be in DRAFT status to be finalized
+- Finalizing an already FINAL report is rejected as an invalid state transition
+- Once finalized, no modifications are permitted
+- A FINAL report cannot be transitioned back to DRAFT
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive finalize variance report request] --> B{Variance report exists?}
+    B -->|No| C[Return error: VARIANCE_REPORT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from DRAFT to FINAL]
+    F --> G[Emit audit event]
+    G --> H[Return finalized variance report]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **VARIANCE_REPORT_NOT_FOUND**: Variance report with the specified ID does not exist
+- **INVALID_STATE**: Variance report is not in DRAFT status (e.g., already FINAL)
+
+## Test Cases
+
+- finalizes a DRAFT variance report transitioning it to FINAL status
+- returns error when variance report does not exist
+- returns error when variance report is already FINAL
+- finalized report cannot be transitioned back to DRAFT
+- emits audit event recording the status transition and acting user