# Test Scenario Guide: Automated Supply Order Custody Management

### 1. Title
# Test Scenario Guide: Automated Supply Order Custody Management

### 2. Scenario Introduction
This feature automates the creation and management of **In-Kind Custody (عهدة عينية)** for agents upon the receipt of goods. When a **Goods Receipt** is created from a **Purchase Order**, the system automatically identifies the responsible agent (from the Supply Order) and generates tangible item records within their custody account. This ensures that every physical item received is tracked until it is delivered to the final customer or returned, providing full accountability for inventory in transit.

### 3. Technical Schema Changes (Detailed) 🔍
While no direct database migrations are present in this diff, the logic flow for data integrity has been significantly altered:

*   **Endpoint:** `POST /api/v1/supply/goods-receipts` (Logic change within `GoodsReceiptService::createFromPurchaseOrder`)
*   **Logic Updates:**
    *   **Agent Identification:** The system now traverses `GoodsReceipt -> PurchaseOrder -> SupplyOrder -> Agent` to find the correct custodian, moving away from a direct link on the Purchase Order.
    *   **Status Automation:** Upon custody creation, the `SupplyOrderItem` status is automatically updated to `ready_for_delivery`.
    *   **Company Context:** `company_id` for tangible items is now derived directly from the `SupplyOrderItem` to ensure multi-tenancy consistency.
*   **Validation Changes:**
    *   No changes to `FormRequest` validation were introduced in this specific diff, but the **Service Layer** now handles agent-less scenarios gracefully by logging a warning instead of failing.

### 4. Why the Update? (Change Log) 🔄
| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Custody Trigger** | Triggered via `GoodsReceiptItemObserver` (Implicit/Async). | Triggered explicitly within `GoodsReceiptService` transaction. | **Atomicity:** Ensures custody is created only if the receipt transaction succeeds. |
| **Agent Source** | Used `PurchaseOrder->agent`. | Uses `SupplyOrder->agent`. | **Accuracy:** Aligns with the business rule that custody belongs to the supply order representative. |
| **Settlement Logic** | Custody account closed as soon as a single item was processed. | Custody account remains open until **all** items are delivered/resolved. | **Data Integrity:** Prevents premature closing of accounts with pending items. |
| **Item Status** | Manual status updates. | Automatic transition to `ready_for_delivery`. | **Efficiency:** Reduces manual work for warehouse staff. |

### 5. API Endpoints Table 📊
| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Create Goods Receipt | `/api/v1/supply/goods-receipts` | `POST` | Processes PO receipt and generates agent custody records. |
| Settle Custody | (Internal Service) | `N/A` | `closeCustodyAccount` logic ensures full resolution of all items. |

### 6. Test Cases 🧪

*   **[Case 1] The Happy Path (Full Lifecycle):**
    1. Create a **Goods Receipt** for a Purchase Order linked to a Supply Order with an assigned **Agent**.
    2. Verify `Advance` (Custody) record is created for the agent.
    3. Verify `TangibleItem` is created for each received item.
    4. Verify `SupplyOrderItem` status changes to `ready_for_delivery`.
    5. Process a **Delivery Note** for one item; verify custody remains "open".
    6. Process delivery for all items; verify custody status changes to `fully_settled`.

*   **[Case 2] Agent-less Supply Order:**
    1. Create a **Goods Receipt** for a PO whose Supply Order has **no agent**.
    2. Verify the receipt is created successfully.
    3. Verify a `Log::warning` is generated in the system logs.
    4. Verify no custody records are created.

*   **[Case 3] Edge Cases & Constraints:**
    *   **Partial Receipts:** Receiving only 50% of PO items. Verify custody only reflects the received quantity.
    *   **Duplicate Receipts:** Ensure idempotency logic in `createTangibleItemsForCustody` prevents duplicate tangible items for the same receipt item.
    *   **Item Resolution Variety:** Mark one item as `delivered` and another as `damaged`. Verify custody settles correctly once all are resolved.

---
**Style Note:** This guide focuses on the transition from Observer-based triggers to Service-layer orchestration to ensure financial and inventory atomicity.