# 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: ```json { "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.