# Test Scenario Guide: Mandatory Google Maps URL and GPS Enforcement in Handover Visit

### 1. Scenario Introduction 🌐
The implementation ensures that every **Handover Visit** (the first critical visit to a client site) captures precise geographic data. This is essential for the **Smart Geographic Distribution** of future maintenance visits, allowing the system to group visits based on real proximity rather than just administrative regions. By enforcing a **Google Maps URL** and validated **GPS coordinates**, we eliminate ambiguity in site location and enable automated technician dispatching logic.

---

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

*   **Endpoint:** `POST /api/v1/maintenance/handover-visits/{visit}/complete`
*   **Validation Changes:**
    *   `google_maps_url`: Changed from `nullable` to `required|url|regex:/^https:\/\/(maps\.google\.com|goo\.gl|maps\.app\.goo\.gl)/`.
    *   `latitude`: Changed from `nullable` to `required|numeric|between:-90,90`.
    *   `longitude`: Changed from `nullable` to `required|numeric|between:-180,180`.
*   **Model Logic Changes:**
    *   The `completeHandoverVisit` service now automatically synchronizes the submitted coordinates to the `ClientSite` record associated with the project.
    *   `SmartSchedulingService` now explicitly checks for the presence of these coordinates before allowing any cluster-based distribution.

---

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

| Feature | Previous Behavior | New Behavior |
| :--- | :--- | :--- |
| **GPS Enforcement** | Coordinates were optional, leading to missing data. | Mandatory for Handover Visit completion. |
| **Location Accuracy** | Relied on `city`/`region` strings for clustering. | Enforces precise GPS coordinates for all future visits. |
| **Validation Rules** | Basic URL validation only. | Strict Google Maps regex validation (supports `goo.gl` & `maps.app.goo.gl`). |
| **Data Sync** | Coordinates stayed on the visit record only. | Automatically updates the **Project Site/Location** record. |
| **Scheduling Guard** | Silent fallback to city-based clustering if GPS was missing. | Throws a hard exception if GPS coordinates are missing. |

---

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Complete Handover** | `/api/v1/maintenance/handover-visits/{visit}/complete` | `POST` | Finalizes handover and updates project location GPS. |
| **Smart Suggestion** | `/api/v1/maintenance/smart-scheduling/suggest` | `GET/POST` | Generates suggestions; fails if any visit has no GPS. |

---

### 5. Test Cases 🧪

#### [Case 1] The Happy Path ✅
*   **Action:** Technician submits a completion request with a valid Google Maps link (e.g., `https://maps.app.goo.gl/xyz`) and numeric coordinates.
*   **Expectation:** 
    *   API returns `200 OK`.
    *   The visit is marked as `COMPLETED`.
    *   The associated `ClientSite` table is updated with the new `latitude`, `longitude`, and `google_maps_url`.

#### [Case 2] Validation Failure: Invalid URL ❌
*   **Action:** Submit a non-Google Maps URL (e.g., `https://bing.com/maps`).
*   **Expectation:** 
    *   API returns `422 Unprocessable Entity`.
    *   Error message: `"The google maps url field format is invalid."`

#### [Case 3] Validation Failure: Missing Coordinates ❌
*   **Action:** Submit the handover completion with `actual_assets` but without `latitude` or `longitude`.
*   **Expectation:** 
    *   API returns `422 Unprocessable Entity`.
    *   Validation errors for both missing numeric fields.

#### [Case 4] Smart Scheduling Guard 🛡️
*   **Action:** Attempt to run **Smart Scheduling** for a project where the handover visit was completed *before* this enforcement (missing GPS).
*   **Expectation:** 
    *   The system throws an Exception: `"Smart scheduling requires GPS coordinates. Please complete the handover visit first for project: [Project Name]"`.
    *   No silent fallback to city/region grouping occurs.

#### [Case 5] Backward Compatibility 🔄
*   **Action:** Run a regular Preventive Maintenance (PM) visit completion.
*   **Expectation:** 
    *   PM visits do not trigger the mandatory GPS rule (unless they share the same request class).
    *   The system continues to allow regular visit workflows while strictly controlling the "Gatekeeper" handover visit.