# CreatePlanVersion

## Permission Scope

accounting

## Overview

createPlanVersion establishes a new plan version for multi-version budget planning. A plan version defines the type of planning exercise (BUDGET, FORECAST, or SIMULATION) and is scoped to a company. An optional base version can be referenced to copy line items from an existing version.

## Business Rules

- Requires a `name`
- Requires a valid `type` of BUDGET, FORECAST, or SIMULATION
- Requires a valid `companyId` referencing an ACTIVE company from the organization module
- `baseVersionId` is optional; when provided, it must reference an existing plan version from which line items can be copied
- Plan versions are scoped to a company
- Emits an audit event recording the acting user, timestamp, and initial field values

## Process Flow

```mermaid
flowchart TD
    A[Receive create plan version request] --> B{Company exists and is ACTIVE?}
    B -->|No| C[Return error: COMPANY_NOT_FOUND]
    B -->|Yes| D{Valid version type?}
    D -->|No| E[Return error: INVALID_VERSION_TYPE]
    D -->|Yes| F{Name provided?}
    F -->|No| G[Return error: INVALID_NAME]
    F -->|Yes| H{Base version provided?}
    H -->|Yes| I{Base version exists?}
    I -->|No| J[Return error: BASE_VERSION_NOT_FOUND]
    I -->|Yes| K[Create plan version with base reference]
    H -->|No| L[Create plan version without base reference]
    K --> M[Emit audit event]
    L --> M
    M --> N[Return created plan version]
```

## External Dependencies

- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE

## Error Scenarios

- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
- **INVALID_VERSION_TYPE**: Type is not BUDGET, FORECAST, or SIMULATION
- **INVALID_NAME**: Name is empty, whitespace-only, or not provided
- **BASE_VERSION_NOT_FOUND**: Referenced base version does not exist

## Test Cases

- creates a plan version of type BUDGET
- creates a plan version of type FORECAST
- creates a plan version of type SIMULATION
- creates a plan version with a base version reference
- creates a plan version without a base version reference
- returns error when company does not exist
- returns error when company is not ACTIVE
- returns error when version type is invalid
- returns error when name is missing
- returns error when base version does not exist
- emits audit event recording acting user, timestamp, and initial field values
