docs/agent/implementation-notes/TICKET_MANAGEMENT_CHECKLIST.md

Ticket Management Implementation Checklist

✅ Phase 1: Ticket Creation (COMPLETED)

• Ticket model with PERMANENT deduplication strategy (timestamp-based, never cleared)
• Removed project_subcontractor_id (use assignments via project_team)
• Ticket schemas (create/update/response)
• Ticket service (create from sales_order/task)
• Ticket API endpoints (create, list, get, update, reschedule, cancel, stats)
• 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