# Test Scenario Guide: Maintenance Inline Faults & Spare Parts

### 2. Scenario Introduction 🛠️
This feature refactors the maintenance visit execution flow to align with real-time technician behavior. Previously, technicians had to complete a visit before reporting faults or requesting spare parts, often leading to disconnected data. The new flow enables **inline reporting**: as a technician performs a checklist, they can immediately flag a non-compliant item, describe the fault, and list the required spare parts in a single, atomic operation per asset. This ensures **high data integrity** and a **seamless UX** for field operations.

### 3. Technical Schema Changes (Detailed) 🔍
The update introduces structured relationships between checklist responses, faults, and spare parts, moving away from unstructured JSON blobs.

* **Endpoint:** `POST /api/maintenance/visits/{id}/assets/maintenance`
* **Validation Changes:**
    * `assets.*.checklist_data.*.is_compliant`: **Required** boolean to explicitly track compliance.
    * `assets.*.checklist_data.*.fault`: **Nullable** object containing description and severity.
    * `assets.*.checklist_data.*.fault.description`: **Required** if a fault object is present.
    * `assets.*.checklist_data.*.fault.severity`: **Nullable** string.
    * `assets.*.checklist_data.*.fault.spare_parts`: **Nullable** array of parts required for that specific fault.
    * `assets.*.checklist_data.*.fault.spare_parts.*.part_name`: **Required** string for each spare part.
    * `assets.*.checklist_data.*.fault.spare_parts.*.quantity`: **Required** numeric value (min 0.01).
* **Response Changes:**
    * The `AssetMaintenanceResource` now returns a structured `faults` array, with nested `spare_parts` for each fault.
    * `checklist_data` is preserved for summary views but is no longer the primary source of truth for faults.

### 4. Why the Update? (Change Log) 🔄
| Feature | Previous Behavior | New Behavior |
| :--- | :--- | :--- |
| **Data Linking** | Spare parts linked to visits/assets generally. | Spare parts linked **directly to specific faults**. |
| **Workflow** | Async reporting (Visit -> Report -> Faults). | **Real-time inline reporting** during checklist execution. |
| **Integrity** | Dependency on `report_id` before it exists. | **No dependency** on reports; saves to primary tables immediately. |
| **Atomicity** | Multiple API calls required for one asset. | **Single atomic request** for all asset maintenance data. |

### 5. API Endpoints Table 📊
| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Save Maintenance** | `/api/maintenance/visits/{id}/assets/maintenance` | `POST` | Save responses, faults, and parts in one batch. |
| **View Maintenance** | `/api/maintenance/visits/{id}/assets/maintenance` | `GET` | Retrieve saved maintenance data for an asset. |
| **Add Fault (Old)** | `/api/maintenance/reports/{id}/faults` | `POST` | **DEPRECATED**: Legacy fault submission. |
| **Add Part (Old)** | `/api/maintenance/visits/{id}/spare-parts` | `POST` | **DEPRECATED**: Legacy spare part submission. |

### 6. Test Cases 🧪

* **[Case 1] The Happy Path (Complete Submission):**
    * **Input:** Valid visit ID, asset ID, and a checklist item with `is_compliant: false`, a `fault` description, and 2 `spare_parts`.
    * **Expected Result:** HTTP 200. Verify `mod_maintenance_visit_checklist_responses` created, `mod_maintenance_visit_faults` created and linked to the response, and 2 `mod_maintenance_visit_spare_parts` created and linked to the fault.

* **[Case 2] Backward Compatibility & Minimal Data:**
    * **Input:** Valid visit ID, asset ID, but only `checklist_data` with `is_compliant: true` and no fault/parts.
    * **Expected Result:** HTTP 200. Verify only the response record is created/updated. Ensure `AssetMaintenanceChecklist` summary is still updated for legacy compatibility.

* **[Case 3] Edge Cases & Constraints (Validation):**
    * **Input:** `is_compliant: false` with a `fault` object but missing `description`.
    * **Expected Result:** HTTP 422. Validation error: "The fault description is required."
    * **Input:** Negative `quantity` for a spare part.
    * **Expected Result:** HTTP 422. Validation error: "Quantity must be at least 0.01."

---
*Generated by Technical Writer AI based on workspace refactoring.*