# Test Scenario Guide: Team Classification & Smart Visit Routing

### 1. Scenario Introduction 🌐
The **Team Classification & Smart Visit Routing** feature is designed to automate and optimize the assignment of maintenance visits to technicians. By grouping technicians into **Specialized Teams**, the system ensures that:
*   **Expertise Match**: Visits are only assigned to teams with the required technical specialties (e.g., HVAC, Electrical, Plumbing).
*   **Chiller Safety**: High-stakes "Chiller" units are strictly handled by certified teams.
*   **Efficiency**: Teams are suggested based on **Geographic Proximity** (minimizing travel) and **Workload Capacity** (preventing burnout).

---

### 2. Technical Schema Changes 🔍

#### **Database Migrations**
*   **`maintenance_teams`**: Stores team metadata (`name`, `max_daily_visits`, `company_id`).
*   **`maintenance_team_users`**: Pivot table linking `users` to `teams` with an `is_leader` flag.
*   **`maintenance_team_specialties`**: Pivot table linking `teams` to `mod_maintenance_asset_types`.

#### **Model Updates**
*   **`User`**: Added `team()` relationship (`BelongsToMany`) and `specialties` (JSON cast) for backward compatibility with legacy technician profiles.
*   **`MaintenanceVisit`**: Integrated with `TeamRoutingService` to provide real-time suggestions in the backlog view.

#### **Validation & Response Changes**
*   **Endpoint:** `POST /api/v1/maintenance/visits/{id}/assign-team`
    *   **Validation**: `team_id` (Required, Exists), `override_leader_id` (Optional, Exists).
    *   **Logic**: Enforces **Specialty Validation** and the **Chiller Hard Constraint** at the service level.
*   **Endpoint:** `GET /api/v1/maintenance/backlog-dispatching/backlog`
    *   **Response**: Injected `suggested_teams` array. Each entry includes `team_id`, `team_name`, `score`, and `leader_name`.

---

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Assignment** | Individual technician assignment only. | Team-based assignment with automatic leader/member roles. | Scalability & Accountability. |
| **Routing** | Manual selection from a long list of technicians. | Smart suggestions based on scoring (+2 Geography, +1 Load). | Operational Efficiency. |
| **Validation** | No automated check for specialized unit types. | Hard rejection for Chiller units if team is unqualified. | Risk Mitigation & Safety. |
| **Data Structure**| Scattered technician skills. | Centralized Team Specialties. | Data Integrity. |

---

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Team List** | `/api/v1/maintenance/teams` | `GET` | Retrieve all teams with members and specialties. |
| **Create Team** | `/api/v1/maintenance/teams` | `POST` | Initialize a new team with name and specialty IDs. |
| **Team Detail** | `/api/v1/maintenance/teams/{id}` | `GET` | View team members, leader, and specialties. |
| **Manage Members**| `/api/v1/maintenance/teams/{id}/members`| `POST`| Sync or attach technicians to a team. |
| **Set Leader** | `/api/v1/maintenance/teams/{id}/leader/{user}`| `POST`| Designate exactly one leader per team. |
| **Team Workload** | `/api/v1/maintenance/teams/workload` | `GET` | Get real-time load % and visit counts per team. |
| **Team Assign** | `/api/v1/maintenance/visits/{id}/assign-team`| `POST`| Dispatch a visit to a specialized team. |

---

### 5. Test Cases 🧪

#### **[Case 1] The Happy Path: Successful Team Dispatch**
1.  **Setup**: Create a team "HVAC Alpha" with "Chiller" and "FCU" specialties.
2.  **Action**: Assign 3 technicians to the team and set one as Leader.
3.  **Observation**: Call `GET .../backlog`. Verify "HVAC Alpha" appears in `suggested_teams` for a visit containing a Chiller unit.
4.  **Execution**: Call `POST .../assign-team` with `team_id`.
5.  **Result**: HTTP 200. Visit status changes to `scheduled`. `mod_maintenance_technician_assignments` contains all 3 members (1 lead, 2 members). Leader receives `VisitDispatchedNotification`.

#### **[Case 2] Backward Compatibility: Legacy Technicians**
1.  **Setup**: Use a technician with the old `specialties` JSON field but no team membership.
2.  **Action**: Perform a standard individual dispatch using the existing `visits/{id}/dispatch` endpoint.
3.  **Result**: HTTP 200. The system continues to support individual technician assignment without requiring team membership.

#### **[Case 3] Edge Cases & Constraints**
*   **Chiller Violation**: Attempt to assign a team without "Chiller" specialty to a visit containing a Chiller unit.
    *   **Expected**: HTTP 422 with message: *"This visit contains Chiller units. Only teams specialized in Chiller maintenance can be assigned."*
*   **Missing Specialties**: Attempt to assign a team to a visit where the team lacks one of the required asset type specialties.
    *   **Expected**: HTTP 422 rejection.
*   **Leaderless Team**: Attempt to assign a team that has no designated leader.
    *   **Expected**: HTTP 422 rejection.
*   **Workload Scoring**: Assign multiple visits to Team A today.
    *   **Expected**: Team A's routing score should decrease (loss of +1 Load score) once they exceed 75% capacity.