# Test Scenario Guide: Attendance & Reporting Enhancements

### 1. Scenario Introduction 🏢
This update enhances the **Attendance Management System** by introducing advanced reporting analytics, enforcing **Financial Integrity** for payroll-related data, and standardizing employee records. The primary goal is to provide administrators with real-time attendance statistics while ensuring that any data already transferred to payroll (salary) remains immutable to prevent financial discrepancies.

---

### 2. Technical Schema Changes (Detailed) 🔍

#### 📊 Attendance Reporting
*   **Endpoint:** `GET /api/v1/attendances/list`
*   **Response Changes:** Added a `statistics` object to the root response.
    *   `total_employees`: Total active employees in the company.
    *   `present`: Count of unique employees who checked in during the period.
    *   `late`: Count of attendance records with a delay in arrival.
    *   `on_leave`: Count of unique employees on approved leave during the period.
    *   `on_break`: Count of attendance records currently marked as "on break".
    *   `absent`: Calculated count of employees neither present nor on leave.

#### 🛡️ Financial Integrity (Rewards & Penalties)
*   **Database Schema:** Added `is_transferred_to_salary` (boolean, default: false) to the `rewards_and_penalties` table.
*   **Validation Changes:**
    *   `PUT /api/v1/rewards-penalties/{id}`: Now throws a **422 Unprocessable Entity** if `is_transferred_to_salary` is true or `is_collected` is true.
    *   `DELETE /api/v1/rewards-penalties/{id}`: Now throws a **422 Unprocessable Entity** if `is_transferred_to_salary` is true or `is_collected` is true.

#### 📍 Location & Metadata
*   **Database Schema:** Added `ip_address` and `checkout_ip_address` to the `attendances` table.
*   **Endpoint:** `POST /api/v1/attendances/check-in` & `check-out`
*   **Logic:** Automatically captures the client's IP address and stores it in the respective fields.

#### 📝 Employee Records
*   **ID Format:** Standardized from `EMP-YYYY-XXXX` to a cleaner `EMP-XXXX` format.
*   **User Status:** Default status for newly created users is now automatically set to `active`.

---

### 3. Why the Update? (Change Log) 🔄

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Attendance Stats** | Only paginated list was returned. | Returns summary stats (Present/Late/Absent) alongside the list. | Faster decision-making for HR. |
| **Payroll Security** | Rewards could be edited after being paid. | Processed rewards/penalties are now immutable. | **Financial Integrity** and audit compliance. |
| **IP Auditing** | No track of where check-in occurred via network. | Captures IP address for every check-in/out. | Enhanced security and proxy prevention. |
| **ID Standardization**| Year-based complex IDs. | Simplified `EMP-XXXX` format. | Consistency across all modules. |
| **Holiday Awareness**| Absence violations created on holidays. | System skips absence violations on holidays/leaves. | Reduced manual correction of false violations. |

---

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Attendance List** | `/api/v1/attendances/list` | `GET` | Returns attendance records + summary statistics. |
| **Check-In** | `/api/v1/attendances/check-in` | `POST` | Record check-in + captures current IP address. |
| **Check-Out** | `/api/v1/attendances/check-out` | `POST` | Record check-out + captures current IP address. |
| **Leave List** | `/api/v1/leaves/list` | `GET` | Filter leaves by `leave_type` and `status`. |
| **Update Reward** | `/api/v1/rewards-penalties/{id}`| `PUT` | Update record (Blocked if transferred to salary). |

---

### 5. Test Cases 🧪

#### ✅ [Case 1] The Happy Path: Real-time Statistics
*   **Action:** Call `GET /api/v1/attendances/list` with `start_date` and `end_date`.
*   **Expected Result:** Receive 200 OK with a `statistics` block containing accurate counts that match the filtered results.

#### 🔄 [Case 2] Backward Compatibility: Legacy Records
*   **Action:** View an attendance record created before the IP tracking update.
*   **Expected Result:** The system should return `null` for IP fields without errors, and statistics should still calculate based on existing status fields.

#### 🚫 [Case 3] Edge Cases & Constraints: Financial Lock
*   **Scenario A (Salary Lock):** Attempt to update a Reward where `is_transferred_to_salary = 1`.
    *   **Expected Result:** 422 Error: "Cannot update reward already transferred to salary."
*   **Scenario B (Holiday Absence):** Run the violation checker on a date marked as a **Company Holiday**.
    *   **Expected Result:** No "Missing Check-in" violations should be created for any active employees.
*   **Scenario C (IP Metadata):** Check-in from a specific network.
    *   **Expected Result:** Verify that the `ip_address` field in the database correctly reflects the caller's IP.