# Test Scenario Guide: Damaged Parts Inventory Lifecycle

### 1. Scenario Introduction 🏢
In the Maintenance Management module, when a technician performs a corrective visit and replaces a faulty part, the old (damaged) part must be returned to the warehouse. 

This feature implements the **Damaged Parts Inventory Lifecycle**, ensuring that when a technician confirms the return of a damaged part, a corresponding record is created in the warehouse inventory with a "damaged" condition tag. This allows inventory managers to track, dispose of, or repair these items separately from usable stock, maintaining total transparency in the supply chain.

---

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

#### Database Migrations
*   **Table:** `catalog_inventories`
    *   Added `condition` column: `ENUM('new', 'used', 'damaged', 'scrap')` default `'new'`.
    *   Updated unique constraint: Now includes `condition` to allow separate stock records for the same product and warehouse.
*   **Table:** `catalog_inventory_transactions`
    *   Added `condition` column: `ENUM('new', 'used', 'damaged', 'scrap')` default `'new'`.
    *   Updated `transaction_type` enum: Added `damaged_return`.

#### Model Updates
*   **`Inventory` & `InventoryTransaction`**: Added `condition` to `$fillable` and `$casts`.
*   **`TransactionType` Enum**: Added `DAMAGED_RETURN = 'damaged_return'`.

#### Service Layer
*   **`InventoryService`**: Added `receiveDamagedReturn(array $data)` to handle the creation/update of damaged stock and record the transaction.
*   **`VisitExtraPartsRequestService`**: Updated `returnDamagedPart()` to trigger the inventory receipt process when the technician marks a part as returned.

#### API Endpoint Changes
*   **Endpoint:** `POST /api/maintenance/extra-parts/{id}/return-damaged`
*   **Logic Change:** Previously only toggled a boolean; now triggers a full inventory movement.
*   **Response:** Returns the updated Extra Parts Request object.

---

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Damaged Stock Tracking** | `damaged_part_returned` was set to `true` but no warehouse entry was created. | System creates a warehouse entry with condition `damaged`. | **Data Integrity**: Accurate tracking of physical assets returned to warehouse. |
| **Inventory Separation** | Damaged parts were not visible in inventory reports. | Damaged parts are tracked as separate inventory lines. | **Operational Clarity**: Inventory managers can distinguish between sellable and non-sellable stock. |
| **Audit Trail** | No stock movement record for returns from visits. | A `damaged_return` transaction is created, linked to the Maintenance Visit. | **Auditability**: Complete history of why and when a part entered damaged stock. |

---

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Confirm Damaged Return | `/api/maintenance/extra-parts/{id}/return-damaged` | `POST` | Marks part as returned and creates inventory record. |
| Get Damaged Stats | `/api/maintenance/statistics` | `GET` | (Updated) Includes damaged parts return statistics. |

---

### 5. Test Cases 🧪

#### 🟢 [Case 1] The Happy Path: Successful Damaged Return
1.  **Requirement**: A corrective visit with an approved "Extra Parts Request".
2.  **Action**: Technician calls `POST /api/maintenance/extra-parts/{request_id}/return-damaged`.
3.  **Expected Result**:
    *   `mod_maintenance_visit_extra_parts_requests.damaged_part_returned` becomes `1`.
    *   A new record (or updated) exists in `catalog_inventories` for the product with `condition = 'damaged'`.
    *   A record exists in `catalog_inventory_transactions` with `transaction_type = 'damaged_return'` and `reference_id` pointing to the visit.

#### 🟡 [Case 2] Backward Compatibility
1.  **Requirement**: Existing inventory records created before the migration.
2.  **Action**: Run migration and check existing records.
3.  **Expected Result**:
    *   Existing records are assigned `condition = 'new'` by default.
    *   Unique constraints are successfully migrated without data loss.

#### 🔴 [Case 3] Edge Cases & Constraints
*   **Missing Warehouse**: If the company has no active warehouse, the system should use a fallback or throw a descriptive error (handled by `Warehouse::active()->first()`).
*   **Unauthorized Return**: Attempting to confirm return by a user without `maintenance.visits.edit` permission.
    *   **Expected**: `403 Forbidden`.
*   **Duplicate Return**: Calling the endpoint twice for the same request.
    *   **Expected**: Inventory increases twice? (Note: The business logic should ideally check if already returned, currently it just increments).
*   **Zero Quantity**: If request quantity is 0.
    *   **Expected**: No inventory movement or validation error.