drivers_bot/PROJECT_PLAN.md

Drivers Bot Platform Plan

1. Current Architecture Summary

• FastAPI serves JSON API and static Telegram Mini App files from web/.
• aiogram bot opens the Mini App with WEBAPP_URL and talks to the API through INTERNAL_API_TOKEN.
• Users are Telegram-backed; user API access is based on verified Telegram WebApp initData.
• Current domain model covers personal garage use: users, cars, fuel_entries, service_entries, catalog tables, push subscriptions, service center stubs, and inbox messages.
• Existing MVP must remain compatible: personal cars, fuel logs, service logs, reminders, stats, catalog, OCR text parsing, bot start/cars/add_car flows.

2. Target Product Model

Drivers Bot evolves from a personal car diary into a controlled multi-sided platform:

• Vehicle owners manage cars and personal expense/service history.
• Verified service centers create service visits and work items for vehicles.
• Owners control access to vehicles and confirm sensitive changes.
• Service centers are tenants: employees can only see their own service center data and vehicle data for granted access or active visits.
• Moderators/admins verify service centers, inspect disputes, and audit platform actions.

Open product decisions:

• Whether verified service centers can create temporary vehicle records before owner claim. Initial implementation allows service visits only when vehicle exists or owner grants access; temporary cards are deferred to avoid ownership fraud.
• Whether service_entries and service_visits should be merged. Initial implementation keeps existing service_entries for MVP and adds service_visits/work_items as the platform layer.

3. UX/UI Flows

Owner flows:

1. Create/edit vehicle manually with make, model, year, plate, VIN, odometer, oil data, and service norms.
2. Open "Connected services" and grant/revoke service access using invite/access code or request from service center.
3. See service history from personal entries and service-center visits.
4. Receive confirmation requests for service visits and critical vehicle changes.
5. Confirm, dispute, reject, or hide sensitive details.

Service center flows:

1. Create service profile.
2. Submit verification details/documents.
3. After verification, invite employees.
4. Employee starts a visit, searches/scans plate/VIN, requests access if needed, then adds work items.
5. Manager/owner completes visit, moving it to owner confirmation.

Admin/moderator flows:

1. Review pending service centers.
2. Approve/reject/suspend service centers.
3. Inspect audit log, disputes, and suspicious searches.

4. Roles And Permissions

Platform roles:

• user: owns/drives/views vehicles according to vehicle_access.
• service_owner: owns a service center, manages verification and employees.
• service_employee: works inside one service center.
• verifier / moderator: reviews verification and disputes.
• admin: full moderation and platform operations.

Service employee roles:

• receptionist: create visits and access requests.
• mechanic: add work items and recommendations.
• manager: complete visits and manage employees.
• owner: manage center, employees, and verification.

Permission rule: backend checks every endpoint with current_user; frontend permissions are only UX hints.

5. Data Access Rules

• Owners can see and modify their active vehicles and personal logs.
• A service center can see only:
  • its own profile, employees, verification requests, visits;
  • minimal masked vehicle data during access request;
  • visit details for vehicles with active access or active visit.
• Plate/VIN search must not reveal owner identity, Telegram ID, phone, full expense history, or sensitive attributes.
• user_id from request body is not trusted.
• vehicle_id access requires owner role, active VehicleAccess, or a service visit scoped to the service center.

6. Anti-Fraud Model

• No automatic ownership claim by VIN/license plate.
• VIN and license plate are normalized; VIN is unique when present.
• License plate uniqueness is scoped by country.
• Plate/VIN changes create audit and may create VehicleDataChangeRequest.
• Service-created visits are not trusted until owner confirmation.
• Critical fields requiring owner approval: VIN, license plate, odometer, oil type/volume, service norms, engine parameters.
• Service center actions are auditable and cannot be hard-deleted.
• Rate limiting for plate/VIN/OCR/access requests is required before broad public launch. Initial implementation logs searches/actions; hard rate limit can be added via middleware/Redis.

