Hugging Face's logo

Spaces:
kamau1
/
swiftops-backend
Sleeping

App Files Community
swiftops-backend
File size: 5,169 Bytes
38ac151
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
# 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