# Test Scenario Guide: Maintenance Visit Execution Enhancements (US-010)

### 1. Title
`# Test Scenario Guide: Maintenance Visit Execution Enhancements (US-010)`

### 2. Scenario Introduction
This feature enhances the maintenance visit report workflow by introducing a **DRAFT** status for technicians to save progress, a structured **Fault Reporting** mechanism linked to checklist responses, and an automated notification system for the Finance department when reports are ready for invoicing (**AWAITING_INVOICING**). It also adds bilingual support for checklist questions and more granular tracking for spare parts (make, model, quantity used) to ensure high data integrity and financial accuracy.

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

Analyze the changes in **FormRequest validation rules** and **API Responses**:

*   **Endpoint:** `POST /api/v1/maintenance/reports/{id}/faults`
    *   **Validation Changes:** New request `StoreMaintenanceVisitFaultRequest`.
        *   `checklist_item_answer_id`: Required, must exist in `mod_maintenance_visit_checklist_responses`.
        *   `description`: Required string.
*   **Endpoint:** `GET /api/v1/maintenance/reports/{id}/faults`
    *   **Response Changes:** Returns a collection of structured faults including linked checklist items and media attachments.
*   **Endpoint:** `POST /api/v1/maintenance/reports/{id}/faults/{faultId}/attachments`
    *   **Validation Changes:**
        *   `files`: Required array of temporary folders.
*   **Endpoint:** `POST /api/v1/maintenance/reports` & `PUT /api/v1/maintenance/reports/{id}`
    *   **Validation Changes:** `work_performed` is now `nullable` if status is `draft`, but `required` if status is `awaiting_approval`, `completed`, or `awaiting_invoicing`.
    *   **Enum Updates:** Added `draft` and `awaiting_invoicing` values to `VisitReportStatus`.
*   **Response Changes (Resources):**
    *   **MaintenanceChecklistItemResource**: Added `question_text_ar` and `question_text_en`.
    *   **MaintenanceVisitReportResource**: Added `checklist_faults` relationship and deprecated `fault_description` in favor of structured faults.
    *   **MaintenanceVisitSparePartResource**: Added `brand`, `make`, `model`, and `quantity_used` fields.

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

*   **Data Integrity**: Structured fault reporting prevents data loss and ensures every fault is tied to a specific checklist item validation.
*   **Operational Efficiency**: The `DRAFT` status prevents technicians from losing data during long site visits with intermittent connectivity.
*   **Financial Acceleration**: Automated notifications to the Finance team when a report is marked as `AWAITING_INVOICING` reduces the "time-to-bill" lag.
*   **Compliance**: Bilingual checklist items allow for better communication between multi-national teams and clients.

### 5. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Create Fault Report | `/api/v1/maintenance/reports/{id}/faults` | `POST` | Links a specific fault description to a non-compliant checklist response. |
| Get Report Faults | `/api/v1/maintenance/reports/{id}/faults` | `GET` | Retrieves all structured faults and their associated photos for a report. |
| Upload Fault Photos | `/api/v1/maintenance/reports/{id}/faults/{faultId}/attachments` | `POST` | Saves photos to a specific fault record using temporary file IDs. |
| Save Report Draft | `/api/v1/maintenance/reports` | `POST/PUT` | Saving with status `draft` bypasses mandatory content validation. |
| Advance to Invoicing | `/api/v1/maintenance/reports/{id}` | `PUT` | Setting status to `awaiting_invoicing` triggers Finance notifications. |

### 6. Test Cases 🧪

*   **[Case 1] The Happy Path:**
    *   1. Technician creates a visit report with status `draft`.
    *   2. Technician answers "No" to a checklist item.
    *   3. Technician creates a "Fault" linked to that "No" response.
    *   4. Technician uploads 2 photos to the fault.
    *   5. Technician completes the report and sets status to `awaiting_invoicing`.
    *   **Expected Result**: Report is saved, fault is linked, photos are moved to permanent storage, and Finance users receive a notification.

*   **[Case 2] Backward Compatibility:**
    *   1. View an old visit report created before these changes.
    *   2. Verify that the `fault_description_deprecated` still contains the legacy text data.
    *   3. Ensure that spare part list displays correctly even if `make`/`model` fields are null for older records.

*   **[Case 3] Edge Cases & Constraints:**
    *   **Validation Failure**: Attempt to add a fault to a checklist item marked as "Compliant" (is_compliant = true). The system should reject this via `MaintenanceVisitFaultService`.
    *   **Validation Failure**: Attempt to set status to `awaiting_invoicing` while `work_performed` is empty. Should return a 422 error.
    *   **Permissions**: Verify that a user without `finance` role does NOT receive the "Ready for Invoicing" notification.
    *   **Data Consistency**: Verify that `quantity_used` in spare parts accepts decimal values (e.g., 1.5 units).