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:

```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.