@tailor-platform/erp-kit 0.6.0 → 0.8.0

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

@@ -0,0 +1,54 @@
+# ActivateBudget
+
+## Overview
+
+activateBudget transitions a budget from APPROVED status to ACTIVE status, enabling funds checking (budgetary control) for the associated cost object. Only one ACTIVE budget of type BUDGET can exist per cost object per fiscal year. Multiple FORECAST or SIMULATION versions can coexist.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in APPROVED status to be activated
+- Upon activation, funds checking is enabled for the cost object
+- Only one ACTIVE budget of type BUDGET can exist per cost object per fiscal year
+- Multiple ACTIVE FORECAST or SIMULATION plan versions can coexist for the same cost object and fiscal year
+- Transitions status from APPROVED to ACTIVE
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate budget request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is APPROVED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Plan version type is BUDGET?}
+    F -->|Yes| G{Another ACTIVE BUDGET exists for same cost object and fiscal year?}
+    G -->|Yes| H[Return error: DUPLICATE_ACTIVE_BUDGET]
+    G -->|No| I[Transition status from APPROVED to ACTIVE]
+    F -->|No| I
+    I --> J[Enable funds checking]
+    J --> K[Emit audit event]
+    K --> L[Return activated budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in APPROVED status
+- **DUPLICATE_ACTIVE_BUDGET**: Another ACTIVE budget of type BUDGET already exists for the same cost object and fiscal year
+
+## Test Cases
+
+- activates an APPROVED budget transitioning it to ACTIVE status
+- enables funds checking upon activation
+- returns error when budget does not exist
+- returns error when budget is not in APPROVED status
+- returns error when another ACTIVE BUDGET exists for the same cost object and fiscal year
+- allows multiple ACTIVE FORECAST versions for the same cost object and fiscal year
+- allows multiple ACTIVE SIMULATION versions for the same cost object and fiscal year
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,43 @@
+# ActivateCostElement
+
+## Overview
+
+activateCostElement transitions a cost element from DRAFT status to ACTIVE status, making it available for use in cost postings and allocation processes. Only cost elements currently in DRAFT status can be activated.
+
+## Business Rules
+
+- Cost element must exist
+- Cost element must be in DRAFT status to be activated
+- Activating an already ACTIVE or INACTIVE cost element is rejected as an invalid state transition
+- Upon activation, the cost element becomes available for cost postings and allocations
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate 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[Transition status from DRAFT to ACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return activated 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 DRAFT status (e.g., already ACTIVE or INACTIVE)
+
+## Test Cases
+
+- activates a DRAFT cost element transitioning it to ACTIVE status
+- returns error when cost element does not exist
+- returns error when cost element is already ACTIVE
+- returns error when cost element is INACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,43 @@
+# ActivateProfitCenter
+
+## Overview
+
+activateProfitCenter transitions a profit center from DRAFT status to ACTIVE status, making it available for transaction tagging and profitability reporting. Only profit centers currently in DRAFT status can be activated.
+
+## Business Rules
+
+- Profit center must exist
+- Profit center must be in DRAFT status to be activated
+- Activating an already ACTIVE or INACTIVE profit center is rejected as an invalid state transition
+- Upon activation, the profit center becomes available for revenue and cost transaction assignments
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate 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[Transition status from DRAFT to ACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return activated 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 DRAFT status (e.g., already ACTIVE or INACTIVE)
+
+## Test Cases
+
+- activates a DRAFT profit center transitioning it to ACTIVE status
+- returns error when profit center does not exist
+- returns error when profit center is already ACTIVE
+- returns error when profit center is INACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,46 @@
+# ApproveBudget
+
+## Overview
+
+approveBudget transitions a budget from SUBMITTED status to APPROVED status. The approver must be a different user from the budget creator to enforce segregation of duties. Only SUBMITTED budgets can be approved.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in SUBMITTED status to be approved
+- Approver must be a different user from the budget creator (segregation of duties)
+- Transitions status from SUBMITTED to APPROVED
+- Emits an audit event recording the status transition, approver, and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive approve 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{Approver different from creator?}
+    F -->|No| G[Return error: SELF_APPROVAL_NOT_ALLOWED]
+    F -->|Yes| H[Transition status from SUBMITTED to APPROVED]
+    H --> I[Emit audit event]
+    I --> J[Return approved 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
+- **SELF_APPROVAL_NOT_ALLOWED**: Approver is the same user who created the budget (segregation of duties violation)
+
+## Test Cases
+
+- approves a SUBMITTED budget transitioning it to APPROVED status
+- returns error when budget does not exist
+- returns error when budget is not in SUBMITTED status
+- returns error when approver is the same as the budget creator
+- emits audit event recording the status transition and approver

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

@@ -0,0 +1,46 @@
+# AssignCostCenterToHierarchyNode
+
+## Overview
+
+assignCostCenterToHierarchyNode moves an existing cost center to a different hierarchy node within the same company's cost center hierarchy. This enables reorganization of the cost center structure without recreating cost center master data.
+
+## Business Rules
+
+- Cost center must exist
+- Target hierarchy node must exist within the same company's hierarchy
+- Cost center and target node must belong to the same company
+- Multiple cost centers can be assigned to the same hierarchy node
+- Emits an audit event recording the hierarchy assignment change and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign cost center to hierarchy node request] --> B{Cost center exists?}
+    B -->|No| C[Return error: COST_CENTER_NOT_FOUND]
+    B -->|Yes| D{Target hierarchy node exists?}
+    D -->|No| E[Return error: HIERARCHY_NODE_NOT_FOUND]
+    D -->|Yes| F{Same company?}
+    F -->|No| G[Return error: COMPANY_MISMATCH]
+    F -->|Yes| H[Assign cost center to target hierarchy node]
+    H --> I[Emit audit event]
+    I --> J[Return updated cost center]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_NOT_FOUND**: Cost center with the specified ID does not exist
+- **HIERARCHY_NODE_NOT_FOUND**: Target hierarchy node does not exist
+- **COMPANY_MISMATCH**: Cost center and target hierarchy node do not belong to the same company
+
+## Test Cases
+
+- returns error when cost center does not exist
+- returns error when target hierarchy node does not exist
+- returns error when cost center and node belong to different companies
+- assigns cost center to hierarchy node successfully
+- updates the hierarchyNodeId field on the cost center

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

@@ -0,0 +1,47 @@
+# AssignProfitCenterToHierarchyNode
+
+## Overview
+
+assignProfitCenterToHierarchyNode assigns a profit center to a specific node within a profit center hierarchy. A profit center can be assigned to exactly one node per hierarchy but can be assigned to nodes in multiple hierarchies simultaneously, enabling multi-dimensional reporting.
+
+## Business Rules
+
+- Profit center must exist
+- Target hierarchy node must exist
+- A profit center can be assigned to exactly one node within a given hierarchy
+- A profit center can be assigned to nodes in multiple hierarchies simultaneously
+- Assigning to a new node within the same hierarchy replaces the previous assignment
+- Emits an audit event recording the hierarchy assignment and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign profit center to hierarchy node request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Target hierarchy node exists?}
+    D -->|No| E[Return error: HIERARCHY_NODE_NOT_FOUND]
+    D -->|Yes| F{Already assigned to a node in this hierarchy?}
+    F -->|Yes| G[Replace existing assignment with new node]
+    F -->|No| H[Create new assignment to target node]
+    G --> I[Emit audit event]
+    H --> I
+    I --> J[Return updated assignment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PROFIT_CENTER_NOT_FOUND**: Profit center with the specified ID does not exist
+- **HIERARCHY_NODE_NOT_FOUND**: Target hierarchy node does not exist
+
+## Test Cases
+
+- assigns a profit center to a hierarchy node (creates new assignment)
+- replaces existing assignment when profit center is already assigned in the same hierarchy
+- allows a profit center to be assigned to nodes in multiple hierarchies
+- returns error when profit center does not exist
+- returns error when target hierarchy node does not exist

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

@@ -0,0 +1,47 @@
+# CloseBudget
+
+## Overview
+
+closeBudget transitions a budget from ACTIVE status to CLOSED status. Once closed, no further modifications are permitted and the budget cannot be reopened. This is the terminal state of the budget lifecycle.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in ACTIVE status to be closed
+- Transitions status from ACTIVE to CLOSED
+- No further modifications are permitted after closure
+- A CLOSED budget cannot be reopened
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close budget request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from ACTIVE to CLOSED]
+    F --> G[Emit audit event]
+    G --> H[Return closed budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in ACTIVE status
+
+## Test Cases
+
+- closes an ACTIVE budget transitioning it to CLOSED status
+- returns error when budget does not exist
+- returns error when budget is not in ACTIVE status
+- returns error when budget is in DRAFT status
+- returns error when budget is in SUBMITTED status
+- returns error when budget is in APPROVED status
+- returns error when budget is already CLOSED
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,45 @@
+# CloseInternalOrder
+
+## Overview
+
+closeInternalOrder transitions an internal order from TECHNICALLY_COMPLETED status to CLOSED status. Once closed, no further changes or cost postings are permitted. This is the terminal state of the internal order lifecycle.
+
+## Business Rules
+
+- Internal order must exist
+- Internal order must be in TECHNICALLY_COMPLETED status to be closed
+- Closing a CREATED, RELEASED, or already CLOSED order is rejected as an invalid state transition
+- CLOSED orders cannot transition to any other status
+- No further modifications are permitted after closure
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close internal order request] --> B{Internal order exists?}
+    B -->|No| C[Return error: INTERNAL_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is TECHNICALLY_COMPLETED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from TECHNICALLY_COMPLETED to CLOSED]
+    F --> G[Emit audit event]
+    G --> H[Return closed 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 TECHNICALLY_COMPLETED status
+
+## Test Cases
+
+- closes a TECHNICALLY_COMPLETED internal order transitioning it to CLOSED status
+- returns error when internal order does not exist
+- returns error when internal order is in CREATED status
+- returns error when internal order is in RELEASED status
+- returns error when internal order is already CLOSED
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,53 @@
+# ConsumeCommitment
+
+## Overview
+
+consumeCommitment reduces an existing commitment and increases the actual amount when goods are received or an invoice is matched against a purchase order. This reclassifies committed funds as actual expenditure, keeping budget availability unchanged for the consumed portion.
+
+## Business Rules
+
+- Commitment must exist for the specified cost element, cost object, and period
+- Requires a positive consumption amount
+- Consumption amount must not exceed the remaining commitment amount
+- Reduces the commitment amount by the consumption amount
+- Increases the actual amount by the consumption amount
+- Budget availability remains unchanged for the consumed portion (commitment decreases, actual increases by the same amount)
+- Emits an audit event recording the consumption and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive consume commitment request] --> B{Commitment exists?}
+    B -->|No| C[Return error: COMMITMENT_NOT_FOUND]
+    B -->|Yes| D{Consumption amount positive?}
+    D -->|No| E[Return error: INVALID_CONSUMPTION_AMOUNT]
+    D -->|Yes| F{Consumption amount <= remaining commitment?}
+    F -->|No| G[Return error: CONSUMPTION_EXCEEDS_COMMITMENT]
+    F -->|Yes| H[Reduce commitment by consumption amount]
+    H --> I[Increase actual by consumption amount]
+    I --> J[Emit audit event]
+    J --> K[Return updated commitment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMMITMENT_NOT_FOUND**: No commitment exists for the specified cost element, cost object, and period
+- **INVALID_CONSUMPTION_AMOUNT**: Consumption amount is not positive
+- **CONSUMPTION_EXCEEDS_COMMITMENT**: Consumption amount exceeds the remaining commitment amount
+
+## Test Cases
+
+- consumes a portion of an existing commitment
+- reduces commitment amount by the consumption amount
+- increases actual amount by the consumption amount
+- budget availability remains unchanged for the consumed portion
+- returns error when commitment does not exist
+- returns error when consumption amount is zero or negative
+- returns error when consumption amount exceeds remaining commitment
+- fully consumes a commitment when consumption equals remaining amount
+- emits audit event recording the consumption and acting user

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

@@ -0,0 +1,55 @@
+# CreateAllocationCycle
+
+## Overview
+
+createAllocationCycle establishes a new allocation cycle in DRAFT status. An allocation cycle groups a set of allocation rules that define how overhead costs are distributed from sender cost centers to receiver cost objects. It requires a name, allocation type (ASSESSMENT or DISTRIBUTION), a company reference, and an accounting period reference.
+
+## Business Rules
+
+- Allocation cycle is always created in DRAFT status
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a valid `name`
+- Requires a valid `type` of either ASSESSMENT or DISTRIBUTION
+- Requires a valid `accountingPeriodId` referencing an existing accounting period from finance-ledger
+- Allocation cycles are scoped to a company; cycles from different companies are fully isolated
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create allocation cycle request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Valid allocation type?}
+    D -->|No| E[Return error: INVALID_ALLOCATION_TYPE]
+    D -->|Yes| F{Accounting period exists?}
+    F -->|No| G[Return error: ACCOUNTING_PERIOD_NOT_FOUND]
+    F -->|Yes| H{Name provided?}
+    H -->|No| I[Return error: INVALID_NAME]
+    H -->|Yes| J[Create allocation cycle in DRAFT status]
+    J --> K[Emit audit event]
+    K --> L[Return created allocation cycle]
+```
+
+## 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
+- **INVALID_ALLOCATION_TYPE**: Type is not ASSESSMENT or DISTRIBUTION
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **INVALID_NAME**: Name is missing or empty
+
+## Test Cases
+
+- creates allocation cycle in DRAFT status with required fields
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when allocation type is invalid
+- returns error when accounting period does not exist
+- returns error when name is missing
+- allocation cycles from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values

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

@@ -0,0 +1,60 @@
+# CreateAllocationRule
+
+## Overview
+
+createAllocationRule adds an allocation rule to a DRAFT allocation cycle. Each rule defines a sender cost center, one or more receiver cost objects (cost center, profit center, or internal order), and the allocation percentage for each receiver. The sender cannot also appear as a receiver within the same rule. Percentage values must be positive.
+
+## Business Rules
+
+- Allocation cycle must exist and be in DRAFT status
+- Rules cannot be added to cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status
+- Requires a valid sender cost center reference
+- Requires one or more valid receiver cost objects (cost center, profit center, or internal order)
+- Sender cost center cannot also be a receiver within the same rule set
+- Percentage values for each receiver must be positive (greater than zero)
+- Emits an audit event recording the rule creation and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create allocation rule 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{Sender cost center valid?}
+    F -->|No| G[Return error: SENDER_NOT_FOUND]
+    F -->|Yes| H{All receivers valid?}
+    H -->|No| I[Return error: RECEIVER_NOT_FOUND]
+    H -->|Yes| J{Sender appears as receiver?}
+    J -->|Yes| K[Return error: SENDER_IS_RECEIVER]
+    J -->|No| L{All percentages positive?}
+    L -->|No| M[Return error: INVALID_PERCENTAGE]
+    L -->|Yes| N[Create allocation rule]
+    N --> O[Emit audit event]
+    O --> P[Return created allocation rule]
+```
+
+## 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
+- **SENDER_NOT_FOUND**: Referenced sender cost center does not exist
+- **RECEIVER_NOT_FOUND**: One or more referenced receiver cost objects do not exist
+- **SENDER_IS_RECEIVER**: Sender cost center appears as a receiver in the same rule
+- **INVALID_PERCENTAGE**: One or more percentage values are not positive
+
+## Test Cases
+
+- adds an allocation rule to a DRAFT allocation cycle
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in DRAFT status
+- returns error when sender cost center does not exist
+- returns error when a receiver cost object does not exist
+- returns error when sender appears as a receiver
+- returns error when percentage value is zero or negative
+- emits audit event recording the rule creation and acting user

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

@@ -0,0 +1,65 @@
+# CreateBudget
+
+## Overview
+
+createBudget establishes a new budget in DRAFT status. A budget is a financial plan that allocates planned amounts to cost elements across accounting periods for a specific cost object. It requires a name, budget holder, fiscal year reference, company reference, cost object type and ID, and a plan version reference.
+
+## Business Rules
+
+- Budget is always created in DRAFT status
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a `name`
+- Requires a `budgetHolderId`
+- Requires a valid `fiscalYearId` referencing an existing fiscal year from finance-ledger
+- Requires a `costObjectType` and `costObjectId` referencing a valid cost object (cost center, profit center, or internal order)
+- Requires a valid `planVersionId` referencing an existing plan version
+- Budgets are scoped to a company; budgets from different companies are fully isolated
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create budget request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Fiscal year exists?}
+    D -->|No| E[Return error: FISCAL_YEAR_NOT_FOUND]
+    D -->|Yes| F{Cost object exists?}
+    F -->|No| G[Return error: COST_OBJECT_NOT_FOUND]
+    F -->|Yes| H{Plan version exists?}
+    H -->|No| I[Return error: PLAN_VERSION_NOT_FOUND]
+    H -->|Yes| J{Name provided?}
+    J -->|No| K[Return error: INVALID_NAME]
+    J -->|Yes| L{Budget holder provided?}
+    L -->|No| M[Return error: BUDGET_HOLDER_REQUIRED]
+    L -->|Yes| N[Create budget in DRAFT status]
+    N --> O[Emit audit event]
+    O --> P[Return created budget]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+- [finance-ledger::getFiscalYear](../../../finance-ledger/docs/queries/GetFiscalYear.md) — Validates that the referenced fiscal year exists
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **FISCAL_YEAR_NOT_FOUND**: Referenced fiscal year does not exist
+- **COST_OBJECT_NOT_FOUND**: Referenced cost object (cost center, profit center, or internal order) does not exist
+- **PLAN_VERSION_NOT_FOUND**: Referenced plan version does not exist
+- **INVALID_NAME**: Name is missing or empty
+- **BUDGET_HOLDER_REQUIRED**: Budget holder reference is missing
+
+## Test Cases
+
+- creates budget in DRAFT status with required fields
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when fiscal year does not exist
+- returns error when cost object does not exist
+- returns error when plan version does not exist
+- returns error when name is missing
+- returns error when budget holder is missing
+- budgets from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values