# Distribute and Schedule Visits from the Backlog

---

## User Story

**As** a maintenance supervisor  
**I want** to view all planned visits without specific dates (Backlog)  
**So that** I can assign them to technicians and define their dates flexibly by selected month

---

## Operational Scenario

### Main Flow

1. The system creates the annual visit plan based on frequency (e.g. 12 visits per year)
2. Visits are automatically distributed across months (e.g. one visit per month)
3. Visits are saved with status "Planned – No Specific Date" (Backlog)
4. The supervisor opens the "Visit Distribution – Backlog" page
5. Selects the desired month (e.g. January 2025)
6. The system displays all planned visits for that month in a Backlog list
7. Available technicians are displayed in a Kanban view
8. The supervisor drags a visit from the Backlog and drops it onto the appropriate technician
9. Sets the date for the visit
10. The system verifies the technician's compatibility with the asset type
11. The visit transitions to status "Scheduled" and a notification is sent to the technician
12. Visits can also be viewed by week

### Alternative Flows

- **Technician not suitable for the asset type:** Warning + assignment blocked
- **Technician has more than 5 visits on the same date** *(count configurable from settings)*: Warning + alternative time suggestions
- Visit date can be edited after assignment

---

## Fields & Data

### Screen: Distribute Visits from Backlog

#### Header — Main Filters

| Filter | Type |
|--------|------|
| Select Month | Dropdown (January 2025 / February 2025 / …) |
| Select Project | Multi-select (optional – to filter visits) |
| Select System Type | Multi-select (HVAC / Generators / Elevators) |
| Select Zone / Location | Multi-select |

**Button:** `Refresh View`

#### Quick Statistics for Selected Month

| Stat | Type | Notes |
|------|------|-------|
| Total Visits in Backlog | Number | Not yet distributed |
| Scheduled Visits | Number | Assigned to technicians |
| Completed Visits | Number | |
| Overdue Visits | Number | In red |

---

### Design — Kanban Board View

The screen is split into two sections:

#### Left Section: Backlog (Visits without dates)

**Section Title:**
```
📋 Backlog – January 2025
(Visit Count: 25)
```

Each visit in the Backlog is displayed as a **Card** containing:

| Field | Notes |
|-------|-------|
| Project Name | |
| Client Name | |
| Location Name | |
| Visit Number | |
| Visit Type | Preventive Maintenance – Execute Maintenance |
| System Type | e.g. HVAC (Chiller) |
| Number of Units in the Visit | |

#### Right Section: Kanban Board (Technicians)

**Technician Filters:**

| Filter | Type |
|--------|------|
| View Technicians | Multi-select (All Technicians / Available Only / By Specialization) |

**Kanban View — Each technician is a column**, showing:
- Technician name
- Asset types they are qualified for (specialization)
- Number of scheduled visits vs. completed visits

Each visit being assigned requires:
- Setting a visit date (either a specific week or an exact date)

**System auto-verification:**
- ✅ Technician specialization matches the system type
- ✅ Technician is available on the specified date and time
- ⚠️ If conflict exists → clear warning

**Upon clicking "Confirm Assignment":**
- The visit disappears from the Backlog
- It appears in the technician's column on the specified date
- Visit status changes from "Planned" to "Scheduled"
- An immediate notification is sent to the technician

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

# Audit Report: Backlog Scheduling & Distribution

[Distribute and Schedule Visits from the Backlog]

## 1. Feature Analysis
The objective is to enable supervisors to schedule visits from an annual backlog by dragging them onto technician Kanban columns for specific months.

## 2. Implementation Audit Details

### ✅ Implemented
- **Backlog Visibility:** The backend correctly identifies visits in the backlog via the `is_scheduled = false` flag.
- **Kanban Data Structure:** Technicians are returned with their specializations and real-time "Assigned/Completed" counts, meeting the Kanban view requirements.
- **Technician Filtering (AC10):** The system filters out unqualified technicians at the retrieval stage (in `getAvailableTechniciansForVisit`).
- **Workload Tracking:** The system tracks the `maximum_daily_visits` attribute for technicians and provides a warning during assignment.
- **Notification System (AC11):** Assignments trigger an immediate `DeliveryPersonAssignedNotification`.

### ❌ Missing
- **Header Global Statistics:** Total counts for Backlog, Scheduled, etc., filtered by *Month* across all projects, are not currently aggregated by a dedicated endpoint.
- **Alternative Slot Suggestions:** The system does not suggest alternative times when a technician's limit is hit.

### ⚠️ Partially Implemented / Differently Implemented
- **Validation Strictness:** Specialization and workload checks are treated as "soft" (filters and warnings) rather than "hard" (saved-level blocking validation).
- **Date Flexibility:** The backend handles specific dates and times; the concept of "assigning to a week" (as mentioned in the spec) is translated to a specific `scheduled_at` timestamp.

## 3. Findings Summary
The core mechanic of moving a visit from the backlog to a scheduled state is fully functional. The primary gap is the lack of a "Global Backlog Dashboard" that aggregates monthly counts for the supervisor's header overview.