# CreateTimeEntryCode

## Permission Scope

`timeEntryCode`

## Overview

Registers a new entry in the semantic time-type catalog: a stable `key`, a normalized `category`, a UI-only `displayName`, and a `payMapKey` that seams the code to a future payroll earnings code.

## Business Rules

- `key` must be unique across the catalog; registering a duplicate `key` is rejected
- `category` is a normalized category key (string) defined by the calculation strategy; any key is accepted (the default JP strategy uses `WORK`, `OVERTIME_WITHIN_STATUTORY`, `OVERTIME_BEYOND_STATUTORY`, `NIGHT`, `HOLIDAY_STATUTORY`, `HOLIDAY_PRESCRIBED`, `BREAK`, `LEAVE` as examples, not an authoritative closed set)
- `displayName` is UI-only and carries no calculation semantics
- `payMapKey` is stored verbatim as the stable seam to a downstream pay/earnings code

## Process Flow

```mermaid
flowchart TD
    A[Receive key, category, displayName, payMapKey] --> B{key already registered?}
    B -- Yes --> C[Reject: DUPLICATE_KEY]
    B -- No --> F[Create TimeEntryCode]
    F --> G[Code resolvable via getTimeEntryCodeByKey; WorkRule/EligibilityRule may now bind to it]
```

## External Dependencies

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

## Error Scenarios

- **DUPLICATE_KEY**: a `TimeEntryCode` with the given `key` already exists

## Test Cases

- creating a code with a duplicate `key` is rejected
- an arbitrary category key is accepted
- a code's `payMapKey` is preserved verbatim for downstream pay routing
- calculation resolves a newly created time type via `getTimeEntryCodeByKey`, not via display name