# Ticket Management Implementation Checklist

## ✅ Phase 1: Ticket Creation (COMPLETED)
- [x] Ticket model with PERMANENT deduplication strategy (timestamp-based, never cleared)
- [x] Removed project_subcontractor_id (use assignments via project_team)
- [x] Ticket schemas (create/update/response)
- [x] Ticket service (create from sales_order/task)
- [x] Ticket API endpoints (create, list, get, update, reschedule, cancel, stats)
- [x] Supabase migration to remove subcontractor_id column
- [ ] Update SalesOrder.promote() to use new ticket service

## 🔲 Phase 2: Ticket Assignment (NEXT)
- [ ] Assignment model (ticket_assignments table)
- [ ] Assignment schemas
- [ ] Assignment service (assign, accept, reject, drop)
- [ ] Assignment API endpoints
- [ ] Self-assignment limit (3 tickets per agent)

## 🔲 Phase 3: Ticket Execution
- [ ] Status transitions (open → assigned → in_progress → completed)
- [ ] GPS tracking integration
- [ ] Arrival verification
- [ ] Work completion with location capture

## 🔲 Phase 4: Ticket Rescheduling
- [ ] Reschedule API endpoint
- [ ] Customer availability handling
- [ ] Reschedule history/audit

## 🔲 Phase 5: Ticket Expenses
- [ ] Ticket expenses model (fuel, materials, transport)
- [ ] Expense creation/approval workflow
- [ ] Location-based expense validation
- [ ] Expense reports

## 🔲 Phase 6: Ticket Inventory
- [ ] Equipment assignment to tickets
- [ ] Material consumption tracking
- [ ] Stock deduction on completion
- [ ] Inventory return workflow

## 🔲 Phase 7: Ticket Invoicing
- [ ] Invoice generation from completed tickets
- [ ] Contractor invoicing
- [ ] Payment tracking
- [ ] Invoice approval workflow

## 🔲 Phase 8: Ticket Analytics
- [ ] Performance metrics (completion time, SLA compliance)
- [ ] Agent performance dashboards
- [ ] Regional performance
- [ ] Customer satisfaction metrics

## 🔲 Phase 9: Ticket Communication
- [ ] Ticket comments/notes
- [ ] Customer communication tracking
- [ ] SMS/Email notifications
- [ ] Real-time updates

## 🔲 Phase 10: Advanced Features
- [ ] Ticket templates
- [ ] Bulk operations
- [ ] Auto-assignment algorithms
- [ ] Route optimization
- [ ] Ticket dependencies (prerequisites)

---

## Notes

### Deduplication Strategy (CORRECTED - With Reactivation)
- `dedup_key = MD5(source + source_id + ticket_type + created_at)`
- **PERMANENT** - never cleared on completion/cancellation
- **Timestamp-based** - ensures uniqueness for each creation
- **Business Rules**:
  1. **One source = One ticket per creation** (dedup_key tracks creation instance)
  2. **Same service reactivation**: Cancelled ticket → Reactivate (REUSE same ticket/dedup_key)
  3. **Different service**: Create NEW sales order → NEW ticket (new dedup_key)
  4. **Space efficient**: No duplicate rows for reactivations
  5. **Payment tracking**: If customer paid before cancelling, we retain that history
  6. **Customer behavior**: Can identify chronic cancellers

**Example Scenarios**:
- Customer cancels WiFi → Wants same WiFi again → REACTIVATE ticket (update status cancelled→open)
- Customer had 10Mbps (cancelled) → Now wants 50Mbps → NEW sales order → NEW ticket
- History shows: Multiple sales orders per customer (each with their own ticket)

### Ticket Scheduling
- `scheduled_date` on ticket can be different from `preferred_visit_date` on sales_order
- Original sales order date remains unchanged
- Ticket date can be modified for rescheduling (customer availability)
- Reschedule history tracked in notes

### Ticket Lifecycle (With Reactivation Support)
```
1. CREATE: Sales order/task → Ticket created (status=open, permanent dedup_key)
2. ASSIGN: Dispatcher assigns to agent via ticket_assignments (status=assigned)
3. ACCEPT: Agent accepts assignment (status=in_progress)
4. EXECUTE: Agent performs work, logs expenses
5. COMPLETE/CANCEL: Agent completes or customer cancels (status=completed/cancelled)
   - Location captured and verified
   - Dedup key REMAINS (permanent audit trail)
   - Subscription created (for installations if completed)

6. REACTIVATION (Same Service):
   - Customer wants same service again
   - Find cancelled/completed ticket
   - Update: status=open, new dates, add reactivation note
   - REUSE same dedup_key (space efficient, payment history preserved)

7. NEW SERVICE:
   - Customer wants different package/service
   - Create NEW sales order
   - Creates NEW ticket (new dedup_key, new creation timestamp)
   - History: Multiple tickets for customer (each with own dedup_key)
```

### Subcontractor Assignment
- **Removed** `project_subcontractor_id` from tickets table
- Subcontractor relationship handled via: `ticket_assignments → users → project_team → project_subcontractors`
- Migration: `20241116000001_remove_subcontractor_from_tickets.sql`

### Future Integrations
- **Expenses**: Track fuel, materials, transport costs
- **Inventory**: Assign equipment (ONT, cables, etc.)
- **Invoicing**: Generate contractor invoices
- **Assignments**: Full assignment history with GPS
- **Communication**: Customer contact attempts
- **Images**: Before/after photos for proof of work