# CreateAccountingPeriod

## Permission Scope

periodManagement

## Overview

createAccountingPeriod establishes a new accounting period in NEVER_OPENED status within a fiscal year. Each period carries a name, start date, end date, period type (e.g., monthly, quarterly, adjustment), and is linked to a fiscal year via `fiscalYearId`. Periods represent the discrete time segments within a fiscal year that control when journal entries can be posted. The system validates that the period does not overlap with existing periods and that there are no gaps in coverage within the fiscal year.

## Business Rules

- Period must reference a valid `fiscalYearId` belonging to the same company
- Period name is required and must be non-empty
- Start date and end date are required, with start date strictly before end date
- Period start and end dates must fall within the referenced fiscal year date range
- Periods within the same fiscal year must not have overlapping date ranges
- Periods within the same fiscal year must cover the full fiscal year date range without gaps
- Two periods in the same fiscal year cannot have identical start and end dates unless one is an adjustment period
- Adjustment periods share the same end date as the final regular period but are typed as adjustment
- Period is always created in NEVER_OPENED status
- Period must reference a valid `companyId`; the period is scoped to the same company as its fiscal year

## Process Flow

```mermaid
flowchart TD
    A[Receive create period request] --> B{Fiscal year exists and belongs to company?}
    B -->|No| C[Return error: fiscal year 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 period in fiscal year?}
    H -->|Yes| I[Return error: overlapping period]
    H -->|No| L[Create period in NEVER_OPENED status]
    L --> N[Return created period]
```

## External Dependencies

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

## Error Scenarios

- **FISCAL_YEAR_NOT_FOUND**: Referenced fiscal year does not exist or does not belong to the specified company
- **NAME_REQUIRED**: Name is empty, whitespace-only, or not provided when required
- **INVALID_DATE_RANGE**: Date range is invalid
- **OVERLAPPING_PERIOD**: The date range overlaps with an existing period within the same fiscal year
- **DUPLICATE_PERIOD_DATES**: Two periods have identical start and end dates and neither is an adjustment period

## Test Cases

- returns error when fiscal year does not exist
- returns error when fiscal year belongs to a different company
- returns error when name is empty
- returns error when start date is not before end date
- returns error when start date equals end date
- returns error when period overlaps with an existing period in the same fiscal year
- returns error when two periods have identical dates and neither is adjustment type
- creates period in NEVER_OPENED status with valid inputs
- creates 12 monthly periods with correct date boundaries for a calendar fiscal year
- creates 13 periods (12 operating + 1 adjustment) for a fiscal year
- adjustment period shares the same end date as the final regular period
- creates periods for a non-calendar fiscal year with correct boundaries
- periods are scoped to a company; periods from different companies are isolated