# US-005: Create a Maintenance Contract from an Approved Quotation

---

## User Story

**As** a contracts employee  
**I want** to create a maintenance contract from an approved quotation  
**So that** I can begin executing the contract within the system

---

## Operational Scenario

### Entry Points

- From the approved quotation page → "Create Contract" button
- From the Contracts page → "Create New Contract" → select an approved quotation  
  *(A contract can also be created without a quotation)*

### Main Flow

1. The contracts employee opens the approved quotation
2. Clicks "Create Contract"
3. The system automatically pulls the quotation data
4. The employee fills in the additional contract data
5. Enters the parties and terms
6. Defines the checklist (scope of work) for each asset type (asset)
7. Clicks "Save"
8. The contract is saved with status "Draft"
9. After review → "Activate Contract" button

---

## Fields & Data

### Screen: Create Maintenance Contract

#### Section 1 — Quotation Data (Read Only)

| Field | Type |
|-------|------|
| Quotation Number | Auto |
| Client Name | Auto |
| Quotation Value | Auto |
| Agreed Maintenance Type | Auto (Preventive) |

#### Section 2 — Contract Header Data

| Field | Type | Notes |
|-------|------|-------|
| Contract Number | Auto (system-generated) | |
| Client Contract Number | Text | In case the contract is a subcontract |
| Contract Title | Text Field | |
| Contract Type | Dropdown | Private Sector / Subcontract / Government Contract / Operations Contract |
| Contract Start Date | Date Picker | |
| Contract End Date | Date Picker | Auto-calculated from contract duration |
| Contract Duration | Number + Dropdown | Month / Year |

#### Section 3 — Parties

**First Party (The Company):**

| Field | Type |
|-------|------|
| Company Name | Text (default from settings) |
| Tax Number | Text |
| Commercial Registration | Text |

**Second Party (The Client):**

| Field | Type |
|-------|------|
| Client Name | Auto from quotation |
| Tax Number | Text |
| Commercial Registration | Text |
| Location | Select |

#### Section 4 — Contract Subject

| Field | Type |
|-------|------|
| Contract Subject | Textarea |

#### Section 5 — Scope of Work by Maintenance Type

**If "Preventive" is selected:**

| Field | Type | Notes |
|-------|------|-------|
| Visit Frequency | Dropdown | Monthly / Quarterly / Semi-annual / Annual — Auto from quotation |
| Annual Number of Visits | Number | Auto from quotation |
| Consumables Included? | Toggle | Auto from quotation |
| If Yes → Consumable Types | Multi-select | Auto from quotation |
| Allowed Consumables Value | Currency | |
| Checklist Template | Dropdown | Select from system / Copy from previous contract / Create new |

**Emergency SLA:**

| Field | Type | Notes |
|-------|------|-------|
| Agreed SLA (Performance Degradation) | Number (hours) | Default: 24 |

#### Section 6 — Detailed Scope of Work (by Unit Type)

*Example: HVAC Units*

| Field | Type |
|-------|------|
| Number of Units | Number |

**Sub-types:**

*Chillers:*

| Field | Type |
|-------|------|
| Number of Units | Number |
| Checklist | Dropdown |

*Water Pumps:*

| Field | Type |
|-------|------|
| Number of Units | Number |
| Checklist | Dropdown |

*Air Handling Units:*

| Field | Type |
|-------|------|
| Number of Units | Number |
| Checklist | Dropdown |

**Button:** `+ Add New Unit Type`

#### Section 7 — Equipment Statement (Optional)

> Note: Assets and accessories are not mandatory in the contract. They can be added later in the handover report.

**Button:** `+ Add Asset` (Optional)

#### Section 8 — Payment Method

| Field | Type |
|-------|------|
| Payment Method | Dropdown (Upfront / Monthly / Quarterly / Upon Execution) |

#### Section 9 — Terms & Conditions

| Field | Type |
|-------|------|
| Cases Not Covered by the Contract | Textarea |
| Delay Penalties | Textarea |

#### Section 10 — Signatures

| Field | Type |
|-------|------|
| First Party Signature | Upload |
| Second Party Signature | Upload |
| Signature Date | Date |

#### Section 11 — Attachments

| Field | Type |
|-------|------|
| Contract Attachments | Upload |

---

## Buttons

| Button | Action |
|--------|--------|
| Save as Draft | |
| Save | |
| Preview PDF | |
| Export PDF | |

---

## Acceptance Criteria

- **AC1:** All quotation data is pulled automatically when an approved quotation is selected
- **AC2:** The "Contract Number" field is auto-generated in a defined format (example: C-2025-001)
- **AC3:** The "Contract End Date" field is auto-calculated = Start Date + Contract Duration
- **AC4:** Scope of work fields change dynamically based on the selected maintenance type
- **AC5:** More than one maintenance type can be selected (Preventive + Corrective + Emergency) and fields for each type appear accordingly
- **AC6:** The "Detailed Scope of Work" section supports adding multiple unit types dynamically
- **AC7:** For each sub-unit type, an independent checklist can be assigned
- **AC8:** The Equipment Statement is optional and does not prevent saving the contract if empty
- **AC9:** Upon "Save as Draft" or "Save", the contract is saved with status "Draft"
- **AC11:** Upon "Activate Contract", it transitions to status "Active" and the system automatically creates:
  - A project linked to the contract
  - A cost center linked to the project
  - A notification 60 days before the contract expires (duration configurable from settings)

======================
# Audit Report: US-005 - Create Maintenance Contract

[US-005: Create a Maintenance Contract from an Approved Quotation]

✅ **Implemented:**
- **AC5/AC6 (Dynamic Scope):** Support for multiple maintenance types and detailed scope by unit type with specific checklists.
- **AC11 (Project Creation):** Activation (`approve()`) successfully creates `MaintenanceProject`, `MaintenanceLocation`, and `MaintenanceProjectAsset` records.
- **Section 3 (Parties):** Model and service correctly handle both Company (First Party) and Client (Second Party) details.
- **Draft Logic (AC9):** Default status is set to `draft` upon creation.
- **Reporting & PDF:** Controller provides methods for previewing and exporting contract PDFs.
- **Expiry Notification:** Automated job `SendContractExpiryAlertJob` manages the 60-day notification threshold.

❌ **Missing:**
- **AC11 (Cost Center):** Automation for creating a linked Cost Center upon contract activation is completely absent from the service logic.
- **AC3 (Auto-End Date):** The service does not dynamically calculate the `end_date` from `duration` if the end date is not explicitly provided in the create request.

⚠️ **Partially Implemented:**
- **AC1 (Quotation Pull):** The system maps from `technical_offer_id` (Stage 1) but ignores the Stage 2 `price_offer_id` (Quotation), meaning final financial values from the quotation must be re-entered.

🔀 **Implemented Differently:**
- **AC2 (Number Format):** Code uses prefix `MC-` and 5-digit padding whereas spec suggested `C-` and 3-digit padding.
- **SLA Mapping:** Spec suggests a single Emergency SLA field; code provides granular P1/P2/P3 Hour fields.