# Test Scenario Guide: Advance Module Accountant Review Enhancements 🚀

## 1. Scenario Introduction 📖
The **Advance** (Petty Cash/Custody) module has been enhanced to provide accountants with robust auditing tools. The primary goal is to shift financial impact from **Transaction Submission** (Employee) to **Transaction Approval** (Accountant). This update introduces automated VAT back-calculations, a dual-phase review lifecycle (Pending -> Approved/Rejected), and detailed financial previews, ensuring that only verified and tax-compliant records hit the general ledger.

---

## 2. Technical Schema Changes 🔍

### Endpoint: `POST /api/v1/advances/{id}/transactions` (Record Transaction)
*   **Validation Changes:**
    *   Added `includes_vat` (boolean): Optional toggle for automatic tax breakdown.
    *   Added `invoice_type` (required): Must be `taxable` or `non_taxable`.
    *   Field `amount_before_tax` and `tax_amount` are now `optional` when `includes_vat` is provided, otherwise they follow the "When VAT is not included" logic (0 tax).
*   **Response Changes:**
    *   Returns the transaction with calculated `amount_before_tax` and `tax_amount` based on 15% VAT if active.
    *   **Financial Impact:** **Removed** automatic journal entry creation upon submission.

### Endpoint: `POST /api/v1/advances/{id}/transactions/{transaction}/approve`
*   **Validation Changes:**
    *   Ensures the transaction exists and is currently in `pending_review` status.
*   **Response Changes:**
    *   Returns updated transaction with `status: approved`.
    *   **Triggers Atomic Journal Entry**: Splits into **Expense** and **Input Tax** accounts.

### Endpoint: `POST /api/v1/advances/{id}/transactions/{transaction}/reject`
*   **Validation Changes:**
    *   `rejection_reason`: **Mandatory** (string, min:10 characters).
*   **Response Changes:**
    *   Returns updated transaction with `status: rejected` and the stored `rejection_reason`.

### Endpoint: `GET /api/v1/advances` (Index)
*   **Filter Changes:**
    *   Added `expense_category_id`: Filters advances containing transactions directed to a specific expense account.
*   **Response Changes (Summary Panel):**
    *   Added `total_tax`: Sum of VAT from approved transactions.
    *   Added `usage_percentage`: Real-time custody consumption rate.

---

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

| Improvement | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Financial Control** | Journal entries hit the ledger upon invoice submission. | Journal entries hit the ledger ONLY upon Accountant Approval. | Prevents unverified expenses from skewing financial reports. |
| **VAT Compliance** | Manual entry only. | "Includes 15% VAT" toggle with automated back-calculation. | Reduces human error and ensures standard 15% rate compliance. |
| **Audit Trace** | No transaction-level status. | Full status lifecycle (Pending/Approved/Rejected) with reviewer name and timestamp. | Provides accountability and rejection feedback to employees. |
| **Transparency** | No way to verify entry before posting. | Read-write logic separation with GET /journal-preview. | Allows zero-risk verification of ledger impact. |

---

## 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Submit Expense** | `/advances/{id}/transactions` | `POST` | Record invoice (Status: Pending) |
| **Single Approval** | `/advances/{id}/transactions/{transaction}/approve` | `POST` | Approve invoice & record journal entry |
| **Single Rejection** | `/advances/{id}/transactions/{transaction}/reject` | `POST` | Reject invoice with mandatory feedback |
| **Bulk Approval** | `/advances/{id}/transactions/bulk-approve` | `POST` | Batch approve selected invoices |
| **Journal Preview** | `/advances/{id}/transactions/{transaction}/journal-preview` | `GET` | View simulated (or recorded) GL lines |
| **Filtered Audit** | `/advances?expense_category_id=X` | `GET` | Filter advances by line item |

---

## 5. Test Cases 🧪

### [Case 1] The Happy Path: VAT Back-calculation & Approval
1.  **Submit** a transaction with `total = 1150`, `invoice_type = taxable`, and `includes_vat = true`.
2.  **Verify** DB stores `amount_before_tax = 1000` and `tax_amount = 150`.
3.  **Preview** the journal entry; verify Debit Expense (1000), Debit Input VAT (150), Credit Custody (1150).
4.  **Approve** the transaction; verify ledger lines are created only now.

### [Case 2] Rejection & Mandatory Feedback
1.  **Submit** an invalid transaction.
2.  **Attempt Reject** with an empty `rejection_reason`; verify **422 Validation Error**.
3.  **Reject** with "Invalid date"; verify **422 Validation Error** (min 10 chars).
4.  **Reject** with "Invoice date does not match transaction date"; verify **Success (200)**.

### [Case 3] Bulk Processing Atomicity
1.  Select 3 transactions.
2.  Trigger **Bulk Approval**.
3.  Verify all 3 move to `approved` and their corresponding journal entries appear.
4.  *Edge Case:* If one transaction fails (e.g., config error), verify **none** are approved (rollback).

### [Case 4] Efficient Reporting
1.  Verify `usage_percentage` matches `total_expenses / total_disbursed`.
2.  Verify `total_tax` only includes taxes from **Approved** items.
3.  Filter by `expense_category_id` and ensure results are accurate.