drivers_bot/GAMIFICATION_PLAN.md

CarPass Gamification Plan

1. Goals

CarPass gamification is a trust and data-quality system, not a game layer. The product goal is to turn a casual vehicle diary into a premium digital vehicle passport that keeps owners returning because the data becomes more useful over time.

Primary goals:

• Increase retention by showing owners how each verified record improves the vehicle passport.
• Improve data quality for VIN, license plate, mileage, oil specs, service intervals, fuel consumption, and service history.
• Motivate owner confirmation of service visits and sensitive vehicle data changes.
• Encourage structured interaction between owners and verified service centers.
• Make the vehicle more resale-ready by building a reliable, private maintenance history.
• Give service centers a trust signal based on confirmed work, low dispute rates, and good operational hygiene.

Non-goals:

• No public leaderboards.
• No speed, harsh driving, racing, or mileage competition.
• No coins, gambling, loot boxes, streak pressure, or daily spam loops.
• No public comparison of users, vehicles, or service centers.

2. UX Philosophy

The experience should feel like a premium automotive SaaS product: calm, precise, and useful. The visual language should resemble a digital inspection report, ownership dashboard, and service-grade vehicle passport.

Principles:

• Use "quality", "verification", "health", and "trust" language instead of "points" or "levels".
• Show progress as professional indicators: rings, bars, badges, timelines, and status chips.
• Explain why each missing item matters: VIN improves identity confidence, full-tank fuel records improve consumption accuracy, confirmed service visits improve resale trust.
• Avoid shame. Use neutral states like "Needs data", "Partially verified", "Attention needed".
• Keep notifications sparse and high-signal.
• Make the owner feel in control. Service centers can propose, but owner confirmation decides trust.

3. Reward Types

Rewards are evidence markers, not currency.

Vehicle rewards:

• Profile Quality: percentage of important fields completed.
• Verified History Status: self-reported, partially verified, verified maintenance history.
• Maintenance Health: green, yellow, red based on overdue service and reminders.
• Passport Badges: durable achievements such as Full Vehicle Profile or First Verified Service.
• Timeline Milestones: service, fuel, verification, OBD, and ownership events.

Owner rewards:

• Garage Quality: average completion across active vehicles.
• Complete Garage: every active vehicle has identity, mileage, and maintenance baseline.
• Maintenance Consistency: regular data capture without aggressive streak language.

Service center rewards:

• Verified Service Center badge.
• Trust Level: new, verified, reliable, high-confidence.
• Confirmation Quality: owner confirmation rate, low dispute rate, completed visit quality.

4. Progression System

Progression is based on increasing confidence in the digital passport.

Vehicle Profile Completion:

• 0-30: Basic profile.
• 31-60: Useful ownership profile.
• 61-85: Strong maintenance profile.
• 86-100: High-confidence vehicle passport.

Verified History:

• Self-reported: owner-only records.
• Partially verified: at least one confirmed service-center visit or a mixed history.
• Verified maintenance history: most service history is confirmed by verified service centers.

Maintenance Health:

• Green: no overdue critical service reminders.
• Yellow: service due soon or incomplete maintenance baseline.
• Red: overdue service by date or mileage.

Service Trust:

• New service: verified account but low confirmed work volume.
• Verified service: documents checked.
• Reliable service: good confirmation rate and low dispute rate.
• High-confidence service: consistent confirmed work and low unresolved disputes.

5. User Engagement Loops

Owner loop:

1. Add vehicle.
2. See passport quality and missing items.
3. Add VIN/license plate/oil/mileage/fuel/service data.
4. Receive a clearer score and timeline.
5. Confirm service-center visits.
6. Build a trustworthy maintenance history.

Service loop:

1. Register service center.
2. Pass verification.
3. Invite employees.
4. Create service visits.
5. Owner confirms work.
6. Trust score improves through confirmed, low-dispute work.

OCR loop:

1. Scan VIN, plate, or document.
2. System extracts candidates.
3. User or employee confirms suggested values.
4. Sensitive changes become pending requests until owner approval.

Notification loop:

• Notify only for due maintenance, owner confirmation, important data quality milestones, and access requests.
• Never send daily streak pressure.

6. Vehicle Profile Completion

Each vehicle gets completeness_score from 0 to 100.

Suggested scoring weights:

• Vehicle exists and has owner access: 5.
• Make/model/year/name baseline: 15.
• VIN: 15.
• License plate with country: 10.
• Current odometer: 10.
• Fuel type and consumption baseline: 10.
• Engine oil type and volume: 10.
• Transmission/coolant/brake fluid fields: 5.
• At least one fuel entry: 5.
• At least one service entry or service visit: 5.
• At least one confirmed service-center visit: 10.
• Future OBD connection: 10.

The score is capped at 100. The API should also return missing_items with practical next actions.

7. Verified Maintenance History

Verified history score measures how trustworthy the service history is.

Inputs:

• Total service records.
• Confirmed service-center visits.
• Whether the service center is verified.
• Disputed/rejected/cancelled visits.
• Owner-created self-reported records.

Statuses:

• self_reported: no confirmed service-center visits.
• partially_verified: at least one confirmed service visit or 30-79% trusted records.
• verified: 80%+ trusted records and no unresolved disputes.

Sensitive rule:

• OCR or service-center input can suggest values, but it cannot automatically make history trusted without owner confirmation.

8. Service Center Trust Mechanics

Trust score is operational quality, not a public star rating.

Inputs:

