# Test Scenario Guide: Periodic Visit Report Approval & Invoicing Flow (US-013)

### 1. Scenario Introduction 🏢
The billing workflow (**US-013**) transitions the Maintenance Visit Report approval process from a supervisor-based qualitative review to a finance-based legal/financial review. In this new flow, the "Official Approval" of a visit is represented by the **Signed Invoice** being uploaded back into the system. This ensures that the technical documentation (Report) and the financial acknowledgment (Signed Invoice) are synchronized.

### 2. Technical Schema Changes 🔍

#### API Validation & Response
*   **Endpoint:** `POST /api/maintenance/reports`
    *   **Validation:** Internally transitions reports to `SUBMITTED_AWAITING_INVOICE` upon submission.
    *   **Dependencies:** Requires `maintenance.finance.manage` permission (or `finance` role) to receive notifications.

*   **Endpoint:** `POST /api/maintenance/invoices`
    *   **Validation Changes:** 
        *   Added `visit_report_id` (`nullable|exists:mod_maintenance_visit_reports,id`).
        *   Added `is_pre_report` (`boolean`).
    *   **Constraint:** If `is_pre_report` is **true**, the system checks for `maintenance.invoices.create_before_report` permission.

*   **Endpoint:** `POST /api/maintenance/invoices/{id}/issue-and-send`
    *   **Payload:** `{ id: integer }`
    *   **Logic:** Updates `is_sent_to_technician` to `true`, sets `sent_at`, and moves linked reports to `AWAITING_SIGNED_INVOICE_UPLOAD`.
    *   **Notification:** Dispatches `InvoiceReadyForTechnicianNotification` to the assigned visit technicians.

*   **Endpoint:** `POST /api/maintenance/invoices/{id}/upload-signed`
    *   **Validation:** `signed_invoice` must be a file (`pdf, jpg, png, jpeg`) max 10MB.
    *   **Logic:** Finalizes the lifecycle. Sets `signed_invoice_path`, `signed_invoice_uploaded_at`, and `officially_approved_at`.
    *   **Status Update:** All linked reports (via pivot or direct link) transition to `OFFICIALLY_APPROVED`.

### 3. Change Log (Why the Update?) 🔄
*   **Previous Behavior:** Supervisors "approved" reports. Finance was aware of the approval but often operated outside the visit lifecycle. Signature tracking was inconsistent.
*   **New Behavior:**
    *   **Revenue Assurance:** Ensures no report is "finished" until a customer-signed invoice is documented.
    *   **Process Transparency:** Finance is the "gatekeeper" for issuance, and the Technician is the "carrier" for signatures.
    *   **Consolidated Billing:** Reduces administrative overhead by allowing one signed invoice to close multiple technical reports.

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Submit Report** | `/api/maintenance/reports` | `POST` | Technician submits report; triggers finance notification. |
| **Issue Invoice** | `/api/maintenance/invoices/{id}/issue-and-send` | `POST` | Finance notifies technician that invoice is ready to sign. |
| **Upload Signed** | `/api/maintenance/invoices/{id}/upload-signed` | `POST` | Technician uploads signature; report reaches final status. |
| **Pre-Report Invoice** | `/api/maintenance/invoices` | `POST` | Allows early invoicing if `is_pre_report` is authorized. |
| **Dashboard Stats** | `/api/maintenance/statistics` | `GET` | Added counts for `awaiting_invoice` and `awaiting_signed_upload`. |

### 5. Test Cases 🧪

#### ✅ [Case 1] The Happy Path (Standard Workflow)
1. **Technician** submits a visit report.
2. Verify status is `SUBMITTED_AWAITING_INVOICE`.
3. **Finance** reviews and hits `/issue-and-send`.
4. Verify technician receives notification and status is `AWAITING_SIGNED_INVOICE_UPLOAD`.
5. **Technician** uploads a valid PDF to `/upload-signed`.
6. Verify status is `OFFICIALLY_APPROVED` and timestamps are logged.

#### 🔄 [Case 2] Backward Compatibility
- Open a report created before this update (Status: `AWAITING_APPROVAL`).
- Verify it still appears in the **Supervisor Pending** count (`pending_legacy`).
- Run the legacy `approve` method (marked with `TODO: DEPRECATED`).
- Verify it still transitions to `AWAITING_INVOICING` correctly.

#### ⚠️ [Case 3] Edge Cases & Constraints
- **Unauthorized Pre-Invoicing:** Try to create an invoice with `is_pre_report: true` using a technician account. (Expected: `403 Forbidden`).
- **Invalid Signature File:** Try to upload a `.docx` or a file larger than 10MB to `/upload-signed`. (Expected: `422 Unprocessable Entity`).
- **Consolidated Signature:** Link one invoice to 3 reports. Upload one signature. (Expected: All 3 reports synchronously move to `OFFICIALLY_APPROVED`).