# Test Scenario Guide: Custody Transfer API Layer 📦

### 1. Scenario Introduction ℹ️
The **Custody Transfer** feature is critical for the **Maintenance Domain** to track the physical movement of spare parts throughout the visit lifecycle. It ensures financial and operational accountability by documenting each handover point: from the store to transit, from transit to a technician, and finally from the technician to the client. This audit trail is backed by **GPS coordinates** and **photographic evidence** to prevent inventory shrinkage and resolve disputes regarding part possession.

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

#### **Endpoint 1: Record Handover**
* **Method:** `POST`
* **Path:** `/api/v1/visits/{visit}/handover`
* **Validation Rules (`VisitHandoverRequest`):**
    * `handover_type`: **Required**. Must be one of: `store_to_transit`, `transit_to_technician`, `technician_to_client`.
    * `gps_lat`: **Required**. Numeric, between -90 and 90.
    * `gps_lng`: **Required**. Numeric, between -180 and 180.
    * `items`: **Required**. Array, minimum 1 item.
    * `items.*.id`: **Required**. Must exist in `mod_maintenance_visit_spare_parts` table.
    * `items.*.quantity`: **Required**. Integer, minimum 1.
    * `photos`: **Required**. Array, minimum 1 file.
    * `photos.*`: **Required**. Must be an image (`jpeg`, `png`, `jpg`) and maximum 5MB.
    * `from_user_id`: **Required**. Must be a valid user ID.
    * `to_user_id`: **Required**. Must be a valid user ID.
* **Response Changes:**
    * Returns the newly created `VisitHandoverLog` object on success (HTTP 201).
    * Standardizes error responses using `ApiResponse` trait (HTTP 400 for logic errors, 422 for validation).

#### **Endpoint 2: Handover Logs**
* **Method:** `GET`
* **Path:** `/api/v1/visits/{visit}/handover-logs`
* **Pagination:**
    * Implements standard **15 items per page** pagination.
* **Response Changes:**
    * Includes eager-loaded `fromUser` and `toUser` relationships.
    * Returns paginated metadata (total, per_page, current_page, etc.).

### 3. Why the Update? (Change Log) 🔄
| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **API Access** | Business logic existed in services but was unreachable via API. | Dedicated RESTful endpoints for handover operations. | Enables mobile/web app integration. |
| **Data Integrity** | Manual or unrecorded transfers led to inventory gaps. | Enforced GPS and photo capture for every transfer. | Robust audit trail and loss prevention. |
| **Validation** | No centralized validation for handover payloads. | Strict `FormRequest` validation for types, ranges, and files. | Prevents corrupted or incomplete log entries. |
| **Visibility** | No way to view the custody chain for a visit. | Searchable, paginated history of all handovers. | Improved operational transparency. |

### 4. API Endpoints Table 📊
| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Record Handover** | `/api/v1/visits/{visit}/handover` | `POST` | Records a new custody transfer with GPS and photos. |
| **View Logs** | `/api/v1/visits/{visit}/handover-logs` | `GET` | Retrieves paginated handover history for a visit. |

### 5. Test Cases 🧪

#### **[Case 1] The Happy Path (Technician to Client) ✅**
* **Action:** Submit a POST request to `/handover` with `handover_type: technician_to_client`.
* **Payload:** Include 1 valid spare part ID, GPS coordinates, 1 JPG photo, and valid `from`/`to` user IDs.
* **Expected Result:** HTTP 201 Created. A new `VisitHandoverLog` is generated, and the spare part `custody_state` transitions to `client_accepted`.

#### **[Case 2] Missing Evidence (Validation Failure) ❌**
* **Action:** Submit a POST request to `/handover` without the `photos` array.
* **Expected Result:** HTTP 422 Unprocessable Entity. Error message specifies that at least one photo is required.

#### **[Case 3] Invalid State Transition (Business Logic) ⚠️**
* **Action:** Attempt to record a `store_to_transit` handover for an item that is already `with_technician`.
* **Expected Result:** HTTP 400 Bad Request. Service throws a `ValidationException` (handled by controller) stating the item cannot move backwards in the custody chain.

#### **[Case 4] Unauthorized Access 🔒**
* **Action:** Attempt to access `handover-logs` without a valid `sanctum` token.
* **Expected Result:** HTTP 401 Unauthorized. Access is protected by the `auth:sanctum` middleware.