# US: Fault Report (Corrective Request)

> A fault report (corrective request) from a client with an active contract, based on a visit report in which a fault was recorded.  
> Added from the Supply Requests section, but with request type set to "Maintenance" — these fields appear when that type is selected.

---

## User Story

**As** an employee responsible for receiving reports  
**I want** to register a fault report from a client who has an active contract  
**So that** the coverage can be determined and a quotation created if needed

---

## Operational Scenario

### Main Flow

1. The employee opens the "Supply Chain Requests" page
2. Clicks "Create New Request"
3. Selects request type: "Corrective"
4. The system searches for the client's active contract
5. The system automatically pulls the contract data
6. Specifies the visit number
7. Reviews the spare parts resulting from the report
8. A supervisor is assigned to the request
9. The request is added and pricing representatives are assigned to complete it through the supply chain flow

---

## Fields & Data

### Screen: Add Maintenance Pricing Request

#### Section 1 — Auto Data from Contract

| Field | Type |
|-------|------|
| Client Name | Read Only |
| Location | Read Only |
| System Type | Read Only |
| Related Visit Number | *(shown only for visits requiring spare parts for this location and client)* |

#### Section 2 — Fault Data (auto-populated from visit report)

| Field | Type | Notes |
|-------|------|-------|
| Faulty Asset | Dropdown | From the list of assets covered by the contract |
| Fault Description | Textarea | Mandatory |
| Fault Photos | Upload | |

#### Section 3 — Items

Items are displayed in the same format currently used, but auto-populated based on the technician's selection in the report.

---

## Acceptance Criteria

- **AC1:** The corrective maintenance request is added from the same interface as adding supply requests
- **AC2:** After the corrective request is added, it follows the same supply chain pricing and customer quotation flow
- **AC3:** After the client approves the quotation and issues a purchase order, a visit is automatically scheduled, appearing in the visit backlog. The expected supply date is displayed so that the visit date can be set accordingly.

--------------------

# Audit Report: Fault Report (Corrective Request)

## [Feature: Fault Report (Corrective Request)]

### ✅ Implemented
- **Dynamic Maintenance Request Type**: Selection of "Corrective" in Supply Requests triggers required maintenance fields (`maintenance_visit_report_id`, `failure_description`, etc.).
- **Contract & Site Auto-Population**: `CorrectiveMaintenanceController@preFill` automatically resolves the client's active contract (linked project) and location data.
- **Spare Parts Integration**: System automatically pulls spare parts with "purchase" source from the visit report and maps them to supply order items.
- **Supervisor Assignment**: Validation rules in `StoreSupplyOrderRequest` ensure a supervisor is assigned to the request.
- **Automatic Visit Scheduling**: `MaintenanceVisitService@createCorrectiveVisitFromPriceOffer` handles the automatic creation of a corrective visit once a quotation is approved.
- **Visit Backlog**: Integration of status-based states (`PENDING_REVIEW`, `AWAITING_PARTS`, `AWAITING_SCHEDULING`) effectively manages the visit backlog as requested.

### ❌ Missing
- **Direct Coverage Determination**: While `OrderContractComparisonService` exists, there is no explicit automated logic that blocks or flags a corrective request specifically based on "coverage" rules inside the contract during the *creation* phase (it appears to be a separate manual/comparison step).

### ⚠️ Partially Implemented
- **Quotation/PO Supply Date Display**: While `MaintenanceVisit` has an `expected_delivery_date` field, the specific UI-linked logic to dynamically display "expected supply date" to the supervisor during scheduling is backend-ready but depends on procurement updates.

### 🔀 Implemented Differently
- **Automatic Scheduling Status**: The specification implies the visit is "automatically scheduled" on PO issuance. In practice, the code places it in a `PENDING_REVIEW` (Backlog) state first for supervisor verification, which is a more robust organizational approach than direct final scheduling.

---

## 📄 Audited Files (Modified with Headers)

### 1. CorrectiveMaintenanceController.php
`app/Domains/Supply/SubDomains/SupplyOrders/Http/Controllers/V1/CorrectiveMaintenanceController.php`

```php
/**
 * [AUDIT: Fault Report (Corrective Request)]
 * ✅ Implemented: Handlers for retrieving reports requiring supply and pre-filling request data.
 * ✅ Implemented: Auto-mapping of spare parts to supply items.
 * ✅ Implemented: Pulling contract/site data from the visit report context.
 */