drivers_bot/docs/production_pilot_entity_map.md

CarPass Production Pilot Entity Map

This map captures the closed-pilot domain model as implemented in the codebase.

Owner Domain

• User owns Car records and authenticates through Telegram.
• Car is the vehicle/passport entity. It owns FuelEntry, ServiceEntry, ExpenseEntry, OdometerHistory, CarServiceLink, ServiceAppointment, ServiceVisit, and MaintenanceRecommendation.
• FuelEntry, ServiceEntry, and ExpenseEntry update ownership analytics and can update the vehicle odometer through OdometerHistory.
• OwnershipAnalytics is computed on demand from entries, expenses, depreciation settings, and loan settings.
• VehicleAccess grants non-owner user access to a vehicle for selected backend flows.

STO Domain

• ServiceCenter is the STO profile and tenant boundary.
• ServiceCenterVerification stores moderation applications and review decisions.
• ServiceEmployee links users to a service center with one of owner, manager, receptionist, or mechanic.
• CarServiceLink is the owner-approved connection between a vehicle and an STO.
• ServiceCenterBookingSettings and ServiceCenterHoliday define the appointment calendar.
• ServiceAppointment is the customer booking request and can become one ServiceVisit.
• ServiceCenterReview and ServiceCenterReviewComment store public feedback.

Work Order Domain

• ServiceVisit is the work order. It links ServiceCenter, Car, owner user, employee, appointment, labor items, product items, status history, and corrections.
• ServiceWorkItem stores labor/repair work and next-service intervals.
• ServiceProductItem stores parts, fluids, materials, SKU and quantity.
• WorkOrderCatalogItem is the STO price/catalog item source.
• InventoryTransaction records consumed products on work-order completion.
• WorkOrderStatusHistory audits status transitions.
• WorkOrderCorrection records post-completion correction requests and owner decisions.
• Completion creates immutable owner records: ServiceEntry, ExpenseEntry, OdometerHistory, MaintenanceRecommendation when applicable, ServiceNotification, and AuditLog.

Trust, Notifications, And Exchange

• MaintenanceRecommendation is connected to a vehicle and optionally a service center/appointment.
• ServiceNotification is the internal notification queue with best-effort Telegram delivery and idempotency keys.
• AuditLog records sensitive and operational actions.
• Achievement, UserAchievement, VehicleScore, ServiceCenterScore, and EngagementEvent power passport quality, trust, and timeline features.
• Import/export is synchronous API work, not a persisted ImportExportJob; schema is carpass.exchange.v1.
• OCR returns preview candidates through API responses; no persisted OCRResult table exists and OCR never writes vehicle data directly.

Pilot Gaps To Keep Explicit

• Browser Web Push stores subscriptions and has a service worker listener, but server-side Web Push delivery is beta and not part of the pilot-critical notification path.
• Inventory exists as consumption transactions and catalog products, not as full stock-level management.
• Correction requests record decisions; they do not mutate completed work-order snapshots automatically.