# US-013: Approve the Periodic Visit Report

---

## User Story

**As** a maintenance supervisor  
**I want** to review and approve visit reports submitted by technicians  
**So that** I can verify execution quality and approve them for invoicing

---

## Operational Scenario

### Main Flow

1. The supervisor receives a notification about a new report
2. Opens the "Visit Reports" page
3. Opens the report for review
4. Reviews all items and photos
5. Verifies the completeness of the data
6. If everything is correct → "Approve"
7. If there is a gap or error → "Reject with Reason" or "Return to Technician"
8. Upon approval → the report becomes ready for invoicing

---

## Fields & Data

### Screen: Visit Reports List

#### Dashboard Statistics

| Stat | Color |
|------|-------|
| Reports Pending Approval | Orange |
| Approved Reports | |
| Rejected Reports | |
| Reports Requiring Supply | |

#### Filters

| Filter | Type |
|--------|------|
| Request Number | Text |
| Visit Number | Text |
| Client Name | Search + Dropdown |
| Technician Name | Multi-select |
| Visit Type | Multi-select (Periodic / Corrective / Emergency / Handover) |
| Project Name | Dropdown |
| Date Range | Date Range |
| Report Status | Multi-select (Pending Approval / Approved / Rejected / Returned to Technician) |

#### Reports Table

| Column | Notes |
|--------|-------|
| Report Number | |
| Visit Number | |
| Visit Type | Colored badge |
| Client | |
| Project | |
| Technician | |
| Visit Date | |
| Report Submission Date | |
| Status | Badge |
| Requires Supply? | Icon (📦) |

**Actions per row:**
- View Report
- Quick Approve (✅)
- Reject (❌)
- Edit
- Add Comment
- Create Invoice *(shown only for approved reports)*
- Convert to Supply Request for Procurement Department

**Bulk action:** Select multiple reports → "Create Consolidated Invoice"

---

### Screen: View Report Details

**Header:**

| Field | Notes |
|-------|-------|
| Report Number | |
| Visit Type | Badge |
| Status | Badge |
| Visit Date | |
| "Change Log" button | Audit Trail |

#### Section 1 — Visit Data

All visit data displayed in a formatted view.

#### Section 2 — Timestamps

| Field | Notes |
|-------|-------|
| Start Time | |
| End Time | |
| *(For emergency visits: all timestamps + SLA)* | |

#### Section 3 — Checklist (if applicable)

All questions and answers displayed in a formatted view:

| Column |
|--------|
| Question |
| Answer |
| Attached Photos (if any) |

#### Section 4 — Inspected Assets

Table:

| Column |
|--------|
| Asset Name |
| Location |
| Post-maintenance Status |
| Photos |

#### Section 5 — Discovered Faults (if any)

For each fault:

| Field |
|-------|
| Fault Description |
| Fault Photos |
| Required Spare Parts Table |

#### Section 8 — Photos & Videos

All uploaded files displayed clearly.

---

### Supervisor Actions Section

**Buttons available based on status:**

*If status = "Pending Approval":*
- Approve Report
- Reject Report *(requires entering a reason)*
- Return to Technician for Edit *(requires entering a reason)*
- Export PDF

*If status = "Approved":*
- Export PDF
- Create Invoice
- Send Copy to Client
- Create Supply Request *(if not already created)*

---

### Modal: Reject Report

| Field | Type |
|-------|------|
| Rejection Reason | Textarea (mandatory) |
| Classification | Dropdown (Missing Data / Unclear Photos / Technical Errors / Other) |

**Buttons:** Confirm Rejection / Cancel

---

### Modal: Return to Technician

| Field | Type |
|-------|------|
| What needs to be edited? | Textarea (mandatory) |

**Buttons:** Return / Cancel

---

## Acceptance Criteria

