# CreateFiscalYear

## Permission Scope

periodManagement

## Overview

createFiscalYear establishes a new fiscal year record for a company. The fiscal year carries a name, start date, end date, and is scoped to a single company via `companyId`. Fiscal years serve as the top-level temporal grouping under which accounting periods are created. The system validates that the fiscal year does not overlap with any existing fiscal year for the same company.

## Business Rules

- Fiscal year requires a valid `companyId` referencing a company from the organization module
- Fiscal year name is required and must be non-empty
- Start date and end date are required, with start date strictly before end date
- Fiscal year date range must not overlap with any existing fiscal year for the same company
- Supports non-calendar fiscal years (e.g., April-to-March, February-to-January)
- Supports 4-4-5 week structures and 13-period fiscal calendars
- Fiscal years are scoped to a company; records from different companies are isolated

## Process Flow

```mermaid
flowchart TD
    A[Receive create fiscal year request] --> B{Company exists?}
    B -->|No| C[Return error: company not found]
    B -->|Yes| D{Name non-empty?}
    D -->|No| E[Return error: name required]
    D -->|Yes| F{Start date before end date?}
    F -->|No| G[Return error: invalid date range]
    F -->|Yes| H{Overlaps with existing fiscal year?}
    H -->|Yes| I[Return error: overlapping fiscal year]
    H -->|No| J[Create fiscal year record]
    J --> L[Return created fiscal year]
```

## External Dependencies

- [organization::getCompany](../../../organization/docs/query/GetCompany.md) - Validates that the referenced company exists

## Error Scenarios

- **COMPANY_NOT_FOUND**: Referenced company does not exist
- **NAME_REQUIRED**: Name is empty, whitespace-only, or not provided when required
- **INVALID_DATE_RANGE**: Date range is invalid
- **OVERLAPPING_FISCAL_YEAR**: The date range overlaps with an existing fiscal year for the same company

## Test Cases

- returns error when company does not exist
- returns error when name is empty
- returns error when start date is not before end date
- returns error when fiscal year overlaps with an existing fiscal year for the same company
- creates fiscal year with valid name, start date, and end date
- creates non-calendar fiscal year (e.g., April-to-March) with correct date boundaries
- fiscal years from different companies are isolated