# Test Scenario Guide: Maintenance Visit Completion & Locking (US-013)

### 1. Scenario Introduction 📝
This feature implements a formal handover process for maintenance visits. It ensures that before a visit is finalized for invoicing, the technician obtains a **Completion Certificate** signed by the client. 

Crucially, once this certificate is submitted with its associated signed document, the system **locks** the visit data. This prevents any further changes to daily logs or installed parts, guaranteeing that the data used for invoicing matches what the client acknowledged on-site.

---

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

Analyze the changes in **FormRequest validation rules** and **API Responses**:

#### **Submit Completion Certificate**
*   **Endpoint:** `POST /api/maintenance/visits/{visit}/completion-certificate`
*   **Validation Changes (`StoreCompletionCertificateRequest`):** 
    *   `signed_by_name`: **Required** string (Max 255).
    *   `client_notes`: Optional text for client feedback.
    *   `replaced_parts_acknowledged`: **Required** boolean to confirm client saw the old parts.
    *   `signature_lat` / `signature_lng`: Optional GPS coordinates of the signing event.
    *   `document`: **Required** file (PDF/Images, Max 10MB).
*   **Response Changes:** 
    *   Returns a `CompletionCertificateResource` containing `signed_at`, `document_url`, and the generated `id`.

#### **View Certificate Data**
*   **Endpoint:** `GET /api/maintenance/visits/{visit}/completion-certificate`
*   **Response Changes:** 
    *   Returns the existing certificate (if any).
    *   **New Section:** `installed_parts` summary. This aggregates all parts from all `VisitDailyLogs` into a flat list for the client to review before signing.

---

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

| Aspect | Previous Behavior | New Behavior |
| :--- | :--- | :--- |
| **Workflow** | Visits could be closed immediately after work completion. | Visits must pass through a "Completion Certificate" step before closing. |
| **Data Integrity** | Daily logs and parts could be edited after the technician left the site. | **Strict Locking:** Observers block any changes to logs/parts once the certificate is uploaded. |
| **Transparency** | No formal proof of client satisfaction or part replacement. | Signed document and acknowledgment flags are stored and linked to the visit. |
| **Automation** | Manual notification to finance. | **Automated Notifications** sent to users with `finance` or `accountant` roles. |

---

### 4. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| Get Handover Data | `/api/maintenance/visits/{visit}/completion-certificate` | `GET` | Fetches certificate info and the aggregated list of installed parts. |
| Submit Certificate | `/api/maintenance/visits/{visit}/completion-certificate` | `POST` | Stores the certificate, uploads the document, and triggers the visit lock. |

---

### 5. Test Cases 🧪

#### **[Case 1] The Happy Path (Standard Workflow)**
1.  **State:** Maintenance Visit is in `COMPLETED` status.
2.  **Action:** Call `GET .../completion-certificate` to verify the list of installed parts is correct.
3.  **Action:** Call `POST .../completion-certificate` with a valid name, acknowledgment `true`, and a PDF file.
4.  **Result:** 
    *   HTTP 201 Created.
    *   Visit status transitions to `AWAITING_INVOICING`.
    *   Notification appears in the database for finance users.

#### **[Case 2] Data Locking Enforcement**
1.  **State:** Visit has a submitted Completion Certificate.
2.  **Action:** Attempt to update a quantity on an existing `VisitInstalledPart` or delete a `VisitDailyLog`.
3.  **Result:** 
    *   System throws an `Exception`: *"Visit is locked, no modifications allowed"*.
    *   The database remains unchanged.

#### **[Case 3] Edge Cases & Constraints**
*   **Missing Document:** Attempt to POST without a `document` file. **Result:** 422 Validation Error.
*   **Invalid Status:** Attempt to POST a certificate for a visit in `SCHEDULED` status. **Result:** 422 Error (*Visit must be completed...*).
*   **Unauthorized Tech:** Attempt to submit a certificate for a visit assigned to a different technician. **Result:** Exception thrown (*Technician not assigned...*).
*   **Closing Guard:** Attempt to call the `close()` service method on a visit that has no certificate. **Result:** Exception thrown (*Visit must have completion certificate to close*).