# CreateBudget

## Permission Scope

accounting

## 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 empty, whitespace-only, or not provided
- **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
