# Maintenance Visit Scheduling - Quick Reference ## 📋 Feature Overview | Feature | Status | Description | |---------|--------|-------------| | **Automatic Visit Generation** | ✅ | Visits auto-generated when contract approved | | **Flexible Scheduling Patterns** | ✅ | Weekly, Monthly, Specific Dates, Custom | | **Bulk Visit Import** | ✅ | Import visits from Excel/CSV | | **Planned vs Scheduled** | ✅ | Distinction between planned and scheduled visits | --- ## 🗄️ Database Tables ### `mod_visit_recurrence_rules` Stores recurrence patterns for automatic visit generation. | Key Fields | Description | |------------|-------------| | `recurrence_type` | weekly, monthly, specific_dates, custom | | `frequency` | e.g., "2" for every 2 weeks | | `specific_days` | JSON: [1, 15] for 1st and 15th | | `total_visits` | Total number to generate | | `visits_generated` | Tracks how many created | ### `mod_maintenance_visits` (Updated) Added fields for scheduling management. | New Fields | Description | |------------|-------------| | `is_scheduled` | Boolean: planned vs scheduled | | `planned_date` | Suggested date (nullable) | | `visit_sequence` | 1st, 2nd, 3rd visit number | | `recurrence_rule_id` | Link to generation rule | ### `mod_contract_addendums` (Updated) Added visit generation control. | New Field | Description | |-----------|-------------| | `visit_generation_mode` | 'manual' or 'automatic' | --- ## 🔌 API Endpoints Quick Reference ### Recurrence Rules ``` POST /api/maintenance/recurrence-rules Create rule GET /api/maintenance/recurrence-rules/{id} View rule PUT /api/maintenance/recurrence-rules/{id} Update rule DELETE /api/maintenance/recurrence-rules/{id} Delete rule POST /api/maintenance/recurrence-rules/preview Preview dates POST /api/maintenance/recurrence-rules/{id}/generate-visits Generate ``` ### Planned/Scheduled Visits ``` GET /api/maintenance/visits/planned List planned POST /api/maintenance/visits/{id}/schedule Schedule one POST /api/maintenance/visits/bulk-schedule Schedule many ``` ### Bulk Import ``` GET /api/maintenance/visits/import-template Download template POST /api/maintenance/projects/{id}/visits/import Import visits ``` --- ## 🎯 Recurrence Pattern Examples ### Monthly (Default for auto-generation) ```json { "recurrence_type": "monthly", "frequency": 1, "total_visits": 12 } ``` **Result:** One visit per month for 12 months ### Weekly ```json { "recurrence_type": "weekly", "frequency": 2, "total_visits": 26 } ``` **Result:** One visit every 2 weeks for 1 year ### Specific Dates ```json { "recurrence_type": "specific_dates", "specific_days": [1, 15], "total_visits": 24 } ``` **Result:** 1st and 15th of each month for 12 months ### Multiple Times Per Month ```json { "recurrence_type": "monthly", "frequency": 3, "total_visits": 36 } ``` **Result:** 3 visits per month for 12 months (evenly distributed) --- ## 💡 Common Use Cases ### Use Case 1: Contract Approval with Auto-Generation ``` 1. Create contract with addendums 2. Set addendum.visit_generation_mode = 'automatic' 3. Set addendum.number_of_visits = 12 4. Approve contract 5. System automatically: - Creates project - Creates recurrence rule (monthly) - Generates 12 planned visits ``` ### Use Case 2: Manual Visit Scheduling ``` 1. GET /api/maintenance/visits/planned 2. Review planned visits 3. POST /api/maintenance/visits/{id}/schedule - Assign technicians - Confirm date/time 4. Visit is now scheduled (is_scheduled = true) ``` ### Use Case 3: Bulk Import Special Visits ``` 1. GET /api/maintenance/visits/import-template 2. Fill Excel with: - Visit Type (preventive/corrective/emergency/inspection) - Planned Date - Notes 3. POST /api/maintenance/projects/{id}/visits/import 4. All visits created as "planned" ``` ### Use Case 4: Quarterly Maintenance Schedule ``` 1. POST /api/maintenance/recurrence-rules/preview { "recurrence_type": "monthly", "frequency": 3, "total_visits": 4 } 2. Review dates (every 3 months) 3. POST /api/maintenance/recurrence-rules (create) 4. POST /api/maintenance/recurrence-rules/{id}/generate-visits ``` --- ## 🔧 Service Layer ### `VisitRecurrenceService` ```php calculateVisitDates(VisitRecurrenceRule $rule): array previewVisitDates(array $ruleData): array calculateNextVisitDate(VisitRecurrenceRule $rule, Carbon $date): ?Carbon ``` ### `VisitGenerationService` ```php generatePlannedVisits(VisitRecurrenceRule $rule): Collection scheduleVisit(MaintenanceVisit $visit, array $data): MaintenanceVisit bulkScheduleVisits(array $visitIds, array $data): Collection ``` ### `VisitBulkImportService` ```php importVisitsFromFile(UploadedFile $file, int $projectId): array generateTemplate(): string ``` --- ## 📊 Model Relationships ``` MaintenanceContract └── hasMany → ContractAddendum ├── number_of_visits ├── visit_generation_mode └── hasMany → VisitRecurrenceRule └── hasMany → MaintenanceVisit ├── is_scheduled ├── planned_date └── visit_sequence ``` --- ## 🎨 Model Scopes ### MaintenanceVisit ```php MaintenanceVisit::planned()->get(); // is_scheduled = false MaintenanceVisit::scheduled()->get(); // is_scheduled = true MaintenanceVisit::unscheduled()->get(); // no scheduled_at date ``` ### VisitRecurrenceRule ```php VisitRecurrenceRule::active()->get(); // is_active = true VisitRecurrenceRule::byContract($contractId); // Filter by contract VisitRecurrenceRule::byProject($projectId); // Filter by project ``` --- ## 🔔 Events & Listeners ### Event: `MaintenanceContractApproved` **Fired when:** Contract is approved **Listener:** `GenerateVisitsFromContract` **Action:** - Creates recurrence rules - Generates planned visits for each addendum - Logs generation activity **Check logs:** ```bash tail -f storage/logs/laravel.log | grep "Generated visits" ``` --- ## ✅ Validation Rules ### StoreRecurrenceRuleRequest ``` contract_id: required|exists addendum_id: required|exists maintenance_project_id: required|exists recurrence_type: required|in:weekly,monthly,specific_dates,custom frequency: required|integer|min:1 specific_days: nullable|array specific_days.*: integer|min:1|max:31 total_visits: required|integer|min:1 start_date: required|date end_date: required|date|after:start_date ``` ### ScheduleVisitRequest ``` scheduled_at: required|date|after_or_equal:today technician_ids: required|array|min:1 technician_ids.*: exists:mod_maintenance_technicians,id notes: nullable|string|max:1000 ``` --- ## 🐛 Troubleshooting ### Issue: Visits not auto-generated on contract approval **Check:** 1. Is `visit_generation_mode = 'automatic'`? 2. Does addendum have `number_of_visits` > 0? 3. Check logs: `storage/logs/laravel.log` 4. Verify event listener registered in `MaintenanceEventsServiceProvider` ### Issue: Preview returns wrong dates **Check:** 1. Verify `start_date < end_date` 2. Check `frequency` value (must be > 0) 3. For specific_dates, check days are between 1-31 4. Verify `total_visits` is reasonable for date range ### Issue: Import fails **Check:** 1. File is .xlsx, .xls, or .csv 2. File size < 5MB 3. First row is header 4. Visit types are valid: preventive, corrective, emergency, inspection 5. Dates are in format: YYYY-MM-DD --- ## 📝 Example Data Flow ### Complete Workflow ``` 1. Contract Created ↓ 2. Contract Approved (MaintenanceContractApproved event) ↓ 3. GenerateVisitsFromContract listener ↓ 4. Creates VisitRecurrenceRule { recurrence_type: 'monthly', total_visits: 12, frequency: 1 } ↓ 5. Calculates 12 dates (one per month) ↓ 6. Generates 12 MaintenanceVisit records { is_scheduled: false, planned_date: '2026-02-01', visit_sequence: 1, visit_type: 'preventive' } ↓ 7. Admin reviews planned visits GET /api/maintenance/visits/planned ↓ 8. Admin schedules visit POST /api/maintenance/visits/101/schedule { scheduled_at: '2026-02-01 09:00', technician_ids: [1, 2] } ↓ 9. Visit updated { is_scheduled: true, scheduled_at: '2026-02-01 09:00' } ↓ 10. Technicians notified (if notification system exists) ``` --- ## 🔐 Permissions All endpoints use existing maintenance permissions: - `maintenance.visits.view` - View visits and rules - `maintenance.visits.create` - Create visits and rules - `maintenance.visits.edit` - Schedule and update visits - `maintenance.visits.delete` - Delete visits and rules --- ## 📖 Additional Resources - **Full Implementation Plan:** `C:\Users\MAB\.claude\plans\replicated-jingling-wind.md` - **API Testing Guide:** `API_TESTING_GUIDE.md` - **Test Script:** `test_visit_scheduling.php` --- **Version:** 1.0 **Date:** 2026-01-22 **Status:** Production Ready ✅