# Late Leave Filing — Frontend Integration Guide

## Overview

The late filing feature automatically flags leave applications submitted close to the leave date. The flag is **informational only** — it does not block processing.

---

## 1. Creating a Leave — Response Changes

### `POST /api/v1/filing/leave`

**New field in response data** — `is_late_filing` (boolean):

```json
{
  "success": true,
  "message": "Leave entries processed successfully.",
  "data": {
    "id": 123,
    "employee_id": "EMP001",
    "date_filed": "2026-05-19",
    "date_leave": "2026-05-21",
    "is_late_filing": true
  }
}
```

**When `is_late_filing` is `true`, an extra top-level field is returned:**

```json
{
  "success": true,
  "message": "Leave entries processed successfully.",
  "data": { "...", "is_late_filing": true },
  "late_filing_alert": "This leave application is flagged as a late filing."
}
```

**Frontend action:** Display this alert to the employee as an in-app notification/toast at submission time.

---

## 2. Updating a Leave

### `PUT /api/v1/filing/leave/{id}`

Update also recalculates `is_late_filing`. Same response format as creation above.

---

## 3. Fetching Leave Records

### `GET /api/v1/filing/leave`

Each leave date in the `leaveData` array now includes `is_late_filing`:

```json
{
  "data": [
    {
      "leave_id_group": "abc123",
      "date_filed": "2026-05-19",
      "employee_id": "EMP001",
      "leave_type": { "name": "SICK LEAVE" },
      "leaveData": [
        {
          "id": 123,
          "date_leave": "2026-05-21",
          "is_late_filing": true
        }
      ]
    }
  ]
}
```

**Frontend action:** Display a "Late Filing" badge/label next to late-flagged leave dates in leave lists and detail views.

---

## 4. Return-to-Work Date (Sick Leave)

For **Sick Leave** only, an employee has **1 working day after returning to work** to file their leave. HR records the return-to-work date.

### `POST /api/v1/filing/leave` — New optional field in body

```json
{
  "return_to_work_date": "2026-05-20"
}
```

This field is only relevant for sick leave entries. It is set by HR when confirming an employee returned from sick leave.

### `GET /api/v1/filing/leave` — Return-to-work date in response

The `return_to_work_date` field is included in the leave record when present.

---

## 5. Late Filing Leave Report

### `GET /api/v1/late-filing-leave-report`

Report now filters on the persisted `is_late_filing` flag instead of old calendar-day heuristics.

Response rows include:

| Field | Type | Description |
|-------|------|-------------|
| `employee_name` | string | Full name |
| `division` | string | Division name |
| `leave_classification` | string | Leave type name |
| `date_filed` | date | When the leave was filed |
| `inclusive_date` | date | The leave date |
| `is_late_filing` | boolean | Late filing flag |
| `days_late` | integer/null | Calendar days between filing and leave (null if not late) |

Export formats (Excel, PDF, CSV) now include **Late Filing** (Yes/No) and **Days Late** columns.

---

## 6. Employee Notifications (NEW)

A new `employee_notifications` table stores system-generated alerts.

### Creating a notification endpoint (suggested)

For the frontend to display late-filing alerts to the employee, create a simple read-only endpoint:

```
GET /api/v1/employee/{employeeId}/notifications
```

Returns notifications sorted by `created_at DESC`:

```json
{
  "data": [
    {
      "id": 1,
      "employee_id": "EMP001",
      "type": "late_filing_alert",
      "message": "This leave application filed on 2026-05-19 for 2026-05-20 is flagged as a late filing.",
      "reference_type": "leave",
      "reference_id": 123,
      "is_read": false,
      "created_at": "2026-05-19T04:00:00.000000Z"
    }
  ]
}
```

**Suggested UX:** Show unread notification count in a header badge. Display the alert message in a dropdown or notification panel.

### Marking notifications as read

```
PATCH /api/v1/notifications/{id}/read
```

---

## Summary of UI Changes Needed

| Area | Change |
|------|--------|
| Leave creation form | Show `late_filing_alert` toast/message on submit |
| Leave detail/list | Show "Late Filing" badge when `is_late_filing: true` |
| Sick leave form | Optionally show `return_to_work_date` field (HR-side) |
| Late Filing Report | New columns: `is_late_filing`, `days_late` |
| Notification badge (optional) | Poll `GET /employee/{id}/notifications` for unread `late_filing_alert` type |