# Test Scenario Guide: Technician Endorsement Stage

### 2. Scenario Introduction 💡
The **Technician Endorsement Stage** is a critical verification step in the **Corrective Maintenance** workflow. Previously, once procurement representatives completed pricing for spare parts, the system allowed immediate quotation creation. This new feature mandates that the **originally assigned technician** must review the final priced items and provide a "Final Endorsement." 

This ensures that:
1. The technician confirms that the priced items exactly match the technical requirements.
2. Any pricing or item discrepancies are caught before the client receives a formal quotation.
3. The workflow maintains a strict audit trail of technical accountability.

---

### 3. Technical Schema Changes 🔍

#### Enums
*   **SupplyOrderStatus:** 
    *   Added `PENDING_TECH_ENDORSEMENT = 'pending_tech_endorsement'`.
    *   Added `READY_FOR_QUOTATION = 'ready_for_quotation'`.

#### API Responses & Gates
*   **Endpoint:** `GET /api/maintenance/reports/{id}/create-quotation`
    *   **Logic Change:** Added a mandatory status check. If a linked **SupplyOrder** exists, it must be in the `READY_FOR_QUOTATION` status.
    *   **Error Response:** Returns `422 Unprocessable Entity` if the order is still in pricing or pending technician endorsement.

#### New Endpoints
*   **Endpoint:** `POST /api/maintenance/supply-orders/{id}/technician-endorse`
    *   **Actor:** Restricted to the technician assigned to the maintenance visit.
    *   **Action:** Updates status to `READY_FOR_QUOTATION`.
*   **Endpoint:** `POST /api/maintenance/supply-orders/{id}/technician-reject`
    *   **Validation:** Requires a mandatory `note` field (string, max 500).
    *   **Action:** Reverts status to `TECHNICIAN_REVIEW`.

---

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

| Aspect | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Workflow Sequence** | `PRICING` -> `QUOTATION` | `PRICING` -> `TECH_ENDORSEMENT` -> `QUOTATION` | Enhanced technical verification. |
| **Quotation Gate** | Open after pricing completion. | Locked until technician endorsement. | Prevents premature or incorrect quotations. |
| **Feedback Loop** | Manual communication for errors. | Systemic rejection back to `TECHNICIAN_REVIEW`. | Improved data integrity and accountability. |
| **Notifications** | None for this stage. | Automated notifications for Techs & Sales. | Faster turnaround and process awareness. |

---

### 5. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Endorse Order** | `/api/maintenance/supply-orders/{id}/technician-endorse` | `POST` | Assigned technician approves the priced items. |
| **Reject Order** | `/api/maintenance/supply-orders/{id}/technician-reject` | `POST` | Technician rejects pricing with a mandatory note. |
| **Quotation Prefill** | `/api/maintenance/reports/{id}/create-quotation` | `GET` | Returns pre-fill data only if endorsement is complete. |

---

### 6. Test Cases 🧪

#### **[Case 1] The Happy Path (Successful Endorsement)**
1.  **Procurement Rep** completes pricing for all items in a Supply Order.
2.  System automatically transitions status to `PENDING_TECH_ENDORSEMENT`.
3.  **Technician** receives `TechnicianEndorsementRequiredNotification`.
4.  **Technician** calls `POST /.../technician-endorse`.
5.  Status updates to `READY_FOR_QUOTATION`.
6.  **Sales Officer** calls `GET /.../create-quotation` and successfully receives pre-fill data.

#### **[Case 2] Backward Compatibility**
*   Orders already in `PRICING_IN_PROGRESS` should correctly transition to `PENDING_TECH_ENDORSEMENT` once the final item is approved, regardless of when the order was created.
*   Orders not linked to a maintenance report (standard supply orders) bypass this stage and move directly to `READY_FOR_PRICING` (standard behavior preserved).

#### **[Case 3] Edge Cases & Constraints**
*   **Unauthorized Endorsement:** Attempt to endorse using a user ID that is NOT assigned to the visit. **Expected:** `403 Forbidden`.
*   **Missing Rejection Note:** Call `technician-reject` without the `note` field. **Expected:** `422 Unprocessable Entity`.
*   **Premature Quotation:** Sales Officer attempts to call `create-quotation` while status is `PENDING_TECH_ENDORSEMENT`. **Expected:** `422` with a message: "Cannot create quotation... must be endorsed by a technician first."
*   **Double Endorsement:** Attempt to endorse an order that is already in `READY_FOR_QUOTATION`. **Expected:** `422` with "Supply order is not in pending technician endorsement stage."