# Test Scenario Guide: GPS Geofencing for Visit Lifecycle

### 1. Scenario Introduction 🌍
The **GPS Geofencing** feature is a critical security and integrity layer for the Maintenance Management module. It ensures that technicians are physically present at the required locations when performing lifecycle actions on a visit. 
* **Departure Integrity:** Verifies the technician is at the **Office** when starting their journey.
* **Arrival Integrity:** Prevents "GPS Fraud" by blocking technicians from marking a visit as "Arrived" unless they are within a **100-meter** radius of the client site.
* **Supervisor Control:** Provides a fallback mechanism where a **Supervisor (R-02)** can manually override location blocks in exceptional cases (e.g., GPS drift, poor signal).

### 2. Technical Schema Changes 🔍

#### Database Migrations
* **`company_settings`**: Added `office_latitude`, `office_longitude`, `arrive_fence_meters`, and `depart_fence_meters`.
* **`mod_maintenance_visits`**: Added `departed_from_lat` and `departed_from_lng` for reference tracking.
* **`visit_gps_overrides`**: New table to log supervisor-approved arrivals that bypassed geofence checks.

#### API Validation & Response
* **Endpoint:** `POST /api/maintenance/visits/{id}/execution/arrive`
    * **Logic Change:** Now compares technician GPS (`lat`/`lng`) against `client_sites.latitude/longitude`.
    * **New Response (Error 422):** Returns `location_too_far` error code with `distance_meters` and `required_meters` if outside the fence.
* **Endpoint:** `POST /api/maintenance/visits/{id}/execution/depart`
    * **Logic Change:** Compares against `company_settings.office_latitude/longitude`. Logs a **Warning** if > 500m but does not block.
* **Endpoint:** `POST /api/maintenance/visits/{id}/execution/arrive-override` (NEW)
    * **Validation:** Requires `reason`, `technician_gps_lat`, and `technician_gps_lng`.
    * **Constraint:** Restricted to users with the **Technical Supervisor** or **R-02** role.

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Location Validation** | No proximity check; tech could check-in from anywhere. | **Blocking** check for Arrival (100m) and **Logged** check for Departure (500m). | Eliminates GPS fraud and ensures technician accountability. |
| **Handover Visits** | N/A | **Excluded** from geofence checks. | Allows setup of site coordinates during the initial handover visit without circular blocks. |
| **Reference Tracking** | Only tech GPS was stored. | Stores the **Office location** used at the time of departure. | Better auditing of departure origin. |
| **Exception Handling** | Generic 400 errors. | Specific **422 LocationTooFar** error with distance metrics. | Improved mobile UX; tech knows exactly how far they are. |

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Visit Departure** | `/api/maintenance/visits/{id}/execution/depart` | `POST` | Records departure; warns if far from office. |
| **Visit Arrival** | `/api/maintenance/visits/{id}/execution/arrive` | `POST` | Blocks arrival if >100m from site coordinates. |
| **Supervisor Override** | `/api/maintenance/visits/{id}/execution/arrive-override` | `POST` | Allows R-02 to force-arrive a visit with a reason. |

### 5. Test Cases 🧪

#### [Case 1] The Happy Path (Standard Arrival)
1.  **Setup:** Ensure the `ClientSite` has valid coordinates (e.g., 24.7136, 46.6753).
2.  **Action:** Technician calls `/arrive` with GPS coordinates within 50m of the site.
3.  **Expected:** Status changes to `ARRIVED`, timestamp recorded, and 200 OK response.

#### [Case 2] Backward Compatibility & Handover
1.  **Scenario A (New Site):** Perform a `HANDOVER` visit.
    *   **Expected:** Proximity check is **skipped** regardless of coordinates, as site coords are being defined.
2.  **Scenario B (Missing Data):** Site coordinates are NULL.
    *   **Expected:** System logs a warning but **allows** the technician to arrive to avoid blocking work due to missing data.

#### [Case 3] Edge Cases & Constraints
1.  **Validation Failure (Distance):** Technician attempts to arrive from 1km away.
    *   **Expected:** `422 Unprocessable Entity` response with `error: location_too_far` and distance info.
2.  **Unauthorized Override:** A standard technician attempts to call `/arrive-override`.
    *   **Expected:** `403 Forbidden` response.
3.  **Successful Override:** A supervisor calls `/arrive-override` with a reason.
    *   **Expected:** 200 OK; record created in `visit_gps_overrides`.