# Test Scenario Guide: Automated Attendance Checkout and Filtering

### 2. Scenario Introduction 🏢
The **Automated Attendance Checkout** feature ensures that all employee attendance records are properly closed at the end of the day. In many workplace environments, employees may forget to "Check Out," leading to incomplete records that complicate payroll and performance tracking. 

This update introduces a **Midnight Split Logic**: if an employee is still checked in when the system reaches 12:00 AM, the system automatically performs a "Check Out" at **23:59:59** for the current day and performs an "Auto Check-In" at **00:00:00** for the new day. This maintains data accuracy for continuous night shifts while ensuring no "open" records persist indefinitely. Additionally, it provides managers with the ability to **filter** records to distinguish between manual actions and system-automated operations.

---

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

#### Database Migrations
*   **New Columns:**
    *   `is_auto_checkout`: Boolean (default: `false`). Marks if the record was closed by the system.
    *   `is_auto_checkin`: Boolean (default: `false`). Marks if the record was created by the midnight split process.

#### API Changes
*   **Endpoint:** `GET /api/v1/attendances/list`
*   **Validation Changes:**
    *   Added `is_auto_checkout`: `nullable|boolean`. Allows filtering by automated checkout status.
*   **Response Changes:**
    *   Added `is_auto_checkout` to the attendance object.
    *   Added `is_auto_checkin` to the attendance object.

---

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Midnight Handling** | Records remained "Open" until manually closed the next day or later. | Records are split at **23:59:59** and **00:00:00**. | **Data Integrity**: Accurate daily working hour calculations. |
| **Checkout Logic** | Auto-checkout was generic and often applied late (e.g., 1:00 AM). | Precise midnight execution with dedicated automation flags. | **Compliance**: Aligns with daily payroll cycles. |
| **Filtering** | No way to filter between manual and system checkouts. | New `is_auto_checkout` filter in the list endpoint. | **Visibility**: Better auditing for HR and managers. |

---

### 5. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **List Attendance** | `/api/v1/attendances/list` | `GET` | Retrieves attendance records with optional `is_auto_checkout` filter. |
| **Attendance Stats** | `/api/v1/attendances/list` | `GET` | Included statistics now reflect the filtered dataset. |

---

### 6. Test Cases 🧪

#### **[Case 1] The Happy Path: Midnight Split**
1.  **Scenario:** Employee "A" checks in at **10:00 PM** on Monday.
2.  **Action:** The system reaches **12:00 AM** (Midnight) on Tuesday.
3.  **Expected Result:**
    *   Monday's record is updated with `check_out: 23:59:59` and `is_auto_checkout: true`.
    *   A new record for Tuesday is created with `check_in: 00:00:00` and `is_auto_checkin: true`.

#### **[Case 2] Backward Compatibility**
1.  **Scenario:** Fetching records created *before* this update.
2.  **Expected Result:** Existing records should return `is_auto_checkout: false` and `is_auto_checkin: false` by default, ensuring existing reports and integrations do not break.

#### **[Case 3] Edge Cases & Constraints**
*   **Filtering Validation:** 
    *   Send `is_auto_checkout=invalid_string`. 
    *   **Expected Result:** `422 Unprocessable Entity` validation error.
*   **Multiple Midnight Passes:** 
    *   If a record was already auto-checked out, the system should not process it again.
*   **Holiday/Leave Interaction:**
    *   The system verifies if the day is a holiday before applying standard auto-checkout rules for "older" missing records.

---
> [!NOTE]
> The automated process is scheduled via the system cron to run exactly at `00:00` daily. Ensure the server timezone is correctly configured to match the company's local time.