# OT Authorization — Frontend & ms-General Integration Guide

> **API Reference:** See [`ot-authorization-api.md`](./ot-authorization-api.md) for complete endpoint documentation, request/response schemas, and field values.

## Overview

The OT Authorization flow follows a **frontend-orchestrated** pattern:

1. **Frontend** creates the OT authorization on **ms-timekeeping**
2. **Frontend** submits the approval request to **ms-general** for the approval workflow
3. **Frontend** receives the ms-general decision and calls **ms-timekeeping** to finalize

```
Frontend                          ms-timekeeping                    ms-general
   │                                    │                              │
   │  (1) POST /filing_authority/overtime │                              │
   │  ───────────────────────────────────►│                              │
   │  ◄──────────────────── { id, status: "pending" }                   │
   │                                    │                              │
   │  (2) POST /api/v1/approval-requests  │                              │
   │  ───────────────────────────────────────────────────────────────►│
   │    module_code: "ot_authorization"  │                              │
   │    request_reference_id: "{overtimeId}" │                           │
   │  ◄──── { approval_request_id }  ◄─────────────────────────────────┤
   │                                    │                              │
   │              ... approval workflow happens in ms-general ...       │
   │                                    │                              │
   │  (3) Frontend/tab receives approval result from ms-general        │
   │                                    │                              │
   │  (4) POST /approval/filing_authority/overtime                    │
   │  ───────────────────────────────────►│                              │
   │    { id: [42], authorization_status: "approved" }                │
   │  ◄─── { success, updated, count } ──┤                              │
   │    (updates status, creates time_entry, credits COC)              │
   │                                    │                              │
```

## Step-by-Step for Frontend

### Step 1: Create OT Authorization

```
POST /api/v1/filing_authority/overtime
```

Creates the authorization record with `authorization_status: "pending"`.  
Send this from the OT Authorization Form UI.

**Response** includes the `id` of the created record — save this as `request_reference_id` for Step 2.

### Step 2: Submit to ms-General for Approval

After getting the OT authorization ID from Step 1, submit an approval request to **ms-general**:

```
POST {ms-general-base-url}/api/v1/approval-requests
```

**Request Body:**

| Field | Value | Description |
|-------|-------|-------------|
| `module_code` | `"ot_authorization"` | Identifies this as an OT authorization request |
| `section_code` | *section of the employee* | Determines the approval routing (division/section) |
| `filed_by` | *employee ID* | Who filed the request |
| `request_reference_id` | *OT authorization ID from Step 1* | Links back to the OT record |
| `callback_url` | *optional, can be omitted* | Frontend handles the result, not callback |

**How to get `section_code`:**  
Use the existing endpoint on ms-timekeeping to get the employee's section:
```
GET /api/v1/dtr/employee-section?employee_id=EMP001
```

**Response:**
```json
{
  "success": true,
  "data": {
    "employee_id": "EMP001",
    "section_code": "Human Resources Division"
  }
}
```

### Step 3: Wait for ms-General Decision

The approval workflow happens in ms-general. The frontend should either:
- **Poll** ms-general for the approval request status
- **Listen** for a webhook/event from ms-general
- **Let the user refresh** to check the status

Once ms-general returns the approval decision, proceed to Step 4.

### Step 4: Finalize on ms-Timekeeping

When ms-general returns **approved** or **rejected**, call ms-timekeeping to finalize:

```
POST /api/v1/approval/filing_authority/overtime
```

**If approved:**
```json
{
  "id": [42],
  "authorization_status": "approved",
  "remarks": "Approved per division head"
}
```

**If rejected:**
```json
{
  "id": [42],
  "authorization_status": "rejected",
  "remarks": "Insufficient justification"
}
```

**What happens on approval in ms-timekeeping:**
1. `authorization_status` → `approved`
2. Creates/updates `time_entry` linked to this OT (OT appears in DTR)
3. Auto-generates schedule/shift if employee has none for that date
4. Creates COC entry (`+` operator) only if `compensation_mode = compensatory_overtime_credit`

