# US-007: Create and Manage the Periodic Visit Plan

---

## User Story

**As** a maintenance supervisor  
**I want** to create an annual periodic visit plan for the project  
**So that** all visits are scheduled in advance and technicians are assigned efficiently

---

## Operational Scenario

### Main Flow

1. After the handover report is approved
2. The supervisor opens the project details page
3. Clicks the "Visits" tab
4. Clicks the "Create Visit Plan" button
5. The system pulls contract data (frequency, number of visits)
6. Visit distribution is shown by month based on frequency and plan start date  
   *(e.g. Visit 1 in February, Visit 2 in April … and so on)*
7. The supervisor reviews the plan and adjusts it if needed
8. Clicks "Save & Approve Plan"

---

## Fields & Data

### Screen: Create Visit Plan

#### Section 1 — Auto Data from Contract

| Field | Type |
|-------|------|
| Project Number | Read Only |
| Client Name | Read Only |
| Contract Type | Read Only (Private Sector / Subcontract) |
| Frequency | Read Only (Monthly / Quarterly / Semi-annual / Annual) |
| Annual Number of Visits | Read Only |
| Contract Start Date | Read Only |
| Contract End Date | Read Only |

#### Section 2 — Plan Settings

| Field | Type | Notes |
|-------|------|-------|
| Plan Year | Dropdown | Starts from the contract start year |

#### Section 3 — Auto-Generated Visits

The system automatically generates a visit schedule based on:
- Frequency defined in the contract
- Contract start date
- Equal distribution throughout the year

**Button:** `Generate Plan Automatically`

**Generated Visits Table:**

| Column | Type | Notes |
|--------|------|-------|
| Visit Number | Auto | Example: V-2025-001 |
| Date | — | Not yet defined |
| Visit Type | Read Only | Periodic Maintenance |
| Status | Read Only | Scheduled |
| Assigned Technician | — | Not yet assigned |
| Actions | — | Edit / Delete |

#### Section 4 — Validation Rules

The system automatically verifies:

- ✅ Number of entered visits = number of contracted visits
- ✅ All visits are within the contract period

If there is an error → a clear warning is shown before saving.

---

## Buttons

| Button | Action |
|--------|--------|
| Save as Draft | |
| Save & Approve Plan | |

---

### Screen: View and Manage Visits

#### Dashboard Statistics

| Stat | Type |
|------|------|
| Total Scheduled Visits | Number |
| Completed Visits | Number |
| Remaining Visits | Number |
| Overdue Visits | Number (in red) |

#### Filters

| Filter | Type |
|--------|------|
| Technician | Multi-select |
| Status | Multi-select (Scheduled / Completed / Overdue / Cancelled) |
| Month | Dropdown |
| Visit Type | Multi-select |

#### Visits Table

| Column | Notes |
|--------|-------|
| Visit Number | |
| Date | |
| Time | |
| Visit Type | |
| Assigned Technician | Photo + Name + quick edit button |
| Status | Color-coded |
| Actions | Edit / Reschedule / Assign Technician / Cancel / View Details |

#### Alternative View — Gantt Chart

- **Button:** "View Gantt Chart"
- Displays visits on a timeline, showing completed and remaining visits per project

---

## Acceptance Criteria

- **AC1:** The "Create Visit Plan" button appears only after the handover report is approved
- **AC3:** The number of auto-generated visits = the number specified in the contract
- **AC4:** Auto-generated dates are distributed equally throughout the year

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

# Audit Report: US-007 - Periodic Visit Plan

[US-007: Create and Manage the Periodic Visit Plan]

✅ **Implemented:**
- **AC3/AC4 (Distribution):** `VisitRecurrenceService` successfully calculates equal intervals across the contract duration to match the target visit count.
- **Dashboard Stats:** `ProjectDetailsResource` provides all requested metrics: Total, Scheduled, Completed, Remaining, and Delayed (Overdue).
- **Technician Assignment:** Service handles assignments, limits, and notifications.
- **Handover Guard (AC1):** `VisitGenerationService` throws an exception if visits are generated before handover approval.

❌ **Missing:**
- **Gantt Logic:** No specialized endpoint for Gantt-compliant data.
- **AC14 Implementation:** The handover guard is mandatory for all projects, even if the contract already contains defined assets (no bypass logic).

⚠️ **Partially Implemented:**
- **Automation Conflict:** The `GenerateVisitsFromContract` listener will always fail initially because it fires before the handover can possibly occur. This prevents truly "automatic" generation at activation.

🔀 **Implemented Differently:**
- **Plan Year:** System relies on actual start/end dates rather than a year-based constraints logic.