FSM / Service (Mongo)
Document-shaped service domain. Owns tickets, jobs/visits, AMC, service partners, technicians. References Medusa orders and Warranty assets by ID + snapshot.
ServiceTicket
ServiceTicket {
_id: uuid
ticketNo: string // short ID (human)
tenantId: string
type: 'complaint'|'installation'|'amc_visit'|'repair'|'cross_vendor'
status: 'new'|'assigned'|'in_progress'|'on_hold'|'closed'|'cancelled'
channel: 'web'|'app'|'whatsapp'|'call'|'ivr'
customer: { id: string; name: string; phone: string } // snapshot
asset?: { id: string; serial?: string; productName?: string } // Warranty ref + snapshot
externalAsset?: ExternalAssetRef // cross-vendor case
issue: { description: string; media: string[] } // "what happened" + photos
invoiceRef?: string // Finance invoice id (paid service)
warrantyDecision?: { covered: boolean; basis: 'warranty'|'extended'|'amc'|'none'; payable?: number }
sla: { dueAt: Date; breached: boolean; escalations: Escalation[] }
region?: string // for scoping
assignedTechnicianId?: string
servicePartnerId?: string
createdAt: Date; updatedAt: Date
}
Job / Visit
Job {
_id: uuid
ticketId: uuid
technicianId: string
scheduledFor: Date
arrivedAt?: Date; completedAt?: Date
checklist: Array<{ item: string; done: boolean }>
partsUsed: Array<{ sparePartId: string; qty: number }> // → Inventory consume
media: string[] // photos/video (object storage keys)
signature?: string // customer sign-off (storage key)
timeSpentMins?: number; expenses?: number
outcome: 'resolved'|'follow_up'|'replace'|'escalate'
csat?: { rating: number; comment?: string }
offlineSyncedAt?: Date // set when synced from offline app
}
AMCContract
AMCContract {
_id: uuid
contractNo: string // short ID
customerId: string
assetIds: string[]
plan: 'comprehensive'|'non_comprehensive'
tier: string // pricing tier
startDate: Date; endDate: Date; years: number
visitsPlanned: Array<{ dueAt: Date; jobId?: string; status: 'pending'|'done'|'missed' }>
price: number; invoiceRef?: string
status: 'active'|'expired'|'cancelled'
renewalRemindersSent: number
}
ServicePartner (notes "service partners")
ServicePartner {
_id: uuid
name: string
type: 'franchise'|'authorized_3p'|'inhouse'
territories: string[]
skills: string[] // product families serviceable
technicianIds: string[]
rating?: number
status: 'active'|'suspended'
}
Technician
Technician {
_id: uuid
name: string; phone: string
servicePartnerId?: string // null = in-house
skills: string[]; zones: string[]
vanStockLocationId?: string // Inventory location
availability: 'available'|'busy'|'off'
lastKnownLocation?: { lat: number; lng: number; at: Date }
scorecard?: { jobs: number; avgCsat: number; slaHitRate: number }
}
ExternalAsset (cross-vendor)
ExternalAsset {
_id: uuid
customerId: string
brand: string // e.g. "Luminous" (not our brand)
productType: string // "solar panel"
issue: string // "cracked by ball impact"
paid: true // always paid service
}
Indexing & scoping
- Index on
tenantId,status,region,assignedTechnicianId,sla.dueAt. - All reads pass through the scoped query layer (RBAC) — region/partner scope injected.
Cross-store rules
- Money (invoices, paid-service charges) → Finance (PG); FSM stores only
invoiceRef. - Asset truth → Warranty (Mongo); FSM stores
assetsnapshot. - Parts consumption emits
job.close→ Inventory decrements stock.