**Response:**
```json
{
  "success": true,
  "data": {
    "success": true,
    "updated": [42],
    "count": 1
  },
  "message": "Overtime approval processed successfully"
}
```

---

## What Frontend Needs from Each Service

### From ms-timekeeping (`/api/v1`)

| Needed For | Endpoint | When |
|------------|----------|------|
| Employee section code | `GET /dtr/employee-section?employee_id=X` | Before submitting to ms-general (Step 2) |
| Create OT authorization | `POST /filing_authority/overtime` | Step 1 |
| Finalize approval | `POST /approval/filing_authority/overtime` | Step 4 |
| COC balance | `GET /available_hours/cto?employee_id=X` | Display on UI |
| OT report | `GET /overtime-report?date_from=X&date_to=X` | Reporting |

### From ms-general

| Needed For | Endpoint | When |
|------------|----------|------|
| Submit approval request | `POST /api/v1/approval-requests` | Step 2 |
| Check approval status | `GET /api/v1/approval-requests/{id}` | After Step 2 |

---

## ms-General: What to Implement

### Endpoint: POST /api/v1/approval-requests

Create an approval request for OT authorization workflow.

**Request Body:**
```json
{
  "module_code": "ot_authorization",
  "section_code": "Human Resources Division",
  "filed_by": 1001,
  "request_reference_id": "42"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `module_code` | `string` | Always `"ot_authorization"` |
| `section_code` | `string` | Section/division code for routing |
| `filed_by` | `int` | Employee ID who filed |
| `request_reference_id` | `string` | OT authorization ID from ms-timekeeping |

**Response:**
```json
{
  "success": true,
  "data": {
    "approval_request": {
      "id": 5001,
      "module_code": "ot_authorization",
      "status": "pending",
      "...": "..."
    }
  }
}
```

### Endpoint: GET /api/v1/approval-requests/{id}

Returns the current status of the approval request. The frontend polls this.

**Response:**
```json
{
  "success": true,
  "data": {
    "approval_request": {
      "id": 5001,
      "module_code": "ot_authorization",
      "status": "approved",
      "request_reference_id": "42",
      "...": "..."
    }
  }
}
```

| Status | Meaning |
|--------|---------|
| `pending` | Still in approval workflow |
| `approved` | Approved — frontend should call ms-timekeeping to finalize |
| `rejected` | Rejected — frontend should call ms-timekeeping to finalize |

---

## Complete Frontend Sequence Pseudocode

```javascript
// Step 1: Create OT authorization
const created = await api.post('/api/v1/filing_authority/overtime', {
  employee_id: ['EMP001'],
  date_filed: '2026-05-25',
  date_overtime: ['2026-05-27'],
  time_start: '17:00:00',
  time_end: '20:00:00',
  total_hours: 3,
  ot_type: 'weekday_ot',
  compensation_mode: 'compensatory_overtime_credit',
  broken_date: true
});
const overtimeId = created.data.id;

// Step 2: Get employee section code
const sectionRes = await api.get('/api/v1/dtr/employee-section', {
  params: { employee_id: 'EMP001' }
});
const sectionCode = sectionRes.data.data.section_code;

// Step 3: Submit to ms-general
const approvalRes = await msGeneralApi.post('/api/v1/approval-requests', {
  module_code: 'ot_authorization',
  section_code: sectionCode,
  filed_by: 1001,
  request_reference_id: String(overtimeId)
});
const approvalRequestId = approvalRes.data.data.approval_request.id;

// Step 4: Poll or wait for approval result from ms-general
// (implementation depends on ms-general's mechanism)

// Step 5: When ms-general returns the decision, finalize on ms-timekeeping
const decision = 'approved'; // or 'rejected'
await api.post('/api/v1/approval/filing_authority/overtime', {
  id: [overtimeId],
  authorization_status: decision,
  remarks: 'Approved per division head'
});
```