• Verification status.
• Confirmed visit count.
• Owner confirmation rate.
• Dispute rate.
• Rejected/cancelled visit rate.
• Employee hygiene: disabled employees, unresolved disputes, suspicious lookup patterns.

Display:

• New service.
• Verified service.
• Reliable service.
• High-confidence service.

Avoid:

• Public numeric ranking.
• Punitive public labels.
• One-click toxic ratings.

9. Anti-Abuse Rules

Achievements:

• Unlock once per user or once per vehicle depending on scope.
• Use unique constraints to prevent duplicate unlocks.
• Do not unlock from deleted or disputed records.

Scoring:

• Ignore duplicate low-quality records created in a short time window.
• Require valid owner access for vehicle score APIs.
• Require confirmed visits for verified-history credit.
• Require verified service-center status for high trust credit.

Search and OCR:

• Rate-limit VIN/license plate search and OCR later.
• Return masked/minimal search results.
• Log lookups in AuditLog or EngagementEvent.

Deletion:

• Owner cannot erase service-center history without trace.
• Use dispute, rejected, hidden, or cancelled status plus audit trail.

10. Notification Strategy

Notification types:

• Maintenance due soon.
• Maintenance overdue.
• Service visit pending owner confirmation.
• Vehicle data change request pending.
• Profile completion milestone: 50%, 80%, 100%.
• First verified service confirmed.

Rules:

• No daily streak reminders.
• No more than one non-critical nudge per vehicle per week.
• Critical maintenance alerts can repeat with conservative cooldown.
• Owner controls notification preferences.
• Notifications must be actionable and quiet.

11. Privacy Considerations

• No public leaderboard.
• No sharing of Telegram ID, phone, VIN, full plate, or service history without consent.
• Service-center search returns masked VIN/plate and minimal vehicle identity.
• Owner controls access duration and revocation.
• Scores are private by default.
• Service trust shown to owners should be aggregate and non-invasive.

12. Database Changes

New tables:

• achievements

  • id
  • code
  • scope: user / vehicle / service_center
  • title
  • description
  • icon
  • category
  • is_active
  • created_at

• user_achievements

  • id
  • user_id
  • achievement_id
  • vehicle_id
  • service_center_id
  • unlocked_at
  • metadata_json

• vehicle_scores

  • id
  • vehicle_id
  • completeness_score
  • verified_history_score
  • maintenance_health_score
  • maintenance_status
  • profile_quality
  • verified_history_status
  • missing_items
  • computed_at

• service_center_scores

  • id
  • service_center_id
  • trust_score
  • trust_level
  • confirmed_visits_count
  • confirmation_rate
  • dispute_rate
  • computed_at

• engagement_events

  • id
  • user_id
  • vehicle_id
  • service_center_id
  • event_type
  • metadata_json
  • created_at

Indexes:

• achievements.code unique.
• user_achievements(user_id, achievement_id, vehicle_id, service_center_id) unique.
• vehicle_scores.vehicle_id unique.
• service_center_scores.service_center_id unique.
• engagement_events(user_id, event_type, created_at).
• engagement_events(vehicle_id, event_type, created_at).

13. API Changes

Owner APIs:

• GET /api/me/achievements
• GET /api/my/vehicles/{vehicle_id}/score
• GET /api/my/vehicles/{vehicle_id}/timeline

Service APIs:

• GET /api/service-centers/{service_center_id}/trust-score

Internal scoring APIs, optional later:

• POST /api/internal/scoring/recompute
• POST /api/internal/achievements/evaluate

Response principles:

• Return computed scores from backend.
• Return missing items and human-readable next actions.
• Never trust user_id from request body.
• Every vehicle endpoint uses current_user and vehicle access checks.

14. Frontend UI Changes

Replace the simple "Профиль учета" strip with a premium passport dashboard:

• Vehicle Passport Quality card with progress ring.
• Verified History card with status and trusted record ratio.
• Maintenance Health widget with green/yellow/red status.
• "Что улучшить" list with 2-4 next actions.
• Achievement cards in calm SaaS style.
• Vehicle timeline with fuel, service, confirmation, OCR, OBD, and achievements.
• Service trust badge in service-center screens.
• Garage overview with average completion and active alerts.

Style:

• Dark premium automotive UI.
• Calm contrast, thin borders, glass/dark panels used sparingly.
• No arcade language, no coin counters, no animated confetti.

15. Future Extensibility

Future modules should plug into the scoring engine without rewriting frontend:

• OBD2: connected vehicle badge, automatic mileage, battery monitoring.
• Insurance: verified maintenance packet for insurance offers.
• Resale: exportable CarPass report.
• Predictive maintenance: service recommendations based on mileage/time/fuel/OBD.
• AI assistant: explain score changes and suggest next best action.
• Service recommendations: based on vehicle type, overdue work, and trusted service access.

Implementation Phases

Phase 1:

• Add backend models and migration.
• Add scoring engine.
• Add achievement engine.
• Add score, achievements, timeline, and trust-score APIs.
• Add focused tests.

Phase 2:

• Replace frontend progress strip with backend-driven widgets.
• Add achievements and timeline UI.
• Keep old MVP data flows intact.

Phase 3:

• Add smart notification events and cooldown-ready schema.
• Expand trust score for service centers.
• Add service-center-facing gamification signals.

Phase 4:

• Add engagement analytics and anti-abuse refinements.
• Optimize queries and add recomputation jobs.
• Prepare production deployment checklist.