# US-006: Execute Handover Visit and Create Handover Report

---

## User Story

**As** a maintenance supervisor  
**I want** to execute an asset handover visit and create a handover report  
**So that** I can verify that the actual assets match the contract before maintenance begins

---

## Operational Scenario

### Main Flow

1. After the contract is activated, the system automatically creates the project
2. The supervisor opens the project details page
3. Clicks the "Create Handover Visit" button
4. Assigns a specialized technician to the visit
5. Schedules the visit date
6. The technician goes to the site and conducts the field survey
7. The technician enters each unit's data into the system
8. The technician submits the handover report
9. The supervisor reviews the report
10. The system verifies the count matches the contract
11. If matched → approve the report
12. If not matched → notification + halt execution

### Alternative Flows

- **Actual count is more:** Immediate notification + request to amend the contract
- **Actual count is less:** Immediate notification + request to amend the contract
- **Exact match:** Approve the report + allow periodic maintenance to begin

---

## Fields & Data

### Screen: Create Handover Visit

> Uses the same existing visit creation page, with fields customized by visit type. Assets and spare parts sections are not displayed.

#### Section 1 — Visit Data

| Field | Type | Notes |
|-------|------|-------|
| Visit Number | Auto | |
| Visit Type | Read Only | Handover Visit |
| Project Number | Read Only | |
| Client Name | Read Only | |
| Location | Read Only | |
| Visit Date | Date Picker | |
| Assigned Technician(s) | Dropdown | Multiple technicians can be assigned |
| Visit Status | Read Only | Scheduled |

**Buttons:** Save & Schedule / Cancel

---

### Screen: Execute Handover Visit (Technician)

#### Section 1 — Auto Data

| Field | Type |
|-------|------|
| Visit Number | Read Only |
| Client Name | Read Only |
| Location | Read Only |
| Visit Type | Read Only |
| Visit Date | Read Only |

#### Section 2 — Expected Assets from Contract (Read Only for comparison)

Table of contracted assets:

| Column | Type |
|--------|------|
| Unit Type | Read Only |
| Contracted Count | Read Only |

#### Section 3 — Actual Asset Survey

**Button:** `+ Add Asset`

For each asset:

| Field | Type | Notes |
|-------|------|-------|
| Asset Type | Dropdown | From the contracted assets list |
| Equipment Name | Text | |
| Location within Building | Text | |
| Code | Text | |
| Model | Text | |
| Serial Number | Text | |
| Brand | Text | |
| Specifications | Textarea | |
| Electrical Voltage | Text | |
| Frequency | Text | |
| Capacity / Operating Pressure | Text | |
| Manufacturer Address | Text | |
| Local Distributor | Text | |
| Production Date | Date | |
| Supply & Installation Date | Date | |
| Asset Condition upon Receipt | Dropdown | Intact / Damaged / Needs Repair (values from settings) |
| Asset Photos | Upload (multiple) | |
| Notes | Textarea | |

**Accessories (Optional):**

*Condenser Unit:*

| Field | Type |
|-------|------|
| Manufacturer | Text |
| Model | Text |
| Serial Number | Text |
| Additional Data | Textarea |

*Evaporator Unit:*

| Field | Type |
|-------|------|
| Manufacturer | Text |
| Model | Text |
| Serial Number | Text |
| Additional Data | Textarea |

#### Section 4 — Comparison Summary (auto-updates during input)

Table comparing:

| Column |
|--------|
| Contracted Count |
| Actual Count Entered |
| Difference |
| Status (✅ Match / ⚠️ Surplus / ⚠️ Shortage) |

#### Section 5 — Signatures

| Field | Type |
|-------|------|
| Technician Signature | Electronic signature |
| Client Representative Signature | Electronic signature + Name (Text) |
| Signature Date | Date (Auto) |

**Buttons:** Save as Draft / Submit Report for Approval

---

### Screen: Approve Handover Report (Supervisor)

#### Section 1 — Report Data

All data entered by the technician displayed as Read Only.

#### Section 2 — Auto-Verification Result

- Display the comparison table
- If there is a discrepancy → clear warning in red
- If exact match → message in green

**Buttons (change based on verification result):**

*If exact match:*
- Approve Report → activates periodic maintenance

*If discrepancy exists:*
- Submit Report to Contracts for Amendment
- Return Report to Technician for Review
- ⚠️ The system prevents any periodic maintenance from starting

---

## Acceptance Criteria

- **AC1:** "Handover Visit" is added as an independent visit type in the settings
- **AC2:** The handover visit is not counted within the contracted periodic visit count
- **AC3:** When the project is created from the contract, the "Create Handover Visit" button appears on the project details page
- **AC4:** No periodic visit can be scheduled before the handover report is approved
- **AC5:** The "Expected Assets" table is automatically pulled from the contract data
- **AC6:** The "Asset Type" field in the survey section contains only the contracted asset types
- **AC7:** The "Comparison Summary" table updates automatically with each new asset added
- **AC8:** If the actual count ≠ contracted count, an immediate notification is shown to the technician during data entry
- **AC9:** When the report is submitted for approval, the system performs automatic verification and displays the result to the supervisor
- **AC10:** If the supervisor approves a report with a discrepancy, a confirmation prompt appears: "The actual count does not match the contract. Do you wish to proceed?"
- **AC11:** If a report with a discrepancy is approved, the system automatically creates a ticket for the contracts department to amend the contract
- **AC12:** No periodic maintenance can begin until the report status = "Approved"
- **AC13:** After the report is approved, all entered assets are automatically added to the project's asset list
- **AC14:** If no assets were entered in the contract's equipment statement, the handover report is mandatory for adding assets



====================

# Audit Report: US-006 - Handover Visit & Report

[US-006: Execute Handover Visit and Create Handover Report]

✅ **Implemented:**
- **AC1, AC2 (Visit Type):** Handover visit is an independent type and doesn't count towards periodic visits.
- **AC5, AC7 (Comparison):** Automatic pulling of expected assets and generation of the `comparison_table` in report metadata.
- **AC13 (Asset Creation):** Assets discovered in the field are automatically created and linked to the project using `MaintenanceProjectAsset::updateOrCreate`.
- **Field Survey:** Detailed fields for asset condition, electrical specs, and accessories are supported in the completion request.

❌ **Missing:**
- **CRITICAL - AC4/AC12 (Halt Maintenance):** The system currently generates periodic visits via `GenerateVisitsFromContract` listener immediately upon contract approval. It **does not** wait for handover approval as required.
- **AC11 (Amendment Ticket):** No logic exists to create a "Ticket" or task for the Contracts department on discrepancy approval.
- **AC14 (Mandatory Guard):** No restriction found that prevents asset usage if a handover wasn't performed for an empty contract equipment statement.

⚠️ **Partially Implemented:**
- **AC6 (Field Filter):** `getContractAssetTypes` exists to provide data, but strict backend validation on the `complete` endpoint to only allow these types is missing.
- **AC8 (Technician Notification):** Backend calculates the status (`is_perfect_match`), but real-time validation during technician entry depends on frontend implementation.