# Test Scenario Guide: Supply Request Linked to Maintenance Visit (US-014)

### 1. Scenario Introduction 🏢
The **Supply Request Linked to Maintenance Visit** feature introduces a specialized workflow for supply chain management within the maintenance domain. When a supply order is generated from a **Maintenance Visit Report**, it often contains technical items that require specialized verification. 

The business logic enforces a **Technician-Led Review** gate. Technicians can now provide execution estimates, logistics notes, and mark specific items as **Internal/Hidden**. The system then automatically **distributes the cost** of these hidden items across visible items proportionally, ensuring that internal logistics or minor material costs are recovered in the final customer quotation without exposing internal details.

---

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

#### 📝 Validation Changes (FormRequests)
*   **Request:** `TechnicianReviewSupplyOrderRequest` (New)
    *   `execution_duration`: `nullable|integer|min:1` (Technician's estimated work time).
    *   `logistics_notes`: `nullable|string|max:1000` (Technical/logistics observations).
    *   `items.*.id`: `required|exists:sup_supply_order_items` (Validation of targeted items).
    *   `items.*.is_hidden_internal`: `sometimes|boolean` (Flag to mark items for cost distribution).
*   **Request:** `StoreSupplyOrderRequest` (Updated)
    *   Added `location_id`: `nullable|exists:cli_client_sites,id` to support site-specific visit filtering.

#### 📦 API Response Changes (Resources)
*   **Resource:** `SupplyOrderResource`
    *   Added `technician_execution_duration`: Estimated time provided by the tech.
    *   Added `technician_logistics_notes`: Internal logistics observations.
    *   Added `excluded_units_note`: Automatically generated note listing items from the visit NOT included in the order.
*   **Resource:** `SupplyOrderItemResource`
    *   Added `is_hidden_internal`: Boolean flag indicating internal visibility only.
    *   Added `distributed_hidden_cost`: Proportional cost allocated from hidden items.
*   **Resource:** `SupplyQuotationResource`
    *   **Filtering:** Items marked as `is_hidden_internal` are now **automatically excluded** from the items collection.
    *   Added `calculated_delivery_duration`: `execution_time` + `safety_margin`.

---

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Review Gate** | Orders went straight to pricing/approval. | Mandatory **Technician Review** for visit-linked orders. | Prevents quoting unverified or technically incorrect parts. |
| **Cost Recovery** | Internal costs were either quoted as line items or lost. | **Hidden Items** cost distribution across visible items. | Improves profitability while maintaining professional quotations. |
| **Duration Logic** | Delivery duration was manual and often inaccurate. | Automated formula: **Tech Duration + Supervisor Margin**. | Increases accuracy and accountability for delivery SLAs. |
| **Data Integrity** | No link to excluded parts from visits. | Automated **Excluded Units Note** generation. | Audit trail for why certain parts recorded in the field weren't ordered. |

---

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Visit Filtering** | `/api/v1/supply/orders/pending-maintenance-visits` | `GET` | Fetch visits filtered by Client AND Location. |
| **Technician Review** | `/api/v1/supply/orders/{order}/technician-review` | `POST` | Tech records duration, notes, and marks hidden items. |
| **Endorsement** | `/api/v1/supply/orders/{order}/technician-endorsement` | `POST` | Final verification and cost distribution trigger. |
| **Quotation Split** | `/api/v1/supply/quotations/{quotation}/split` | `POST` | Move specific items to a new quotation for approval. |

---

### 5. Test Scenarios 🧪

#### ✅ [Case 1] The Happy Path (Standard Workflow)
1.  **Generate Order:** Create a supply order from a `MaintenanceVisitReport`.
2.  **Technician Review:** Call `technician-review` providing `execution_duration` and marking 1 item as `is_hidden_internal`.
3.  **Pricing:** Agents provide pricing for all items (hidden and visible).
4.  **Endorsement:** Call `technician-endorsement`. Verify that the hidden item status becomes `TECHNICIAN_ENDORSED` and its cost is added to the `distributed_hidden_cost` of visible items.
5.  **Quotation:** Generate a Quotation. Verify that the **hidden item does not appear** in the items list, but the total amount remains accurate.

#### 🔄 [Case 2] Backward Compatibility
1.  **Legacy Orders:** Fetch a supply order created before these changes. Verify it defaults to `NEW` status and bypasses the technician review gates if not linked to a visit.
2.  **Legacy Quotations:** Verify existing quotations still render all items correctly if `is_hidden_internal` is null/false.

#### ⚠️ [Case 3] Edge Cases & Constraints
*   **Zero Visible Items:** Attempt to endorse an order where ALL items are marked hidden.
    *   **Expected:** Service should throw an exception ("Cannot distribute costs if no visible items exist").
*   **Visit Filtering:** Request pending visits with a `location_id` that doesn't belong to the `customer_id`.
    *   **Expected:** Validation failure or empty result set.
*   **Splitting Quotations:** Split a quotation using an `item_id` that belongs to a different supply order.
    *   **Expected:** SQL/Model exception (handled as 422) or validation error.