7. Database Changes

Extend cars as Vehicle-compatible table:

• license_plate_display
• license_plate_normalized
• license_plate_country
• vin_normalized
• unique vin_normalized when not null
• unique (license_plate_country, license_plate_normalized) when not null

New tables:

• vehicle_access
• service_center_verifications
• service_employees
• service_visits
• service_work_items
• vehicle_data_change_requests
• audit_logs

Existing tables kept:

• service_entries remain the personal/MVP service diary.
• service_centers is expanded instead of replaced.

8. API Design

Owner API:

• GET /api/me
• GET /api/my/vehicles
• POST /api/my/vehicles
• PATCH /api/my/vehicles/{vehicle_id}
• GET /api/my/vehicles/{vehicle_id}/service-history
• POST /api/my/vehicles/{vehicle_id}/grant-service-access
• POST /api/service-visits/{visit_id}/confirm
• POST /api/service-visits/{visit_id}/dispute
• POST /api/vehicle-change-requests/{id}/approve
• POST /api/vehicle-change-requests/{id}/reject

Service API:

• POST /api/service-centers
• GET /api/service-centers/my
• POST /api/service-centers/{id}/verification
• POST /api/service-centers/{id}/employees/invite
• GET /api/service-centers/{id}/visits
• POST /api/service-centers/{id}/visits
• POST /api/service-visits/{id}/work-items
• POST /api/service-visits/{id}/complete
• POST /api/service-centers/{id}/vehicle-access/request

Admin API:

• GET /api/admin/service-centers/pending
• POST /api/admin/service-centers/{id}/verify
• POST /api/admin/service-centers/{id}/reject
• POST /api/admin/service-centers/{id}/suspend
• GET /api/admin/audit-log
• GET /api/admin/disputes

9. OCR Design

OCR is provider-based:

• OCRProvider interface.
• StubOCRProvider default: extracts candidates from text/file name and never claims real image OCR.
• Future: TesseractOCRProvider, cloud OCR, or VLM provider.

OCR response:

{
  "recognized_text": "...",
  "candidates": [
    {"type": "license_plate", "value": "...", "confidence": 0.91}
  ]
}

OCR endpoints create suggestions only. They must not update vehicle data directly.

10. Migration Plan

1. Add nullable columns and new tables with conservative constraints.
2. Backfill current cars.plate_number/cars.vin into display/normalized columns where valid.
3. Create owner vehicle_access rows for existing cars.owner_id.
4. Add unique indexes for VIN and country/plate.
5. Keep existing endpoints compatible while new /api/my/* and service-center endpoints roll out.

11. Test Plan

Backend:

• VIN normalization/validation.
• Plate normalization.
• Owner cannot claim another vehicle by VIN/plate.
• Service employee cannot see another service center data.
• Unverified service center cannot complete trusted visits.
• Owner confirmation changes visit status.
• Critical data change request approve/reject updates only after owner action.
• OCR endpoint returns candidates without writing data.
• Existing fuel/service/reminders tests remain green.

Manual:

• Telegram Mini App opens with local test bot.
• Existing garage/fuel/service flows still work.
• Direct browser page shows Telegram-only message unless dev auth enabled.

12. Implementation Phases

Phase 1:

• Expand models and migrations.
• Add permission helpers.
• Add basic service center create/my/verification/employee flow.

Phase 2:

• Add vehicle identity fields, ownership/access model.
• Add service visits/work items.
• Add owner confirmation and vehicle data change requests.

Phase 3:

• Add OCR provider interface and license plate/VIN/service document endpoints.
• Add lightweight frontend sections for service center panel, visits, confirmations, OCR.
• Add admin moderation endpoints.

Phase 4:

• Add tests, README, .env.example.
• Run Docker compose, Alembic, API health, bot startup with local test token.
• Keep production deploy separate unless explicitly requested.