# Test Scenario Guide: Corrective Quotation Creation for Spare Parts (US-015)

### 2. Scenario Introduction 💡
The **Corrective Quotation Creation for Spare Parts** feature bridges the Maintenance and Supply Chain domains. When a maintenance technician identifies a fault requiring spare parts during a visit, they submit a report. The new feature seamlessly integrates this report into the supply process by allowing agents to generate a pre-filled correct quotation directly from the fault report. Additionally, it provides visibility into the maintenance context (such as asset details and fault descriptions) within the quotation itself and automates the calculation of total delivery durations by combining supplier lead times with internal execution estimates and safety margins.

---

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

#### 🗄️ Database Changes (Migration)
*   **Table:** `sup_supply_quotations`
    *   Added `execution_time` (unsigned integer, nullable).
    *   Added `safety_margin` (unsigned integer, nullable).
    *   Added `calculated_delivery_duration` (unsigned integer, nullable).

#### 🛡️ Validation Changes (FormRequests)
*   **Request:** `StoreSupplyQuotationRequest` & `UpdateSupplyQuotationRequest`
    *   Added `execution_time` (`nullable|integer|min:0`).
    *   Added `safety_margin` (`nullable|integer|min:0`).

#### 📦 API Response Changes (Resources)
*   **Resource:** `SupplyOrderQuotationDataResource`
    *   Added `maintenance_context` object visible when the order originates from a maintenance visit. Contains: `failure_description`, `asset_name`, `asset_code`, and `origin_department` ('maintenance').
*   **Resource:** `SupplyQuotationResource`
    *   Added calculated fields: `execution_time`, `safety_margin`, and `calculated_delivery_duration`.
    *   Added `maintenance_section` conditionally visible if the quotation is linked to a maintenance visit.
    *   Gated internal financial fields (`purchase_price`, `supplier_info`) behind a strict permission check (`$canViewPurchasePrices`) to protect internal margins.

---

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Quotation Creation Flow** | Quotations were built manually with no direct link to the maintenance fault that triggered them. | Quotations can be pre-filled via an entry point on the Maintenance Visit Report. | **Data Integrity & Efficiency**: Reduces manual data entry errors and streamlines the supply workflow. |
| **Maintenance Visibility** | Supply Chain agents had to navigate back to the maintenance module to see why parts were requested. | The Quotation API automatically injects `maintenance_context` into the response. | **Improved Context**: Supply agents see fault descriptions and asset data instantly. |
| **Delivery Duration Formula** | Only supplier `min_delivery_lead_time` was tracked, leading to inaccurate client delivery estimates. | `calculateTotalDeliveryDuration` automatically sums lead time, execution time, and a safety margin. | **SLA Reliability**: Provides realistic, automated delivery promises to the customer. |
| **Data Protection** | Internal purchase costs were sometimes inadvertently exposed if not explicitly hidden by front-end clients. | Internal costs (`purchase_price`, `supplier_info`) are strictly gated at the API Resource level based on user permissions. | **Improved Security**: Safeguards company margins and vendor details from unauthorized viewers. |

---

### 5. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Prefill Quotation** | `/api/v1/maintenance/reports/{id}/create-quotation` | `GET` | Returns pre-filled quotation payload bridging visit report data (faults, assets, spare parts) to the supply domain. |
| **Store Quotation** | `/api/v1/supply/quotations` | `POST` | Intercepts `execution_time` and `safety_margin`, automating the total calculated duration. |
| **Update Quotation** | `/api/v1/supply/quotations/{quotation}` | `PUT` | Updates Quotation criteria and re-fires duration recalculation. |
| **Quotation Spitting** | `/api/v1/supply/quotations/{quotation}/split` | `POST` | Splits items into a new quotation, gracefully replicating execution duration times. |

---

### 6. Test Cases 🧪

*   **[Case 1] The Happy Path:** 
    *   Access `/api/v1/maintenance/reports/{id}/create-quotation` for a valid report. Verify the payload returns `maintenance_asset_id`, `failure_description`, and any `items` accurately mapped from the recorded spare parts.
    *   Create a quotation providing `execution_time` (e.g., 2) and `safety_margin` (e.g., 3). Verify the stored `calculated_delivery_duration` reflects the sum of these values plus the maximum supplier lead time.
*   **[Case 2] Backward Compatibility:** 
    *   Update a legacy quotation without `execution_time` or `safety_margin` in the request. Ensure the update succeeds without forcing these nullable values and that the duration defaults accurately to the supplier lead time.
    *   Fetch a standard supply quotation (not linked to maintenance). Ensure `maintenance_section` and `maintenance_context` do not appear in the Resource response.
*   **[Case 3] Edge Cases & Constraints:** 
    *   **Validation Failures:** Send negative integers for `execution_time` or `safety_margin`. The server should respond with `422 Unprocessable Entity`.
    *   **Permission & Security:** Fetch a quotation using a standard Client/Tenant token. Verify that `purchase_price` and `supplier_info` are entirely missing from the item payloads.
    *   **Quotation Splitting:** Call the `/split` endpoint for a quotation. Ensure the newly minted quotation accurately retains the copied `execution_time` and `safety_margin` from the parent.