# Test Scenario Guide: Hidden Items Cost Distribution

### 1. Scenario Introduction 🏢
In the **Maintenance Management** module, particularly for **Corrective Maintenance Quotations**, certain operational costs (such as oils, rags, and small consumables) are tracked internally but should not be explicitly itemized for the client. 

This feature introduces a **financial distribution logic** that calculates the total cost of these "hidden" items (`show_in_offer = false`) and distributes them **proportionally** across all "visible" items (`show_in_offer = true`). This ensures that internal costs are fully recovered through the visible quotation lines while maintaining a clean, professional interface for the end customer.

---

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

The implementation involved modifications to the database schema, internal logic services, and API response structures.

*   **Database Migration:**
    *   **Table:** `mod_maintenance_price_offer_costs`
    *   **New Field:** `hidden_cost_addition` (Decimal 10,2, Nullable). Stores the calculated portion of hidden costs assigned to this specific visible item.

*   **API Response Changes (Resources):**
    *   **Endpoint:** `GET /api/v1/maintenance/price-offers/{id}`
    *   **Resource:** `MaintenancePriceOfferResource`
        *   Added `hidden_cost_distributed` (Boolean) to the `calculations` object. Indicates if hidden costs have been successfully applied to visible items.
    *   **Resource:** `MaintenancePriceOfferCostResource`
        *   Added `hidden_cost_addition` (Float): The exact amount added from hidden items.
        *   Added `total_adjusted_cost` (Float): The sum of the original `cost_value` and the `hidden_cost_addition`.

*   **Validation & Logic (Service):**
    *   The logic is triggered automatically during **Total Calculation** and **PDF Generation**.
    *   **Formula:** `item_hidden_addition = (item_cost / total_visible_cost) * total_hidden_cost`.
    *   Includes a **remainder adjustment** for the last visible item to ensure total distributed costs match total hidden costs exactly (to the penny).

---

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

| Metric | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Cost Recovery** | Hidden items were excluded from the client subtotal, leading to revenue loss. | Hidden costs are proportionally added to visible items. | **100% Cost Recovery** |
| **Client Presentation** | Clients saw a discrepancy between internal totals and quotation totals. | Clients see professional, all-inclusive prices for main services. | **Professionalism & Clarity** |
| **Audit Trail** | No clear record of how hidden costs were accounted for. | Specific `hidden_cost_addition` field tracks the distribution per item. | **Financial Integrity** |

---

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Fetch Price Offer** | `/api/v1/maintenance/price-offers/{id}` | `GET` | Returns offer details including distribution status and adjusted costs. |
| **Calculate Totals** | `/api/v1/maintenance/price-offers/{id}/calculate-totals` | `POST` | Triggers the distribution logic and updates database records. |
| **Generate PDF** | `/api/v1/maintenance/price-offers/{id}/pdf` | `GET` | Generates a client-facing PDF with all-inclusive adjusted prices. |

---

### 5. Test Cases 🧪

#### **[Case 1] The Happy Path: Standard Distribution**
*   **Setup:** Create an offer with 2 visible items (1,000 SAR each) and 1 hidden item (500 SAR).
*   **Execution:** Call `calculateTotals` or fetch the offer.
*   **Expected Result:**
    *   `hidden_cost_distributed` is `true`.
    *   Each visible item has a `hidden_cost_addition` of `250.00`.
    *   `total_adjusted_cost` for each is `1,250.00`.
    *   PDF shows two items at `1,250.00` each.

#### **[Case 2] Backward Compatibility & No Hidden Items**
*   **Setup:** Open an existing offer that has NO hidden items.
*   **Execution:** Call `calculateTotals`.
*   **Expected Result:**
    *   `hidden_cost_distributed` is `false`.
    *   `hidden_cost_addition` is `0` or `null` for all items.
    *   Prices remain unchanged.

#### **[Case 3] Edge Cases & Constraints**
*   **Empty Visible Items:** If an offer has hidden items but **no visible items**, the logic should skip distribution (to avoid division by zero) and `hidden_cost_distributed` remains `false`.
*   **Rounding Remainder:** Create an offer where 500 SAR must be distributed across 3 items (500/3 = 166.666...).
    *   **Expected Result:** Item 1 and 2 get `166.67`, Item 3 gets `166.66` (total = `500.00`).
*   **Zero Cost Items:** If a visible item has `cost_value = 0`, it receives `0` share of the hidden costs.

---