# US-001: Receive a Pricing Request for a Preventive Maintenance Contract

**Collection:** US-001: Pricing Requests — Full CRUD

---

## User Story

**As** an employee responsible for receiving requests  
**I want** to enter a new preventive maintenance pricing request  
**So that** the request is fully documented and forwarded to the technical team to prepare the quotation

---

## Operational Scenario

### Main Flow

1. The employee opens the "Pricing Requests" page
2. Clicks the "Create New Pricing Request" button
3. Fills in the shared fields
4. Selects maintenance type: "Preventive"
5. The fields specific to preventive maintenance appear (second stage)
6. Fills in all required fields
7. Clicks "Save" or "Save as Draft"
8. The system generates an automatic request number and saves the data

### Alternative Flow

- If "Save as Draft" is selected → the request is visible only to the creating employee
- If "Save" is selected → the request is forwarded to the assigned technical supervisor

---

## Fields & Data

### Screen: Create Preventive Pricing Request

#### Stage 1 — Shared Fields

| Field | Type | Notes |
|-------|------|-------|
| Client Name | Search + Dropdown + "Add New Client" button | |
| Location | Select + "Add New Location" button | |
| Responsible Contact | Select (based on client contacts) | |
| Request Source | Dropdown | Phone / WhatsApp / Email / Website / Direct |
| Responsible Technical Supervisor | Dropdown | |
| Is the request commission-based? | Toggle | Yes / No |
| Maintenance Type | Multi-select | Preventive / Emergency |
| Receiving Employee | Auto (non-editable) | |
| Request Received Date | Auto (non-editable) | |
| Attachments | Upload | Optional |
| Additional Notes | Textarea | Optional |

#### Stage 2 — Preventive Maintenance Fields (appear when "Preventive" is selected)

| Field | Type | Notes |
|-------|------|-------|
| System Type | Multi-select | HVAC / Generators / Elevators / Other |
| Does it include a chiller? | Toggle | Yes / No |
| Approximate Number of Units | Number | |
| Required Frequency | Dropdown | Monthly / Quarterly / Semi-annual / Annual |
| Are consumables required? | Toggle | Yes / No |
| If Yes → Consumable Types | Multi-select | Filters / Oils / Lubricants / Other |
| File Attachments | Upload | |
| Required Scope of Work | Textarea | |

---

## Buttons

| Button | Action |
|--------|--------|
| Save | Creates the request and forwards it to the supervisor |
| Save as Draft | Saves without forwarding |
| Cancel | Closes the screen without saving |

---

## Acceptance Criteria

- **AC1:** When the Pricing Requests page is opened, the "Create New Pricing Request" button is clearly visible
- **AC2:** When clicking "Create New Pricing Request", a screen appears showing only the shared fields first
- **AC3:** When "Preventive" is selected from maintenance type, the preventive maintenance fields appear automatically on the same screen
- **AC4:** The "Client Name" field supports dynamic search and shows an "Add New Client" button
- **AC5:** When clicking "Save", the system generates an automatic request number in a defined format (example: RQ-2025-001)
- **AC6:** Mandatory fields (Client Name, Location, System Type, Number of Units) must be filled before saving
- **AC7:** When "Save as Draft" is clicked, the system saves the request with status "Draft" and does not send a notification to the supervisor
- **AC18:** When "Save" is clicked, the system saves the request with status "New" and automatically sends a notification to the assigned technical supervisor

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

# Audit Report: US-001 - Pricing Request

[US-001: Receive a Pricing Request for a Preventive Maintenance Contract]

✅ **Implemented:**
- **Automatic Numbering:** Implementation in `MaintenanceRequestSequenceService` generates the `RQ-YYYY-NNN` format as specified in AC5.
- **Status Transitions:** Logic in `MaintenanceRequestService::createRequest` correctly handles "Save" (Status: New) vs "Save as Draft" (Status: Draft, no notification).
- **Notifications:** Automatic notification sent to the assigned technical supervisor when status is not "draft" (AC18).
- **Preventive Fields:** Stage 2 fields (`system_types`, `has_chiller`, `approximate_unit_count`, `visit_frequency`, `consumables_required`, `consumable_types`, `scope_of_work`) are present in the model and validated conditionally.
- **Auto-populated Fields:** `created_by` and `requested_at` are handled automatically by the service layer.
- **UI Support (Backend):** Controller provides endpoints for dynamic customer search and fetching locations/contacts.

❌ **Missing:**
- None.

⚠️ **Partially Implemented:**
- **AC6 (Mandatory Fields):** Specification requires "Location" to be mandatory. The `StoreMaintenanceRequestRequest` validation currently tags `location_id` and `location` as `nullable`.

🔀 **Implemented Differently:**
- **Maintenance Type:** The spec specifies "Multi-select" for Maintenance Type. The code currently uses an `enum` column `request_type`, allowing only **one** selection (Preventive OR Emergency, etc.).
- **Commission-based Field:** Named `is_percentage` in the code, whereas the spec uses "commission-based".
- **Consumable Naming:** Spec lists "Lubricants"; code validation uses "greases".