Add CarPass gamification scoring foundation

GAMIFICATION_PLAN.md

@@ -0,0 +1,389 @@
+# 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.