- **AC1:** When a technician submits a report, an immediate notification is sent to the supervisor
- **AC2:** Reports "Pending Approval" are displayed with a distinct color in the list
- **AC3:** The supervisor can open the report and see all details in a formatted view
- **AC4:** Asset photos are displayed at full size when clicked
- **AC6:** When "Approve Report" is clicked, the status changes to "Approved" and a notification is sent to the technician
- **AC7:** When "Reject Report" is clicked, the rejection reason field is mandatory
- **AC8:** When "Return to Technician" is clicked, a notification is sent to the technician with the requested edits, and the technician can edit the report
- **AC9:** Only an approved report can be used to create an invoice
- **AC10:** Multiple approved reports can be selected and a consolidated invoice can be created for them
- **AC11:** The "Create Supply Request" button appears only if spare parts are required in the report
- **AC12:** When a supply request is created from the report, the parts are automatically transferred to the purchase request
- **AC14:** The Change Log documents: who approved, when; who rejected, when; who edited, when

=====================================
# Audit Report: US-013 Approve the Periodic Visit Report

| Feature Name | US-013: Approve the Periodic Visit Report |
| :--- | :--- |
| **Audit Date** | 2026-04-15 |
| **Status** | Reviewed |

## 1. Executive Summary
The approval workflow is robust, providing supervisors with full visibility into visit data, checklists, and faults. The integration with the procurement system for automatic supply requests is a highlight of the implementation. However, the closing of the financial loop (invoicing) remains a placeholder.

---

## 2. Acceptance Criteria Verification

| ID | Requirement | Implementation Status | Code Reference |
| :--- | :--- | :--- | :--- |
| **AC1** | Notification to supervisor | ✅ Implemented | `MaintenanceVisitService::completeVisitAndSubmitReport` |
| **AC2** | Distinct pending status color | ✅ Implemented | Handled via status badge logic and `pending` endpoint. |
| **AC3** | Formatted review screen | ✅ Implemented | `MaintenanceVisitReportResource` |
| **AC4** | Full-size photos (click) | ✅ Implemented | Provided via `Attachments` relation in Resource. |
| **AC6** | Approve -> Notif to technician | ⚠️ Partially Implemented | Status changes correctly; push notification to tech is missing. |
| **AC7** | Rejection reason mandatory | ✅ Implemented | `RejectVisitReportRequest` |
| **AC8** | Return for Edit -> Notification | ⚠️ Partially Implemented | Logic exists in service; push notification is missing. |
| **AC9** | Invoice only if approved | ❌ Missing | Implementation is a placeholder. |
| **AC10**| Consolidated Invoice | ⚠️ Partially Implemented | Endpoint accepts multiple IDs; core logic is pending. |
| **AC11**| Supply Request button logic | ✅ Implemented | `AutomaticProcurementService::createSupplyRequest` |
| **AC12**| Auto-transfer parts to purchase | ✅ Implemented | `AutomaticProcurementService.extractProcurementItems` |
| **AC14**| Change Log (Who/When) | ✅ Implemented | Logged via Spatie Activity Log in `ReportApprovalService`. |

---

## 3. Data & Field Mapping

### Screen: Reports List & Dashboards
- **Filters:** Extensive support for Request/Visit numbers, Clients, Technicians, types, and date ranges via `FilterMaintenanceVisitRequest`.
- **Statistics:** `ReportApprovalService::getStatistics` provides real-time counts for the dashboard.

### Screen: View Report Details
- **Timestamps:** Start/End times, durations, and SLA compliance (for emergency) are fully exposed.
- **Checklist:** Answers and photos are loaded through eager-loaded relationships.
- **Comparison:** The system includes a custom `parts_comparison` in the Resource to show variance between approved and installed parts.

---

## 4. Required Actions / Improvements
1. **Notifications:** Implement actual push/SMS notifications in the `ReportApprovalService` for approval/rejection/return actions.
2. **Rejection Meta:** Add `classification` column to `MaintenanceVisitReport` to support classification of rejection reasons.
3. **Invoicing:** Complete the integration with the Accounting domain to allow actual invoice generation from approved reports.
4. **Audit Trail:** Add `activity()` logging to `MaintenanceVisitReportService::updateReport` to track technician edits.