Add service platform foundation
This commit is contained in:
VPN SaaS Dev
226
PROJECT_PLAN.md
Normal file
226
PROJECT_PLAN.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user