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.