# annual-leave-register

## Overview

The Annual Leave Register is the compliance view over the leave ledger and request history. Japanese employers are legally required to maintain a per-worker register of annual paid leave — the days granted, the days taken, and the balance with the relevant dates — and to keep it for the statutory retention period. On top of the register, this feature tracks the **5-day mandatory acquisition obligation**: since the 2019 Labor Standards Act revision, every worker granted 10 or more days of annual leave must actually take at least 5 of them within the year following the grant, and the employer must ensure and record this.

This feature owns no new persisted balance — it is entirely derived from `LeaveGrant` (grants, expirations), `LeaveConsumption` / `LeaveRequest` (approved takings), and each worker's grant-year window. It reports who is behind on the 5-day obligation so administrators can prompt or designate leave dates before the deadline.

## Business Purpose

- Satisfy the legal duty to maintain an annual leave register per worker (grant date, granted days, taken days, dates, balance) derived from the ledger
- Track the 5-day mandatory annual-leave acquisition for workers granted 10+ days, surfacing those at risk of falling short before their grant-year deadline (Labor Standards Act Article 39 paragraph 7)
- Give administrators a defensible compliance report without a separate cache — the register is a query over the same drift-free ledger (ADR-005)
- Support enterprise-scale oversight: filter and roll up obligation status across an organization so large headcounts remain auditable

## Process Flow

```mermaid
flowchart TD
    A[Select worker + grant-year window] --> B[Load STATUTORY grants active in the window from LeaveGrant]
    B --> C[Sum granted days and identify grants of 10+ days subject to the 5-day duty]
    C --> D[Load approved paid-leave takings from LeaveRequest / LeaveConsumption in the window]
    D --> E[Compute taken days and remaining balance from the ledger]
    E --> F{granted >= 10 days?}
    F -- Yes --> G{taken >= 5 within the grant year?}
    G -- Yes --> H[Obligation satisfied]
    G -- No --> I[At risk: report shortfall and deadline]
    F -- No --> J[5-day duty not triggered; register still shows grant/taken/balance]
    H --> K[Render register row: granted / taken / balance / dates]
    I --> K
    J --> K
```

## Scenario Patterns

- **Register per worker**: a worker's register lists each grant (date, days, expiration), the approved takings against it, and the derived remaining balance
- **5-day duty triggered**: a worker granted 10+ days in the grant year is subject to the obligation; the report shows takings so far and the deadline
- **At-risk detection**: a worker granted 10+ days who has taken fewer than 5 with the grant-year deadline approaching is flagged for a prompt or employer-designated leave date
- **Duty satisfied**: once 5+ days are taken within the grant year, the worker is marked compliant
- **Duty not triggered**: a worker granted fewer than 10 days in the year (e.g. a partial-year or manual sub-10-day grant) still appears in the register but without the 5-day flag
- **Half-day counting**: takings recorded in 0.5-day units aggregate correctly toward the 5-day count and the balance
- **Organization roll-up**: administrators filter obligation status across the workforce to see who is behind at scale

## Test Cases

- a worker's register aggregates granted, taken, and remaining days purely from the ledger with no cached column
- a worker granted 10+ days in the grant year is marked subject to the 5-day obligation
- a worker granted 10+ days who has taken fewer than 5 near the deadline is flagged at-risk
- a worker who has taken 5+ days within the grant year is marked compliant
- a worker granted fewer than 10 days is not subject to the 5-day duty but still appears in the register
- half-day takings aggregate correctly toward the 5-day count
- the obligation report can be rolled up and filtered across the organization

## Reference Links

- Data-model design research (compliance register derived from the ledger): https://github.com/tailor-sandbox/Omakase-ERP-attendance/issues/7
- Enterprise gap analysis (compliance reporting expectations vs SMB tooling): https://github.com/tailor-sandbox/Omakase-ERP-attendance/issues/9
- [Labor Standards Act Article 39 (Annual Paid Leave and the 5-day designated-timing duty) — e-Gov Law Search](https://laws.e-gov.go.jp/law/322AC0000000049) — the 5-day mandatory acquisition duty and register requirement (ADR-009)
- [KING OF TIME Support Center — Annual leave register](https://support.ta.kingoftime.jp/hc/ja) — annual-leave register and 5-day obligation tracking benchmarked per ADR-009