# Holiday Management — Frontend Integration Guide

## Overview

The Holiday CRUD now supports **scope** (National/Local) and **adjacent workday flag**. Employees can be whitelisted per holiday (embedded in the create/update payload — no separate endpoint).

## Base URL

```
/api/v1/holidays     (no auth)
/api/v2/holidays     (service token auth)
```

---

## Endpoints

### GET /api/v1/holidays — List holidays

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `year` | int | Filter by year (uses `holiday_date`) |
| `name` | string | Search by name (like) |
| `type` | string | `regular`, `special`, `non-working` — legacy field |
| `scope` | string | Filter: `National` or `Local` |
| `adjacent_workday` | bool | Filter: `true` or `false` |
| `holiday_type_id` | int | Filter by holiday type |
| `limit` | int | Items per page (max 1000) |
| `page` | int | Page number |

**Response:**

```json
{
  "success": true,
  "message": "Holidays retrieved successfully",
  "data": [
    {
      "id": 1,
      "holiday_type_id": 1,
      "holiday_date": "2026-12-25",
      "name": "Christmas Day",
      "type": "regular",
      "scope": "National",
      "adjacent_workday": false,
      "is_recurring": false,
      "holiday_allowed_employees": [
        {
          "id": 1,
          "employee_id": 101,
          "status": "Active"
        }
      ]
    }
  ],
  "pagination": { ... }
}
```

---

### GET /api/v1/holidays/{id} — Get single holiday

Returns the same shape as a single item from the list above, including `holiday_allowed_employees`.

---

### POST /api/v1/holidays — Create holiday

**Body:**

```json
{
  "holiday_date": "2026-10-05",
  "name": "QC Foundation Day",
  "holiday_type_id": 1,
  "scope": "Local",
  "adjacent_workday": false,
  "employees": [101, 102, 103]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `holiday_date` | string (Y-m-d) | Yes | Date of the holiday |
| `name` | string | Yes | Holiday name |
| `holiday_type_id` | int | Yes | `1` = Regular Holiday, `2` = Special Non-Working Day (from `GET /api/v1/holiday_types`) |
| `scope` | string | Yes | `National` or `Local` |
| `adjacent_workday` | bool | No | Default `false`. For compressed work week scheduling |
| `is_recurring` | bool | No | Default `false` |
| `employees` | int[] | No | Array of employee IDs to whitelist. If omitted, the holiday applies to all globally-eligible employees |

**Response (201):**

```json
{
  "success": true,
  "message": "Holiday created successfully",
  "data": {
    "id": 42,
    "name": "QC Foundation Day",
    "scope": "Local",
    "adjacent_workday": false,
    "holiday_allowed_employees": [
      { "id": 10, "employee_id": 101 },
      { "id": 11, "employee_id": 102 },
      { "id": 12, "employee_id": 103 }
    ]
  }
}
```

---

### PUT /api/v1/holidays/{id} — Update holiday

**Body:** Same fields as create, but all optional.

| Field | Behavior |
|-------|----------|
| `employees` omitted | **No change** — existing whitelist stays |
| `employees: []` | **Clears** all whitelisted employees |
| `employees: [1,2,3]` | **Replaces** whitelist with new set |

> When `scope` is changed from `National` to `Local` (or vice versa) on an existing holiday, the DTR computation logic uses the new value for future calculations.

---

### DELETE /api/v1/holidays/{id} — Delete holiday

Soft-deletes the holiday and cascades to `holiday_allowed_employees`.

---

## Holiday Types Reference

```
GET /api/v1/holiday_types
```

Returns the available holiday types with their pay multipliers:

```json
{
  "data": [
    { "id": 1, "name": "Regular Holiday", "multiplier": "2.00", "status": "Active" },
    { "id": 2, "name": "Special Non-Working Day", "multiplier": "1.30", "status": "Active" }
  ]
}
```

---

## Employee Whitelist Behavior

| Scenario | Behavior |
|----------|----------|
| Holiday with **no** whitelist | DTR applies holiday pay to all globally-eligible employees (via `HolidayEligibility` flag) |
| Holiday with **specific** employees | DTR applies holiday pay **only** to those whitelisted employees |
| Update clearing the whitelist (`employees: []`) | Falls back to global eligibility |

---

## UI Suggested Workflow

1. **Index page** — `GET /api/v1/holidays` with filters (year, scope, type)
2. **Add Holiday** — Form with:
   - Holiday Name (text input)
   - Date (date picker)
   - Holiday Type (dropdown from `GET /api/v1/holiday_types`)
   - Scope (radio/dropdown: National | Local)
   - Adjacent Workday (checkbox)
   - Employee Picker (multi-select or searchable dropdown) — optional
3. **Edit Holiday** — Same form pre-filled
4. **Delete** — Confirmation dialog, then `DELETE /api/v1/holidays/{id}`

### Employee Picker

For the `employees` multi-select, use `GET /api/v1/employees` (if available) or a search endpoint. The selected employee IDs are sent as an array in the create/update payload.

---

## Error Responses

```json
{
  "success": false,
  "message": "The holiday_type_id field is required.",
  "data": null
}
```

Standard Laravel validation error format. Handle `422` status codes for validation failures.