# Test Scenario Guide: Logistics Field in Technical Offer

### 1. Title
# Test Scenario Guide: Logistics Field in Technical Offer

### 2. Scenario Introduction 🏢
The **logistics_notes** field is a specialized internal field added to the **Maintenance Technical Offer** flow. In the corrective maintenance process, when a technical supervisor or technician reviews a fault request, they must identify specific operational requirements such as specialized transportation (e.g., heavy-duty trucks), equipment (e.g., cranes, lifting gear), or site access constraints (e.g., security clearances, restricted hours). 

This field is strictly for **INTERNAL USE ONLY**. It serves as a bridge between technical assessment and operational execution, ensuring that the pricing and execution teams are aware of overheads that don't necessarily appear as line items in a client-facing quotation but affect the margin and feasibility of the job.

### 3. Technical Schema Changes (Detailed) 🔍
Analysis of the technical implementation reveals changes across the model, validation layers, and API responses:

*   **Model Update:** Added `logistics_notes` to the `$fillable` array in `MaintenanceTechnicalOffer`.
*   **FormRequest Validation:**
    *   **Endpoint:** `POST /api/v1/maintenance/technical-offers`
    *   **Endpoint:** `PUT /api/v1/maintenance/technical-offers/{id}`
    *   **Validation Rule:** Added `'logistics_notes' => 'nullable|string'`. This ensures the field accepts plain text or can be omitted if not applicable.
*   **API Response Changes:**
    *   **Resource:** `MaintenanceTechnicalOfferResource`
    *   **New Field:** `logistics_notes` added to the JSON output.
    *   **Role-Based Visibility:** Implemented a visibility guard. The field is **only** included if the user has specific technical roles:
        *   `R-02` (Technical Supervisor)
        *   `R-08` (Technical Manager)
        *   `super_admin`

### 4. Why the Update? (Change Log) 🔄
| Previous Behavior | New Behavior |
| :--- | :--- |
| Internal logistics needs were often mixed with the general `description` or communicated outside the system. | Dedicated, searchable field for **internal logistics requirements**. |
| No granular control over who can see internal operational notes. | **Role-Based Access Control (RBAC)** ensures field-level privacy. |
| Potential for internal planning details to leak into client PDFs. | Guaranteed **exclusion** from all client-facing Price Offer PDFs and payloads. |

**Benefits:**
*   **Data Integrity:** Keeps the offer's public description professional while preserving technical operational details.
*   **Improved Security:** Prevents Sales Officers or Clients from seeing internal cost/logistics discussions.
*   **Operational Readiness:** Execution teams have immediate access to technical requirements upon offer approval.

### 5. API Endpoints Table 📊
| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Create Technical Offer | `/api/v1/maintenance/technical-offers` | `POST` | Store new offer with `logistics_notes`. |
| Update Technical Offer | `/api/v1/maintenance/technical-offers/{id}` | `PUT` | Modify existing `logistics_notes`. |
| View Offer Details | `/api/v1/maintenance/technical-offers/{id}` | `GET` | View technical details (Logistics visible to R-02/R-08 only). |
| List Technical Offers | `/api/v1/maintenance/technical-offers` | `GET` | Retrieve collection of offers with internal notes for authorized users. |

### 6. Test Cases 🧪

*   **[Case 1] The Happy Path (Authorized User):**
    1.  **Action:** Authenticate as a **Technical Supervisor (R-02)**.
    2.  **Action:** Send a `POST` request to create a Technical Offer with `"logistics_notes": "Needs a 10-ton crane for chiller lifting and nighttime site access clearance."`.
    3.  **Expectation:** `201 Created`. The response includes the `logistics_notes` field with the correct text.
    4.  **Action:** Perform a `GET` request for the same offer.
    5.  **Expectation:** The field is visible in the resource output.

*   **[Case 2] Data Privacy (Unauthorized User):**
    1.  **Action:** Authenticate as a **Sales Officer (R-04)** or **Client (R-09)**.
    2.  **Action:** Perform a `GET` request for the Technical Offer created in Case 1.
    3.  **Expectation:** The `logistics_notes` field is **absent** from the JSON response.
    4.  **Action:** Generate a Price Offer PDF based on this Technical Offer.
    5.  **Expectation:** The PDF does **not** contain the string "10-ton crane" or any logistics notes.

*   **[Case 3] Backward Compatibility & Validation:**
    1.  **Action:** Fetch an old Technical Offer (created before this feature).
    2.  **Expectation:** API returns successfully; `logistics_notes` is either `null` or missing, depending on the role.
    3.  **Action:** Send an `UPDATE` request with `"logistics_notes": ["invalid", "array"]`.
    4.  **Expectation:** `422 Unprocessable Entity` error for the `logistics_notes` field.
    5.  **Action:** Send an `UPDATE` request with `"logistics_notes": null`.
    6.  **Expectation:** `200 OK`. The field is cleared correctly.