# Test Scenario Guide: Mandatory Fields Enforcement (Photos, Serial, Chiller Accessories)

## 2. Scenario Introduction 🏢
During the **Handover Visit** (Asset Receipt), it is critical for the system to capture accurate and complete data about the assets found on-site. This data forms the foundation for all future maintenance activities and asset tracking.

This update enforces strict validation during the **handover completion flow** to ensure that technicians do not leave critical fields empty. By mandating **serial numbers**, **models**, and **photos**, we eliminate "unknown" assets in the inventory. Additionally, for specialized equipment like **Chillers**, we mandate the collection of **accessory details** (e.g., condenser and evaporator data) to comply with technical maintenance standards.

## 3. Technical Schema Changes (Detailed) 🔍
The validation logic has been moved to a dedicated **FormRequest** and a pre-save validation method in the **Service** layer to ensure data integrity.

*   **Endpoint:** `POST /api/maintenance/handover-visits/{visit}/complete`
*   **Validation Changes (CompleteHandoverVisitRequest):**
    *   `actual_assets.*.serial_number`: Changed from `nullable` to `required|string|max:255`.
    *   `actual_assets.*.model`: Changed from `nullable` to `required|string|max:255`.
    *   `actual_assets.*.images`: Changed from `nullable` to `required|array|min:1`.
    *   `actual_assets.*.images.*`: Must be a valid file (`jpg, jpeg, png, webp`) with a maximum size of **10MB**.
    *   `actual_assets.*.accessories`: Added `required_if:actual_assets.*.asset_type_code,chiller`.
*   **Internal logic:** Added `prepareForValidation` to resolve `asset_type_code` from the database if only `asset_type_id` is provided by the frontend.
*   **Response Changes:**
    *   In case of failure, the response identifies exactly which asset in the list failed using nested keys (e.g., `actual_assets.2.images`).

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

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Asset Metadata** | `serial_number` and `model` were optional. | Both fields are now **strictly mandatory**. | Eliminates duplicate or unidentified assets. |
| **Visual Evidence** | Assets could be recorded without photos. | At least **one photo** per asset is required. | Provides visual proof of asset condition at handover. |
| **Chiller Compliance** | Accessories were optional for all asset types. | **Accessories are mandatory** for Chiller units. | Ensures technical specifications for complex units are captured. |
| **Enforcement Point** | Basic validation in the controller. | Multi-layer validation (Request + Service). | Prevents data corruption even if bypass attempts occur. |

## 5. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Complete Handover | `/api/maintenance/handover-visits/{visit}/complete` | `POST` | Validates and finalizes asset receipt, generating reports. |

## 6. Test Cases 🧪

### [Case 1] The Happy Path (Complete Submission) ✅
*   **Input:** Submit a handover with 3 assets. All have `serial_number`, `model`, and 1+ images. One asset is a "Chiller" and has an `accessories` array populated.
*   **Expected Result:** `200 OK`. Reports are generated, assets are created/updated in the system.

### [Case 2] Backward Compatibility 🔄
*   **Input:** Frontend sends only `asset_type_id` (integer) for a Chiller, but no `asset_type_code`.
*   **Internal Logic:** The system resolves the code internally.
*   **Expected Result:** Validation correctly identifies the Chiller and mandates accessories.

### [Case 3] Edge Cases & Constraints ⚠️
*   **Missing Images:** Submit an asset without the `images` field. 
    *   *Result:* `422 Unprocessable Entity` with error `validation.assets_images_required`.
*   **Missing Chiller Accessories:** Submit a Chiller asset type but with an empty `accessories` array.
    *   *Result:* `422 Unprocessable Entity` with error `validation.chiller_accessories_required`.
*   **Invalid File Types:** Upload a PDF or a 15MB image in the `images` array.
    *   *Result:* `422 Unprocessable Entity` highlighting the specific image index.
*   **Draft Preservation:** Attempting to save as a draft (if implemented in other flows).
    *   *Note:* These validations apply **only** to the completion flow. Drafts remain unrestricted.