# Test Scenario Guide: Maintenance Backlog & Smart Scheduling

### 1. Scenario Introduction 🛠️
The **Maintenance Backlog Dispatching** system is designed to manage large volumes of planned maintenance visits. A critical part of this process is **Smart Suggestion**, which automatically matches visits to the best-suited technicians based on their **specialties (System Types)** and **geographical location (Coordinates)**.

To ensure accuracy, each visit must accurately report its **System Type** (e.g., Elevators, HVAC) and **Asset Count**. This allows the algorithm to:
1.  Filter technicians who are certified for that specific system.
2.  Calculate the workload impact based on the number of units to be serviced.

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

*   **Model:** `App\Domains\Maintenance\SubDomains\Visits\Models\MaintenanceVisit`
    *   **Added Accessor:** `system_type`. Provides a fallback mechanism if the direct column is empty.
        *   Priority: `direct column` > `linked asset type` > `contract technical offer` > `first project asset type`.
    *   **Added Accessor:** `asset_count`. Ensures a minimum of 1 unit is reported.
        *   Priority: `direct column` > `technical offer unit count` > `project asset total count`.

*   **Service:** `App\Domains\Maintenance\Services\BacklogDispatchingService`
    *   **Endpoint:** `GET /api/v1/maintenance/backlog-dispatching/config`
        *   **Change:** `system_types` now dynamically returns only the types currently present in the pending backlog, rather than all possible system types in the company.
    *   **Endpoint:** `GET /api/v1/maintenance/backlog-dispatching/backlog`
        *   **Change:** Standardized response to use the new `system_type` and `asset_count` accessors.

*   **Service:** `App\Domains\Maintenance\Services\SmartSchedulingService`
    *   **Logic Change:** Improved eager loading of nested relationships (`project.contract.technicalOffer`, etc.) to support the new fallback logic without performance degradation (N+1 fix).

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **System Identification** | Returned `null` if the visit wasn't explicitly linked to a system type. | Multi-level fallback to identify system type from project or contract. | Better technician matching. |
| **Workload Calculation** | Returned `0` units for many visits, leading to incorrect load percentages. | Defaults to contract unit counts or project asset counts. | Accurate workload planning. |
| **Filter Options** | Showed all system types, even those with no pending visits. | Shows only relevant system types found in the current backlog. | Cleaner UI / Improved UX. |

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Get Config | `/api/v1/maintenance/backlog-dispatching/config` | `GET` | Retrieve filter options including relevant system types. |
| Get Backlog | `/api/v1/maintenance/backlog-dispatching/backlog` | `GET` | List visits with accurate system types and unit counts. |
| Smart Suggest | `/api/v1/maintenance/backlog-dispatching/smart-suggest` | `POST` | Get AI-driven technician assignment proposals. |

### 5. Test Cases 🧪

*   **[Case 1] The Happy Path (Complete Data):**
    *   **Input:** Request backlog for a project with defined assets and a contract.
    *   **Expected Result:** `system_type` shows the asset's system (e.g., "Elevator") and `asset_count` matches the unit count in the technical offer.
*   **[Case 2] Fallback Logic (Missing Direct Link):**
    *   **Input:** A visit with `maintenance_project_asset_id = null` but linked to a project that has assets.
    *   **Expected Result:** The system should look at the project's assets and return the type of the first asset found.
*   **[Case 3] Smart Suggestion with specialties:**
    *   **Input:** Call `smart-suggest` for a month containing "Chiller" visits.
    *   **Expected Result:** Technicians without the "Chiller" specialty should NOT be assigned these visits. The response should cluster visits correctly by their derived system types.
*   **[Case 4] Empty Backlog Config:**
    *   **Input:** Request `/config` when no visits are planned.
    *   **Expected Result:** `system_types` should fall back to returning all active system types defined in the system.