# CreateHolidayCalendar

## Permission Scope

`holidayCalendar`

## Overview

Registers a new named holiday calendar — a stable `key` and a human-facing `name` — that `CompanyHoliday` entries belong to and that `WorkRule` references for holiday classification. Creating a calendar makes per-region/per-entity holiday scoping possible without any code change.

## Business Rules

- `key` must be unique across all calendars; registering a second calendar with an already-registered `key` is rejected
- `name` is a human-facing label and carries no scoping or calculation semantics
- HolidayCalendar is master data, not effective-dated — creation stores the record directly with no generation/versioning semantics
- Once created, the calendar can immediately be referenced by a `CompanyHoliday` (`calendarId`) and by a `WorkRule` (`holidayCalendarId`)

## Process Flow

```mermaid
flowchart TD
    A[Receive key, name] --> B{key already registered?}
    B -- Yes --> C[Reject: DUPLICATE_CALENDAR_KEY]
    B -- No --> D[Create HolidayCalendar]
    D --> E[Calendar available to scope CompanyHoliday entries via calendarId]
    D --> F[Calendar available for WorkRule holiday classification via holidayCalendarId]
```

## External Dependencies

- [time-tracking::HolidayCalendar](../model/HolidayCalendar.md) model — the entity this command creates

## Error Scenarios

- **DUPLICATE_CALENDAR_KEY**: a calendar is already registered with the given key

## Test Cases

- creating a calendar with a duplicate `key` is rejected
- creates the calendar with the given `key` and `name`
- a newly created calendar is immediately resolvable by `getHolidayCalendar`
- a newly created calendar can be referenced by a `CompanyHoliday` and a `WorkRule`