# Force Leave Module — Frontend Integration Guide > **Source of truth for menu hierarchy:** [`MENU_HIERARCHY.md`](../MENU_HIERARCHY.md) in the frontend repo. --- ## 1. Menu Placement Force Leave has **two entry points** in the sidebar: | Feature | Menu Location | `[name]` (permission) | |---------|---------------|----------------------| | **Force Leave Management** (candidates, schedule) | `Time Management > Leave Ledger > Force Leave` | `ForceLeave` | | **Force Leave Record Report** (exportable) | `Time Management > Leave Management Report > Force Leave Record Report` | `ForceLeaveRecordReport` | ### Hierarchy ``` Time Management [name: "PersonalAdministration"] ├── Leave Ledger [name: "LeaveLedger"] │ ├── Leave Balance History [name: "LeaveBalanceHistory"] │ ├── Leave Card [name: "LeaveCard"] │ ├── CL Balances [name: "CLBalances"] │ ├── CL Ledger [name: "CLLedger"] │ └── Force Leave [name: "ForceLeave"] ← Management screen │ ├── Leave Management Report [name: "LeaveManagementReport"] │ ├── Absent Without Official Leave [name: "AbsentWithoutOfficialLeaveReport"] │ ├── Late Leave Filing Report [name: "LateLeaveFilingReport"] │ ├── Prolonged Leave Report [name: "ProlongedLeaveReport"] │ └── Force Leave Record Report [name: "ForceLeaveRecordReport"] ← NEW report ``` --- ## 2. API Endpoints All endpoints exist under **both** v1 (`/api/v1`) and v2 (`/api/v2`) prefixes. ### 2.1 Force Leave Management | Method | URL | Description | |--------|-----|-------------| | GET | `/api/v1/cl/force-leave/candidates?year=2026` | List employees exceeding 120-day VL cap | | GET | `/api/v1/cl/force-leave/obligations?employee_id=EMP001&year=2026` | Get force leave obligations (paginated) | | POST | `/api/v1/cl/force-leave/schedule` | Schedule a force leave entry | #### Candidates Response ```json { "success": true, "message": "Force leave candidates retrieved successfully", "data": [ { "employee_id": "EMP001", "vl_balance": 135, "excess_vl_days": 15, "obligation_id": 1, "required_days": 5, "scheduled_days": 2, "remaining_days": 3, "status": "in_progress" } ] } ``` #### Schedule Request (POST) ```json { "employee_id": "EMP001", "days": 5, "date_from": "2026-06-15" } ``` #### Schedule Response ```json { "success": true, "message": "Force leave scheduled successfully", "data": { "employee_id": "EMP001", "scheduled_days": 5, "remaining_days": 0, "status": "completed", "dates": ["2026-06-15", "2026-06-16", "2026-06-17", "2026-06-18", "2026-06-19"] } } ``` #### Business Rules (validate on frontend too) 1. **`date_from` must be at least 5 working days ahead** — backend returns 422 with message if violated 2. **`days` cannot exceed `remaining_days`** — backend returns 422 3. **Only employees with an existing obligation can be scheduled** — backend returns 422 if no obligation found 4. **Completed obligations cannot be re-scheduled** — backend returns 422 ### 2.2 Force Leave Record Report | Method | URL | Description | |--------|-----|-------------| | GET | `/api/v1/force-leave-record-report` | List all force leave obligations (JSON) | | GET | `/api/v1/force-leave-record-report?export=excel` | Download as Excel (.xlsx) | | GET | `/api/v1/force-leave-record-report?employee_id=EMP001` | Filter by employee | | GET | `/api/v1/force-leave-record-report?year=2026` | Filter by year | | GET | `/api/v1/force-leave-record-report?status=pending` | Filter by status (pending/in_progress/completed) | #### Report Response (JSON) ```json { "success": true, "data": [ { "id": 1, "employee_id": "EMP001", "employee": { "full_name": "Dela Cruz, Juan A.", "division": "Administrative Division" }, "year": 2026, "excess_vl_days": 15, "required_force_leave_days": 5, "scheduled_days": 3, "remaining_days": 2, "status": "in_progress", "created_at": "2026-05-18T10:00:00.000000Z" } ], "total": 1 } ``` #### Excel Export Columns | Column | Source | |--------|--------| | Employee Name | `employee.full_name` or `employee.name` | | Employee ID | `employee_id` | | Division | `employee.division` | | Year | `year` | | Excess VL Days | `excess_vl_days` | | Required FL Days | `required_force_leave_days` | | Scheduled Days | `scheduled_days` | | Remaining Days | `remaining_days` | | Status | `status` (ucfirst) | --- ## 3. Force Leave Management Screen Workflow ### Screen 1: Candidates List ``` ┌──────────────────────────────────────────────────────────────┐ │ Force Leave Management [Year: 2026▾] │ ├──────────────────────────────────────────────────────────────┤ │ ┌──────────────────────────────────────────────────────────┐│ │ │ Candidates (3) ││ │ │ ┌───────┬──────────┬──────┬──────┬──────┬──────┬────────┐│ │ │ │ Name │ Employee │ VL │Excess│Reqd │Schd │ Action ││ │ │ │ │ ID │ Bal │ Days │ Days │ Days │ ││ │ │ ├───────┼──────────┼──────┼──────┼──────┼──────┼────────┤│ │ │ │ Juan │ EMP001 │ 135 │ 15 │ 5 │ 0 │[Sched] ││ │ │ │ Maria │ EMP002 │ 142 │ 22 │ 5 │ 0 │[Sched] ││ │ │ │ Pedro │ EMP003 │ 128 │ 8 │ 5 │ 5 │ Done ✓ ││ │ │ └───────┴──────────┴──────┴──────┴──────┴──────┴────────┘│ │ └──────────────────────────────────────────────────────────┘│ │ │ │ ┌──────────────────────────────────────────────────────────┐│ │ │ Force Leave Record Report [Download ▾]││ │ │ ││ │ │ Summary: 3 candidates, 5 total required days remaining ││ │ └──────────────────────────────────────────────────────────┘│ └──────────────────────────────────────────────────────────────┘ ``` ### Screen 2: Schedule Dialog (Modal) When clicking [Sched] on a candidate: ``` ┌── Schedule Force Leave ────────────────────── [X] ─┐ │ │ │ Employee: Juan Dela Cruz (EMP001) │ │ VL Balance: 135 days (15 excess) │ │ Remaining: 5 days required │ │ │ │ Start Date: [2026-06-15 📅] │ │ Days: [5] │ │ │ │ ⚠ Must be at least 5 working days from today │ │ │ │ Scheduled Dates (preview): │ │ • Mon, Jun 15, 2026 │ │ • Tue, Jun 16, 2026 │ │ • Wed, Jun 17, 2026 │ │ • Thu, Jun 18, 2026 │ │ • Fri, Jun 19, 2026 │ │ │ │ [Cancel] [Schedule] │ └─────────────────────────────────────────────────────┘ ``` --- ## 4. Integration Checklist 1. **Add menu items** in `src/App/links.tsx`: - `Force Leave` under `LeaveLedger` → `{ label: "Force Leave", name: "ForceLeave", path: "/force-leave" }` - `Force Leave Record Report` under `LeaveManagementReport` → `{ label: "Force Leave Record Report", name: "ForceLeaveRecordReport", path: "/force-leave-record-report" }` 2. **Add routes** in `src/App/newFeature.tsx`: ```tsx } /> } /> ``` 3. **Register permission names** in the backend: - `ForceLeave` (may already exist) - `ForceLeaveRecordReport` 4. **Frontend validation** — mirror the 5 working day rule on the schedule form to provide instant feedback before the API call --- ## 5. Error Handling All endpoints return this format: ```json // Success { "success": true, "message": "...", "data": { "...response data..." } } // Validation Error (422) { "success": false, "message": "Force leave must be scheduled at least 5 working days in advance. Earliest date: 2026-06-01.", "data": null, "status_code": 422 } ``` | HTTP | Meaning | |------|---------| | 200 | Success | | 422 | Validation error (advance notice, days exceeded, no obligation, already completed) | | 500 | Server error | --- ## 6. Quick Reference ``` ─── FORCE LEAVE MANAGEMENT ─── Menu: Time Management > Leave Ledger > Force Leave [name: "ForceLeave"] GET /api/v1/cl/force-leave/candidates?year=2026 list candidates GET /api/v1/cl/force-leave/obligations?employee_id=X list obligations POST /api/v1/cl/force-leave/schedule schedule force leave ─── FORCE LEAVE RECORD REPORT ─── Menu: Time Management > Leave Management Report > Force Leave Record Report [name: "ForceLeaveRecordReport"] GET /api/v1/force-leave-record-report list records (JSON) GET /api/v1/force-leave-record-report?export=excel download Excel GET /api/v1/force-leave-record-report?employee_id=X filter by employee GET /api/v1/force-leave-record-report?year=2026 filter by year GET /api/v1/force-leave-record-report?status=pending filter by status ```