fix(login): обратный отсчёт кода + возврат на оплату после входа

Жалоба: по ссылке на оплату жмёшь «получить код» — «слишком часто».
- на шаге кода кнопка «отправить ещё раз» с отсчётом (60с, синхронно с
  бэкендом); на 429 ведём отсчёт по Retry-After и не пугаем
- кнопка «Получить код» блокируется на время кулдауна
- RequireAuth запоминает путь (ссылку на оплату); после входа по коду и
  через Telegram возвращаем туда, а не на баланс

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitignore

@@ -38,3 +38,4 @@ Thumbs.db
 # IDE
 .idea/
 .vscode/
+.superpowers/

README.md

@@ -40,7 +40,7 @@ mechanic-pwa/                                  ← корень git репо
 └── README.md
 ```
 
-> **Внимание:** backend-модуль `mechanic` (Phase B-F плана) живёт **не в этом репо**, а в виде ветки `feat/mechanic-mvp` внутри репозитория `taxi-dashboard` (Premium CRM). Этот репо — только frontend + специфика, документация и ops.
+> **Внимание:** backend-модуль `mechanic` (Phase B-F плана) живёт **не в этом репо**, а в виде ветки `feat/mechanic-mvp` внутри репозитория [`premium-crm`](http://100.64.0.9:3001/tremble7681/premium-crm). Этот репо — только frontend + специфика, документация и ops.
 
 ## Текущая фаза
 

docs/backend-layout-notes.md

@@ -0,0 +1,50 @@
+# TaxiDashboard backend — найденные пути для модуля `mechanic`
+
+Записано по результатам Task A1 (recon существующего кода `c:\NewProject\taxi-dashboard\backend\app\`).
+
+## Корень backend
+
+`/opt/sites/taxi-dashboard/backend/app/` (на VDS)
+`c:\NewProject\taxi-dashboard\backend\app\` (локально)
+
+## Импорты для нового модуля `mechanic`
+
+```python
+from app.models.base import Base, TimestampMixin       # SQLAlchemy declarative + created_at/updated_at
+from app.db import get_db, async_session, engine       # async session factory + dependency
+from app.auth.deps import get_current_user             # OAuth2 Bearer JWT
+from app.models.user import User                       # User модель
+```
+
+## Auth
+
+- **OAuth2 Password Flow + Bearer JWT** (не PIN, как я ошибочно писал в спеке).
+- Логин: `POST /v1/auth/login` (или похожий, нужно найти в `app/api/auth.py`) с form-data `username` + `password` → возвращает `{ "access_token": "...", "token_type": "bearer" }`.
+- Дальнейшие запросы: header `Authorization: Bearer <token>`.
+
+## Naming clash + решение
+
+В TaxiDashboard уже есть модуль `app.api.inspections` (читает данные **CarInspection**, импортированные от вендора NaughtySoft через VendorBridge) под префиксом `/v2/inspections`.
+
+Чтобы не конфликтовать:
+- Наш новый модуль: `app/api/mechanic.py` (или `app/mechanic/router.py` как подмодуль) — префикс `/api/v1/mechanic`
+- Наши новые таблицы:
+  - `mechanic_inspections` (наша запись осмотров через PWA)
+  - `mechanic_inspection_photos`
+  - `mechanic_damage_markers`
+- Наши новые модели:
+  - `app/models/mechanic_inspection.py` — `MechanicInspection`
+  - `app/models/mechanic_inspection_photo.py` — `MechanicInspectionPhoto`
+  - `app/models/mechanic_damage_marker.py` — `MechanicDamageMarker`
+
+Существующие `CarInspection`, `car_inspections`, `inspection_failed_photo` — **не трогаем**. Они продолжают жить read-only от VendorBridge.
+
+## Существующий стек
+
+- Python 3.x + FastAPI + SQLAlchemy 2.x async
+- PostgreSQL (видна migration via Alembic — папку проверим в первом backend-task)
+- Frontend: `c:\NewProject\taxi-dashboard\frontend\` (React, существующий — НЕ наш target)
+
+## Vehicle model
+
+В existing `CarInspection` авто указывается через `car_number: String(100)`. Возможно есть отдельная модель `Car` в `app/models/car_v2.py` (видел в импортах). Проверим в backend task B2 при создании FK.

docs/superpowers/STATE.md

@@ -0,0 +1,384 @@
+# Premium Mechanic PWA — Implementation State
+
+> Last updated: 2026-05-17 (Phase 1 MVP LIVE IN PRODUCTION)
+
+## Status: 🟢 **DEPLOYED — Phase 1 MVP LIVE on https://mechanic.pptaxi.ru**
+
+All 4 deployment phases executed successfully:
+
+- ✅ **J1 Backend**: `git push vds feat/mechanic-mvp` → checkout on VDS → `docker build` → rolling restart blue+green → healthz 5/5 green on `https://crm.pptaxi.ru/api/v1/mechanic/healthz`
+- ✅ **J2 Frontend**: `scp dist/` → VDS at `/opt/sites/mechanic-pwa/dist/` (448K) → added Caddy block + bind mount → `docker compose up -d --force-recreate caddy` → Let's Encrypt cert auto-issued → HTTPS 200 on `https://mechanic.pptaxi.ru/`
+- ✅ **J3a Merge**: `feat/mechanic-mvp` → `main` (ff-only) in BOTH repos, pushed to Gitea + VDS
+- ✅ **J3b Prod sync**: VDS now on `main` branch, healthz still green
+
+**Smoke checks passed:**
+| Check | Result |
+|---|---|
+| `GET https://mechanic.pptaxi.ru/` | 200 OK, text/html, served from SPA |
+| `GET /manifest.webmanifest` | JSON with `"name": "Premium Механик"` |
+| `GET /api/v1/mechanic/healthz` (via mechanic.pptaxi.ru) | `{"status":"ok"}` |
+| `GET /api/v1/mechanic/me` (no auth) | 401 |
+| `GET /api/v1/mechanic/vehicles` (no auth) | 401 |
+| `GET /icons/icon-192.png` | 200 image/png, 2326 bytes |
+| `GET /sw.js` (service worker) | 200 text/javascript |
+| `GET /vehicles/12345` (SPA route) | 200 text/html (index.html fallback) |
+| `crm.pptaxi.ru/api/v1/mechanic/healthz` x5 | 5/5 ok (both blue+green serving) |
+
+**Remaining manual smoke (mobile, J3 step 8):** open `https://mechanic.pptaxi.ru` on Android Chrome / iOS Safari, login with test mechanic account, create inspection, snap photo, verify MinIO upload + thumbnail appears, verify "Add to Home Screen" works. *Not automated — you'll do that on a phone.*
+
+## What is done
+
+| Phase | Task | Status | Artifact |
+|---|---|---|---|
+| 0 | Git infrastructure (Gitea + repos + feature branches) | ✅ DONE | repos exist, ssh keys configured |
+| A | A1: Recon TaxiDashboard backend structure | ✅ DONE | `docs/backend-layout-notes.md` |
+| A | A2: Caddy fragment for `mechanic.pptaxi.ru` | ✅ DONE | `ops/Caddyfile.fragment` |
+| A | A3: MinIO CORS on `pp-inspections` bucket | ✅ DONE | `ops/set-minio-cors.sh`, applied, preflight 204 |
+| A | A4: SQLAlchemy models (`MechanicInspection`, `MechanicInspectionPhoto`, `MechanicDamageMarker`) | ✅ DONE | commit `be0553e` on `feat/mechanic-mvp` |
+| B | B1: Mechanic module skeleton + `/healthz` | ✅ DONE | commit `d2113a0` — flat `backend/app/api/mechanic.py` with `APIRouter(prefix="/v1/mechanic")`, registered in `app/main.py` with `prefix="/api"` → final URL `/api/v1/mechanic/healthz` |
+| B | B2: SQLAlchemy models registered + tests | ✅ DONE | **already shipped in A4** (`be0553e`) — 38 metadata tests in `backend/tests/test_mechanic_models.py`, no extra B2 commit |
+| B | B3: Pydantic schemas | ✅ DONE | commit `2739cc8` + fix `2fb978d` — 14 schemas + 6 Literals in `backend/app/api/mechanic_schemas.py`, 15 behavioral tests in `backend/tests/test_mechanic_schemas.py`; fix added `= None` defaults to `Optional[X]` fields and tightened `MarkerOut.damage_type`/`severity` to `DamageType`/`Severity` Literals |
+| B | B4: Auth + DB session dependencies | ✅ DONE | commit `f0d7e83` — `backend/app/api/mechanic_deps.py` re-exports `get_db`+`get_current_user`, adds `require_mechanic` guard (admin OR member of any active `dept_type='svc'` department); 9 tests in `backend/tests/test_mechanic_deps.py` use fake-DB stubs (no real session needed)
+| C | C1: `GET /me` endpoint | ✅ DONE | commit `a0bdcaa` + signature fix `1e5b822` — appended to `backend/app/api/mechanic.py`; returns `MeOut` from `require_mechanic` user; `permissions` is `["admin", "mechanic:inspect"]` for admins else `["mechanic:inspect"]`. Test fixtures (`client`, `override_mechanic`, `_fake_user`) in `backend/tests/test_mechanic_endpoints.py` use FastAPI `TestClient` + `app.dependency_overrides` per Option A — no real DB / no async. 6 endpoint tests. |
+| C | C2: `GET /vehicles` list with `q`+`limit` search | ✅ DONE | commit `7be8783` — new `backend/app/api/mechanic_service.py` with `search_vehicles_with_last_inspection` (single aggregated subquery + outerjoin to avoid N+1 for last completed inspection per vehicle); endpoint in `mechanic.py`; new `VehicleListResponse` schema; 8 tests (6 endpoint + 2 service-stmt) with `_FakeSession.execute()` returning canned rows. Search hits plate (`CarV2.number`) + VIN only. |
+| C | C3: `GET /vehicles/{id}` detail + bound /vehicles limit | ✅ DONE | commit `9109383` + style fix `90b8c66` — new `VehicleDetail(VehicleSummary)` + `InspectionSummary(_Base)` schemas; service `get_vehicle_by_id` + `recent_mechanic_inspections`; endpoint raises 404 when missing, `last_inspection_at` derived from first completed inspection in the list; applied `Query(20, ge=1, le=200)` bounds to C2's `/vehicles` limit param. 7 new tests (5 detail + 2 bounds). Service is now FastAPI-free (404 raise lives in endpoint, matching `automations.py` convention). |
+| D-pre | B3 schemas widened from vendor recon (`a187a92`) | ✅ DONE | After read-only recon of `car_inspections` (14k rows, 2yr): `InspectionType` extended 4→9 (added `initial`, `seizure`, `equipment-change`, `pre-repair`, `post-repair`); `DamageType` fully replaced 7→16 (removed `rust`/`glass`/`paint` which had 0 vendor occurrences; added real-world types from vendor distribution: `damaged`, `chip`, `scuff`, `burn`, `bent`, `puncture`, `bulge`, `not-working`, etc.). `Severity` unchanged (4 values, optional — vendor populates only 3%). 2 new positive-coverage tests. Stale comment in `mechanic_damage_marker.py:54` references old DamageType values — fix in Phase F when touching that model. |
+| D | D1: `POST /inspections` with inline carry-over markers | ✅ DONE | commits `39a6579` + correctness fix `ee3d370` — service `start_inspection` + `latest_completed_inspection` (with `NULLS LAST` ordering); endpoint returns 201 with full InspectionDetail via re-query with `selectinload(photos, markers)`. Carry-over: copies all **unresolved** markers from prev completed inspection (`resolved=False` filter — closed defects don't reopen), each new marker has `carried_over_from_id=source.id`, `photo_id=None`, `resolved=False`. `_FakeSession` extended with `add`/`flush`/`commit`/`refresh` write-path methods + `rows_per_call` queue for multi-SELECT service flows. 9 new tests (6 endpoint + 3 service). |
+| D | D2: `GET /inspections/{id}` with photos+markers | ✅ DONE | commit `1776a81` — service `get_inspection_by_id_with_relations` (selectinload both relationships, `scalar_one_or_none`); endpoint raises 404 with `"inspection not found"` parallel to vehicle's 404. D1's inline re-query block refactored to call the same helper (DRY). 6 new tests (4 endpoint + 2 service introspecting `stmt._with_options`). |
+| D | D3: `PATCH /inspections/{id}` status/notes/finished_at | ✅ DONE | commit `aefe117` — service `get_inspection_by_id` (thin `session.get` wrapper) + `patch_inspection` (auto-sets `finished_at=now(UTC)` when status→completed AND finished_at not in payload; `setattr` loop applies all `model_dump(exclude_unset=True)` fields). Endpoint re-loads via `get_inspection_by_id_with_relations` for the response. 8 new tests (6 endpoint + 2 service). Endpoint and service both named `patch_inspection` — disambiguated by module path in code, by `as svc_patch` alias in tests. |
+| D | Housekeeping: extract test fakes to `mechanic_fakes.py` | ✅ DONE | commit `eedbf23` — pure refactor. Moved `_FakeResult`, `_FakeSession`, `_fake_user`, `_fake_car`, `_fake_inspection`, `_fake_inspection_orm`, `_fake_marker_orm` from `test_mechanic_endpoints.py` (was 899 lines) to new `backend/tests/mechanic_fakes.py` (207 lines). Test file dropped to 697 lines. Pytest fixtures (`client`, `override_mechanic`, `override_db`) stayed in the test file. Phase E tests will import from `mechanic_fakes` directly. |
+| E | E1: MinIO async presigned PUT URL wrapper | ✅ DONE | commit `fe38981` — added `presigned_put_url(bucket, key, *, content_type, expires_sec=300)` to `app/services/storage.py`; `PresignedUploadResponse.fields` defaults to `{}`; 3 storage tests. |
+| E | E2: `POST /inspections/{id}/photos/upload-url` | ✅ DONE | commit `111661b` — service `create_pending_photo` + `_storage_key_for_photo` helper in `mechanic_service.py`; endpoint in `mechanic.py` with 415-before-404 guard; UUID4 hex storage keys at `mechanic/inspections/{id}/<uuid>.<ext>`; 9 new tests (7 endpoint + 2 service). |
+| E | E3: `POST /photos/{id}/confirm` | ✅ DONE | commit `724b209` — service `get_photo_by_id` + `confirm_photo` (None-safe dim update, status→ready); endpoint verifies `storage.exists`, 409 if missing, 404 covers both photo-missing and inspection-mismatch; 9 new tests (7 endpoint + 2 service). `_fake_photo_orm` factory added to `mechanic_fakes.py`. |
+| E | E4: `GET /photos/{id}` + `/thumb` (302 redirect) | ✅ DONE | commit `8361ee1` — auth-guarded 302 to presigned MinIO GET URLs (1h expiry). Thumb endpoint falls back to `storage_key` when `thumb_key is None` so galleries degrade gracefully if E5 task hasn't run yet. 8 endpoint tests. |
+| E | E5: async thumbnail generation | ✅ DONE | commit `b37a068` — `generate_and_store_thumbnail` worker (download → Pillow resize to 480px → upload → DB update) with try/except at each step (failures logged, return None, never crashes event loop). Triggered via `asyncio.create_task` from E3 confirm endpoint. `_thumb_key_for` predictable naming (`<key-base>-thumb.jpg`). `pillow_heif.register_heif_opener()` wrapped in try/except for dev-env tolerance. 6 new tests (5 storage unit + 1 endpoint trigger). |
+| F | F1+F2: markers CRUD (POST/PATCH/DELETE) | ✅ DONE | commit `7275a23` — 3 endpoints (`POST /inspections/{id}/markers`, `PATCH /markers/{id}`, `DELETE /markers/{id}`). Service helpers `get_marker_by_id`/`create_marker`/`patch_marker`/`delete_marker`. Stale comment in `mechanic_damage_marker.py:54` fixed. `_FakeSession.delete()` added; `_FakeSession.refresh()` auto-sets `created_at` for server-default fields. 15 new tests. **159 mechanic tests total. Backend Phase 1 MVP feature-complete.** |
+| G | G1-G5: Vite + React + TS + Tailwind + shadcn + PWA scaffold | ✅ DONE | commit `e815955` in `PremiumDriverApp/mechanic-pwa/frontend/` — 38 files, 8973 insertions. React 19 + Vite 8 + Tailwind v3 + TS strict + shadcn/ui (manually written to bypass broken @shadcn 4.7 "base-nova" style) + vite-plugin-pwa v1.3 (auto-bumped from v0.20 for Vite 8 compat). Service worker (`sw.js` + workbox, 10 precached entries). Cream palette (CSS vars from memory `feedback_design_prefs`). API client (ky) + auth store (zustand persist). 5 stub pages. **Build: 91 KB gzip JS, 0 warnings.** |
+| H | H1-H3: Login + Home + VehicleCard pages | ✅ DONE | commit `537548d` — Login uses OAuth2 password flow (form-urlencoded) against `/api/auth/login` (NOT mechanic-prefixed). Home shows vehicle list with search + logout + `/me` fetch. VehicleCard has all 9 inspection-type buttons (top 4 primary, rest outline). Russian locale dates. Semantic Tailwind tokens throughout (no hex). **Build: 110 KB gzip JS.** |
+| I | I1-I3: photo capture/upload infra | ✅ DONE | commit `fc4060d` — `api/photos.ts` with presigned PUT pattern (not POST/FormData per plan), `confirmPhoto(inspection_id, photo_id, meta)` with both IDs in path per E3 backend. `AuthImg` component (fetches with Bearer JWT → blob URL → `<img>`) solving the `<img>`-can't-send-Authorization problem. `CameraCapture` uses `<input type="file" capture="environment">` for max compat. `PhotoSlot` combines them. |
+| I | I4-I6: VehicleScheme + InspectionEditor + InspectionReview | ✅ DONE | commit `a428395` — `sedan-top.svg` (top-view with 7 transparent zone rects), `VehicleScheme.tsx` with click+hover handlers + point-marker overlays + zone-count badges. `inspections.ts` typed with `PhotoSummary`/`MarkerSummary`. Editor wires scheme + 8 photo slots + marker list + finalize button (gated on `status==="in_progress"`); zone tap creates marker with `damage_type="damaged"`/`severity="minor"`. Review is read-only with AuthImg thumb grid. **Build: 113 KB gzip JS. Frontend Phase 1 MVP feature-complete.** |
+
+**Branch state:** `feat/mechanic-mvp` at `b37a068`. Full stack: A4 → B1 → B3 + fix → B4 → C1 + fix → C2 → C3 + fix → B3-vendor-align → D1 + fix → D2 → D3 → test-refactor → E1 → E2 → E3 → E4 → E5. All pushed to `origin` (Gitea). See git log for full SHAs.
+
+**Test count on branch:** **144 mechanic tests pass** (38 models + 17 schemas + 9 deps + 9 storage + 71 endpoints) in ~2.5s, no real DB needed. Pillow image-resize tests use real PIL in-memory (verify JPEG magic header + dimensions); thumbnail task end-to-end uses mocked I/O.
+
+**Live mechanic API surface (11 routes):**
+- `GET /api/v1/mechanic/healthz`
+- `GET /api/v1/mechanic/me`
+- `GET /api/v1/mechanic/vehicles?q=&limit=`
+- `GET /api/v1/mechanic/vehicles/{vehicle_id}`
+- `POST /api/v1/mechanic/inspections` — create with carry-over for type=return
+- `GET /api/v1/mechanic/inspections/{inspection_id}` — full detail with photos+markers
+- `PATCH /api/v1/mechanic/inspections/{inspection_id}` — partial update + auto finished_at
+- `POST /api/v1/mechanic/inspections/{inspection_id}/photos/upload-url` — create pending photo row + presigned PUT URL (5min expiry)
+- `POST /api/v1/mechanic/inspections/{inspection_id}/photos/{photo_id}/confirm` — verify upload, mark ready, schedule thumbnail task
+- `GET /api/v1/mechanic/photos/{photo_id}` — auth-guarded 302 to presigned GET (1h)
+- `GET /api/v1/mechanic/photos/{photo_id}/thumb` — same with thumb_key, falls back to original
+
+### Phase E architecture decisions (RESOLVED 2026-05-17)
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Upload pattern | PUT (single presigned URL) not POST/FormData | Simpler PWA code: `fetch(url, {method:'PUT', body:blob})`. `PresignedUploadResponse.fields` defaults to `{}` for future POST migration. |
+| Storage key naming | `mechanic/inspections/{insp_id}/<uuid4hex>.<ext>` | Human-readable path + unguessable suffix. UUID4 avoids enumeration. |
+| Allowed content types | `image/{jpeg,png,heic,webp}` | Whitelist; 415 on others. |
+| Confirm status semantics | `status="ready"` set immediately on confirm; thumb generated async | Frontend doesn't need to poll. Galleries fall back to original via E4 endpoint. |
+| Thumbnail backend | `asyncio.create_task` + Pillow (no Celery) | Pillow + 15+ existing fire-and-forget call sites; no broker setup needed. Thumb resize is ~50ms for typical photo — acceptable on event loop. |
+| Thumb size | 480px max-edge, JPEG q=85 | Matches `services/download_wazzup_media.py` precedent. |
+| Auth model for read URLs | Auth-required on `/photos/{id}` endpoint; presigned URLs themselves bearer-free (1h TTL) | Same as existing `media_proxy.py` convention. |
+
+### Vendor data reality (from recon 2026-05-17 — 14,013 inspections, 2 years)
+
+| Metric | Value | Implication |
+|---|---|---|
+| Inspections with damage | 1,941 / 14,013 = 13.9% | Most inspections have empty marker list — UI optimize for that |
+| Median markers per inspection | 2 | Inline carry-over copy is cheap |
+| p95 markers | 10 | Confirms no async needed |
+| Max markers | 34 | Worst case still ~50 inserts on commit |
+| Median photos per inspection | 11 (`all_photo_ids`) | Includes 9 sides + damage photos |
+| Max photos per inspection | 30 | Set MinIO presigned batch size accordingly |
+| Carry-over in vendor | **None — denormalized snapshot** | Our `prev_inspection_id`+`carried_over_from_id` FK approach is net improvement |
+| Vendor inspection status field | **None — write-once when completed** | Our `in_progress`/`completed`/`cancelled` is greenfield, no conflicts |
+
+## Where things live
+
+### Repos (Gitea: `http://100.64.0.9:3001/tremble7681`)
+
+| Repo | Local clone | Working branch |
+|---|---|---|
+| `mechanic-pwa` | `c:\NewProject\PremiumDriverApp\` | `feat/mechanic-mvp` |
+| `taxi-dashboard` | `c:\NewProject\taxi-dashboard\` | `feat/mechanic-mvp` |
+
+`taxi-dashboard` clone has two remotes: `origin` → Gitea, `vds` → SSH to `/opt/sites/taxi-dashboard/` on 100.64.0.12 (for pulling back-and-forth with prod).
+
+### Reference paths (real, verified — see `docs/backend-layout-notes.md`)
+
+- `Base`, `TimestampMixin` → `app.models.base`
+- `get_db` → `app.db` (file: `app/db/__init__.py`)
+- `get_current_user` → `app.auth.deps`
+- `User` → `app.models.user`
+- Auth flow: **OAuth2 password + Bearer JWT** (not PIN as plan originally said)
+- DB init: **`Base.metadata.create_all`** at startup (not Alembic) + inline `ALTER TABLE ADD COLUMN IF NOT EXISTS` in `app/main.py` lifespan
+- Backend Docker container: `taxi-backend-green` / `taxi-backend-blue` (blue/green)
+- MinIO container: `taxi-minio`
+- Models registered in: `app/models/__init__.py` (imports + `__all__`)
+
+### Naming clash decision
+
+Existing `app/api/inspections.py` + model `CarInspection` (table `car_inspections`) hold **vendor-imported read-only** data from NaughtySoft. Our new tables use the **`mechanic_`** prefix to coexist:
+
+- `mechanic_inspections` (model `MechanicInspection`)
+- `mechanic_inspection_photos` (model `MechanicInspectionPhoto`)
+- `mechanic_damage_markers` (model `MechanicDamageMarker`)
+
+### Plan-vs-reality overrides applied in Phase B (Authoritative)
+
+Three places where the original plan (`docs/superpowers/plans/2026-05-16-premium-mechanic-phase1.md`) was overridden during execution because Phase A1 recon showed the codebase doesn't match the plan's assumptions:
+
+| Plan said | Actual implementation | Why |
+|---|---|---|
+| `backend/app/mechanic/router.py` (subpackage) | `backend/app/api/mechanic.py` (flat) | TaxiDashboard uses flat `app/api/*.py` files; no subpackages |
+| `backend/app/mechanic/schemas.py` (subpackage) | `backend/app/api/mechanic_schemas.py` (flat sibling) | Same convention |
+| `backend/app/mechanic/deps.py` (subpackage) | `backend/app/api/mechanic_deps.py` (flat sibling) | Same convention |
+| Router prefix `/api/v1/mechanic` | Router prefix `/v1/mechanic`, with `app.include_router(..., prefix="/api")` in `main.py` | Matches existing convention (`inspections.py` → `/v2/inspections` + include with `/api`). Final URL is identical: `/api/v1/mechanic/...` |
+| `require_mechanic` checks `user.dept.lower() in (...)` | Queries `UserDepartment ⨝ Department WHERE dept_type='svc' AND is_active`, admin shortcuts before DB hit | `User` has no `dept` attribute; departments are M2M via `user_departments`. `DEPT_TYPES=['ops','svc','adm']`, `svc` = service-type (мастерская) |
+
+When dispatching Phase C–F implementers, copy this override map into their context so they don't follow the stale subpackage / dept paths from the plan.
+
+## Phase C testing-infrastructure decision (RESOLVED — Option A in force)
+
+Phase C runs against `FastAPI TestClient` (sync) + `app.dependency_overrides[require_mechanic]` and `app.dependency_overrides[get_db]` to inject fake user / fake session. Fake session is a `SimpleNamespace`-flavored `_FakeSession` class in `tests/test_mechanic_endpoints.py` that supports `.execute(stmt)` (returns `_FakeResult` seeded with rows) and `.get(model, pk)` (returns seeded object or `None`).
+
+No `conftest.py`, no `pytest-asyncio`, no real DB. SQL correctness is deliberately deferred to Phase J e2e.
+
+If Phase D/E/F needs a more complex query shape (e.g. `.scalars().one()` / `.first()`), extend `_FakeResult.scalars()` accordingly — currently it returns `self` and supports only `.all()`. See `test_mechanic_endpoints.py:_FakeResult` docstring.
+
+## Deployment runbook (Phase J — execute manually)
+
+**Status:** prep done, awaiting user OK. Phase 1 MVP code is on `feat/mechanic-mvp` in both Gitea repos.
+
+### J0 — Pre-flight (verified)
+
+- [x] Backend `requirements.txt` already has `aiobotocore>=2.13.0`, `Pillow==10.4.0`, `pillow-heif==0.18.0`.
+- [x] Backend uses `Base.metadata.create_all` in lifespan (NOT Alembic) — new mechanic tables auto-create on container restart. **No migration step needed.**
+- [x] MinIO bucket `pp-inspections` exists with CORS configured (Phase A3, `ops/set-minio-cors.sh` already applied).
+- [x] Caddy fragment `ops/Caddyfile.fragment` ready in PremiumDriverApp repo.
+- [x] Frontend `dist/` build clean: **113 KB gzip JS**, 12 KB CSS, sw.js + workbox precaching.
+- [ ] **DNS**: confirm `mechanic.pptaxi.ru` resolves to the VDS IP before Caddy reload.
+- [ ] **Test mechanic user exists**: need a User in the DB with `is_admin=true` OR membership in a `Department` with `dept_type='svc'`. Verify with: `SELECT u.id, u.username, u.is_admin FROM users u LEFT JOIN user_departments ud ON ud.user_id=u.id LEFT JOIN departments d ON d.id=ud.department_id WHERE u.is_admin=true OR d.dept_type='svc';`
+
+### J1 — Backend deploy (taxi-dashboard)
+
+**⚠️ Production touch — affects live CRM.**
+
+Plan said `systemctl restart taxi-dashboard-backend.service` + `alembic upgrade head` — **both wrong for our setup**. We use Docker blue/green + `Base.metadata.create_all`. Correct steps:
+
+```bash
+ssh root@100.64.0.12
+cd /opt/sites/taxi-dashboard
+
+# 1. Pull the mechanic branch into prod's tracking copy
+git fetch origin feat/mechanic-mvp
+git checkout feat/mechanic-mvp  # OR merge into main first if your release process needs that
+
+# 2. Rebuild backend image (pulls in new requirements: Pillow, pillow-heif, aiobotocore should already be installed if it wasn't a fresh deploy, but rebuild to be safe)
+docker compose build backend-blue backend-green
+
+# 3. Rolling restart (blue first, then green — preserves availability)
+docker compose up -d --no-deps backend-blue
+sleep 10
+docker logs taxi-backend-blue --tail 50  # check for clean startup + table-create logs
+docker compose up -d --no-deps backend-green
+sleep 10
+docker logs taxi-backend-green --tail 50
+
+# 4. Smoke test
+curl -sS https://crm.pptaxi.ru/api/v1/mechanic/healthz
+# Expected: {"status":"ok"}
+```
+
+**Rollback if broken:** `git checkout main && docker compose up -d --no-deps backend-blue backend-green`. The `Base.metadata.create_all` is additive (CREATE TABLE IF NOT EXISTS) — new tables stay, no data loss.
+
+### J2 — Frontend deploy (mechanic-pwa)
+
+```bash
+# 1. Build locally (already done; use the fresh dist/)
+cd c:/NewProject/PremiumDriverApp/mechanic-pwa/frontend
+npm run build
+
+# 2. Create target dir on VDS if first deploy
+ssh root@100.64.0.12 'mkdir -p /opt/sites/mechanic-pwa/dist'
+
+# 3. Sync the built assets
+rsync -avz --delete dist/ root@100.64.0.12:/opt/sites/mechanic-pwa/dist/
+
+# 4. Install Caddy fragment (first deploy only)
+ssh root@100.64.0.12
+cd /opt/sites/mechanic-pwa
+# (assumes PremiumDriverApp repo is checked out at /opt/sites/mechanic-pwa/repo;
+#  if not, scp ops/Caddyfile.fragment instead)
+cp /opt/sites/mechanic-pwa/repo/ops/Caddyfile.fragment /etc/caddy/sites-enabled/mechanic.pptaxi.ru
+caddy validate --config /etc/caddy/Caddyfile  # OR appropriate validation cmd
+systemctl reload caddy
+
+# 5. Smoke test
+curl -I https://mechanic.pptaxi.ru
+# Expected: 200 OK, Content-Type: text/html
+curl -sS https://mechanic.pptaxi.ru/manifest.webmanifest | head -20
+# Expected: JSON with "name": "Premium Механик"
+```
+
+**Rollback:** `rm /etc/caddy/sites-enabled/mechanic.pptaxi.ru && systemctl reload caddy` removes the route; old `dist/` can be restored from previous rsync run if you take a snapshot first.
+
+### J3 — Smoke test (manual)
+
+Open `https://mechanic.pptaxi.ru` on a mobile browser (Android Chrome / iOS Safari):
+
+1. Login with the test mechanic account
+2. Search for any car → open card → start "Передача"
+3. Tap 2 zones on the scheme → markers appear with red badges
+4. Snap 1 photo (any slot) → wait for "загружено" toast → thumb appears
+5. Tap "Завершить осмотр" → redirected to review page showing photo + markers
+6. Verify in DB:
+   ```sql
+   SELECT id, vehicle_id, type, status, performed_by, started_at, finished_at
+   FROM mechanic_inspections ORDER BY id DESC LIMIT 3;
+   SELECT id, side, slot_index, status, thumb_key IS NOT NULL AS has_thumb
+   FROM mechanic_inspection_photos WHERE inspection_id=<NEW_ID>;
+   SELECT id, side, damage_type, carried_over_from_id, resolved
+   FROM mechanic_damage_markers WHERE inspection_id=<NEW_ID>;
+   ```
+7. Verify in MinIO console (`https://s3-admin.pptaxi.ru`) bucket `pp-inspections`: see the `mechanic/inspections/<NEW_ID>/<uuid>.jpg` original + `<uuid>-thumb.jpg` next to it.
+8. PWA install: tap browser menu → "Add to Home Screen" → opens fullscreen.
+
+If all 8 pass → **MVP is live**. File UX issues as Gitea issues.
+
+## Acceptance criteria (from plan §3)
+
+- [ ] Mechanic can log in on `mechanic.pptaxi.ru` from mobile
+- [ ] Find vehicle by license plate
+- [ ] Open vehicle card, see recent inspections
+- [ ] Start handover / return / periodic / ad-hoc inspection
+- [ ] On return: carry-over markers from prev appear with `carried_over_from_id`
+- [ ] Take ≥4 photos in slots, uploaded directly to MinIO via presigned PUT
+- [ ] Click zones on SVG scheme → point markers added
+- [ ] Finalize inspection (status=completed, finished_at auto-set)
+- [ ] View read-only review with all photos + markers
+- [ ] PWA installable to home screen on Android + iOS
+
+## Next task (post-deploy)
+
+### **Task F1 — Markers CRUD** (Phase F starts; only 2 tasks) — DONE see table above
+
+After successful J3 smoke test, **Phase 1 MVP is complete**. Phase 2 backlog: polygon annotation editor (Konva), offline IndexedDB queue, native APK wrap, push notifications, VendorBridge data import, admin stats dashboard, QR scanner.
+
+(From `docs/superpowers/plans/2026-05-16-premium-mechanic-phase1.md` Phase F.)
+
+**Working dir:** `c:\NewProject\taxi-dashboard` (branch `feat/mechanic-mvp`, HEAD `b37a068`)
+
+Phase F adds the marker endpoints — finally exposes the carry-over data we've been carefully copying since D1. After F, backend Phase 1 MVP is feature-complete and Phase G begins frontend work.
+
+**Two endpoints:**
+- `POST /inspections/{inspection_id}/markers` — create a new damage marker (request: `MarkerCreate` from B3)
+- `PATCH /markers/{marker_id}` — update marker (request: `MarkerPatch` from B3)
+
+The plan likely also wants `DELETE /markers/{marker_id}` — verify in the plan. There may also be a "resolve marker" endpoint that's just a PATCH with `resolved=True`.
+
+**Important context:**
+- `MechanicDamageMarker` has a stale comment at line 54 (refs old DamageType values like `rust`/`glass`/`paint`) — fix in F1 while touching this model area.
+- `MarkerCreate` and `MarkerOut` schemas already exist in `mechanic_schemas.py` from B3.
+- The carry-over markers (`carried_over_from_id IS NOT NULL`) deserve a thought: PATCH should be allowed to update them (mechanic confirms the existing damage is still there with current photo); DELETE should probably be NOT allowed on carry-overs (only on freshly-created markers) to preserve audit trail. Verify this in the plan.
+
+**Phase F implementer pattern:** apply the same Phase D path overrides (flat `app/api/`, `MechanicDamageMarker` not `DamageMarker`, etc.). Reuse `_FakeSession` + `_fake_marker_orm` from `mechanic_fakes.py`.
+
+### Phase D architecture decisions (RESOLVED 2026-05-17)
+
+1. **Carry-over: inline в POST /inspections** (atomic in the same transaction). Until carry-over copy completes, the new inspection isn't "ready" for the UI — async would create race conditions and complicate testing without a meaningful payoff for ~10-20 markers per copy.
+
+2. **`_FakeSession` write-path extension.** Add the following to the existing `_FakeSession` in `tests/test_mechanic_endpoints.py`:
+   - `add(obj)` — appends to `self.added` list; auto-assigns `obj.id` if not set, popping from `_next_ids` queue if provided, else incrementing `_next_id_counter` (starts at 1000 to avoid collision with test-seeded ids in the 1-99 range)
+   - `async flush()` — no-op + `self.flush_count += 1` (ids already assigned in `add`)
+   - `async commit()` — no-op + `self.commit_count += 1`
+   - `async refresh(obj)` — no-op + `self.refresh_count += 1`
+   - **`rows_per_call: Optional[list[Sequence]]`** kwarg — if provided, each `execute()` call pops one item from this queue and returns it as the result rows. This handles multi-query service flows (e.g. `start_inspection` does `select(prev_inspection)` then `select(prev_markers)`).
+   - Existing `execute(stmt)` and `get(model, pk)` keep their behavior.
+   - All extensions backward-compatible with current 83 tests.
+
+3. **Test infrastructure: stay on Option A, do NOT add real DB.** SQL specifics (selectinload, cascade, JSONB) will be validated in Phase J e2e. aiosqlite ≠ Postgres (JSONB mismatch), testcontainers is too heavy for 3 endpoints, two-paradigm test suite is more pain than gain. Extend the mock instead (see point 2).
+
+### Phase D path overrides (apply to D1, D2, D3)
+
+Same flat-file pattern as Phase B-C; map plan's stale paths:
+
+| Plan says | Use instead |
+|---|---|
+| `backend/app/mechanic/router.py` | `backend/app/api/mechanic.py` (append) |
+| `backend/app/mechanic/service.py` | `backend/app/api/mechanic_service.py` (append) |
+| `backend/app/mechanic/schemas.py` | `backend/app/api/mechanic_schemas.py` (already has all needed shapes from B3) |
+| `backend/tests/test_mechanic/test_inspections.py` | `backend/tests/test_mechanic_endpoints.py` (append) |
+| `Inspection` model | `MechanicInspection` (`app/models/mechanic_inspection`) |
+| `DamageMarker` model | `MechanicDamageMarker` (`app/models/mechanic_damage_marker`) |
+| `InspectionPhoto` model | `MechanicInspectionPhoto` (`app/models/mechanic_inspection_photo`) |
+| `service.get_vehicle_or_404` (plan) | `service.get_vehicle_by_id` + endpoint-level `None`-check + `HTTPException(404)` raise (C3 fix) |
+| `from fastapi import HTTPException` inline in service | At endpoint level only; service stays FastAPI-free |
+| 404 raise inside endpoint via inline `from fastapi import HTTPException` | Use top-of-file import (already there from C3) |
+
+Pydantic schemas (already shipped in B3):
+- `InspectionCreate` (vehicle_id, type, driver_id) — request body for POST
+- `InspectionPatch` (status, notes, finished_at) — request body for PATCH
+- `InspectionDetail` (full response with photos + markers list) — response model
+
+Phase B3 schemas use `model_config = ConfigDict(from_attributes=True)` via `_Base`, so SQLAlchemy ORM instances serialize automatically with `response_model=InspectionDetail`.
+
+## How to resume in a new session
+
+In a new Claude Code chat in `c:\NewProject\`, paste this prompt:
+
+```
+Продолжаем проект Premium Mechanic PWA.
+
+Прочитай PremiumDriverApp/docs/superpowers/STATE.md — Phase 1 MVP code-complete.
+Backend (14 routes, 159 тестов) + Frontend (113 KB gzip PWA) запушены на feat/mechanic-mvp.
+
+Deployment runbook готов в STATE.md секция "Deployment runbook". Выполни J1+J2+J3:
+1. SSH в root@100.64.0.12, git pull feat/mechanic-mvp, docker compose rebuild + rolling restart blue→green
+2. rsync mechanic-pwa/frontend/dist/ на VDS + caddy reload mechanic.pptaxi.ru
+3. Smoke test на мобильном браузере по чек-листу из runbook'а
+
+После успешного deploy: merge feat/mechanic-mvp → main в обоих репах (PremiumDriverApp + taxi-dashboard).
+```
+
+That prompt is the **single entry point** for the next session — Claude reads STATE.md, executes the deployment runbook, runs smoke tests, merges to main.
+
+## Remaining roadmap (Phase 1 MVP)
+
+- ~~**Phase B** (4 tasks)~~ ✅ done — module skeleton, models, schemas, auth deps
+- ~~**Phase C** (3 tasks)~~ ✅ done — GET /me, GET /vehicles, GET /vehicles/{id}
+- ~~**Phase D** (3 tasks)~~ ✅ done
+- ~~**Phase E** (5 tasks)~~ ✅ done
+- ~~**Phase F** (2 tasks)~~ ✅ done — backend Phase 1 MVP feature-complete (14 routes, 159 tests)
+- ~~**Phase G** (5 tasks)~~ ✅ done — frontend scaffold (91 KB gzip after G; 113 KB after I)
+- ~~**Phase H** (3 tasks)~~ ✅ done — Login + Home + VehicleCard
+- ~~**Phase I** (6 tasks)~~ ✅ done — CameraCapture + AuthImg + PhotoSlot + VehicleScheme + Editor + Review
+- **Phase J** (4 tasks): code-complete, **deployment runbook ready, awaiting user OK** ← **HERE**
+
+**Code work is done. Phase 1 MVP delivery is one `ssh root@100.64.0.12` + Docker compose restart + rsync away.**
+
+≈ 25 tasks left until MVP live on `mechanic.pptaxi.ru`.
+
+## Known external dependencies
+
+- MinIO `pp-inspections` bucket — CORS already configured, presigned uploads will work
+- Caddy on 100.64.0.12 — fragment ready, will be wired during Phase J deploy
+- Docker blue/green deployment on VDS — backend re-deployment will need a touch of `docker compose` (Phase J)
+- Frontend deployment target: `/opt/sites/mechanic-pwa/dist/` on VDS (Phase J)
+
+## Conventions reminder
+
+- All new code in `feat/mechanic-mvp` branches in both repos
+- All new tables use `mechanic_` prefix
+- Don't touch existing `app/api/inspections.py` or `app/models/inspection.py` (vendor-imported)
+- All new mechanic source lives in **flat files under `backend/app/api/`** with `mechanic_*` naming (`mechanic.py`, `mechanic_schemas.py`, `mechanic_deps.py`). No `app/mechanic/` subpackage — see "Plan-vs-reality overrides" table above.
+- Router prefix is `/v1/mechanic`; `/api` is added by `include_router(..., prefix="/api")` in `main.py`. Final URLs always `/api/v1/mechanic/*`.
+- Phase C+ endpoint tests: pending the test-infrastructure decision (Option A / B / C above). Do NOT introduce `pytest-asyncio`, `conftest.py`, or a real DB without first resolving that decision.
+- `require_mechanic` allows admins + members of any active `Department` with `dept_type='svc'`. Use it as the default auth dep for all mechanic endpoints.

docs/superpowers/specs/2026-06-18-premium-driver-pwa-design.md

@@ -0,0 +1,68 @@
+# Премиум Водитель — PWA (дизайн)
+
+**Дата:** 2026-06-18
+**Статус:** дизайн согласован (брейншторм + визуальный компаньон). Код не начат.
+**Цель:** PWA-приложение водителя «Премиум Водитель» — вход по телефону (код через TG/MAX), просмотр баланса (счета из CRM-леджера), пополнение через Т-Банк (СБП/карта), история пополнений. Поверхность для уже построенного бэкенда (Фаза 1 платежей + авторизация водителя в `crm2/app/modules/payments`).
+
+## Размещение и стек
+- Новый PWA — **сиблинг** `PremiumDriverApp/driver-pwa/frontend/` (рядом с `mechanic-pwa/`), на том же стеке: **React + Vite + vite-plugin-pwa + TypeScript + Tailwind + @tanstack/react-query + ky + zod + react-router-dom + react-hook-form + zustand + sonner (тосты) + lucide-react + vitest**. Структура `src/{api,components,pages,hooks,lib,store}` как у mechanic-pwa.
+- Хостинг: **app.pptaxi.ru** (статика + Caddy; деплой как у mechanic — build → dist → tar/rsync, см. mechanic deploy flow).
+- Имя приложения (везде в UI, манифест PWA, заголовок): **«Премиум Водитель»**.
+
+## Визуальный язык — Cream Minimal
+- Палитра (без жёлтого): фон `#F3EEE3` (cream), карточка/поверхность `#FBF8F1`, линия-разделитель `#E4DCCB`, чернила `#1C1B19`, вторичный текст `#7C7361`/opacity. Кнопки primary — тёмные `#1C1B19` с текстом `#F3EEE3`. Долг (минус) `#C0493A`, плюс/депозит `#3B6E4A`.
+- Типографика: **Inter** (один шрифт), без эмодзи. Иконки — lucide (тонкие, монохром).
+- Скругления 12–16px, тонкие 1px-границы, мягкие тени минимально. Крупные тап-таргеты (мобайл-фёрст). App-like / edit-first: минимум лишних кнопок, экран сам реагирует.
+
+## Экраны (MVP)
+1. **Вход.**
+   - Шаг 1: поле телефона `+7 ___ ___-__-__` → «Получить код». → `POST /api/driver/auth/request {phone}`.
+   - Если ответ `code_sent` → шаг 2: ввод кода (свой цифровой кейпад) → `POST /api/driver/auth/verify {phone, code}` → сохраняем driver JWT → на «Баланс».
+   - Если ответ `onboarding` → экран «Подключите бота»: две кнопки **Telegram** / **MAX** (открывают `deep_links.tg`/`.max`); подсказка «нажмите Старт у бота, затем вернитесь и запросите код снова». Кнопка «Я подключил — запросить код».
+2. **Баланс** (компоновка B: hero + список).
+   - Шапка: «Премиум Водитель» + инициалы водителя.
+   - **Hero-блок «Общий долг»** — крупная сумма (сумма отрицательных счетов).
+   - **Список счетов** (bucket из `/api/driver/balance`): название + подпись (марка/госномер для аренды, «N неоплаченных» для штрафов) + значение (минус — красный, плюс — зелёный).
+   - Кнопка **«Пополнить»** (primary). Тап по счёту/кнопке → «Пополнение» с предвыбранным счётом.
+   - Внизу/в меню: «История», «Выйти».
+3. **Пополнение** (компоновка C: свой кейпад).
+   - Заголовок «Пополнить · <счёт>». Крупная сумма. Строка «к оплате X ₽ (комиссия Y ₽)» — пересчёт на лету по ставке (получаем из ответа `/topup` или показываем оценку и уточняем).
+   - **Свой цифровой кейпад** (1–9, 0, ·, ⌫) — без системной клавиатуры; крупные клавиши. Быстрые суммы 500/1000/2000 (чипы).
+   - Сегмент **СБП / Картой**.
+   - Кнопка **«Оплатить»** → `POST /api/driver/topup {bucket, amount, method}` → получаем `{order_id, pay_url}`.
+4. **Оплата / статус** (вариант A: авто-статус, без QR).
+   - Иконка «СБП», сумма к оплате, кнопка **«Оплатить через СБП»** (или «Оплатить картой») → открывает `pay_url` (СБП deep-link `qr.nspk.ru/...` → приложение банка; карта → форма `pay.tbank.ru`). **QR не показываем, «оплата с другого устройства» убрана** — водитель платит на том же телефоне через приложение банка.
+   - Под кнопкой — авто-статус «Ожидаем оплату…» (спиннер). Приложение **опрашивает статус** платежа; при `PAID` → экран **«Оплачено»** (зелёная галочка, «<счёт> пополнен на N ₽») → кнопка «На главную» (баланс перезапрашивается).
+5. **История пополнений.**
+   - Список из `driver_payments` водителя: дата, счёт, сумма, статус (Оплачено/Ожидает/Отклонён), способ. Пусто → «Пока нет пополнений».
+6. **Выход** — очистка JWT, возврат на «Вход».
+
+## Поток данных / API (crm2 BFF, префикс `/api`)
+Готово (Фаза 1 + авторизация):
+- `POST /driver/auth/request {phone}` → `{status:"code_sent",channel}` | `{status:"onboarding",deep_links:{tg,max}}`
+- `POST /driver/auth/verify {phone, code}` → `{token, driver_id}`
+- `GET  /driver/balance` (Bearer) → `{accounts:[{bucket, balance}]}`
+- `POST /driver/topup {bucket, amount, method}` (Bearer) → `{order_id, pay_url, commission, total}`
+
+**Нужно добавить на бэкенде (зависимость этого PWA — отдельные backend-задачи):**
+- `GET /driver/payments` (Bearer) → история пополнений водителя (из `driver_payments`: order_id, bucket, amount, commission, method, status, created_at, paid_at).
+- `GET /driver/payment/{order_id}` (Bearer) → `{status}` для авто-опроса статуса оплаты (NEW/FORM/PAID/REJECTED). (Альтернатива: опрашивать `/driver/balance` и сравнивать — но явный статус надёжнее и показывает «Оплачено».)
+- (Опц.) В `/driver/topup` вернуть и `commission_rate`, чтобы кейпад считал «к оплате» локально до запроса.
+
+## Сессия / клиент
+- driver JWT (typ='driver', 30 дн) хранится в `localStorage`; `ky`-инстанс добавляет `Authorization: Bearer`. На 401 → разлогин (на «Вход»).
+- `@tanstack/react-query` для balance/history (кэш + рефетч); `zod` валидирует ответы; `zustand` — сессия (token, driver_id). Тосты ошибок — `sonner`.
+- База API из env (`VITE_API_BASE`, по умолчанию `https://crm.pptaxi.ru/api`). CORS: бэкенд должен разрешить origin `https://app.pptaxi.ru` для `/api/driver/*` (backend-задача).
+
+## PWA
+- `vite-plugin-pwa`: manifest (name «Премиум Водитель», cream theme `#F3EEE3`, иконки 192/512, standalone, портрет), service worker (precache оболочки, network-first для API). Устанавливается на телефон без сторов (по ссылке app.pptaxi.ru → «На экран Домой»).
+
+## Обработка ошибок
+- Телефон не найден (404) → «Номер не найден. Обратитесь в парк.» Неверный код (401) → «Неверный или просроченный код» + повтор. Платёж не создан → тост + остаёмся на «Пополнении». Авто-опрос: таймаут N минут → «Не дождались оплаты» + кнопка «Проверить ещё раз»/«Вернуться».
+
+## Тестирование
+- vitest + @testing-library/react: рендер экранов, кейпад (ввод/⌫/быстрые суммы, пересчёт «к оплате»), форма телефона/кода, маппинг ответов API (zod-схемы), guard приватных роутов (нет токена → «Вход»), авто-статус (мок таймера/опроса → success). API мокается (msw или ky-mock), без сети.
+
+## Скоуп / порядок
+MVP-экраны: Вход (+онбординг) · Баланс · Пополнение · Оплата/статус · История · Выход. **Вне MVP:** push-уведомления, вывод средств, профиль/настройки, мультиязычность.
+Порядок сборки (для плана): каркас приложения+PWA+API-клиент+сессия → Вход/онбординг → Баланс → Пополнение(кейпад) → Оплата/авто-статус → История → деплой app.pptaxi.ru. Бэкенд-зависимости (`/driver/payments`, `/driver/payment/{order_id}`, CORS) — отдельные мелкие задачи в crm2 (сделать до/параллельно соответствующим экранам).

driver-pwa/frontend/.env.example

@@ -0,0 +1,26 @@
+# Премиум Водитель (PWA) — переменные сборки.
+# Как поднять фронт локально — README.md рядом с этим файлом.
+
+# --- VITE_API_BASE: база API для ky (src/api/client.ts) ----------------------
+#
+# Боевой сборке задавать её НЕ обязательно: если переменной нет, client.ts
+# подставляет https://crm.pptaxi.ru/api. Поэтому строка ниже закомментирована
+# намеренно — скопированный в .env боевой адрес сборке ничего не добавляет,
+# а локальную разработку ломает: значение из файла приоритетнее дев-дефолта,
+# и `npm run dev` начнёт бить в боевой терминал вместо локального бэкенда.
+#
+#VITE_API_BASE=https://crm.pptaxi.ru/api
+
+# --- Локальная разработка ----------------------------------------------------
+#
+# Копировать этот файл в .env не нужно. `npm run dev` сам ставит
+# VITE_API_BASE=/api и проксирует /api на локальный бэкенд (vite.config.ts),
+# то есть запрос идёт с того же origin, что и страница, и CORS не участвует —
+# CORS_ALLOW_LOCALHOST в backend/.env для этого фронта не нужен.
+#
+# Свой адрес бэкенда, поход в API мимо прокси, PowerShell-вариант команд —
+# в README.md. Рецепты держим в одном месте: разъедутся — поверят не тому.
+#
+# ВНИМАНИЕ: crm.pptaxi.ru — боевой терминал Т-Банка и боевая касса АТОЛ.
+# Пополнение, сделанное «просто посмотреть», — это реальные деньги водителя,
+# реальный чек 54-ФЗ и реальная проводка в леджере.

driver-pwa/frontend/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.env.local
+*.tsbuildinfo

driver-pwa/frontend/README.md

@@ -0,0 +1,148 @@
+# Премиум Водитель — PWA водителя
+
+React + Vite + TypeScript. Прод: **https://app.pptaxi.ru**.
+Бэкенд — модуль `payments` в Premium CRM (`https://crm.pptaxi.ru/api`,
+репозиторий `crm2`, `backend/app/modules/payments/`).
+
+## Как поднять локально
+
+```bash
+npm install
+npm run dev            # http://localhost:5174
+```
+
+Отдельно поднимается бэкенд `crm2` на **127.0.0.1:8000** (тот же порт, что в
+`backend/Dockerfile`). Больше настраивать нечего: dev-сервер сам подставляет
+`VITE_API_BASE=/api` и проксирует `/api` на бэкенд — см. `vite.config.ts`.
+
+**Почему через прокси, а не «разрешить localhost в CORS бэкенда».** Прокси
+делает запрос ОДНОГО происхождения со страницей (`http://localhost:5174/api/…`),
+поэтому CORS в разработке не участвует вообще. Боевой список origin'ов на
+бэкенде остаётся закрытым, а `CORS_ALLOW_LOCALHOST=true` в `backend/.env` для
+этого фронта включать не надо. (Раньше рецепт с `CORS_ALLOW_LOCALHOST` тут и не
+работал: прокси не было, и фронт по умолчанию уходил на боевой домен, а не на
+локальный бэкенд.)
+
+Сервис-воркер в режиме разработки не регистрируется (`devOptions` у
+`vite-plugin-pwa` по умолчанию выключены) — старый кэш прод-версии в дев не
+лезет.
+
+### Бэкенд не на `127.0.0.1:8000`
+
+```bash
+VITE_API_TARGET=http://127.0.0.1:8090 npm run dev
+```
+
+В PowerShell инлайн-префикса `VAR=... команда` нет — переменную ставят отдельно:
+
+```powershell
+$env:VITE_API_TARGET="http://127.0.0.1:8090"; npm run dev
+```
+
+Имя переменной то же, что в CRM (`crm2/frontend/vite.config.ts`), — рецепт один
+на оба фронта.
+
+### Ходить в API напрямую, мимо прокси
+
+`.env.local` (в git не попадает):
+
+```
+VITE_API_BASE=http://127.0.0.1:8000/api
+```
+
+Своя настройка приоритетнее дев-дефолта — специально, чтобы `npm run dev` её не
+перебивал. Для похода в чужой origin бэкенду понадобится
+`CORS_ALLOW_LOCALHOST=true` в `backend/.env` и рестарт.
+
+> ⚠️ `crm.pptaxi.ru` — боевой терминал Т-Банка и боевая касса АТОЛ. Пополнение,
+> сделанное «просто посмотреть», — это реальные деньги водителя, реальный чек
+> 54-ФЗ и реальная проводка в леджере. Поэтому прокси по умолчанию смотрит в
+> локальный бэкенд, а не в прод.
+
+## Проверки
+
+```bash
+npx tsc -b             # типы
+npm test               # vitest run
+```
+
+`npx tsc --noEmit` **без `-b`** здесь всегда зелёный и ничего не значит:
+корневой `tsconfig.json` — solution-файл (`files: []` + `references`), под него
+не попадает ни один файл (`tsc --noEmit --listFiles` печатает пустоту). Типы
+живут в `tsconfig.app.json` (`src`) и `tsconfig.node.json` (конфиги +
+`dev-proxy.test.ts`), и до обоих добирается только `tsc -b`.
+
+## Сборка
+
+```bash
+npm run build          # tsc -b && vite build → dist/
+```
+
+Дев-дефолт `VITE_API_BASE=/api` подставляется только при запущенном dev-сервере
+и в бандл не попадает: в собранном `assets/index-*.js` лежит
+`https://crm.pptaxi.ru/api` (проверено сборкой). Поэтому `VITE_API_BASE` боевой
+сборке задавать не обязательно — без неё `src/api/client.ts` подставляет ровно
+этот адрес.
+
+> ⚠️ `npm run preview` поднимает **уже собранный** бандл, а база в нём
+> абсолютная: запросы уходят на боевой `crm.pptaxi.ru` мимо прокси dev-сервера.
+> Смотреть локальные правки — только `npm run dev`.
+
+Куда выкладывается `dist/` — в плане проекта:
+`../../docs/superpowers/plans/2026-06-18-premium-driver-pwa.md`, раздел
+«Deployment notes»: статика на `app.pptaxi.ru`, Caddy с фолбэком на `index.html`.
+
+## Кто может войти и как смотреть чужой экран
+
+> **Запущено 22.08.2026: вход открыт всем водителям.** Список номеров ниже пуст,
+> то есть гейт выключен. Раздел оставлен как инструкция на случай, если вход
+> снова понадобится сузить — например под обкатку следующей крупной правки.
+
+### 1. Вход только по списку номеров (сейчас выключено)
+
+Переменная бэкенда (`crm2/backend/.env`, читается в `app/config.py`):
+
+```
+DRIVER_APP_ALLOWED_PHONES=+7 (914) 123-45-67, 79990001122
+```
+
+Разделители — запятая, точка с запятой, перенос строки (пробел разделителем не
+считается: номер вписывают в привычном виде). Сверяются последние 10 цифр.
+**Пусто — гейт выключен, вход открыт всем водителям.**
+
+Проверка стоит в единственной воронке выдачи токена
+(`modules/payments/driver_auth.create_driver_token_for`), поэтому закрыты сразу
+все пять путей входа: код в бот, кнопка «Войти через Telegram», колбэки своего
+бота и два аварийных отката на n8n. Бот отвечает человеку текстом, остальные
+пути — 403. Логика гейта: `modules/payments/login_gate.py`.
+
+### 2. Просмотр от лица водителя (сотрудник)
+
+На экране входа внизу — «Вход для сотрудника» (`/dev`): логин и пароль **учётки
+CRM**, при включённой двухфакторке спросит код. Дальше поиск по ФИО, телефону
+или id — и приложение открывается от лица выбранного водителя.
+
+* Токен помечен claim'ом `imp`, живёт 8 часов (обычный водительский — 30 дней).
+* Гейт — `is_admin` в CRM. Каждая выдача пишется в аудит (`driver_app.impersonate`).
+* Кнопка «Отозвать доступ» в CRM гасит и просмотр сотрудника — поколение общее.
+* Гейт обкатки на этот путь не распространяется: смотреть надо как раз на
+  водителей, которых в allowlist нет.
+
+Пока просмотр действует, сверху на всех экранах висит плашка «Смотрю как …» со
+ссылкой на вкладку **«Отладка»** (`/debug`, водителю недоступна):
+
+* от чьего лица открыт экран и кнопка сменить водителя;
+* `driver_id`, режим, сотрудник, когда истекает токен, адрес API, коммит и время
+  сборки, состояние сети;
+* журнал последних 40 ответивших запросов (метод, путь, статус, миллисекунды);
+* сброс кэша сервис-воркера с перезагрузкой — лечит «правка не приехала»;
+* выходы: из просмотра, из учётки сотрудника.
+
+### Деньги под просмотром: учебный платёж
+
+Пополнение под `imp`-токеном **не идёт в банк**. Проверки суммы, категории и
+расчёт комиссии настоящие, а вместо Init на терминале заводится учебный заказ в
+Redis (`modules/payments/mock_pay.py`, префикс `mock-`, час жизни). Экран
+`/mock-pay/:orderId` даёт выбрать, что «ответит» банк — оплачено, отказ,
+истёкший счёт, возврат, — и настоящий экран оплаты разбирает эти статусы своим
+боевым кодом. В `driver_payments` не попадает ни строки, чек 54-ФЗ не пробивается.

driver-pwa/frontend/dev-proxy.test.ts

@@ -0,0 +1,103 @@
+// @vitest-environment node
+/**
+ * Локальная разработка PWA водителя.
+ *
+ * Гейт CORS на бэкенде (CORS_ALLOW_LOCALHOST, по умолчанию выключен) закрыл
+ * дыру, но заодно оставил этот фронт без рабочего дева: прокси не было, а
+ * client.ts по умолчанию уходит на боевой https://crm.pptaxi.ru/api — то есть
+ * «включи CORS_ALLOW_LOCALHOST» тут не помогало, запрос вообще не доходил до
+ * локального бэкенда.
+ *
+ * Тесты держат обе половины договорённости:
+ *   1) `npm run dev` доводит фронт до локального бэкенда сам, без правки .env;
+ *   2) боевая сборка от этого не меняется — относительная дев-база в бандл
+ *      попасть не может (в проде он живёт на app.pptaxi.ru, где /api нет).
+ *
+ * Конфиг резолвится по-настоящему (resolveConfig читает vite.config.ts и
+ * env-файлы) — иначе тест проверял бы не то, что увидит vite.
+ *
+ * Файл лежит рядом с vite.config.ts и НЕ называется vite.config.test.ts:
+ * в дефолтном exclude vitest есть `**\/{...,vite,...}.config.*`, под который
+ * такое имя попадает целиком — тест молча не запускался бы.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import path from "path";
+import { fileURLToPath } from "url";
+import { resolveConfig } from "vite";
+
+const ROOT = path.dirname(fileURLToPath(import.meta.url));
+
+/** Обе переменные — process.env, и dev-дефолт их же и трогает: сохраняем. */
+const SAVED = {
+  base: process.env.VITE_API_BASE,
+  target: process.env.VITE_API_TARGET,
+};
+
+function restore(key: "VITE_API_BASE" | "VITE_API_TARGET", value: string | undefined): void {
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+}
+
+beforeEach(() => {
+  delete process.env.VITE_API_BASE;
+  delete process.env.VITE_API_TARGET;
+});
+
+afterEach(() => {
+  restore("VITE_API_BASE", SAVED.base);
+  restore("VITE_API_TARGET", SAVED.target);
+});
+
+const resolve = (command: "serve" | "build", mode: "development" | "production") =>
+  resolveConfig({ root: ROOT, configFile: path.join(ROOT, "vite.config.ts"), logLevel: "silent" },
+                command, mode, mode);
+
+describe("dev-сервер доводит фронт до локального бэкенда", () => {
+  it("подставляет относительную базу — запрос идёт со своего origin, CORS не участвует", async () => {
+    const cfg = await resolve("serve", "development");
+    expect(cfg.env.VITE_API_BASE).toBe("/api");
+  });
+
+  it("проксирует /api на локальный бэкенд, а не на боевой домен", async () => {
+    const cfg = await resolve("serve", "development");
+    const proxy = cfg.server.proxy?.["/api"];
+    expect(typeof proxy === "object" && proxy.target).toBe("http://127.0.0.1:8000");
+  });
+
+  it("цель прокси переопределяется VITE_API_TARGET (стенд, тайлнет)", async () => {
+    process.env.VITE_API_TARGET = "http://127.0.0.1:8090";
+    const cfg = await resolve("serve", "development");
+    const proxy = cfg.server.proxy?.["/api"];
+    expect(typeof proxy === "object" && proxy.target).toBe("http://127.0.0.1:8090");
+  });
+
+  it("база и путь прокси — одно и то же", async () => {
+    // Две половины рецепта живут в разных местах конфига: базу подставляем в
+    // env, путь перечисляем в server.proxy. Разъедутся (например, база станет
+    // "/backend") — dev-сервер отдаст на этот путь index.html вместо ответа
+    // бэкенда, и падать будет уже в разборе JSON, далеко от причины.
+    const cfg = await resolve("serve", "development");
+    expect(Object.keys(cfg.server.proxy ?? {})).toContain(cfg.env.VITE_API_BASE);
+  });
+
+  it("не перебивает базу, заданную разработчиком", async () => {
+    process.env.VITE_API_BASE = "https://stand.example/api";
+    const cfg = await resolve("serve", "development");
+    expect(cfg.env.VITE_API_BASE).toBe("https://stand.example/api");
+  });
+});
+
+describe("боевая сборка остаётся боевой", () => {
+  it("дев-дефолт в сборку не течёт: base пустая → client.ts берёт прод-адрес", async () => {
+    const cfg = await resolve("build", "production");
+    expect(cfg.env.VITE_API_BASE).toBeUndefined();
+    expect(process.env.VITE_API_BASE).toBeUndefined();
+  });
+
+  it("ни один env-файл не подсовывает сборке относительную базу", async () => {
+    // Относительный /api в проде означал бы app.pptaxi.ru/api — такого нет.
+    // Ловит и коммит .env с дев-значением, и локальный .env на машине сборки.
+    const cfg = await resolve("build", "production");
+    expect(cfg.env.VITE_API_BASE).not.toBe("/api");
+  });
+});

driver-pwa/frontend/index.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <meta name="theme-color" content="#EEF1F5" />
+    <link rel="icon" type="image/png" sizes="192x192" href="/icons/icon-192.png" />
+    <!-- iOS манифест не читает: иконку «на экран Домой» он берёт только отсюда. -->
+    <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" />
+    <!-- iOS берёт подпись под иконкой отсюда, а не из манифеста. -->
+    <meta name="apple-mobile-web-app-title" content="Водитель" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800&display=swap" rel="stylesheet" />
+    <title>Премиум Водитель</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

driver-pwa/frontend/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "driver-pwa",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.51.0",
+    "ky": "^1.7.2",
+    "lucide-react": "^0.454.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.26.0",
+    "sonner": "^1.5.0",
+    "zod": "^3.23.8",
+    "zustand": "^4.5.5"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.5.0",
+    "@testing-library/react": "^16.0.1",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^22.5.0",
+    "@types/react": "^18.3.5",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.20",
+    "jsdom": "^25.0.0",
+    "postcss": "^8.4.45",
+    "tailwindcss": "^3.4.10",
+    "typescript": "^5.5.4",
+    "vite": "^5.4.2",
+    "vite-plugin-pwa": "^0.20.5",
+    "vitest": "^2.0.5",
+    "workbox-core": "^7.4.1",
+    "workbox-precaching": "^7.4.1"
+  }
+}

driver-pwa/frontend/postcss.config.js

@@ -0,0 +1 @@
+export default { plugins: { tailwindcss: {}, autoprefixer: {} } };

driver-pwa/frontend/public/manifest.webmanifest

@@ -0,0 +1,14 @@
+{
+  "name": "Премиум Водитель",
+  "short_name": "Водитель",
+  "start_url": "/",
+  "display": "standalone",
+  "orientation": "portrait",
+  "background_color": "#EEF1F5",
+  "theme_color": "#EEF1F5",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
+  ]
+}

driver-pwa/frontend/scripts/gen-icons.py

@@ -0,0 +1,63 @@
+"""Иконки приложения — тот же значок, что у сайта pptaxi.ru.
+
+Сайт отдаёт `favicon.svg`: красная скруглённая плитка --s-accent и белая «П».
+Повторяем её здесь, чтобы значок в браузере, на экране телефона и на сайте был
+один и тот же.
+
+Рисуем сами (Pillow), потому что тянуть растеризатор SVG ради одной плитки с
+буквой незачем. Сглаживание — сверхдискретизацией ×4.
+
+Запуск (нужен Pillow):
+    python scripts/gen-icons.py
+"""
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+OUT = Path(__file__).resolve().parent.parent / "public" / "icons"
+ACCENT = (220, 38, 38, 255)   # --s-accent сайта
+PAPER = (255, 255, 255, 255)  # --s-paper
+SS = 4
+
+# Шрифт ищем среди системных: у сайта заголовки набраны Manrope, но ради одной
+# буквы тащить файл шрифта в репозиторий не стоит — берём ближайший гротеск.
+FONT_CANDIDATES = [
+    r"C:\Windows\Fonts\segoeuib.ttf",
+    r"C:\Windows\Fonts\arialbd.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+]
+
+
+def _font(size: int) -> ImageFont.FreeTypeFont:
+    for path in FONT_CANDIDATES:
+        if Path(path).exists():
+            return ImageFont.truetype(path, size)
+    raise SystemExit("не нашёл жирный шрифт для буквы")
+
+
+def compose(size: int, inset: float, radius_ratio: float = 0.22) -> Image.Image:
+    """inset — доля стороны под плитку. У maskable она меньше: Android режет
+    иконку по кругу, и плитка без запаса теряет углы."""
+    big = size * SS
+    img = Image.new("RGBA", (big, big), PAPER)
+    draw = ImageDraw.Draw(img)
+    pad = big * (1 - inset) / 2
+    box = (pad, pad, big - pad, big - pad)
+    draw.rounded_rectangle(box, radius=(box[2] - box[0]) * radius_ratio, fill=ACCENT)
+
+    letter = "П"
+    font = _font(int((box[3] - box[1]) * 0.72))
+    l, t, r, b = draw.textbbox((0, 0), letter, font=font)
+    draw.text(((box[0] + box[2] - (r - l)) / 2 - l,
+               (box[1] + box[3] - (b - t)) / 2 - t), letter, font=font, fill=PAPER)
+    return img.resize((size, size), Image.LANCZOS)
+
+
+if __name__ == "__main__":
+    OUT.mkdir(parents=True, exist_ok=True)
+    for name, size, inset in (("icon-192.png", 192, 1.0),
+                              ("icon-512.png", 512, 1.0),
+                              ("icon-maskable-512.png", 512, 0.72),
+                              ("apple-touch-icon.png", 180, 1.0)):
+        compose(size, inset).save(OUT / name)
+        print("собрано", name)

driver-pwa/frontend/src/App.test.tsx

@@ -0,0 +1,25 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import App from "./App";
+import { useAuth } from "@/store/auth";
+
+function renderAt(path: string) {
+  const qc = new QueryClient();
+  return render(
+    <QueryClientProvider client={qc}>
+      <MemoryRouter initialEntries={[path]}>
+        <App />
+      </MemoryRouter>
+    </QueryClientProvider>
+  );
+}
+
+describe("routing guard", () => {
+  beforeEach(() => useAuth.getState().clear());
+  it("redirects to login when no token", () => {
+    renderAt("/");
+    expect(screen.getByText(/Вход в приложение/i)).toBeInTheDocument();
+  });
+});

driver-pwa/frontend/src/App.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react";
+import { useEffect } from "react";
+import { Navigate, Route, Routes, useLocation, useNavigate } from "react-router-dom";
+import { useAuth } from "@/store/auth";
+import { useStaff } from "@/store/staff";
+import { setReturnTo } from "@/lib/returnTo";
+import { ImpersonationBar } from "@/components/ImpersonationBar";
+import { LoginPage } from "@/pages/LoginPage";
+import { TgWaitPage } from "@/pages/TgWaitPage";
+import { OnboardingPage } from "@/pages/OnboardingPage";
+import { BalancePage } from "@/pages/BalancePage";
+import { TopupPage } from "@/pages/TopupPage";
+import { PaymentPage } from "@/pages/PaymentPage";
+import { DevLoginPage } from "@/pages/DevLoginPage";
+import { DebugPage } from "@/pages/DebugPage";
+import { MockPayPage } from "@/pages/MockPayPage";
+import { FineDetailPage } from "@/pages/FineDetailPage";
+import { NotificationsPage } from "@/pages/NotificationsPage";
+import { markNotificationsRead } from "@/api/driver";
+
+function RequireAuth({ children }: { children: ReactNode }) {
+  const token = useAuth((s) => s.token);
+  const loc = useLocation();
+  if (token) return <>{children}</>;
+  // Запоминаем, куда шёл водитель (напр. ссылку на оплату), чтобы вернуть его
+  // туда после входа, а не на баланс.
+  setReturnTo(loc.pathname + loc.search);
+  return <Navigate to="/login" replace />;
+}
+
+/** Отладка существует только для сотрудника: либо он вошёл учёткой CRM, либо
+ * прямо сейчас смотрит от лица водителя. Обычному водителю адрес /debug ничего
+ * не даёт — его уводит на главную. */
+function RequireStaff({ children }: { children: ReactNode }) {
+  const impersonated = useAuth((s) => s.impersonated);
+  const staffToken = useStaff((s) => s.token);
+  return impersonated || staffToken ? <>{children}</> : <Navigate to="/" replace />;
+}
+
+/**
+ * Нажатие по пушу — единственный честный признак, что уведомление увидели.
+ * Сам воркер отметить его не может: токен водителя лежит в хранилище страницы,
+ * ему недоступном. Поэтому воркер добавляет к адресу `?n=<номер>`, а отмечает
+ * страница — и тут же убирает параметр, чтобы он не остался в истории.
+ */
+function MarkPushRead() {
+  const loc = useLocation();
+  const nav = useNavigate();
+
+  useEffect(() => {
+    const params = new URLSearchParams(loc.search);
+    const raw = params.get("n");
+    if (!raw) return;
+    const id = Number(raw);
+    if (Number.isFinite(id) && id > 0) void markNotificationsRead([id], "push");
+    params.delete("n");
+    const rest = params.toString();
+    nav(loc.pathname + (rest ? `?${rest}` : ""), { replace: true });
+  }, [loc.search, loc.pathname, nav]);
+
+  return null;
+}
+
+export default function App() {
+  return (
+    <div className="mx-auto max-w-md min-h-full px-4 pt-3 pb-8">
+      {/* Плашка живёт над маршрутами: чей экран открыт, видно на каждом из них,
+          а не только там, где про неё вспомнили. Сама решает, показываться ли. */}
+      <ImpersonationBar />
+      <MarkPushRead />
+      <Routes>
+        <Route path="/login" element={<LoginPage />} />
+        <Route path="/dev" element={<DevLoginPage />} />
+        <Route path="/tg-wait" element={<TgWaitPage />} />
+        <Route path="/onboarding" element={<OnboardingPage />} />
+        <Route path="/" element={<RequireAuth><BalancePage /></RequireAuth>} />
+        <Route path="/topup" element={<RequireAuth><TopupPage /></RequireAuth>} />
+        <Route path="/pay/:orderId" element={<RequireAuth><PaymentPage /></RequireAuth>} />
+        <Route path="/mock-pay/:orderId" element={<RequireAuth><MockPayPage /></RequireAuth>} />
+        <Route path="/fines/:fineId" element={<RequireAuth><FineDetailPage /></RequireAuth>} />
+        <Route path="/notifications" element={<RequireAuth><NotificationsPage /></RequireAuth>} />
+        <Route path="/debug" element={<RequireAuth><RequireStaff><DebugPage /></RequireStaff></RequireAuth>} />
+        <Route path="*" element={<Navigate to="/" replace />} />
+      </Routes>
+    </div>
+  );
+}

driver-pwa/frontend/src/api/client.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { api } from "./client";
+import { useAuth } from "@/store/auth";
+
+/**
+ * Продление сеанса: бэкенд кладёт свежий токен в заголовок `X-Driver-Token`,
+ * приложение обязано молча его подменить. Без этого 30 дней жизни токена
+ * считались бы от входа, и раз в месяц водителя выкидывало бы на экран входа —
+ * при том, что пароля у него нет и «войти» означает сходить в бота за кодом.
+ */
+function answer(headers: Record<string, string> = {}) {
+  return vi.fn(async () =>
+    new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json", ...headers },
+    }));
+}
+
+describe("продление токена водителя", () => {
+  beforeEach(() => {
+    useAuth.setState({ token: "OLD", driverId: 7, impersonated: false, driverName: null, own: null });
+  });
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("подменяет токен, когда ответ принёс свежий", async () => {
+    vi.stubGlobal("fetch", answer({ "X-Driver-Token": "NEW" }));
+    await api.get("driver/balance").json();
+    expect(useAuth.getState().token).toBe("NEW");
+    expect(useAuth.getState().driverId).toBe(7);
+  });
+
+  it("без заголовка ничего не трогает", async () => {
+    vi.stubGlobal("fetch", answer());
+    await api.get("driver/balance").json();
+    expect(useAuth.getState().token).toBe("OLD");
+  });
+
+  it("не продлевает просмотр от лица водителя", async () => {
+    // Восемь часов просмотра — сознательный предел для чужого баланса на чужом
+    // ноутбуке. Бэкенд заголовок и не пришлёт, но полагаться на это нельзя:
+    // ответ на запрос, ушедший ДО начала просмотра, может прийти уже после.
+    useAuth.setState({ token: "IMP", driverId: 9, impersonated: true, driverName: "Петров" });
+    vi.stubGlobal("fetch", answer({ "X-Driver-Token": "NEW" }));
+    await api.get("driver/balance").json();
+    expect(useAuth.getState().token).toBe("IMP");
+  });
+
+  it("не воскрешает сеанс, закрытый пока запрос был в пути", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => {
+      useAuth.getState().clear();          // водитель нажал «выйти»
+      return new Response("{}", { status: 200, headers: { "X-Driver-Token": "NEW" } });
+    }));
+    await api.get("driver/balance").json();
+    expect(useAuth.getState().token).toBeNull();
+  });
+});

driver-pwa/frontend/src/api/client.ts

@@ -0,0 +1,66 @@
+import ky, { type KyInstance } from "ky";
+import { pushEntry, shortPath } from "@/lib/reqlog";
+import { useAuth } from "@/store/auth";
+
+export const API_BASE = import.meta.env.VITE_API_BASE ?? "https://crm.pptaxi.ru/api";
+
+/** Засечка времени на конкретный запрос. WeakMap — чтобы не держать Request'ы. */
+const started = new WeakMap<Request, number>();
+
+/**
+ * Заголовок, которым бэкенд отдаёт ПРОДЛЁННЫЙ токен водителя (см. driver_auth.py).
+ *
+ * Токен живёт 30 дней, и без продления они считались бы от входа: раз в месяц
+ * водителя выкидывало бы на экран входа, а «войти» для него означает сходить в
+ * бота за кодом. Начиная с пятого дня жизни токена бэкенд кладёт в ответ свежий,
+ * мы его молча подменяем — и 30 дней начинают считаться от последнего захода.
+ */
+const RENEWED_TOKEN_HEADER = "X-Driver-Token";
+
+/** Подменить токен на продлённый, если ответ его принёс. */
+function adoptRenewedToken(request: Request, response: Response): void {
+  const fresh = response.headers.get(RENEWED_TOKEN_HEADER);
+  if (!fresh) return;
+  const auth = useAuth.getState();
+  // Сеанс мог смениться, пока запрос был в пути: водитель вышел, сотрудник начал
+  // просмотр от чужого лица. Подменяем только тот токен, с которым сами ушли, —
+  // иначе продление чужого ответа вернёт закрытый сеанс к жизни.
+  if (auth.impersonated || auth.driverId == null) return;
+  if (request.headers.get("Authorization") !== `Bearer ${auth.token}`) return;
+  auth.setSession(fresh, auth.driverId);
+}
+
+export const api: KyInstance = ky.create({
+  prefixUrl: API_BASE,
+  timeout: 30_000,
+  retry: { limit: 2, methods: ["get"] },
+  hooks: {
+    beforeRequest: [
+      (request) => {
+        started.set(request, performance.now());
+        const token = useAuth.getState().token;
+        if (token) request.headers.set("Authorization", `Bearer ${token}`);
+      },
+    ],
+    // В журнал попадают ОТВЕТИВШИЕ запросы, включая 4xx/5xx. Запрос, оборвавшийся
+    // без ответа (таймаут, пропавшая сеть), ky сюда не приносит — на экране
+    // отладки об этом сказано прямо, чтобы пустая строка не читалась как «дошло».
+    afterResponse: [
+      (request, _options, response) => {
+        pushEntry({
+          method: request.method,
+          path: shortPath(request.url),
+          status: response.status,
+          ms: Math.round(performance.now() - (started.get(request) ?? performance.now())),
+        });
+        adoptRenewedToken(request, response);
+      },
+    ],
+    beforeError: [
+      (error) => {
+        if (error.response?.status === 401) useAuth.getState().clear();
+        return error;
+      },
+    ],
+  },
+});

driver-pwa/frontend/src/api/driver.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { BalanceSchema, TopupSchema, PaymentsSchema, AuthRequestSchema, TgSessionSchema, TgPollSchema } from "./driver";
+
+describe("driver api schemas", () => {
+  it("parses balance", () => {
+    const v = BalanceSchema.parse({ accounts: [{ bucket: "Долг аренда", balance: -3200 }] });
+    expect(v.accounts[0].bucket).toBe("Долг аренда");
+  });
+  it("parses topup", () => {
+    const v = TopupSchema.parse({ order_id: "o1", pay_url: "https://x", commission: 52, total: 1052 });
+    expect(v.pay_url).toBe("https://x");
+  });
+  it("parses auth request onboarding + code_sent", () => {
+    expect(AuthRequestSchema.parse({ status: "code_sent", channel: "tg" }).status).toBe("code_sent");
+    const pair = { pair_session: "S", poll_secret: "SEC", confirm_code: "4217" };
+    const o = AuthRequestSchema.parse({ status: "onboarding", deep_links: { tg: "t", max: "m" }, ...pair });
+    expect(o.status === "onboarding" && o.deep_links.tg).toBe("t");
+    // prod: MAX bot not configured → backend omits `max`, must still parse (regression guard)
+    const tgOnly = AuthRequestSchema.parse({ status: "onboarding", deep_links: { tg: "t" }, ...pair });
+    expect(tgOnly.status === "onboarding" && tgOnly.deep_links.tg).toBe("t");
+  });
+  it("parses payments history", () => {
+    const v = PaymentsSchema.parse({ payments: [{ order_id: "o1", bucket: "b", amount: 100,
+      commission: 5.2, method: "qr", status: "PAID", created_at: "2026-06-18T09:00:00Z", paid_at: null }] });
+    expect(v.payments[0].status).toBe("PAID");
+  });
+});
+
+describe("tg verified-login schemas", () => {
+  it("parses tg session", () => {
+    const v = TgSessionSchema.parse({ pair_session: "S", poll_secret: "SEC", confirm_code: "4217",
+                                     deep_link: "https://t.me/x?start=S" });
+    expect(v.pair_session).toBe("S");
+    expect(v.poll_secret).toBe("SEC");
+    // вторая половина ключа в deep-link не уходит
+    expect(v.deep_link).not.toContain("SEC");
+  });
+  it("parses tg poll states", () => {
+    expect(TgPollSchema.parse({ status: "pending" }).status).toBe("pending");
+    expect(TgPollSchema.parse({ status: "expired" }).status).toBe("expired");
+    const a = TgPollSchema.parse({ status: "authenticated", token: "T", driver_id: 7 });
+    expect(a.status === "authenticated" && a.token).toBe("T");
+  });
+});

driver-pwa/frontend/src/api/driver.ts

@@ -0,0 +1,238 @@
+import { HTTPError } from "ky";
+import { z } from "zod";
+import { api } from "./client";
+
+/** Pairing-сессия входа. `poll_secret` не покидает приложение (в deep-link уходит
+ * только `pair_session`), `confirm_code` человек сверяет с сообщением бота. */
+export const TgSessionSchema = z.object({
+  pair_session: z.string(),
+  poll_secret: z.string(),
+  confirm_code: z.string(),
+  deep_link: z.string().nullable(),
+});
+
+export const AuthRequestSchema = z.union([
+  z.object({ status: z.literal("code_sent"), channel: z.string() }),
+  z.object({
+    status: z.literal("onboarding"),
+    deep_links: z.object({ tg: z.string().optional(), max: z.string().optional() }),
+    pair_session: z.string(),
+    poll_secret: z.string(),
+    confirm_code: z.string(),
+  }),
+]);
+export type AuthRequest = z.infer<typeof AuthRequestSchema>;
+
+export const VerifySchema = z.object({ token: z.string(), driver_id: z.number() });
+export const BalanceSchema = z.object({
+  accounts: z.array(z.object({
+    bucket: z.string(),
+    balance: z.number(),
+    // Можно ли платить в эту статью. «Страховка» приходит из 1С, но платежом не
+    // закрывается — строку показываем, нажатие не предлагаем.
+    payable: z.boolean().default(true),
+  })),
+  // Итог берём с сервера, а не суммой строк: 1С округляет статьи до рублей, а итог
+  // держит с копейками, и сумма строк с ним не сходится (−8 976 против −8 976,25).
+  total: z.number().nullable().default(null),
+  synced_at: z.string().nullable().default(null),
+  // Принято нами, но ещё не проведено в 1С. В сумму баланса не входит.
+  pending_topup: z.number().default(0),
+});
+export const BucketsSchema = z.object({
+  buckets: z.array(z.string()),
+  with_debt: z.array(z.string()),
+});
+export const TopupSchema = z.object({
+  order_id: z.string(), pay_url: z.string(), commission: z.number(), total: z.number(),
+  // Учебный платёж: сотрудник смотрит от лица водителя, банка в этой ветке нет
+  // (см. backend modules/payments/mock_pay.py). У обычного водителя всегда false.
+  mock: z.boolean().default(false),
+});
+export const PaymentStateSchema = z.object({ order_id: z.string(), status: z.string() });
+export const CommissionSchema = z.object({ rate: z.number() });
+export const PaymentsSchema = z.object({
+  payments: z.array(z.object({
+    order_id: z.string(), bucket: z.string(), amount: z.number(), commission: z.number(),
+    method: z.string(), status: z.string(),
+    created_at: z.string().nullable(), paid_at: z.string().nullable(),
+    reversed_at: z.string().nullable().default(null),
+  })),
+});
+
+export const TgPollSchema = z.union([
+  z.object({ status: z.literal("pending") }),
+  z.object({ status: z.literal("expired") }),
+  z.object({ status: z.literal("authenticated"), token: z.string(), driver_id: z.number() }),
+]);
+
+/**
+ * Текст ошибки от бэкенда.
+ *
+ * Раньше все отказы схлопывались в «Не удалось создать платёж», и осмысленные
+ * сообщения — про минимум СБП, про потолок суммы, про неизвестную категорию —
+ * до водителя не доходили: экран просто не реагировал.
+ */
+export async function apiErrorText(err: unknown, fallback: string): Promise<string> {
+  if (err instanceof HTTPError) {
+    try {
+      const body = await err.response.json();
+      const detail = (body as { detail?: unknown })?.detail;
+      if (typeof detail === "string" && detail.trim()) return detail;
+    } catch {
+      /* тело не JSON — отдадим запасной текст */
+    }
+  }
+  return fallback;
+}
+
+/**
+ * Сколько секунд ждать перед повторным запросом кода. Берём из заголовка
+ * Retry-After ответа 429; если его нет — null (вызывающий решит сам).
+ */
+export function retryAfterSeconds(err: unknown): number | null {
+  if (err instanceof HTTPError) {
+    const raw = err.response.headers.get("Retry-After");
+    const n = raw ? parseInt(raw, 10) : NaN;
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return null;
+}
+
+export const tgSession = async () =>
+  TgSessionSchema.parse(await api.post("driver/auth/tg/session").json());
+/** POST, а не GET: в query-параметре pair_session оседал в access-логах. */
+export const tgPoll = async (pairSession: string, pollSecret: string) =>
+  TgPollSchema.parse(
+    await api.post("driver/auth/tg/poll", {
+      json: { pair_session: pairSession, poll_secret: pollSecret },
+    }).json(),
+  );
+
+export const authRequest = async (phone: string) =>
+  AuthRequestSchema.parse(await api.post("driver/auth/request", { json: { phone } }).json());
+export const authVerify = async (phone: string, code: string) =>
+  VerifySchema.parse(await api.post("driver/auth/verify", { json: { phone, code } }).json());
+export const getBalance = async () =>
+  BalanceSchema.parse(await api.get("driver/balance").json());
+export const getBuckets = async () =>
+  BucketsSchema.parse(await api.get("driver/buckets").json());
+export const topup = async (bucket: string, amount: number, method: "qr" | "card",
+                            live = false) =>
+  TopupSchema.parse(await api.post("driver/topup", {
+    json: { bucket, amount, method, live },
+  }).json());
+export const getPaymentState = async (orderId: string) =>
+  PaymentStateSchema.parse(await api.get(`driver/payment/${orderId}`).json());
+export const getPayments = async () =>
+  PaymentsSchema.parse(await api.get("driver/payments").json());
+export const getCommission = async () =>
+  CommissionSchema.parse(await api.get("driver/commission").json());
+
+/** Исход учебного платежа. Работает только под просмотром сотрудника. */
+export const mockPayOutcome = async (
+  orderId: string, outcome: "paid" | "rejected" | "expired" | "reversed",
+) => PaymentStateSchema.parse(
+  await api.post(`driver/mock-pay/${orderId}`, { json: { outcome } }).json(),
+);
+
+export const StatementSchema = z.object({
+  items: z.array(z.object({
+    date: z.string().nullable(),
+    title: z.string(),
+    description: z.string().default(""),
+    amount: z.number(),
+    kind: z.enum(["charges", "payments", "fines"]),
+    // Карточка штрафа, если постановление у нас есть. null — строка не ссылка.
+    fine_id: z.number().nullable().default(null),
+  })),
+  from: z.string(),
+  to: z.string(),
+  kind: z.string(),
+});
+export type StatementKind = "all" | "charges" | "payments" | "fines";
+
+/** Выписка по счёту за период. Даты — ISO (ГГГГ-ММ-ДД), как их понимает бэкенд. */
+export const getStatement = async (from: string, to: string, kind: StatementKind) =>
+  StatementSchema.parse(await api.get("driver/statement", {
+    searchParams: { from, to, kind },
+  }).json());
+
+const FineBriefSchema = z.object({
+  id: z.number(),
+  number: z.string(),
+  date: z.string().nullable(),
+  article: z.string(),
+  address: z.string().default(""),
+  car_number: z.string().default(""),
+  // Сумма, начисленная ВОДИТЕЛЮ. Номинала постановления, скидки и расчётов парка
+  // с ГИБДД в приложении нет намеренно — водителю нужен факт штрафа и сумма.
+  amount: z.number(),
+  // Погашен ли штраф водителем перед парком. Постановление парк гасит авансом,
+  // и на этот признак его расчёты не влияют.
+  settled: z.enum(["owed", "paid", "not_charged", "cancelled", "unknown"]),
+  cancelled: z.boolean().default(false),
+  has_photo: z.boolean().default(false),
+});
+export type FineBrief = z.infer<typeof FineBriefSchema>;
+
+export const FinesSchema = z.object({
+  items: z.array(FineBriefSchema),
+  open_count: z.number(),
+  // Долг по штрафам из 1С — тот же, что на главном экране (отрицательный).
+  debt: z.number(),
+});
+
+export const FineDetailSchema = FineBriefSchema.extend({
+  post_date: z.string().nullable().default(null),
+  speed: z.number().nullable().default(null),
+  speed_limit: z.number().nullable().default(null),
+  speed_excess: z.number().nullable().default(null),
+  camera: z.string().default(""),
+  // Ссылки подписанные и живут час — держать их в кэше дольше нет смысла.
+  photos: z.array(z.string()).default([]),
+  document: z.string().nullable().default(null),
+});
+
+export const getFines = async (status: "all" | "open") =>
+  FinesSchema.parse(await api.get("driver/fines", { searchParams: { status } }).json());
+
+export const getFine = async (id: number) =>
+  FineDetailSchema.parse(await api.get(`driver/fines/${id}`).json());
+
+export const NotificationSchema = z.object({
+  id: z.number(),
+  kind: z.string(),
+  title: z.string(),
+  body: z.string(),
+  url: z.string().nullable().default(null),
+  created_at: z.string().nullable().default(null),
+  read_at: z.string().nullable().default(null),
+});
+export type DriverNotification = z.infer<typeof NotificationSchema>;
+
+export const NotificationsSchema = z.object({
+  items: z.array(NotificationSchema),
+  unread: z.number(),
+});
+
+export const getNotifications = async () =>
+  NotificationsSchema.parse(await api.get("driver/notifications").json());
+
+/** Отметить прочитанным. Без списка — «всё»: так отмечает открытие ленты. */
+export const markNotificationsRead = async (ids?: number[], source: "app" | "push" = "app") =>
+  api.post("driver/notifications/read", { json: { ids: ids ?? null, source } }).json();
+
+export const PushKeySchema = z.object({ key: z.string(), enabled: z.boolean() });
+
+export const getPushKey = async () =>
+  PushKeySchema.parse(await api.get("driver/push/key").json());
+
+export const subscribePush = async (sub: { endpoint: string; p256dh: string; auth: string }) =>
+  api.post("driver/push/subscribe", { json: sub }).json();
+
+export const unsubscribePush = async (endpoint: string) =>
+  api.post("driver/push/unsubscribe", { json: { endpoint } }).json();
+
+/** Пробное уведомление себе. Доступно только при просмотре сотрудником. */
+export const sendTestPush = async () => api.post("driver/push/test").json();

driver-pwa/frontend/src/api/staff.ts

@@ -0,0 +1,85 @@
+import ky from "ky";
+import { z } from "zod";
+import { pushEntry, shortPath } from "@/lib/reqlog";
+import { API_BASE } from "./client";
+import { useStaff } from "@/store/staff";
+
+/**
+ * Учётка CRM внутри приложения водителя — только ради просмотра от чужого лица.
+ *
+ * Свой экземпляр ky, а не общий `api`: тот подставляет ВОДИТЕЛЬСКИЙ токен, и на
+ * запросе к /driver/staff/* заголовок оказался бы чужим. Плюс 401 здесь означает
+ * «протух сеанс сотрудника», а не «водителя выкинуло».
+ */
+const started = new WeakMap<Request, number>();
+
+const staffApi = ky.create({
+  prefixUrl: API_BASE,
+  timeout: 30_000,
+  hooks: {
+    beforeRequest: [
+      (request) => {
+        started.set(request, performance.now());
+        const token = useStaff.getState().token;
+        if (token) request.headers.set("Authorization", `Bearer ${token}`);
+      },
+    ],
+    afterResponse: [
+      (request, _o, response) => {
+        pushEntry({
+          method: request.method, path: shortPath(request.url), status: response.status,
+          ms: Math.round(performance.now() - (started.get(request) ?? performance.now())),
+        });
+      },
+    ],
+    beforeError: [
+      (error) => {
+        if (error.response?.status === 401) useStaff.getState().clear();
+        return error;
+      },
+    ],
+  },
+});
+
+export const LoginSchema = z.object({
+  access_token: z.string().nullable().default(null),
+  requires_2fa: z.boolean().default(false),
+  partial_token: z.string().nullable().default(null),
+});
+
+export const DriverBriefSchema = z.object({
+  id: z.number(),
+  fio: z.string(),
+  phone: z.string(),
+  status: z.string(),
+  driver_kind: z.string(),
+});
+export type DriverBrief = z.infer<typeof DriverBriefSchema>;
+
+export const DriversSchema = z.object({ drivers: z.array(DriverBriefSchema) });
+export const ImpersonateSchema = z.object({
+  token: z.string(),
+  driver: DriverBriefSchema,
+});
+
+/** Логин CRM. Форма, а не JSON: эндпоинт принимает OAuth2PasswordRequestForm. */
+export const staffLogin = async (username: string, password: string) => {
+  const body = new URLSearchParams({ username, password });
+  return LoginSchema.parse(await staffApi.post("auth/login", { body }).json());
+};
+
+/** Второй шаг, если у учётки включена двухфакторка. */
+export const staffLogin2fa = async (partialToken: string, code: string) =>
+  LoginSchema.parse(await staffApi.post("auth/2fa", {
+    json: { partial_token: partialToken, code, remember_device: false },
+  }).json());
+
+export const searchDrivers = async (q: string) =>
+  DriversSchema.parse(await staffApi.get("driver/staff/drivers", {
+    searchParams: { q, limit: 30 },
+  }).json());
+
+export const impersonate = async (driverId: number) =>
+  ImpersonateSchema.parse(await staffApi.post("driver/staff/impersonate", {
+    json: { driver_id: driverId },
+  }).json());

driver-pwa/frontend/src/components/AppHeader.tsx

@@ -0,0 +1,41 @@
+import { useNavigate } from "react-router-dom";
+import { useRef } from "react";
+
+import { NotificationsBell } from "@/pages/NotificationsPage";
+
+/** Долгое нажатие, после которого открывается вход для сотрудника. */
+const LONG_PRESS_MS = 1500;
+
+/** Колокольчик по умолчанию выключен: он тянет счётчик уведомлений, а шапка
+ *  стоит на каждом экране — незачем ходить за ним с оплаты или из штрафа.
+ *  Включается там, откуда водитель и правда пойдёт читать: на главной. */
+export function AppHeader({ bell = false }: { bell?: boolean } = {}) {
+  const nav = useNavigate();
+  const timer = useRef<number | null>(null);
+
+  // Ссылки «для сотрудника» на экранах водителя нет намеренно: водителю она
+  // ничего не даёт, а место занимает. Но сотруднику, уже вошедшему водителем,
+  // адрес /dev иначе приходится набирать руками — отсюда долгий тап по названию.
+  const start = () => {
+    timer.current = window.setTimeout(() => nav("/dev"), LONG_PRESS_MS);
+  };
+  const cancel = () => {
+    if (timer.current) window.clearTimeout(timer.current);
+    timer.current = null;
+  };
+
+  return (
+    <header className="mb-4 flex items-center justify-between">
+      <span
+        className="text-sm font-bold select-none"
+        onPointerDown={start}
+        onPointerUp={cancel}
+        onPointerLeave={cancel}
+        onContextMenu={(e) => e.preventDefault()}
+      >
+        Премиум Водитель
+      </span>
+      {bell && <NotificationsBell />}
+    </header>
+  );
+}

driver-pwa/frontend/src/components/DriverPicker.tsx

@@ -0,0 +1,86 @@
+import { useEffect, useState } from "react";
+import { Search } from "lucide-react";
+import { toast } from "sonner";
+import { apiErrorText } from "@/api/driver";
+import { impersonate, searchDrivers, type DriverBrief } from "@/api/staff";
+import { useAuth } from "@/store/auth";
+import { Spinner } from "@/components/Spinner";
+
+/**
+ * Выбор водителя, от лица которого смотреть. Один компонент на два места:
+ * первый вход сотрудника (/dev) и смена водителя на вкладке «Отладка».
+ */
+export function DriverPicker({ onPicked }: { onPicked: (d: DriverBrief) => void }) {
+  const startImpersonation = useAuth((s) => s.startImpersonation);
+  const [q, setQ] = useState("");
+  const [list, setList] = useState<DriverBrief[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [busyId, setBusyId] = useState<number | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    setLoading(true);
+    // Пауза перед запросом: иначе поиск уходит на каждую букву, и ответы
+    // возвращаются вперемешку — список прыгает.
+    const t = setTimeout(() => {
+      searchDrivers(q)
+        .then((r) => { if (alive) setList(r.drivers); })
+        .catch(async (e) => { if (alive) toast.error(await apiErrorText(e, "Не удалось найти водителей")); })
+        .finally(() => { if (alive) setLoading(false); });
+    }, 300);
+    return () => { alive = false; clearTimeout(t); };
+  }, [q]);
+
+  async function pick(d: DriverBrief) {
+    setBusyId(d.id);
+    try {
+      const r = await impersonate(d.id);
+      startImpersonation(r.token, r.driver.id, r.driver.fio);
+      onPicked(r.driver);
+    } catch (e: unknown) {
+      toast.error(await apiErrorText(e, "Не удалось открыть приложение за водителя"));
+    } finally {
+      setBusyId(null);
+    }
+  }
+
+  return (
+    <div>
+      <div className="card flex items-center gap-2 px-3 py-2.5 mb-3 bg-surface">
+        <Search size={16} className="text-muted shrink-0" />
+        <input
+          autoFocus
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+          placeholder="ФИО, телефон или id"
+          className="w-full text-base bg-transparent outline-none"
+        />
+      </div>
+
+      {loading ? (
+        <div className="flex justify-center py-8"><Spinner /></div>
+      ) : list.length === 0 ? (
+        <p className="text-muted text-sm text-center py-8">Никого не нашли</p>
+      ) : (
+        <div className="card divide-y divide-line">
+          {list.map((d) => (
+            <button
+              key={d.id}
+              disabled={busyId !== null}
+              onClick={() => pick(d)}
+              className="w-full text-left px-4 py-3 flex items-center justify-between gap-3 disabled:opacity-50"
+            >
+              <span className="min-w-0">
+                <span className="block text-sm font-semibold truncate">{d.fio}</span>
+                <span className="block text-muted text-xs truncate">
+                  #{d.id}{d.phone ? ` · ${d.phone}` : ""}{d.status ? ` · ${d.status}` : ""}
+                </span>
+              </span>
+              {busyId === d.id ? <Spinner /> : <span className="text-muted text-xs shrink-0">смотреть</span>}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

driver-pwa/frontend/src/components/ImpersonationBar.tsx

@@ -0,0 +1,34 @@
+import { useLocation, useNavigate } from "react-router-dom";
+import { Eye } from "lucide-react";
+import { useAuth } from "@/store/auth";
+
+/**
+ * Плашка «вы смотрите чужой экран». Видна на каждом экране и всегда, пока
+ * действует токен просмотра.
+ *
+ * Она не украшение: интерфейс в этом режиме неотличим от водительского — те же
+ * суммы, те же долги, та же история. Без постоянного напоминания легко принять
+ * чужой баланс за свой и, например, позвонить водителю с чужими цифрами.
+ */
+export function ImpersonationBar() {
+  const nav = useNavigate();
+  const loc = useLocation();
+  const { impersonated, driverName, driverId } = useAuth();
+  if (!impersonated) return null;
+  const onDebug = loc.pathname === "/debug";
+
+  return (
+    <div className="flex items-center gap-2 mb-3 px-3 py-2 rounded-xl2 border border-warn/40 bg-warn/10 text-warn text-xs">
+      <Eye size={14} className="shrink-0" />
+      <span className="min-w-0 truncate">
+        Смотрю как <b>{driverName ?? `водитель #${driverId}`}</b>
+      </span>
+      <button
+        className="ml-auto shrink-0 underline underline-offset-2"
+        onClick={() => nav(onDebug ? "/" : "/debug")}
+      >
+        {onDebug ? "к приложению" : "отладка"}
+      </button>
+    </div>
+  );
+}

driver-pwa/frontend/src/components/NotificationsPrompt.test.tsx

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+vi.mock("@/lib/push", () => ({
+  currentState: vi.fn(async () => "off"),
+  enable: vi.fn(async () => "on"),
+  installed: vi.fn(() => true),
+}));
+
+import { NotificationsPrompt } from "./NotificationsPrompt";
+import * as push from "@/lib/push";
+
+describe("предложение включить уведомления", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    vi.clearAllMocks();
+    vi.mocked(push.installed).mockReturnValue(true);
+    vi.mocked(push.currentState).mockResolvedValue("off");
+  });
+
+  it("установленному приложению предлагаем — своей карточкой, а не системным окном", async () => {
+    render(<NotificationsPrompt />);
+    expect(await screen.findByText("Сообщать о новом?")).toBeInTheDocument();
+    // Системное окно вызывается только по кнопке: оно показывается один раз за
+    // установку, и отказ браузер запоминает навсегда.
+    expect(push.enable).not.toHaveBeenCalled();
+    await userEvent.click(screen.getByRole("button", { name: "Включить" }));
+    expect(push.enable).toHaveBeenCalled();
+  });
+
+  it("во вкладке браузера не предлагаем: на iPhone это всё равно не работает", async () => {
+    vi.mocked(push.installed).mockReturnValue(false);
+    render(<NotificationsPrompt />);
+    expect(screen.queryByText("Сообщать о новом?")).not.toBeInTheDocument();
+  });
+
+  it("«не сейчас» откладывает на неделю, а не отказывает навсегда", async () => {
+    render(<NotificationsPrompt />);
+    await userEvent.click(await screen.findByRole("button", { name: "Не сейчас" }));
+    expect(screen.queryByText("Сообщать о новом?")).not.toBeInTheDocument();
+    const until = Number(localStorage.getItem("pp-push-prompt-later"));
+    const days = (until - Date.now()) / 86400_000;
+    expect(days).toBeGreaterThan(6.5);
+    expect(days).toBeLessThan(7.5);
+
+    // Пока срок не вышел — не показываем повторно.
+    render(<NotificationsPrompt />);
+    expect(screen.queryByText("Сообщать о новом?")).not.toBeInTheDocument();
+  });
+
+  it("уже включено — карточки нет", async () => {
+    vi.mocked(push.currentState).mockResolvedValue("on");
+    render(<NotificationsPrompt />);
+    expect(screen.queryByText("Сообщать о новом?")).not.toBeInTheDocument();
+  });
+});

driver-pwa/frontend/src/components/NotificationsPrompt.tsx

@@ -0,0 +1,84 @@
+import { useEffect, useState } from "react";
+import { Bell } from "lucide-react";
+import { toast } from "sonner";
+import { currentState, enable, installed, type PushState } from "@/lib/push";
+
+/**
+ * Предложение включить уведомления — после установки приложения.
+ *
+ * Почему своя карточка, а не сразу системное окно. Системное показывается ОДИН
+ * раз за установку: отказ браузер запоминает навсегда, и переспросить нельзя.
+ * Своё предложение отказа не стоит — «не сейчас» просто откладывает его на
+ * неделю, и вернуться к разговору можно.
+ *
+ * Почему после установки, а не на входе. На iPhone уведомления работают только в
+ * установленном приложении, а человеку, который ещё не решил, нужен ли ему этот
+ * сайт вообще, вопрос про уведомления мешает.
+ */
+const DELAY_KEY = "pp-push-prompt-later";
+const REMIND_AFTER_DAYS = 7;
+
+function postponed(): boolean {
+  const raw = localStorage.getItem(DELAY_KEY);
+  if (!raw) return false;
+  const until = Number(raw);
+  return Number.isFinite(until) && Date.now() < until;
+}
+
+export function NotificationsPrompt() {
+  const [state, setState] = useState<PushState | null>(null);
+  const [hidden, setHidden] = useState(postponed());
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    let alive = true;
+    const refresh = () => currentState().then((s) => { if (alive) setState(s); });
+    refresh();
+    // Приложение только что поставили на домашний экран — самое время спросить,
+    // человек как раз занят настройкой.
+    const onInstalled = () => { setHidden(false); refresh(); };
+    window.addEventListener("appinstalled", onInstalled);
+    return () => { alive = false; window.removeEventListener("appinstalled", onInstalled); };
+  }, []);
+
+  // Показываем только установленному приложению и только пока разрешение не
+  // спрашивали: «включить» для остальных живёт строкой внизу экрана.
+  if (hidden || state !== "off" || !installed()) return null;
+
+  async function turnOn() {
+    setBusy(true);
+    try {
+      const next = await enable();
+      setState(next);
+      if (next !== "on") toast.error("Уведомления не включились");
+    } catch {
+      toast.error("Не удалось включить уведомления");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  function later() {
+    localStorage.setItem(DELAY_KEY, String(Date.now() + REMIND_AFTER_DAYS * 86400_000));
+    setHidden(true);
+  }
+
+  return (
+    <div className="card p-4 mb-3">
+      <div className="flex items-start gap-3">
+        <Bell size={18} strokeWidth={1.5} className="text-muted shrink-0 mt-0.5" />
+        <div className="min-w-0">
+          <p className="text-sm font-semibold mb-1">Сообщать о новом?</p>
+          <p className="text-muted text-xs">
+            Пришлём уведомление, когда появится новый штраф или когда пополнение
+            дойдёт до баланса.
+          </p>
+        </div>
+      </div>
+      <div className="flex gap-2 mt-3">
+        <button className="btn-primary" disabled={busy} onClick={turnOn}>Включить</button>
+        <button className="btn-ghost" disabled={busy} onClick={later}>Не сейчас</button>
+      </div>
+    </div>
+  );
+}

driver-pwa/frontend/src/components/NotificationsRow.test.tsx

@@ -0,0 +1,40 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+vi.mock("@/lib/push", () => ({
+  currentState: vi.fn(async () => "off"),
+  enable: vi.fn(async () => "on"),
+}));
+
+import { NotificationsRow } from "./NotificationsRow";
+import * as push from "@/lib/push";
+
+describe("строка уведомлений", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(push.currentState).mockResolvedValue("off");
+  });
+
+  it("выключенные уведомления предлагает включить", async () => {
+    render(<NotificationsRow />);
+    await userEvent.click(await screen.findByRole("button", { name: /Включить уведомления/ }));
+    expect(push.enable).toHaveBeenCalled();
+  });
+
+  it("включённые — строки нет: отказаться от них мы не предлагаем", async () => {
+    // Отключение остаётся системным (настройки телефона или сайта в браузере) —
+    // рядом с балансом кнопка «выключить» только подталкивала бы к отказу.
+    vi.mocked(push.currentState).mockResolvedValue("on");
+    const { container } = render(<NotificationsRow />);
+    await vi.waitFor(() => expect(container.textContent).toBe(""));
+    expect(screen.queryByText(/Выключить/)).not.toBeInTheDocument();
+  });
+
+  it("запрещённые в браузере — объясняем, а не предлагаем кнопку", async () => {
+    vi.mocked(push.currentState).mockResolvedValue("denied");
+    render(<NotificationsRow />);
+    expect(await screen.findByText(/запрещены в настройках браузера/)).toBeInTheDocument();
+    expect(screen.queryByRole("button")).not.toBeInTheDocument();
+  });
+});

driver-pwa/frontend/src/components/NotificationsRow.tsx

@@ -0,0 +1,69 @@
+import { useEffect, useState } from "react";
+import { Bell } from "lucide-react";
+import { toast } from "sonner";
+import { currentState, enable, type PushState } from "@/lib/push";
+
+/**
+ * Включение уведомлений — одной строкой на главном экране.
+ *
+ * Не всплывающим окном на входе: разрешение спрашивается один раз за установку,
+ * и потраченная впустую попытка закрывает канал навсегда. Здесь водитель жмёт
+ * сам, увидев, ради чего.
+ *
+ * Выключения здесь НЕТ намеренно (решение владельца 19.08.2026). Включённые
+ * уведомления — это ровно те два события, ради которых приложение и открывают;
+ * кнопка «выключить» рядом с балансом только предлагает от них отказаться.
+ * Способ отключить остаётся системный: настройки уведомлений телефона или
+ * настройки сайта в браузере — там же, где человек управляет всеми остальными
+ * приложениями.
+ */
+export function NotificationsRow() {
+  const [state, setState] = useState<PushState | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    let alive = true;
+    currentState().then((s) => { if (alive) setState(s); });
+    return () => { alive = false; };
+  }, []);
+
+  // Включено — строки нет: предлагать нечего.
+  if (state === null || state === "unsupported" || state === "on") return null;
+
+  async function turnOn() {
+    setBusy(true);
+    try {
+      setState(await enable());
+    } catch {
+      toast.error("Не удалось включить уведомления");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (state === "needs-install") {
+    return (
+      <p className="text-muted text-xs text-center mt-6">
+        Чтобы получать уведомления о штрафах и платежах, добавьте приложение на домашний экран.
+      </p>
+    );
+  }
+
+  if (state === "denied") {
+    return (
+      <p className="text-muted text-xs text-center mt-6">
+        Уведомления запрещены в настройках браузера — включить их можно только там.
+      </p>
+    );
+  }
+
+  return (
+    <button
+      className="flex items-center justify-center gap-1.5 text-muted text-xs mt-6 w-full"
+      disabled={busy}
+      onClick={turnOn}
+    >
+      <Bell size={15} /> Включить уведомления
+    </button>
+  );
+}

driver-pwa/frontend/src/components/Segment.tsx

@@ -0,0 +1,19 @@
+interface Props { value: string; options: { value: string; label: string }[]; onChange: (v: string) => void; }
+export function Segment({ value, options, onChange }: Props) {
+  return (
+    <div className="flex gap-1.5">
+      {options.map((o) => (
+        <button
+          key={o.value}
+          type="button"
+          onClick={() => onChange(o.value)}
+          className={`flex-1 py-2.5 rounded-xl2 text-xs border ${
+            value === o.value ? "bg-ink text-white border-ink font-bold" : "bg-surface border-line text-muted"
+          }`}
+        >
+          {o.label}
+        </button>
+      ))}
+    </div>
+  );
+}

driver-pwa/frontend/src/components/Sheet.tsx

@@ -0,0 +1,52 @@
+import { useEffect, type ReactNode } from "react";
+
+/**
+ * Шторка снизу — выбор, который не уводит с экрана.
+ *
+ * Отдельным экраном такой выбор стоит дороже, чем кажется: человек теряет из
+ * виду то, ради чего пришёл (баланс), и возвращается кнопкой «назад», которой на
+ * телефоне ещё надо попасть. Здесь выбор происходит поверх экрана, а закрывается
+ * тапом мимо, кнопкой и клавишей Escape.
+ */
+export function Sheet({ open, onClose, title, children }: {
+  open: boolean;
+  onClose: () => void;
+  title: string;
+  children: ReactNode;
+}) {
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
+    document.addEventListener("keydown", onKey);
+    // Фон не должен уезжать под шторкой: иначе список категорий листает страницу.
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = prev;
+    };
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-end justify-center">
+      <button
+        aria-label="Закрыть"
+        className="absolute inset-0 bg-ink/40"
+        onClick={onClose}
+      />
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        className="relative w-full max-w-md bg-surface rounded-t-2xl pb-6 pt-2 max-h-[80vh] overflow-y-auto"
+      >
+        {/* Полоска-ручка: на телефоне она объясняет, что панель тянется, лучше любой подписи. */}
+        <div className="mx-auto mb-3 h-1 w-10 rounded-full bg-line" />
+        <p className="px-5 pb-2 text-sm font-bold">{title}</p>
+        {children}
+      </div>
+    </div>
+  );
+}

driver-pwa/frontend/src/components/Spinner.tsx

@@ -0,0 +1,3 @@
+export function Spinner() {
+  return <span className="inline-block w-3.5 h-3.5 border-2 border-line border-t-ink rounded-full animate-spin" />;
+}

driver-pwa/frontend/src/components/Statement.tsx

@@ -0,0 +1,153 @@
+import { useQuery } from "@tanstack/react-query";
+import { useNavigate } from "react-router-dom";
+import { ChevronRight, Image as ImageIcon } from "lucide-react";
+import { getFines, getStatement, type StatementKind } from "@/api/driver";
+import { fineStatusText, isOwed } from "@/lib/fineStatus";
+import { formatDate, formatMoney } from "@/lib/format";
+import { OperationIcon } from "@/components/operationIcon";
+import { Spinner } from "@/components/Spinner";
+
+const FILTERS: { key: StatementKind; label: string }[] = [
+  { key: "all", label: "Все операции" },
+  { key: "charges", label: "Начисления" },
+  { key: "payments", label: "Пополнения" },
+  { key: "fines", label: "Штрафы" },
+];
+
+/**
+ * Нижняя половина главного экрана: за что списаны деньги.
+ *
+ * Три фильтра показывают проводки 1С, а «Штрафы» — сами постановления, а не
+ * проводки по ним. Разница существенная: штраф, который водитель оплатил сам,
+ * парк не выставлял, проводки по нему нет, и в выписке он бы не появился вовсе.
+ * Отдельного экрана штрафов нет намеренно — два списка одного и того же в разных
+ * местах сбивают с толку.
+ */
+export function Statement({ from, to, kind, onFrom, onTo, onKind }: {
+  from: string;
+  to: string;
+  kind: StatementKind;
+  onFrom: (v: string) => void;
+  onTo: (v: string) => void;
+  onKind: (k: StatementKind) => void;
+}) {
+  const nav = useNavigate();
+  const showFines = kind === "fines";
+
+  const ops = useQuery({
+    queryKey: ["statement", from, to, kind],
+    queryFn: () => getStatement(from, to, kind),
+    enabled: !showFines,
+  });
+  const fines = useQuery({
+    queryKey: ["fines"],
+    queryFn: () => getFines("all"),
+    enabled: showFines,
+  });
+
+  const active = showFines ? fines : ops;
+  // Период распространяется и на штрафы: иначе календарь над списком стоял бы,
+  // ничего не меняя, — это хуже, чем его отсутствие.
+  const fineRows = (fines.data?.items ?? []).filter(
+    (f) => !f.date || (f.date >= from && f.date <= to),
+  );
+  const opRows = ops.data?.items ?? [];
+  const isEmpty = showFines ? fineRows.length === 0 : opRows.length === 0;
+  const rowCls = "w-full flex items-center gap-3 py-2.5 border-b border-line last:border-0 text-left";
+
+  return (
+    <div>
+      <div className="flex items-center gap-2 mb-3">
+        {/* Нативный date-input: календарь телефона знакомее любого нашего. */}
+        <input type="date" value={from} max={to} onChange={(e) => onFrom(e.target.value)}
+               aria-label="Начало периода"
+               className="card flex-1 px-3 py-2 text-xs bg-surface" />
+        <span className="text-muted text-xs">—</span>
+        <input type="date" value={to} min={from} onChange={(e) => onTo(e.target.value)}
+               aria-label="Конец периода"
+               className="card flex-1 px-3 py-2 text-xs bg-surface" />
+      </div>
+
+      <div className="flex gap-1.5 mb-3 overflow-x-auto">
+        {FILTERS.map((f) => (
+          <button
+            key={f.key}
+            onClick={() => onKind(f.key)}
+            className={`shrink-0 px-3 py-2 rounded-xl2 text-xs border ${
+              f.key === kind ? "border-ink bg-surface font-semibold" : "border-line text-muted"
+            }`}
+          >
+            {f.label}
+          </button>
+        ))}
+      </div>
+
+      {active.isLoading ? (
+        <div className="flex justify-center py-8"><Spinner /></div>
+      ) : active.isError ? (
+        <div className="text-center py-6">
+          <p className="text-muted text-sm mb-3">Не удалось загрузить операции</p>
+          <button className="btn-ghost" onClick={() => active.refetch()}>Повторить</button>
+        </div>
+      ) : isEmpty ? (
+        <p className="text-muted text-sm text-center py-8">
+          {showFines ? "Штрафов за период нет" : "Нет операций за выбранный период"}
+        </p>
+      ) : showFines ? (
+        <div>
+          {fineRows.map((f) => (
+            // Штраф ведёт в карточку: там фотография с камеры, место и скорость.
+            <button key={f.id} className={rowCls} onClick={() => nav(`/fines/${f.id}`)}>
+              <OperationIcon title="Штраф" />
+              <span className="min-w-0 flex-1">
+                <span className="flex items-center gap-1.5 text-xs font-semibold">
+                  {formatDate(f.date)}
+                  {f.has_photo && <ImageIcon size={12} strokeWidth={1.5} className="text-muted" />}
+                </span>
+                <span className="block text-sm truncate">{f.article}</span>
+                <span className="block text-muted text-xs">
+                  {fineStatusText(f)}{f.car_number ? ` · ${f.car_number}` : ""}
+                </span>
+              </span>
+              <b className={`shrink-0 ${isOwed(f) ? "text-neg" : "text-muted"}`}>
+                {formatMoney(f.amount)}
+              </b>
+              <ChevronRight size={16} className="text-muted shrink-0" />
+            </button>
+          ))}
+        </div>
+      ) : (
+        <div>
+          {opRows.map((op, idx) => {
+            const row = (
+              <>
+                <OperationIcon title={op.title} />
+                <span className="min-w-0 flex-1">
+                  {/* Дата — первой строкой: в выписке ищут «что было 12-го», а не
+                      название операции. */}
+                  <span className="block text-xs font-semibold">{formatDate(op.date)}</span>
+                  <span className="block text-sm">{op.title}</span>
+                  {op.description && (
+                    <span className="block text-muted text-xs truncate">{op.description}</span>
+                  )}
+                </span>
+                <b className={`shrink-0 ${op.amount < 0 ? "text-neg" : "text-pos"}`}>
+                  {formatMoney(op.amount)}
+                </b>
+              </>
+            );
+            return op.fine_id != null ? (
+              <button key={`${op.date}-${idx}`} className={rowCls}
+                      onClick={() => nav(`/fines/${op.fine_id}`)}>
+                {row}
+                <ChevronRight size={16} className="text-muted shrink-0" />
+              </button>
+            ) : (
+              <div key={`${op.date}-${idx}`} className={rowCls}>{row}</div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

driver-pwa/frontend/src/components/operationIcon.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import { operationIcon } from "./operationIcon";
+
+/** Названия — настоящие теги 1С из выписки (finance_ledger_entries.tag). */
+describe("значок операции", () => {
+  it("разные виды операций различаются", () => {
+    const names = [
+      "Аренда автомобиля",
+      "Пени",
+      "Штраф ГИБДД",
+      "Пополнение баланса через мобильное приложение",
+      "ДТП",
+      "Перевод с депозита на баланс",
+    ].map((t) => operationIcon(t));
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it("штраф ГИБДД и штраф компании — один значок: для водителя это одно и то же", () => {
+    expect(operationIcon("Штраф ГИБДД")).toBe(operationIcon("Штраф компании"));
+  });
+
+  it("незнакомый тег получает нейтральный значок, а не пустоту", () => {
+    expect(operationIcon("Списание за что-то новое")).toBeTruthy();
+  });
+});

driver-pwa/frontend/src/components/operationIcon.tsx

@@ -0,0 +1,53 @@
+import {
+  Banknote, Car, Flag, Gavel, Gift, HandCoins, Percent, PiggyBank, Receipt,
+  RefreshCcw, ShieldAlert, TriangleAlert, Wrench, type LucideIcon,
+} from "lucide-react";
+
+/**
+ * Значок операции в выписке — по тегу 1С, а не по знаку суммы.
+ *
+ * Список сливается в стену текста: за неделю у активного водителя два десятка
+ * строк, и половина из них — одинаковая по виду «аренда автомобиля». Значок
+ * даёт зацепку для глаза, чтобы взгляд находил нужное, не читая каждую строку.
+ *
+ * Общий компонент, а не иконка на месте применения: тот же приём, что в складе
+ * CRM (modules/warehouse/categoryIcons.tsx). Разложены по местам — и размеры с
+ * толщиной линии разъезжаются при первой же правке.
+ *
+ * Монохромные намеренно: цвет в этом списке уже занят и означает направление
+ * денег (красное — списали, зелёное — пришло). Цветной значок спорил бы с ним.
+ */
+const BY_TAG: [RegExp, LucideIcon][] = [
+  [/аренда/i, Car],
+  [/пени/i, Percent],
+  [/штраф/i, Gavel],
+  [/дтп|повреждени/i, TriangleAlert],
+  [/депозит/i, PiggyBank],
+  [/пополнение|оплата/i, Banknote],
+  [/ремонт|запчаст/i, Wrench],
+  [/компенсац/i, HandCoins],
+  [/акци|бонус|подар/i, Gift],
+  [/коррекц|сторно|перерасч/i, RefreshCcw],
+  [/страхов/i, ShieldAlert],
+  [/остаток|opening/i, Flag],
+];
+
+export function operationIcon(title: string): LucideIcon {
+  for (const [re, icon] of BY_TAG) {
+    if (re.test(title)) return icon;
+  }
+  return Receipt;
+}
+
+/** Значок в рамке — как в списке склада: одинаковый размер у всех строк. */
+export function OperationIcon({ title }: { title: string }) {
+  const Icon = operationIcon(title);
+  return (
+    <span
+      aria-hidden
+      className="shrink-0 w-8 h-8 rounded-xl2 border border-line bg-canvas flex items-center justify-center text-muted"
+    >
+      <Icon size={16} strokeWidth={1.5} />
+    </span>
+  );
+}

driver-pwa/frontend/src/hooks/usePairPoll.test.tsx

@@ -0,0 +1,43 @@
+// src/hooks/usePairPoll.test.tsx
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { usePairPoll } from "./usePairPoll";
+import * as driver from "@/api/driver";
+import { useAuth } from "@/store/auth";
+
+beforeEach(() => { useAuth.getState().clear(); vi.restoreAllMocks(); });
+
+describe("usePairPoll", () => {
+  it("sets session on authenticated", async () => {
+    vi.spyOn(driver, "tgPoll").mockResolvedValue({ status: "authenticated", token: "T", driver_id: 7 } as any);
+    const { result } = renderHook(() => usePairPoll("SESS", "SEC"));
+    await waitFor(() => expect(result.current.status).toBe("authenticated"));
+    expect(useAuth.getState().token).toBe("T");
+    expect(useAuth.getState().driverId).toBe(7);
+  });
+  it("stays pending then expired", async () => {
+    vi.spyOn(driver, "tgPoll").mockResolvedValue({ status: "expired" } as any);
+    const { result } = renderHook(() => usePairPoll("SESS", "SEC"));
+    await waitFor(() => expect(result.current.status).toBe("expired"));
+  });
+  it("does nothing when session is null", () => {
+    const spy = vi.spyOn(driver, "tgPoll");
+    const { result } = renderHook(() => usePairPoll(null, "SEC"));
+    expect(result.current.status).toBe("pending");
+    expect(spy).not.toHaveBeenCalled();
+  });
+  it("does not poll without the secret half of the key", () => {
+    // pair_session уходит боту в deep-link и оседает в логах; одной его половины
+    // для получения токена быть недостаточно.
+    const spy = vi.spyOn(driver, "tgPoll");
+    const { result } = renderHook(() => usePairPoll("SESS", null));
+    expect(result.current.status).toBe("pending");
+    expect(spy).not.toHaveBeenCalled();
+  });
+  it("sends both halves to the backend", async () => {
+    const spy = vi.spyOn(driver, "tgPoll").mockResolvedValue({ status: "expired" } as any);
+    const { result } = renderHook(() => usePairPoll("SESS", "SEC"));
+    await waitFor(() => expect(result.current.status).toBe("expired"));
+    expect(spy).toHaveBeenCalledWith("SESS", "SEC");
+  });
+});

driver-pwa/frontend/src/hooks/usePairPoll.ts

@@ -0,0 +1,49 @@
+// src/hooks/usePairPoll.ts
+import { useEffect, useRef, useState } from "react";
+import { tgPoll } from "@/api/driver";
+import { useAuth } from "@/store/auth";
+
+type Status = "pending" | "authenticated" | "expired";
+const INTERVAL_MS = 2000;
+const TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Опрос pairing-сессии. Нужны ОБЕ половины ключа: `pairSession` уходит боту в
+ * deep-link, `pollSecret` остаётся только здесь — знать одну сессию (например,
+ * подсмотрев её в access-логе) для получения токена уже недостаточно.
+ */
+export function usePairPoll(pairSession: string | null,
+                            pollSecret: string | null): { status: Status } {
+  const [status, setStatus] = useState<Status>("pending");
+  const setSession = useAuth((s) => s.setSession);
+  const startedAt = useRef<number>(0);
+
+  useEffect(() => {
+    if (!pairSession || !pollSecret) return;
+    let alive = true;
+    let timer: ReturnType<typeof setTimeout>;
+    startedAt.current = Date.now();
+
+    const tick = async () => {
+      if (!alive) return;
+      try {
+        const r = await tgPoll(pairSession, pollSecret);
+        if (!alive) return;
+        if (r.status === "authenticated") {
+          setSession(r.token, r.driver_id);
+          setStatus("authenticated");
+          return;
+        }
+        if (r.status === "expired") { setStatus("expired"); return; }
+      } catch {
+        // transient — keep polling until timeout
+      }
+      if (Date.now() - startedAt.current > TIMEOUT_MS) { setStatus("expired"); return; }
+      timer = setTimeout(tick, INTERVAL_MS);
+    };
+    tick();
+    return () => { alive = false; clearTimeout(timer); };
+  }, [pairSession, pollSecret, setSession]);
+
+  return { status };
+}

driver-pwa/frontend/src/hooks/usePaymentStatus.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { getPaymentState } from "@/api/driver";
+
+// финальные статусы: дальше опрашивать нечего, экран показывает итог —
+// оплачено, отказ, истёкший срок или ошибка
+const TERMINAL = new Set([
+  "PAID", "CONFIRMED", "REJECTED", "REVERSED", "REFUNDED",
+  "PARTIAL_REVERSED", "PARTIAL_REFUNDED",
+  "CANCELED", "AUTH_FAIL", "DEADLINE_EXPIRED", "ATTEMPTS_EXPIRED", "ERROR",
+]);
+
+export function usePaymentStatus(orderId: string) {
+  const query = useQuery({
+    queryKey: ["payment", orderId],
+    queryFn: () => getPaymentState(orderId),
+    refetchInterval: (q) => (q.state.data && TERMINAL.has(q.state.data.status) ? false : 1500),
+    // повтором здесь работает сам опрос через 1.5 с, а внутренние ретраи с backoff
+    // только оттягивают момент, когда сбой станет виден на экране
+    retry: false,
+  });
+
+  // серию неудач считаем сами: failureCount обнуляется в начале каждого опроса
+  // и о том, сколько раз подряд не ответил бэкенд, ничего не говорит
+  const [failStreak, setFailStreak] = useState(0);
+  useEffect(() => {
+    if (query.errorUpdatedAt) setFailStreak((n) => n + 1);
+  }, [query.errorUpdatedAt]);
+  useEffect(() => {
+    if (query.dataUpdatedAt) setFailStreak(0);
+  }, [query.dataUpdatedAt]);
+
+  // пока ни одного удачного ответа не было, на время запроса isError снова гаснет
+  // (react-query возвращает статус в pending) — экран бы моргал ожиданием на каждом опросе.
+  // отметки времени такого провала не дают и гаснут ровно тогда, когда пришли данные
+  const lastFailed = query.errorUpdatedAt > query.dataUpdatedAt;
+
+  return { ...query, failStreak, lastFailed };
+}

driver-pwa/frontend/src/index.css

@@ -0,0 +1,16 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+html, body, #root { height: 100%; }
+body { @apply bg-canvas text-ink font-sans antialiased; margin: 0; }
+button { font-family: inherit; }
+
+@layer components {
+  /* Кнопки повторяют сайт: действие — фирменным красным с белым текстом
+     (.s-btn--accent), второстепенное — белым с чернильным текстом и рамкой
+     (.s-btn--ghost). */
+  .btn-primary { @apply bg-accent text-white rounded-xl2 py-3.5 px-4 text-sm font-bold text-center w-full active:bg-accent-press disabled:opacity-50; }
+  .btn-ghost { @apply bg-surface border border-line text-ink rounded-xl2 py-3 px-4 text-sm font-semibold text-center w-full active:bg-canvas-soft; }
+  .card { @apply bg-surface border border-line rounded-2xl; }
+}

driver-pwa/frontend/src/lib/amount.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { keypadReduce, parseAmount, withCommission } from "./amount";
+
+describe("amount keypad", () => {
+  it("appends digits, ignores leading zero, caps length", () => {
+    expect(keypadReduce("0", "5")).toBe("5");
+    expect(keypadReduce("100", "0")).toBe("1000");
+    expect(keypadReduce("", "0")).toBe("");
+    expect(keypadReduce("999999", "9")).toBe("999999");
+  });
+  it("backspace removes last digit", () => {
+    expect(keypadReduce("105", "back")).toBe("10");
+    expect(keypadReduce("", "back")).toBe("");
+  });
+  it("withCommission computes total at given rate", () => {
+    expect(withCommission(1000, 0.052)).toEqual({ commission: 52, total: 1052 });
+    expect(withCommission(333, 0.052)).toEqual({ commission: 17.32, total: 350.32 });
+  });
+  it("separator key builds kopecks — раньше клавиша была нарисована, но не работала", () => {
+    expect(keypadReduce("100", ",")).toBe("100,");
+    expect(keypadReduce("100,", "5")).toBe("100,5");
+    expect(keypadReduce("100,5", "2")).toBe("100,52");
+    expect(keypadReduce("100,52", "9")).toBe("100,52");   // копеек ровно две
+    expect(keypadReduce("100,52", ",")).toBe("100,52");   // второй разделитель не нужен
+    expect(keypadReduce("", ",")).toBe("0,");
+    expect(keypadReduce("100,5", "back")).toBe("100,");
+  });
+  it("parseAmount reads the keypad string", () => {
+    expect(parseAmount("100,52")).toBe(100.52);
+    expect(parseAmount("100,")).toBe(100);
+    expect(parseAmount("")).toBe(0);
+  });
+});

driver-pwa/frontend/src/lib/amount.ts

@@ -0,0 +1,40 @@
+const MAX_DIGITS = 6;   // целая часть
+const SEP = ",";        // русский разделитель — как на клавише
+
+/**
+ * Одно нажатие клавиатуры суммы.
+ *
+ * Разделитель раньше был нарисован на клавише, но ничего не делал: `press`
+ * молча игнорировал его, а `keypadReduce` принимал только цифры. Заплатить
+ * точный долг вроде 1234,56 было нечем.
+ */
+export function keypadReduce(current: string, key: string): string {
+  if (key === "back") return current.slice(0, -1);
+  if (key === SEP || key === "." || key === "·") {
+    if (current.includes(SEP)) return current;      // второй разделитель не нужен
+    return current === "" ? "0" + SEP : current + SEP;
+  }
+  if (!/^\d$/.test(key)) return current;
+  const [whole, frac] = current.split(SEP);
+  if (frac !== undefined) {
+    if (frac.length >= 2) return current;           // копеек ровно две
+    return `${whole}${SEP}${frac}${key}`;
+  }
+  if (current === "0") return key === "0" ? "0" : key;  // replace leading zero
+  if (current === "" && key === "0") return "";          // no leading zero from empty
+  if (current.length >= MAX_DIGITS) return current;
+  return current + key;
+}
+
+/** Строка с клавиатуры → число рублей. Незавершённое «100,» читается как 100. */
+export function parseAmount(raw: string): number {
+  if (!raw) return 0;
+  const n = parseFloat(raw.replace(SEP, "."));
+  return Number.isFinite(n) ? Math.round(n * 100) / 100 : 0;
+}
+
+export function withCommission(base: number, rate: number): { commission: number; total: number } {
+  const commission = Math.round(base * rate * 100) / 100;
+  const total = Math.round((base + commission) * 100) / 100;
+  return { commission, total };
+}

driver-pwa/frontend/src/lib/fineStatus.ts

@@ -0,0 +1,30 @@
+import type { FineBrief } from "@/api/driver";
+
+/**
+ * Что написать водителю о штрафе.
+ *
+ * Ключевое различие, которое интерфейс обязан удерживать: постановление в ГИБДД
+ * гасит ПАРК, обычно авансом и со скидкой, — и с этого момента штраф закрыт для
+ * государства, но не для водителя. Водитель возвращает деньги парку, и это видно
+ * только по балансу «Долг по штрафам». Поэтому слово «оплачен» здесь не
+ * используется вовсе: оно означало бы для человека «я ничего не должен».
+ */
+export function fineStatusText(f: Pick<FineBrief, "settled">): string {
+  switch (f.settled) {
+    case "owed":
+      return "не погашен";
+    case "paid":
+      return "погашен";
+    case "not_charged":
+      return "не выставлялся";
+    case "cancelled":
+      return "отменён";
+    default:
+      return "уточняется";
+  }
+}
+
+/** Долг именно этого штрафа перед парком — по нему красим сумму. */
+export function isOwed(f: Pick<FineBrief, "settled">): boolean {
+  return f.settled === "owed";
+}

driver-pwa/frontend/src/lib/format.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { formatMoney, formatPhone, digitsOnly } from "./format";
+
+describe("format", () => {
+  it("formatMoney groups thousands and adds ₽", () => {
+    expect(formatMoney(1000)).toBe("1 000 ₽");
+    expect(formatMoney(-3200)).toBe("−3 200 ₽");
+    expect(formatMoney(0)).toBe("0 ₽");
+  });
+  it("formatMoney keeps kopecks — раньше Math.round() показывал не ту сумму, что спишет банк", () => {
+    expect(formatMoney(350.32)).toBe("350,32 ₽");
+    expect(formatMoney(1052)).toBe("1 052 ₽");
+    expect(formatMoney(10.5)).toBe("10,50 ₽");
+    expect(formatMoney(-350.32)).toBe("−350,32 ₽");
+  });
+  it("digitsOnly strips non-digits", () => {
+    expect(digitsOnly("+7 (914) 305-44-00")).toBe("79143054400");
+  });
+  it("formatPhone renders +7 mask progressively", () => {
+    expect(formatPhone("9143054400")).toBe("+7 914 305-44-00");
+    expect(formatPhone("914305")).toBe("+7 914 305");
+  });
+});

driver-pwa/frontend/src/lib/format.ts

@@ -0,0 +1,50 @@
+export function digitsOnly(s: string): string {
+  return (s || "").replace(/\D/g, "");
+}
+
+/**
+ * Деньги для показа. Копейки печатаем ТОЛЬКО когда они есть.
+ *
+ * Раньше здесь было Math.round(), и водителю показывали одну сумму, а банк
+ * списывал другую: комиссия 5.2% почти всегда даёт копейки (1000 → 1052,00, но
+ * 333 → 350,32), и «к оплате 350 ₽» расходилось и со списанием, и с чеком.
+ */
+export function formatMoney(rub: number): string {
+  const neg = rub < 0;
+  const abs = Math.abs(rub);
+  const kop = Math.round(abs * 100);
+  const whole = Math.floor(kop / 100);
+  const rest = kop % 100;
+  const grouped = whole.toString().replace(/\B(?=(\d{3})+(?!\d))/g, " ");
+  const tail = rest ? `,${rest.toString().padStart(2, "0")}` : "";
+  return `${neg ? "−" : ""}${grouped}${tail} ₽`;
+}
+
+/** Render a Russian mobile from up-to-10 national digits as +7 914 305-44-00. */
+export function formatPhone(national10: string): string {
+  const d = digitsOnly(national10).slice(0, 10);
+  const p: string[] = ["+7"];
+  if (d.length > 0) p.push(" " + d.slice(0, 3));
+  if (d.length > 3) p.push(" " + d.slice(3, 6));
+  if (d.length > 6) p.push("-" + d.slice(6, 8));
+  if (d.length > 8) p.push("-" + d.slice(8, 10));
+  return p.join("");
+}
+
+/** Дата человеку — ДД.ММ.ГГГГ. На проводе и в <input type="date"> остаётся ISO. */
+export function formatDate(iso: string | null): string {
+  if (!iso) return "";
+  const [y, m, d] = iso.split("-");
+  return y && m && d ? `${d}.${m}.${y}` : iso;
+}
+
+/** ISO-дата на N дней назад от сегодня — для периода выписки по умолчанию. */
+export function isoDaysAgo(days: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() - days);
+  return d.toISOString().slice(0, 10);
+}
+
+export function isoToday(): string {
+  return new Date().toISOString().slice(0, 10);
+}

driver-pwa/frontend/src/lib/jwt.ts

@@ -0,0 +1,40 @@
+/**
+ * Чтение полезной нагрузки JWT без проверки подписи — для экрана отладки.
+ *
+ * Проверять подпись здесь нечем и не нужно: решение о доступе принимает бэкенд,
+ * а приложению эти поля нужны ровно для того, чтобы показать человеку, чем он
+ * сейчас держится — до какого времени живёт токен и чей это сеанс.
+ */
+export interface TokenInfo {
+  sub: string | null;
+  exp: number | null;
+  impersonated: boolean;
+}
+
+export function readToken(token: string | null): TokenInfo | null {
+  if (!token) return null;
+  const part = token.split(".")[1];
+  if (!part) return null;
+  try {
+    const json = atob(part.replace(/-/g, "+").replace(/_/g, "/"));
+    const claims = JSON.parse(json) as Record<string, unknown>;
+    return {
+      sub: typeof claims.sub === "string" ? claims.sub : null,
+      exp: typeof claims.exp === "number" ? claims.exp : null,
+      impersonated: claims.imp === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** «через 7 ч 20 мин» / «истёк» — человеку, а не в секундах. */
+export function expiresIn(exp: number | null): string {
+  if (exp == null) return "—";
+  const left = exp * 1000 - Date.now();
+  if (left <= 0) return "истёк";
+  const h = Math.floor(left / 3_600_000);
+  const m = Math.floor((left % 3_600_000) / 60_000);
+  if (h >= 24) return `через ${Math.floor(h / 24)} дн ${h % 24} ч`;
+  return h > 0 ? `через ${h} ч ${m} мин` : `через ${m} мин`;
+}

driver-pwa/frontend/src/lib/pairing.ts

@@ -0,0 +1,45 @@
+/**
+ * Pairing-сессия входа через Telegram, пока приложение ждёт бота.
+ *
+ * Держим в sessionStorage: экран ожидания переживает уход в Telegram и возврат,
+ * но сессия не должна пережить закрытие вкладки — это половина ключа к JWT.
+ * Раньше ключи раскладывались по три штуки в каждом экране; теперь одно место,
+ * чтобы `poll_secret` нельзя было забыть положить или забыть стереть.
+ */
+const K_SESSION = "pp-pair-session";
+const K_SECRET = "pp-pair-secret";
+const K_CONFIRM = "pp-pair-confirm";
+const K_LINK = "pp-pair-deeplink";
+
+export interface Pairing {
+  pairSession: string;
+  pollSecret: string;
+  confirmCode: string;
+  deepLink: string | null;
+}
+
+export function savePairing(p: {
+  pair_session: string; poll_secret: string; confirm_code: string; deep_link?: string | null;
+}): void {
+  sessionStorage.setItem(K_SESSION, p.pair_session);
+  sessionStorage.setItem(K_SECRET, p.poll_secret);
+  sessionStorage.setItem(K_CONFIRM, p.confirm_code);
+  if (p.deep_link) sessionStorage.setItem(K_LINK, p.deep_link);
+  else sessionStorage.removeItem(K_LINK);
+}
+
+export function loadPairing(): Pairing | null {
+  const pairSession = sessionStorage.getItem(K_SESSION);
+  const pollSecret = sessionStorage.getItem(K_SECRET);
+  if (!pairSession || !pollSecret) return null;
+  return {
+    pairSession,
+    pollSecret,
+    confirmCode: sessionStorage.getItem(K_CONFIRM) ?? "",
+    deepLink: sessionStorage.getItem(K_LINK),
+  };
+}
+
+export function clearPairing(): void {
+  [K_SESSION, K_SECRET, K_CONFIRM, K_LINK].forEach((k) => sessionStorage.removeItem(k));
+}

driver-pwa/frontend/src/lib/paymentWatch.ts

@@ -0,0 +1,51 @@
+/**
+ * Отметка «водитель только что платил» — общая для экранов пополнения и баланса.
+ *
+ * Зачем она нужна, если экран баланса и так опрашивает себя, пока висит
+ * «Зачисляется» (pending_topup > 0). У опроса по одному этому признаку два
+ * слепых пятна, и оба приходятся ровно на сбойные сценарии:
+ *
+ * 1. Водитель ушёл с экрана оплаты жестом «назад» ДО прихода вебхука банка
+ *    (СБП подтверждается и через 10–60 секунд). Баланс на тот момент отвечает
+ *    pending_topup=0 — опрос не взводится, и когда вебхук наконец ставит PAID,
+ *    перезапросить баланс уже некому: экран оплаты размонтирован вместе со
+ *    своим опросом. Старый итог висит без строки «Зачисляется» бессрочно.
+ *
+ * 2. «Зачисляется» гаснет в момент записи платежа в 1С, и в норме итог в том же
+ *    ответе уже новый. Но точечное обновление снимка — не гарантия (1С может
+ *    не ответить, тогда снимок догонит общий синк за ≤2 минуты): опрос,
+ *    выключившийся по pending_topup=0, этот догон уже не увидит — деньги
+ *    «пропадают» с экрана до смены фокуса.
+ *
+ * Поэтому платёжная активность (создание платежа, факт оплаты) оставляет
+ * отметку, и баланс продолжает опрашиваться ещё WATCH_MS после неё — окно с
+ * запасом накрывает и лаг вебхука, и полный цикл общего синка.
+ *
+ * sessionStorage, а не переменная модуля: PWA на телефоне перезагружает
+ * страницу охотно (нехватка памяти, возврат из банковского приложения), и
+ * отметка в памяти не пережила бы ровно тот переход, ради которого заведена.
+ */
+
+const KEY = "pp-payment-activity-at";
+
+/** Окно опроса после платёжной активности: лаг вебхука (до минуты) + запись в
+ * 1С (≤15 с) + общий синк снимка (≤2 мин) — с запасом. */
+export const WATCH_MS = 5 * 60_000;
+
+export function markPaymentActivity(): void {
+  try {
+    sessionStorage.setItem(KEY, String(Date.now()));
+  } catch {
+    // Приватный режим или отключённое хранилище: без отметки остаётся опрос по
+    // «Зачисляется» — деградация до прежнего поведения, а не поломка.
+  }
+}
+
+export function paymentActivityWithin(ms: number = WATCH_MS): boolean {
+  try {
+    const t = Number(sessionStorage.getItem(KEY) || 0);
+    return t > 0 && Date.now() - t < ms;
+  } catch {
+    return false;
+  }
+}

driver-pwa/frontend/src/lib/push.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("@/api/driver", () => ({
+  getPushKey: vi.fn(async () => ({ key: "BIIh_RELLY", enabled: true })),
+  subscribePush: vi.fn(async () => ({ ok: true })),
+  unsubscribePush: vi.fn(async () => ({ ok: true })),
+}));
+
+import { currentState, enable, supported } from "./push";
+import * as api from "@/api/driver";
+
+const SUB = {
+  endpoint: "https://fcm.googleapis.com/fcm/send/abc",
+  toJSON: () => ({
+    endpoint: "https://fcm.googleapis.com/fcm/send/abc",
+    keys: { p256dh: "p256", auth: "auth" },
+  }),
+  unsubscribe: vi.fn(async () => true),
+};
+
+function stubBrowser(opts: {
+  permission?: NotificationPermission;
+  existing?: unknown;
+  ios?: boolean;
+  standalone?: boolean;
+} = {}) {
+  const perm = opts.permission ?? "default";
+  const registration = {
+    pushManager: {
+      getSubscription: vi.fn(async () => opts.existing ?? null),
+      subscribe: vi.fn(async () => SUB),
+    },
+  };
+  vi.stubGlobal("navigator", {
+    serviceWorker: {
+      getRegistration: vi.fn(async () => registration),
+      ready: Promise.resolve(registration),
+    },
+    userAgent: opts.ios ? "iPhone" : "Android Chrome",
+    standalone: opts.standalone,
+  });
+  const notification = {
+    permission: perm,
+    requestPermission: vi.fn(async () => (opts.permission === "denied" ? "denied" : "granted")),
+  };
+  // Notification обязан лежать И в window: supported() проверяет именно его —
+  // так же, как это делает браузер.
+  vi.stubGlobal("window", {
+    PushManager: function () {},
+    Notification: notification,
+    matchMedia: () => ({ matches: !!opts.standalone }),
+  });
+  vi.stubGlobal("Notification", notification);
+  return registration;
+}
+
+describe("уведомления в приложении", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("iPhone без установки на экран: объясняем, а не молчим", async () => {
+    vi.stubGlobal("navigator", { userAgent: "iPhone", standalone: false });
+    vi.stubGlobal("window", { matchMedia: () => ({ matches: false }) });
+    expect(supported()).toBe(false);
+    expect(await currentState()).toBe("needs-install");
+  });
+
+  it("разрешение отклонено — переспросить нечем", async () => {
+    stubBrowser({ permission: "denied" });
+    expect(await currentState()).toBe("denied");
+  });
+
+  it("подписка уходит на сервер с ключами из браузера", async () => {
+    stubBrowser();
+    expect(await enable()).toBe("on");
+    expect(api.subscribePush).toHaveBeenCalledWith({
+      endpoint: "https://fcm.googleapis.com/fcm/send/abc",
+      p256dh: "p256",
+      auth: "auth",
+    });
+  });
+
+  it("сервер не настроен — разрешение НЕ спрашиваем", async () => {
+    // Единственная попытка на установку: потратить её впустую нельзя.
+    vi.mocked(api.getPushKey).mockResolvedValueOnce({ key: "", enabled: false });
+    stubBrowser();
+    expect(await enable()).toBe("off");
+    expect(Notification.requestPermission).not.toHaveBeenCalled();
+    expect(api.subscribePush).not.toHaveBeenCalled();
+  });
+});

driver-pwa/frontend/src/lib/push.ts

@@ -0,0 +1,92 @@
+import { getPushKey, subscribePush, unsubscribePush } from "@/api/driver";
+
+/**
+ * Включение уведомлений в приложении.
+ *
+ * Главное правило экрана вокруг этого кода: разрешение спрашивается ОДИН раз за
+ * всю жизнь установки. Отказ браузер запоминает, переспросить нельзя — только
+ * руками в настройках сайта, куда водитель не пойдёт. Поэтому запрос идёт
+ * строго по нажатию и только когда сервер подтвердил, что уведомления настроены.
+ */
+export type PushState =
+  | "unsupported"   // браузер не умеет (или iOS без установки на домашний экран)
+  | "needs-install" // iOS: умеет, но только когда приложение добавлено на экран
+  | "denied"        // разрешение отклонено — переспросить нечем
+  | "off"           // можно включить
+  | "on";           // подписка есть
+
+/** Приложение открыто как установленное (с домашнего экрана), а не вкладкой. */
+export function installed(): boolean {
+  return isStandalone();
+}
+
+function isStandalone(): boolean {
+  return window.matchMedia("(display-mode: standalone)").matches ||
+    // iOS до 17 не поддерживает display-mode: standalone в matchMedia
+    (navigator as { standalone?: boolean }).standalone === true;
+}
+
+function isIos(): boolean {
+  return /iPad|iPhone|iPod/.test(navigator.userAgent);
+}
+
+export function supported(): boolean {
+  return "serviceWorker" in navigator && "PushManager" in window && "Notification" in window;
+}
+
+export async function currentState(): Promise<PushState> {
+  if (!supported()) return isIos() && !isStandalone() ? "needs-install" : "unsupported";
+  if (Notification.permission === "denied") return "denied";
+  const reg = await navigator.serviceWorker.getRegistration();
+  const sub = await reg?.pushManager.getSubscription();
+  return sub ? "on" : "off";
+}
+
+/** base64url → байты: ключ VAPID браузер принимает только так.
+ * Возвращаем ArrayBuffer, а не Uint8Array: типы DOM ждут BufferSource. */
+function keyToBytes(base64: string): ArrayBuffer {
+  const padded = base64.replace(/-/g, "+").replace(/_/g, "/") +
+    "=".repeat((4 - (base64.length % 4)) % 4);
+  const raw = atob(padded);
+  const bytes = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
+  return bytes.buffer;
+}
+
+/** Включить уведомления. Возвращает новое состояние. */
+export async function enable(): Promise<PushState> {
+  if (!supported()) return currentState();
+  const { key, enabled } = await getPushKey();
+  // Ключа нет — сервер уведомления не отправляет. Разрешение не спрашиваем:
+  // потратить единственную попытку впустую нельзя.
+  if (!enabled || !key) return "off";
+
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") return permission === "denied" ? "denied" : "off";
+
+  const reg = await navigator.serviceWorker.ready;
+  const sub = await reg.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: keyToBytes(key),
+  });
+  const json = sub.toJSON() as { endpoint?: string; keys?: { p256dh?: string; auth?: string } };
+  await subscribePush({
+    endpoint: json.endpoint ?? sub.endpoint,
+    p256dh: json.keys?.p256dh ?? "",
+    auth: json.keys?.auth ?? "",
+  });
+  return "on";
+}
+
+/** Выключить: снимаем подписку и в браузере, и на сервере. */
+export async function disable(): Promise<PushState> {
+  const reg = await navigator.serviceWorker.getRegistration();
+  const sub = await reg?.pushManager.getSubscription();
+  if (sub) {
+    // Сначала сервер: не сумеем достучаться — подписка останется живой, и
+    // уведомления продолжат приходить, а это лучше «выключил, а они идут».
+    await unsubscribePush(sub.endpoint);
+    await sub.unsubscribe();
+  }
+  return "off";
+}

driver-pwa/frontend/src/lib/reqlog.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { clearLog, getLog, pushEntry, shortPath, subscribe } from "./reqlog";
+
+describe("журнал запросов", () => {
+  beforeEach(() => clearLog());
+
+  it("новые записи сверху, старые вытесняются", () => {
+    for (let i = 0; i < 45; i++) pushEntry({ method: "GET", path: `/api/${i}`, status: 200, ms: 1 });
+    const log = getLog();
+    expect(log.length).toBe(40);
+    expect(log[0].path).toBe("/api/44");
+  });
+
+  it("подписчик узнаёт о записи — на этом держится экран отладки", () => {
+    let calls = 0;
+    const off = subscribe(() => { calls += 1; });
+    pushEntry({ method: "GET", path: "/api/x", status: 200, ms: 1 });
+    expect(calls).toBe(1);
+    off();
+    pushEntry({ method: "GET", path: "/api/y", status: 200, ms: 1 });
+    expect(calls).toBe(1);
+  });
+
+  it("query отбрасывается: в нём ездят идентификаторы", () => {
+    expect(shortPath("https://crm.pptaxi.ru/api/driver/payment/x?token=secret"))
+      .toBe("/api/driver/payment/x");
+  });
+});

driver-pwa/frontend/src/lib/reqlog.ts

@@ -0,0 +1,55 @@
+/**
+ * Кольцевой журнал запросов приложения — для вкладки «Отладка».
+ *
+ * Зачем он, если есть DevTools: приложение живёт на телефоне, и половина
+ * интересных случаев (протухший токен, отвалившийся Wi-Fi, 429 от лимита) видна
+ * только там, где DevTools нет. Журнал даёт те же четыре факта — метод, путь,
+ * статус, длительность — прямо на экране.
+ *
+ * Живёт в памяти и умирает вместе с вкладкой: это отладочный след, а не история.
+ * В нём НЕТ ни тел запросов, ни заголовков — токен водителя в отладочный экран
+ * попасть не должен.
+ */
+export interface ReqEntry {
+  id: number;
+  method: string;
+  path: string;
+  status: number | null;
+  ms: number;
+  at: number;
+}
+
+const LIMIT = 40;
+let seq = 0;
+let entries: ReqEntry[] = [];
+const listeners = new Set<() => void>();
+
+export function pushEntry(e: Omit<ReqEntry, "id" | "at">): void {
+  seq += 1;
+  entries = [{ ...e, id: seq, at: Date.now() }, ...entries].slice(0, LIMIT);
+  listeners.forEach((l) => l());
+}
+
+export function clearLog(): void {
+  entries = [];
+  listeners.forEach((l) => l());
+}
+
+/** Снимок для useSyncExternalStore: ссылка меняется только при новой записи. */
+export function getLog(): ReqEntry[] {
+  return entries;
+}
+
+export function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Путь без origin и без query: в query ездят идентификаторы, а экран публичный. */
+export function shortPath(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url.split("?")[0];
+  }
+}

driver-pwa/frontend/src/lib/returnTo.ts

@@ -0,0 +1,32 @@
+/**
+ * Куда вернуть водителя после входа.
+ *
+ * Ссылки на оплату (`/pay/:id`) открываются под RequireAuth: незалогиненного
+ * бросает на /login. Раньше после входа он попадал на баланс, а не на оплату,
+ * ради которой пришёл. Запоминаем нужный путь тут (переживает переход через
+ * /tg-wait и онбординг), после любого успешного входа — забираем и очищаем.
+ */
+const KEY = "pp-return-to";
+
+/** Путь для сохранения — только внутренние маршруты приложения. */
+export function setReturnTo(path: string | null | undefined): void {
+  try {
+    if (path && path.startsWith("/") && !path.startsWith("//") && path !== "/login") {
+      sessionStorage.setItem(KEY, path);
+    }
+  } catch {
+    /* приватный режим/недоступный storage — не критично */
+  }
+}
+
+/** Забрать сохранённый путь (и очистить). По умолчанию — на главную. */
+export function takeReturnTo(): string {
+  try {
+    const v = sessionStorage.getItem(KEY);
+    sessionStorage.removeItem(KEY);
+    if (v && v.startsWith("/") && !v.startsWith("//")) return v;
+  } catch {
+    /* см. выше */
+  }
+  return "/";
+}

driver-pwa/frontend/src/main.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Toaster } from "sonner";
+import App from "./App";
+import "./index.css";
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: 1, staleTime: 15_000 } },
+});
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <App />
+        <Toaster richColors position="top-center" />
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+);

driver-pwa/frontend/src/pages/BalancePage.test.tsx

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeAll, afterAll } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+// Ответ как у настоящего водителя: статьи 1С, итог отдельным числом.
+vi.mock("@/api/driver", () => ({
+  // Колокольчик в шапке главного экрана спрашивает счётчик непрочитанного.
+  getNotifications: vi.fn(async () => ({ items: [], unread: 0 })),
+  markNotificationsRead: vi.fn(async () => ({ marked: 0 })),
+  getBalance: vi.fn(async () => ({
+    accounts: [
+      { bucket: "Долг аренда", balance: -3050, payable: true },
+      { bucket: "Долг по штрафам", balance: -5156, payable: true },
+      { bucket: "Страховка", balance: 200, payable: false },
+    ],
+    total: -8976.25,
+    synced_at: null,
+    pending_topup: 1500,
+  })),
+  getFines: vi.fn(async () => ({
+    items: [{
+      id: 12, number: "18810525260813035846", date: "2026-08-13",
+      article: "12.09.2 - Превышение скорости", address: "", car_number: "А947УТ125",
+      amount: 618.75, settled: "owed" as const, cancelled: false, has_photo: true,
+    }],
+    open_count: 1, debt: -5156,
+  })),
+  getStatement: vi.fn(async () => ({
+    items: [
+      { date: "2026-08-17", title: "Аренда автомобиля", description: "ТС А947УТ125",
+        amount: -2600, kind: "charges" },
+      { date: "2026-08-17", title: "Пополнение баланса", description: "", amount: 1000,
+        kind: "payments" },
+    ],
+    from: "2026-08-11", to: "2026-08-18", kind: "all",
+  })),
+}));
+
+// Экран режет постановления по периоду «последние 7 дней от сегодня», а даты в
+// моках фиксированные: без замороженных часов штраф от 13.08 выпадает из окна,
+// как только настоящее «сегодня» уходит за 20.08. Морозим только Date — таймеры
+// остаются настоящими, иначе userEvent и waitFor зависнут.
+beforeAll(() => {
+  vi.useFakeTimers({ toFake: ["Date"] });
+  vi.setSystemTime(new Date("2026-08-18T12:00:00Z"));
+});
+afterAll(() => vi.useRealTimers());
+
+import { BalancePage, balancePollMs } from "./BalancePage";
+import { markPaymentActivity } from "@/lib/paymentWatch";
+import * as driver from "@/api/driver";
+
+function wrap() {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={qc}>
+      <MemoryRouter>
+        <Routes>
+          <Route path="/" element={<BalancePage />} />
+          <Route path="/topup" element={<p>экран пополнения</p>} />
+        </Routes>
+      </MemoryRouter>
+    </QueryClientProvider>
+  );
+}
+
+describe("главный экран", () => {
+  it("опрос баланса: пока висит «зачисляется» или водитель недавно платил", () => {
+    // Водитель после оплаты смотрит на экран и ждёт новый итог — экран обязан
+    // обновиться сам. Вне платёжных окон опроса быть не должно.
+    sessionStorage.clear();
+    expect(balancePollMs({ pending_topup: 1500 })).toBe(4000);
+    expect(balancePollMs({ pending_topup: 0 })).toBe(false);
+    expect(balancePollMs(undefined)).toBe(false);
+    // Свежая платёжная активность держит опрос и без «зачисляется»: вебхук
+    // банка может запаздывать (опрос обязан застать появление строки), а снимок
+    // баланса — догонять платёж общим синком уже после её погашения.
+    markPaymentActivity();
+    expect(balancePollMs({ pending_topup: 0 })).toBe(4000);
+    sessionStorage.clear();
+  });
+
+  it("сверху деньги: итог с сервера и строка «зачисляется»", async () => {
+    wrap();
+    // Сумма статей дала бы −8 006, а в CRM у водителя −8 976,25. Показываем её.
+    expect(await screen.findByText("−8 976,25 ₽")).toBeInTheDocument();
+    expect(screen.getByText("Зачисляется")).toBeInTheDocument();
+    expect(screen.getByText("1 500 ₽")).toBeInTheDocument();
+  });
+
+  it("снизу выписка за период", async () => {
+    wrap();
+    expect(await screen.findByText("Аренда автомобиля")).toBeInTheDocument();
+    expect(screen.getAllByText(/17\.08\.2026/).length).toBe(2);  // обе операции того дня
+    expect(screen.getByRole("button", { name: "Все операции" })).toBeInTheDocument();
+    expect(driver.getStatement).toHaveBeenCalled();
+  });
+
+  it("фильтр перезапрашивает операции выбранного вида", async () => {
+    wrap();
+    await userEvent.click(await screen.findByRole("button", { name: "Начисления" }));
+    const calls = vi.mocked(driver.getStatement).mock.calls;
+    expect(calls[calls.length - 1][2]).toBe("charges");
+  });
+
+  it("фильтр «Штрафы» показывает постановления, а не проводки", async () => {
+    // Штраф, оплаченный водителем самостоятельно, парк не выставлял — проводки по
+    // нему нет, и в выписке он бы не появился вовсе (Морозов, 18.08.2026).
+    wrap();
+    await userEvent.click(await screen.findByRole("button", { name: "Штрафы" }));
+    expect(await screen.findByText(/Превышение скорости/)).toBeInTheDocument();
+    expect(driver.getFines).toHaveBeenCalled();
+  });
+
+  it("аренда и штрафы видны сразу, остальные статьи — нет", async () => {
+    wrap();
+    await screen.findByText("−8 976,25 ₽");
+    // Эти две водитель проверяет каждый день — они на экране.
+    expect(screen.getByText("Долг аренда")).toBeInTheDocument();
+    expect(screen.getByText("Долг по штрафам")).toBeInTheDocument();
+    expect(screen.getByText("−3 050 ₽")).toBeInTheDocument();
+    // Редкие статьи на экран не лезут: для них есть шторка.
+    expect(screen.queryByText("Страховка")).not.toBeInTheDocument();
+  });
+
+  it("аренда ведёт к оплате, а штрафы — в свой список", async () => {
+    wrap();
+    await userEvent.click(await screen.findByRole("button", { name: /Долг аренда/ }));
+    expect(await screen.findByText("экран пополнения")).toBeInTheDocument();
+  });
+
+  it("строка штрафов включает фильтр внизу, а не уводит на другой экран", async () => {
+    wrap();
+    await userEvent.click(await screen.findByRole("button", { name: /Долг по штрафам/ }));
+    expect(await screen.findByText(/Превышение скорости/)).toBeInTheDocument();
+    expect(driver.getFines).toHaveBeenCalled();
+  });
+
+  it("категории для выбора живут в шторке «Пополнить»", async () => {
+    wrap();
+    await screen.findByText("−8 976,25 ₽");
+    await userEvent.click(screen.getByRole("button", { name: /^Пополнить$/ }));
+    const sheet = await screen.findByRole("dialog", { name: "Куда пополнить" });
+    const inSheet = within(sheet);
+    expect(inSheet.getByText("Долг аренда")).toBeInTheDocument();
+    expect(inSheet.getByText("Долг по штрафам")).toBeInTheDocument();
+    // «Страховка» платежом не закрывается — в списке выбора ей делать нечего.
+    expect(inSheet.queryByText("Страховка")).not.toBeInTheDocument();
+  });
+
+  it("шторка закрывается тапом мимо", async () => {
+    wrap();
+    await screen.findByText("−8 976,25 ₽");
+    await userEvent.click(screen.getByRole("button", { name: /^Пополнить$/ }));
+    await userEvent.click(await screen.findByRole("button", { name: "Закрыть" }));
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
+  it("отдельного раздела пополнений нет — они в выписке", async () => {
+    // Раздел «Мои пополнения» показывал наши платежи и у большинства водителей был
+    // пуст: 1С проводит пополнения сама, и они уже видны фильтром в выписке.
+    wrap();
+    await screen.findByText("−8 976,25 ₽");
+    expect(screen.queryByText(/Мои пополнения/)).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Пополнения" })).toBeInTheDocument();
+  });
+
+  it("баланс не загрузился — экран говорит об этом, а не рисует ноль", async () => {
+    vi.mocked(driver.getBalance).mockRejectedValueOnce(new Error("boom"));
+    wrap();
+    expect(await screen.findByRole("button", { name: /Обновить баланс/ })).toBeInTheDocument();
+  });
+});

driver-pwa/frontend/src/pages/BalancePage.tsx

@@ -0,0 +1,167 @@
+import { useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useNavigate } from "react-router-dom";
+import { ArrowUp, ChevronRight, LogOut } from "lucide-react";
+import { getBalance, type StatementKind } from "@/api/driver";
+import { formatMoney, isoDaysAgo, isoToday } from "@/lib/format";
+import { paymentActivityWithin } from "@/lib/paymentWatch";
+import { useAuth } from "@/store/auth";
+import { AppHeader } from "@/components/AppHeader";
+import { NotificationsPrompt } from "@/components/NotificationsPrompt";
+import { NotificationsRow } from "@/components/NotificationsRow";
+import { Sheet } from "@/components/Sheet";
+import { Spinner } from "@/components/Spinner";
+import { Statement } from "@/components/Statement";
+
+// Две статьи, которые водитель проверяет каждый день: за них он платит и из-за
+// них ему звонят. Остальные (депозит, повреждения, прочее) — редкие, им хватает
+// шторки «Пополнить», иначе экран снова превращается в столбик из шести строк.
+const MAIN_BUCKETS = ["Долг аренда", "Долг по штрафам"];
+
+// Пока висит «Зачисляется» ЛИБО водитель недавно платил, экран опрашивает
+// баланс сам: платёж доезжает до 1С за секунды, и новый итог должен появиться
+// на глазах — водитель после оплаты смотрит именно сюда, а перезапускать
+// приложение он не обязан. Одного «зачисляется» мало: опрос по нему не
+// взводится, пока вебхук банка запаздывает, и гаснет раньше, чем снимок
+// баланса догонит платёж при сбое точечного обновления (см. lib/paymentWatch).
+// Вне этих окон опрос не нужен: остальные движения баланса водитель не
+// караулит у экрана.
+export const balancePollMs = (d?: { pending_topup?: number }): number | false =>
+  (d?.pending_topup ?? 0) > 0 || paymentActivityWithin() ? 4000 : false;
+
+/**
+ * Главный экран из двух половин: сверху деньги, снизу — за что они списаны.
+ *
+ * Разбивка по статьям живёт в шторке «Пополнить», а не на экране: водителю она
+ * нужна ровно в момент, когда он решает, куда платить, а всё остальное время
+ * это шесть строк, отодвигающих выписку за нижний край телефона.
+ */
+export function BalancePage() {
+  const nav = useNavigate();
+  const clear = useAuth((s) => s.clear);
+  const { data, isLoading, isError, refetch } = useQuery({
+    queryKey: ["balance"],
+    queryFn: getBalance,
+    refetchInterval: (q) => balancePollMs(q.state.data),
+  });
+  const [sheet, setSheet] = useState(false);
+  // Неделя — тот же период, что у вендора: столько человек помнит свои поездки.
+  const [from, setFrom] = useState(isoDaysAgo(7));
+  const [to, setTo] = useState(isoToday());
+  const [kind, setKind] = useState<StatementKind>("all");
+
+  const accounts = data?.accounts ?? [];
+  const total = data?.total ?? accounts.reduce((s, a) => s + a.balance, 0);
+  const pending = data?.pending_topup ?? 0;
+  const noData = !isLoading && !isError && accounts.length === 0;
+  const payable = accounts.filter((a) => a.payable);
+  const main = MAIN_BUCKETS.map((b) => accounts.find((a) => a.bucket === b)).filter(
+    (a): a is NonNullable<typeof a> => a != null,
+  );
+
+  function pick(bucket?: string) {
+    setSheet(false);
+    nav("/topup", { state: bucket ? { bucket } : undefined });
+  }
+
+  return (
+    <div>
+      <AppHeader bell />
+
+      <NotificationsPrompt />
+
+      {/* ── Деньги ─────────────────────────────────────────────── */}
+      <div className="card p-4 mb-3">
+        <div className="flex justify-between items-baseline">
+          <span className="text-muted text-xs">Баланс в парке</span>
+          {isLoading ? (
+            <Spinner />
+          ) : noData ? (
+            <span className="text-sm font-semibold">уточняется</span>
+          ) : (
+            <b className={`text-2xl ${total < 0 ? "text-neg" : "text-pos"}`}>{formatMoney(total)}</b>
+          )}
+        </div>
+        {main.length > 0 && (
+          <div className="mt-3 pt-3 border-t border-line">
+            {main.map((a) => (
+              // Аренда ведёт к оплате — за тем её и открывают. Штрафы включают
+              // фильтр в списке ниже: «−5 156 ₽» не отвечает на вопрос «за что»,
+              // а отдельного экрана штрафов нет — два списка одного и того же в
+              // разных местах сбивали с толку.
+              <button
+                key={a.bucket}
+                disabled={!a.payable}
+                onClick={() =>
+                  a.bucket === "Долг по штрафам"
+                    ? setKind("fines")
+                    : nav("/topup", { state: { bucket: a.bucket } })
+                }
+                className="w-full flex justify-between items-baseline py-1.5 text-left disabled:opacity-100"
+              >
+                <span className="text-muted text-xs">{a.bucket}</span>
+                <span className={`text-sm ${a.balance < 0 ? "text-neg" : a.balance > 0 ? "text-pos" : ""}`}>
+                  {formatMoney(a.balance)}
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+        {pending > 0 && (
+          // Платёж принят нами, но 1С его ещё не провела. В сумму не входит: сложить
+          // оба источника значило бы показать пополнение дважды после проведения.
+          <div className="flex justify-between items-baseline mt-3 pt-3 border-t border-line">
+            <span className="text-muted text-xs">Зачисляется</span>
+            <span className="text-sm">{formatMoney(pending)}</span>
+          </div>
+        )}
+        {isError && (
+          <button className="btn-ghost mt-3" onClick={() => refetch()}>Обновить баланс</button>
+        )}
+      </div>
+
+      <button className="btn-primary flex items-center justify-center gap-2 mb-5"
+              onClick={() => setSheet(true)}>
+        <ArrowUp size={18} /> Пополнить
+      </button>
+
+      {/* ── За что списано ─────────────────────────────────────── */}
+      <Statement from={from} to={to} kind={kind}
+                 onFrom={setFrom} onTo={setTo} onKind={setKind} />
+
+      <NotificationsRow />
+
+      <div className="flex justify-center mt-6 text-muted text-xs">
+        {/* Отдельного раздела «Мои пополнения» нет намеренно: пополнения видны в
+            выписке выше по фильтру, а дублирующий пустой экран сбивал с толку. */}
+        <button className="flex items-center gap-1.5" onClick={() => { clear(); nav("/login"); }}>
+          <LogOut size={15} /> Выйти
+        </button>
+      </div>
+
+      <Sheet open={sheet} onClose={() => setSheet(false)} title="Куда пополнить">
+        {payable.length === 0 ? (
+          <p className="text-muted text-sm px-5 py-4">
+            Категории пока не загрузились. Попробуйте ещё раз через минуту.
+          </p>
+        ) : (
+          payable.map((a) => (
+            <button
+              key={a.bucket}
+              onClick={() => pick(a.bucket)}
+              className="w-full flex justify-between items-center gap-3 px-5 py-3.5 border-b border-line last:border-0 text-left"
+            >
+              <span className="text-sm">{a.bucket}</span>
+              <span className="flex items-center gap-2 shrink-0">
+                <b className={a.balance < 0 ? "text-neg" : a.balance > 0 ? "text-pos" : "text-muted"}>
+                  {formatMoney(a.balance)}
+                </b>
+                <ChevronRight size={16} className="text-muted" />
+              </span>
+            </button>
+          ))
+        )}
+      </Sheet>
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/DebugPage.test.tsx

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("@/api/staff", () => ({
+  searchDrivers: vi.fn(async () => ({ drivers: [] })),
+  impersonate: vi.fn(),
+}));
+// Экран баланса, на который уводит редирект, тянет свои запросы — отдаём пустышки.
+vi.mock("@/api/driver", () => ({
+  apiErrorText: vi.fn(async (_e: unknown, f: string) => f),
+  getBalance: vi.fn(async () => ({ accounts: [], pending_topup: 0 })),
+  // Тесты доходят до главного экрана, а у него в шапке колокольчик.
+  getNotifications: vi.fn(async () => ({ items: [], unread: 0 })),
+  markNotificationsRead: vi.fn(async () => ({ marked: 0 })),
+}));
+
+import App from "@/App";
+import { DebugPage } from "./DebugPage";
+import { clearLog, pushEntry } from "@/lib/reqlog";
+import { useAuth } from "@/store/auth";
+import { useStaff } from "@/store/staff";
+
+function renderAt(path: string) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={qc}>
+      <MemoryRouter initialEntries={[path]}><App /></MemoryRouter>
+    </QueryClientProvider>
+  );
+}
+
+describe("вкладка отладки", () => {
+  beforeEach(() => { useAuth.getState().clear(); useStaff.getState().clear(); clearLog(); });
+
+  it("водителя на /debug не пускает — уводит в приложение", () => {
+    useAuth.getState().setSession("t", 42);
+    renderAt("/debug");
+    expect(screen.queryByRole("heading", { name: "Отладка" })).not.toBeInTheDocument();
+  });
+
+  it("сотруднику показывает, от чьего лица открыт экран", () => {
+    useAuth.getState().setSession("t", 42, { impersonated: true, driverName: "Петров Пётр" });
+    renderAt("/debug");
+    expect(screen.getByRole("heading", { name: "Отладка" })).toBeInTheDocument();
+    // Плашка живёт над маршрутами и видна на любом экране, включая этот.
+    expect(screen.getByText(/Смотрю как/)).toBeInTheDocument();
+    expect(screen.getAllByText(/Петров Пётр/).length).toBeGreaterThan(0);
+  });
+
+  it("плашки нет у обычного водителя", () => {
+    useAuth.getState().setSession("t", 42);
+    renderAt("/");
+    expect(screen.queryByText(/Смотрю как/)).not.toBeInTheDocument();
+  });
+
+  it("журнал запросов виден со статусами и временем", () => {
+    useAuth.getState().setSession("t", 42, { impersonated: true, driverName: "Петров" });
+    pushEntry({ method: "GET", path: "/api/driver/balance", status: 401, ms: 123 });
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <MemoryRouter><DebugPage /></MemoryRouter>
+      </QueryClientProvider>
+    );
+    expect(screen.getByText("/api/driver/balance")).toBeInTheDocument();
+    expect(screen.getByText("401")).toBeInTheDocument();
+    expect(screen.getByText("123 мс")).toBeInTheDocument();
+  });
+});
+
+describe("возврат к своему аккаунту", () => {
+  beforeEach(() => { useAuth.getState().clear(); useStaff.getState().clear(); clearLog(); });
+
+  it("свой вход не теряется при просмотре чужого экрана", () => {
+    useAuth.getState().setSession("мой-токен", 91);
+    useAuth.getState().startImpersonation("чужой-токен", 6866, "Тест Тестовый тестович");
+    let s = useAuth.getState();
+    expect([s.token, s.driverId, s.impersonated]).toEqual(["чужой-токен", 6866, true]);
+
+    // смена водителя внутри просмотра не должна подменять отложенный свой вход
+    useAuth.getState().startImpersonation("третий-токен", 2869, "Тестик Николай");
+    expect(useAuth.getState().own).toEqual({ token: "мой-токен", driverId: 91 });
+
+    expect(useAuth.getState().stopImpersonation()).toBe(true);
+    s = useAuth.getState();
+    expect([s.token, s.driverId, s.impersonated, s.own]).toEqual(["мой-токен", 91, false, null]);
+  });
+
+  it("если своего входа не было — просмотр просто заканчивается выходом", () => {
+    useAuth.getState().startImpersonation("чужой-токен", 6866, "Тест");
+    expect(useAuth.getState().stopImpersonation()).toBe(false);
+    expect(useAuth.getState().token).toBeNull();
+  });
+
+  it("кнопка предлагает вернуться к себе, когда есть куда", async () => {
+    useAuth.getState().setSession("мой-токен", 91);
+    useAuth.getState().startImpersonation("чужой-токен", 6866, "Тест Тестовый тестович");
+    renderAt("/debug");
+    expect(screen.getByRole("button", { name: /Вернуться к своему аккаунту/ })).toBeInTheDocument();
+  });
+});

driver-pwa/frontend/src/pages/DebugPage.tsx

@@ -0,0 +1,154 @@
+import { useState, useSyncExternalStore } from "react";
+import { useNavigate } from "react-router-dom";
+import { LogOut, RefreshCw, Trash2, UserCog } from "lucide-react";
+import { toast } from "sonner";
+import { API_BASE } from "@/api/client";
+import { clearLog, getLog, subscribe } from "@/lib/reqlog";
+import { expiresIn, readToken } from "@/lib/jwt";
+import { useAuth } from "@/store/auth";
+import { useStaff } from "@/store/staff";
+import { DriverPicker } from "@/components/DriverPicker";
+
+function Row({ k, v }: { k: string; v: string }) {
+  return (
+    <div className="flex justify-between gap-3 py-2 border-b border-line last:border-0">
+      <span className="text-muted text-xs shrink-0">{k}</span>
+      <span className="text-xs text-right break-all">{v}</span>
+    </div>
+  );
+}
+
+/**
+ * Вкладка «Отладка» — то, чего в приложении водителя нет и быть не должно:
+ * от чьего лица открыт экран, куда ходят запросы, чем они отвечают.
+ *
+ * Показывается только сотруднику (есть учётка CRM или действует просмотр). У
+ * водителя маршрут ведёт на главную — см. App.
+ */
+export function DebugPage() {
+  const nav = useNavigate();
+  const { token, driverId, driverName, impersonated, own, clear, stopImpersonation } = useAuth();
+  const staff = useStaff();
+  const log = useSyncExternalStore(subscribe, getLog);
+  const [switching, setSwitching] = useState(false);
+  const info = readToken(token);
+
+  async function hardReload() {
+    // Кэш сервис-воркера переживает деплой и показывает вчерашний бандл — на
+    // отладке это стоит часа «почему правка не приехала».
+    try {
+      const regs = await navigator.serviceWorker?.getRegistrations?.();
+      await Promise.all((regs ?? []).map((r) => r.unregister()));
+      const keys = await caches?.keys?.();
+      await Promise.all((keys ?? []).map((k) => caches.delete(k)));
+      toast.success("Кэш сброшен, перезагружаю");
+    } catch {
+      toast.error("Не удалось сбросить кэш");
+    }
+    location.reload();
+  }
+
+  return (
+    <div className="pt-3">
+      <h1 className="text-lg font-extrabold mb-4">Отладка</h1>
+
+      <div className="card p-4 mb-4">
+        <p className="text-muted text-xs mb-1">Сейчас смотрю</p>
+        <p className="text-sm font-bold mb-3">
+          {impersonated ? (driverName ?? `Водитель #${driverId}`) : "Свой аккаунт водителя"}
+        </p>
+        <button className="btn-ghost flex items-center justify-center gap-2"
+                onClick={() => setSwitching((s) => !s)}>
+          <UserCog size={16} /> {switching ? "Свернуть" : "Сменить водителя"}
+        </button>
+        {switching && (
+          <div className="mt-4">
+            <DriverPicker onPicked={(d) => { setSwitching(false); toast.success(`Смотрю как ${d.fio}`); }} />
+          </div>
+        )}
+      </div>
+
+      {impersonated && (
+        <div className="card p-4 mb-4">
+          <p className="text-sm font-semibold mb-1">Боевая оплата</p>
+          <p className="text-muted text-xs mb-3">
+            Выключено — пополнение открывает учебный экран, деньги не двигаются.
+            Включено — платёж уходит в банк по-настоящему: спишется с вашей карты,
+            чек уйдёт на телефон водителя, сумма зачислится ему в 1С.
+          </p>
+          <button
+            className={staff.livePay ? "btn-primary" : "btn-ghost"}
+            onClick={() => staff.setLivePay(!staff.livePay)}
+          >
+            {staff.livePay ? "Боевая оплата включена — выключить" : "Включить боевую оплату"}
+          </button>
+        </div>
+      )}
+
+      <div className="card p-4 mb-4">
+        <p className="text-muted text-xs mb-2">Сведения</p>
+        <Row k="driver_id" v={String(driverId ?? "—")} />
+        <Row k="режим" v={impersonated ? "просмотр сотрудником (imp)" : "обычный вход водителя"} />
+        {impersonated && (
+          <Row k="оплата" v={staff.livePay ? "боевая — деньги двигаются" : "учебная"} />
+        )}
+        <Row k="сотрудник" v={staff.username ?? "не входил"} />
+        <Row k="токен истекает" v={expiresIn(info?.exp ?? null)} />
+        <Row k="API" v={API_BASE} />
+        <Row k="сборка" v={`${__BUILD_COMMIT__} · ${__BUILD_TIME__}`} />
+        <Row k="сеть" v={navigator.onLine ? "онлайн" : "офлайн"} />
+      </div>
+
+      <div className="card p-4 mb-4">
+        <div className="flex items-center justify-between mb-2">
+          <p className="text-muted text-xs">Последние запросы</p>
+          <button className="text-muted text-xs flex items-center gap-1" onClick={clearLog}>
+            <Trash2 size={12} /> очистить
+          </button>
+        </div>
+        {log.length === 0 ? (
+          <p className="text-muted text-xs py-2">Пока пусто</p>
+        ) : (
+          <div className="font-mono text-[11px] leading-5">
+            {log.map((e) => (
+              <div key={e.id} className="flex gap-2 border-b border-line last:border-0 py-1">
+                <span className={e.status && e.status >= 400 ? "text-neg" : "text-pos"}>
+                  {e.status ?? "—"}
+                </span>
+                <span className="text-muted">{e.method}</span>
+                <span className="truncate">{e.path}</span>
+                <span className="ml-auto text-muted shrink-0">{e.ms} мс</span>
+              </div>
+            ))}
+          </div>
+        )}
+        <p className="text-muted text-[11px] mt-2">
+          Запрос, оборвавшийся без ответа, сюда не попадает.
+        </p>
+      </div>
+
+      <button className="btn-ghost flex items-center justify-center gap-2 mb-2" onClick={hardReload}>
+        <RefreshCw size={16} /> Сбросить кэш и перезагрузить
+      </button>
+      <button
+        className="btn-ghost flex items-center justify-center gap-2"
+        onClick={() => {
+          // Свой вход, отложенный на время просмотра, возвращаем на место: иначе
+          // «посмотреть чужой экран» означало бы заново входить через Telegram.
+          if (impersonated && stopImpersonation()) { nav("/"); return; }
+          clear();
+          nav(staff.token ? "/dev" : "/login");
+        }}
+      >
+        <LogOut size={16} />{" "}
+        {impersonated ? (own ? "Вернуться к своему аккаунту" : "Выйти из просмотра") : "Выйти"}
+      </button>
+      {staff.token && (
+        <button className="text-muted text-xs w-full mt-4"
+                onClick={() => { clear(); staff.clear(); nav("/login"); }}>
+          Выйти и из учётки сотрудника
+        </button>
+      )}
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/DevLoginPage.test.tsx

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router-dom";
+
+vi.mock("@/api/staff", () => ({
+  staffLogin: vi.fn(async () => ({ access_token: "staff-tok", requires_2fa: false, partial_token: null })),
+  staffLogin2fa: vi.fn(async () => ({ access_token: "staff-tok", requires_2fa: false, partial_token: null })),
+  searchDrivers: vi.fn(async () => ({
+    drivers: [{ id: 42, fio: "Петров Пётр", phone: "+79141234567", status: "Работает", driver_kind: "park" }],
+  })),
+  impersonate: vi.fn(async () => ({
+    token: "driver-tok",
+    driver: { id: 42, fio: "Петров Пётр", phone: "+79141234567", status: "Работает", driver_kind: "park" },
+  })),
+}));
+vi.mock("@/api/driver", () => ({ apiErrorText: vi.fn(async (_e: unknown, f: string) => f) }));
+
+import { DevLoginPage } from "./DevLoginPage";
+import * as staffApi from "@/api/staff";
+import { useAuth } from "@/store/auth";
+import { useStaff } from "@/store/staff";
+
+const wrap = () => render(<MemoryRouter><DevLoginPage /></MemoryRouter>);
+
+describe("DevLoginPage", () => {
+  beforeEach(() => {
+    useAuth.getState().clear();
+    useStaff.getState().clear();
+    vi.clearAllMocks();
+  });
+
+  it("логин учёткой CRM, выбор водителя — и сеанс помечен как просмотр", async () => {
+    wrap();
+    await userEvent.type(screen.getByPlaceholderText("Логин"), "vlad");
+    await userEvent.type(screen.getByPlaceholderText("Пароль"), "secret");
+    await userEvent.click(screen.getByRole("button", { name: "Войти" }));
+
+    expect(staffApi.staffLogin).toHaveBeenCalledWith("vlad", "secret");
+    expect(useStaff.getState().token).toBe("staff-tok");
+
+    await userEvent.click(await screen.findByRole("button", { name: /Петров Пётр/ }));
+    expect(staffApi.impersonate).toHaveBeenCalledWith(42);
+    const auth = useAuth.getState();
+    // Метка просмотра — то, на чём держатся и плашка, и запрет боевой оплаты.
+    expect(auth.token).toBe("driver-tok");
+    expect(auth.driverId).toBe(42);
+    expect(auth.impersonated).toBe(true);
+    expect(auth.driverName).toBe("Петров Пётр");
+  });
+
+  it("двухфакторка: пароль сам по себе сеанса не открывает", async () => {
+    vi.mocked(staffApi.staffLogin).mockResolvedValueOnce({
+      access_token: null, requires_2fa: true, partial_token: "partial",
+    });
+    wrap();
+    await userEvent.type(screen.getByPlaceholderText("Логин"), "vlad");
+    await userEvent.type(screen.getByPlaceholderText("Пароль"), "secret");
+    await userEvent.click(screen.getByRole("button", { name: "Войти" }));
+    expect(useStaff.getState().token).toBeNull();
+
+    // Шестая цифра отправляет код сама: раньше форма ждала нажатия, а «Готово» на
+    // клавиатуре телефона ничего не делало — выглядело как «код не принят».
+    await userEvent.type(await screen.findByPlaceholderText("000000"), "123456");
+    expect(staffApi.staffLogin2fa).toHaveBeenCalledWith("partial", "123456");
+    expect(useStaff.getState().token).toBe("staff-tok");
+  });
+});

driver-pwa/frontend/src/pages/DevLoginPage.tsx

@@ -0,0 +1,132 @@
+import { useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { toast } from "sonner";
+import { apiErrorText } from "@/api/driver";
+import { staffLogin, staffLogin2fa } from "@/api/staff";
+import { useStaff } from "@/store/staff";
+import { DriverPicker } from "@/components/DriverPicker";
+import { Spinner } from "@/components/Spinner";
+
+/**
+ * Вход сотрудника — тот же логин и пароль, что в CRM.
+ *
+ * Экран нужен, пока приложение обкатывается: интерфейс проверяется на живых
+ * данных, а живые данные лежат у настоящих водителей. Отдельного входа «за
+ * водителя» здесь нет: сотрудник входит СОБОЙ, а дальше выбирает, чей экран
+ * смотреть, — и это записывается в аудит CRM.
+ */
+export function DevLoginPage() {
+  const nav = useNavigate();
+  const { token: staffToken, username: staffName, setStaff, clear } = useStaff();
+  const [username, setUsername] = useState("");
+  const [password, setPassword] = useState("");
+  const [partial, setPartial] = useState<string | null>(null);
+  const [code, setCode] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  async function submit() {
+    if (!username || !password || busy) return;
+    setBusy(true);
+    try {
+      const r = await staffLogin(username, password);
+      if (r.requires_2fa && r.partial_token) {
+        setPartial(r.partial_token);
+        return;
+      }
+      if (!r.access_token) throw new Error("no token");
+      setStaff(r.access_token, username);
+    } catch (e: unknown) {
+      toast.error(await apiErrorText(e, "Неверный логин или пароль"));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function submit2fa(value = code) {
+    if (!partial || value.length < 6 || busy) return;
+    setBusy(true);
+    try {
+      const r = await staffLogin2fa(partial, value);
+      if (!r.access_token) throw new Error("no token");
+      setStaff(r.access_token, username);
+      setPartial(null);
+    } catch (e: unknown) {
+      toast.error(await apiErrorText(e, "Код не подошёл"));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (staffToken) {
+    return (
+      <div className="pt-10">
+        <h1 className="text-lg font-extrabold mb-1">Кого смотрим</h1>
+        <p className="text-muted text-xs mb-5">
+          Сотрудник: {staffName}. Приложение откроется от лица выбранного водителя,
+          деньги в этом режиме не двигаются.
+        </p>
+        <DriverPicker onPicked={() => nav("/")} />
+        <button className="btn-ghost mt-5" onClick={clear}>Выйти из учётки сотрудника</button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="pt-16">
+      <h1 className="text-xl font-extrabold mb-1">Вход для сотрудника</h1>
+      <p className="text-muted text-sm mb-8">Учётная запись Premium CRM</p>
+
+      {partial ? (
+        <>
+          <p className="text-sm mb-2">Код из приложения-аутентификатора.</p>
+          <input
+            autoFocus
+            inputMode="numeric"
+            autoComplete="one-time-code"
+            value={code}
+            onChange={(e) => {
+              const next = e.target.value.replace(/\D/g, "").slice(0, 6);
+              setCode(next);
+              // Шесть цифр — код собран, ждать нажатия нечего: у TOTP всё равно
+              // остаётся секунд тридцать. Раньше отправки не было ни по Enter, ни
+              // по «Готово» на клавиатуре телефона, и это выглядело как «код не принят».
+              if (next.length === 6) void submit2fa(next);
+            }}
+            onKeyDown={(e) => { if (e.key === "Enter") void submit2fa(); }}
+            placeholder="000000"
+            className="card w-full px-4 py-3 mb-3 text-base tracking-widest bg-surface"
+          />
+          <button className="btn-primary" disabled={busy || code.length < 6} onClick={() => submit2fa()}>
+            {busy ? <Spinner /> : "Подтвердить"}
+          </button>
+          <button className="btn-ghost mt-2" onClick={() => { setPartial(null); setCode(""); }}>
+            Назад
+          </button>
+        </>
+      ) : (
+        <>
+          <input
+            autoCapitalize="none"
+            autoCorrect="off"
+            value={username}
+            onChange={(e) => setUsername(e.target.value)}
+            placeholder="Логин"
+            className="card w-full px-4 py-3 mb-2 text-base bg-surface"
+          />
+          <input
+            type="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            onKeyDown={(e) => { if (e.key === "Enter") submit(); }}
+            placeholder="Пароль"
+            className="card w-full px-4 py-3 mb-3 text-base bg-surface"
+          />
+          <button className="btn-primary" disabled={busy || !username || !password} onClick={submit}>
+            {busy ? <Spinner /> : "Войти"}
+          </button>
+          <button className="btn-ghost mt-2" onClick={() => nav("/login")}>Я водитель</button>
+        </>
+      )}
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/FineDetailPage.tsx

@@ -0,0 +1,115 @@
+import { useQuery } from "@tanstack/react-query";
+import { useNavigate, useParams } from "react-router-dom";
+import { FileText, Gauge } from "lucide-react";
+import { getFine } from "@/api/driver";
+import { fineStatusText, isOwed } from "@/lib/fineStatus";
+import { formatDate, formatMoney } from "@/lib/format";
+import { Spinner } from "@/components/Spinner";
+
+function Row({ k, v }: { k: string; v: string }) {
+  return (
+    <div className="flex justify-between gap-3 py-2 border-b border-line last:border-0">
+      <span className="text-muted text-xs shrink-0">{k}</span>
+      <span className="text-xs text-right">{v}</span>
+    </div>
+  );
+}
+
+/**
+ * Карточка штрафа. Главное здесь — фотография с камеры: по ней водитель узнаёт
+ * свою машину и свою поездку либо понимает, что штраф не его. Поэтому она стоит
+ * первой, до реквизитов, и открывается в полный размер по нажатию.
+ *
+ * Что парк заплатил ГИБДД, со скидкой ли и какой номинал у постановления — здесь
+ * не показывается: водителю нужен факт штрафа и сумма к возврату, а разбор
+ * расчётов парка уводит разговор от долга к внутренней кухне.
+ */
+export function FineDetailPage() {
+  const { fineId = "" } = useParams();
+  const nav = useNavigate();
+  const { data: f, isLoading, isError } = useQuery({
+    queryKey: ["fine", fineId],
+    queryFn: () => getFine(Number(fineId)),
+  });
+
+  if (isLoading) return <div className="flex justify-center py-16"><Spinner /></div>;
+  if (isError || !f) {
+    return (
+      <div className="pt-16 text-center">
+        <p className="text-sm font-semibold mb-1">Штраф не найден</p>
+        <p className="text-muted text-xs mb-6">Возможно, он больше не числится за вами.</p>
+        <button className="btn-ghost" onClick={() => nav("/")}>На главную</button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="pt-2 pb-4">
+      <button className="text-muted text-xs mb-3" onClick={() => nav("/")}>‹ Назад</button>
+
+      {f.photos.length > 0 ? (
+        <div className="mb-4 space-y-2">
+          {f.photos.map((src, i) => (
+            <a key={src} href={src} target="_blank" rel="noopener noreferrer" className="block">
+              <img
+                src={src}
+                alt={`Фото нарушения ${i + 1}`}
+                loading="lazy"
+                className="w-full rounded-xl2 border border-line"
+              />
+            </a>
+          ))}
+          <p className="text-muted text-[11px]">Нажмите на фото, чтобы открыть в полном размере</p>
+        </div>
+      ) : (
+        <p className="text-muted text-xs mb-4">
+          Фотографии по этому постановлению нет — её присылают не по всем нарушениям.
+        </p>
+      )}
+
+      <h1 className="text-base font-extrabold mb-1">{f.article}</h1>
+      <p className="text-muted text-xs mb-4">
+        {formatDate(f.date)}{f.address ? ` · ${f.address}` : ""}
+      </p>
+
+      <div className="card p-4 mb-4 text-center">
+        <p className="text-muted text-xs mb-1">Начислено вам</p>
+        <p className={`text-2xl font-extrabold ${isOwed(f) ? "text-neg" : ""}`}>
+          {formatMoney(f.amount)}
+        </p>
+        <p className="text-muted text-xs mt-1">{fineStatusText(f)}</p>
+      </div>
+
+      {f.speed != null && f.speed_limit != null && (
+        <div className="card p-4 mb-4 flex items-center gap-3">
+          <Gauge size={20} strokeWidth={1.5} className="text-muted shrink-0" />
+          <p className="text-sm">
+            {f.speed} км/ч при разрешённых {f.speed_limit}
+            {f.speed_excess ? ` — превышение на ${f.speed_excess}` : ""}
+          </p>
+        </div>
+      )}
+
+      <div className="card p-4 mb-4">
+        <Row k="Постановление" v={f.number} />
+        {f.post_date && <Row k="Дата постановления" v={formatDate(f.post_date)} />}
+        {f.car_number && <Row k="Автомобиль" v={f.car_number} />}
+        {f.camera && <Row k="Камера" v={f.camera} />}
+      </div>
+
+      {f.document && (
+        <a href={f.document} target="_blank" rel="noopener noreferrer"
+           className="btn-ghost flex items-center justify-center gap-2 no-underline mb-2">
+          <FileText size={16} /> Открыть постановление
+        </a>
+      )}
+
+      {isOwed(f) && (
+        <button className="btn-primary"
+                onClick={() => nav("/topup", { state: { bucket: "Долг по штрафам" } })}>
+          Оплатить штрафы
+        </button>
+      )}
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/LoginPage.test.tsx

@@ -0,0 +1,32 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router-dom";
+
+vi.mock("@/api/driver", () => ({
+  authRequest: vi.fn(async () => ({ status: "code_sent", channel: "tg" })),
+  authVerify: vi.fn(async () => ({ token: "T", driver_id: 7 })),
+  tgSession: vi.fn(async () => ({ pair_session: "sess123", deep_link: null })),
+}));
+
+import { LoginPage } from "./LoginPage";
+import * as driver from "@/api/driver";
+import { useAuth } from "@/store/auth";
+
+const wrap = () => render(<MemoryRouter><LoginPage /></MemoryRouter>);
+
+describe("LoginPage", () => {
+  beforeEach(() => useAuth.getState().clear());
+  it("requests code then verifies and stores session", async () => {
+    wrap();
+    expect(screen.getByText(/Вход в приложение/i)).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: /Войти по коду/i }));
+    await userEvent.type(screen.getByPlaceholderText(/телефон/i), "9143054400");
+    await userEvent.click(screen.getByRole("button", { name: /Получить код/i }));
+    expect(driver.authRequest).toHaveBeenCalledWith("79143054400");
+    const codeInput = await screen.findByPlaceholderText(/код/i);
+    await userEvent.type(codeInput, "123456");
+    await userEvent.click(screen.getByRole("button", { name: /Войти/i }));
+    expect(driver.authVerify).toHaveBeenCalledWith("79143054400", "123456");
+  });
+});

driver-pwa/frontend/src/pages/LoginPage.tsx

@@ -0,0 +1,187 @@
+import { useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { toast } from "sonner";
+import { apiErrorText, authRequest, authVerify, retryAfterSeconds, tgSession } from "@/api/driver";
+import { digitsOnly, formatPhone } from "@/lib/format";
+import { savePairing } from "@/lib/pairing";
+import { takeReturnTo } from "@/lib/returnTo";
+import { useAuth } from "@/store/auth";
+import { Spinner } from "@/components/Spinner";
+
+// Кулдаун повторной отправки кода — синхронно с бэкендом (60с). Точное значение
+// приходит в Retry-After на 429; это дефолт после успешной отправки.
+const RESEND_COOLDOWN_SEC = 60;
+
+function fmtMMSS(sec: number): string {
+  const m = Math.floor(sec / 60);
+  const s = sec % 60;
+  return `${m}:${String(s).padStart(2, "0")}`;
+}
+
+export function LoginPage() {
+  const nav = useNavigate();
+  const setSession = useAuth((s) => s.setSession);
+  const [phone, setPhone] = useState("");          // national 10 digits
+  const [code, setCode] = useState("");
+  const [step, setStep] = useState<"phone" | "code">("phone");
+  const [channel, setChannel] = useState<string>("");
+  const [busy, setBusy] = useState(false);
+  const [mode, setMode] = useState<"choose" | "code">("choose");
+  // Секунды до разрешённой повторной отправки кода (0 — можно отправлять).
+  const [cooldown, setCooldown] = useState(0);
+  // Prefetched pairing session so the «Войти через Telegram» control is a real
+  // <a href> the OS opens in Telegram (a synchronous user gesture) WITHOUT
+  // navigating the PWA away — the app stays mounted on /tg-wait and polls.
+  const [tg, setTg] = useState<{ pair_session: string; poll_secret: string;
+                                 confirm_code: string; deep_link: string | null } | null>(null);
+  const e164 = "7" + phone;
+
+  useEffect(() => {
+    let alive = true;
+    tgSession().then((r) => { if (alive) setTg(r); }).catch(() => {});
+    return () => { alive = false; };
+  }, []);
+
+  // Тик обратного отсчёта повторной отправки.
+  useEffect(() => {
+    if (cooldown <= 0) return;
+    const t = setTimeout(() => setCooldown((s) => Math.max(0, s - 1)), 1000);
+    return () => clearTimeout(t);
+  }, [cooldown]);
+
+  function startTg() {
+    if (!tg) return;
+    savePairing(tg);
+    nav("/tg-wait");
+  }
+
+  async function requestCode() {
+    if (phone.length < 10 || cooldown > 0) return;
+    setBusy(true);
+    try {
+      const r = await authRequest(e164);
+      if (r.status === "onboarding") {
+        // Онбординг теперь идёт той же pairing-сессией: бот попросит поделиться
+        // контактом, Telegram подтвердит номер, приложение заберёт токен опросом.
+        // Второй раз номер вводить не нужно.
+        savePairing({ ...r, deep_link: r.deep_links.tg ?? null });
+        sessionStorage.setItem("pp-onboarding", JSON.stringify({ ...r.deep_links, phone }));
+        nav("/onboarding");
+        return;
+      }
+      setChannel(r.channel);
+      setStep("code");
+      // Запускаем отсчёт до повторной отправки — чтобы водитель не жал повторно
+      // раньше времени и не упирался в «слишком часто».
+      setCooldown(RESEND_COOLDOWN_SEC);
+    } catch (err: unknown) {
+      const status = (err as { response?: { status?: number } })?.response?.status;
+      if (status === 429) {
+        // Точный остаток — из Retry-After; ведём по нему отсчёт и не пугаем.
+        const wait = retryAfterSeconds(err) ?? RESEND_COOLDOWN_SEC;
+        setCooldown(wait);
+        if (step === "phone") setStep("code");  // код мог уйти ранее — дать ввести
+        toast.info(await apiErrorText(err, `Код уже отправляли. Повторить можно через ${wait} сек.`));
+      } else {
+        const fallback =
+          status === 404 ? "Номер не найден. Обратитесь в парк." :
+          "Не удалось отправить код";
+        toast.error(await apiErrorText(err, fallback));
+      }
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function verify() {
+    if (code.length < 4) return;
+    setBusy(true);
+    try {
+      const r = await authVerify(e164, code);
+      setSession(r.token, r.driver_id);
+      // Возврат туда, откуда пришёл (напр. ссылка на оплату), иначе на баланс.
+      nav(takeReturnTo(), { replace: true });
+    } catch (err: unknown) {
+      toast.error(await apiErrorText(err, "Неверный или просроченный код"));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="pt-16">
+      <h1 className="text-xl font-extrabold mb-1">Премиум Водитель</h1>
+      <p className="text-muted text-sm mb-8">Вход в приложение</p>
+
+      {mode === "choose" ? (
+        <>
+          {tg?.deep_link ? (
+            <a
+              href={tg.deep_link}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="btn-primary block text-center"
+              onClick={startTg}
+            >
+              Войти через Telegram
+            </a>
+          ) : (
+            <button className="btn-primary" disabled>
+              <Spinner />
+            </button>
+          )}
+          <p className="text-muted text-xs mt-3">Telegram подтвердит ваш номер автоматически.</p>
+          <button className="btn-ghost mt-4" onClick={() => setMode("code")}>Войти по коду</button>
+          {/* Пока идёт обкатка, сотруднику надо попадать внутрь без карточки
+              водителя и без бота — учёткой CRM. Ссылка неприметная намеренно. */}
+          <button className="text-muted text-xs w-full mt-6" onClick={() => nav("/dev")}>
+            Вход для сотрудника
+          </button>
+        </>
+      ) : (
+        <>
+          {step === "phone" ? (
+            <>
+              <input
+                inputMode="numeric"
+                placeholder="Номер телефона"
+                value={phone ? formatPhone(phone) : ""}
+                onChange={(e) => setPhone(digitsOnly(e.target.value).replace(/^7/, "").slice(0, 10))}
+                className="card w-full px-4 py-3 mb-3 text-base bg-surface"
+              />
+              <button className="btn-primary" disabled={busy || phone.length < 10 || cooldown > 0} onClick={requestCode}>
+                {busy ? <Spinner /> : cooldown > 0 ? `Повторить через ${fmtMMSS(cooldown)}` : "Получить код"}
+              </button>
+              <p className="text-muted text-xs mt-3">Код придёт в Telegram или MAX.</p>
+            </>
+          ) : (
+            <>
+              <p className="text-sm mb-2">Код отправлен в {channel === "max" ? "MAX" : "Telegram"}.</p>
+              <input
+                inputMode="numeric"
+                placeholder="Код из сообщения"
+                value={code}
+                onChange={(e) => setCode(digitsOnly(e.target.value).slice(0, 6))}
+                className="card w-full px-4 py-3 mb-3 text-base tracking-widest bg-surface"
+              />
+              <button className="btn-primary" disabled={busy || code.length < 4} onClick={verify}>
+                {busy ? <Spinner /> : "Войти"}
+              </button>
+              {/* Повторная отправка прямо здесь: не пришёл код — не надо
+                  возвращаться к номеру и упираться в «слишком часто». Кнопка
+                  ждёт кулдаун и показывает, сколько осталось. */}
+              <button
+                className="btn-ghost mt-2"
+                disabled={busy || cooldown > 0}
+                onClick={requestCode}
+              >
+                {cooldown > 0 ? `Отправить ещё раз через ${fmtMMSS(cooldown)}` : "Отправить код ещё раз"}
+              </button>
+              <button className="btn-ghost mt-1" onClick={() => setStep("phone")}>Изменить номер</button>
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/MockPayPage.test.tsx

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+
+vi.mock("@/api/driver", () => ({
+  mockPayOutcome: vi.fn(async () => ({ order_id: "mock-1", status: "PAID" })),
+  apiErrorText: vi.fn(async (_e: unknown, f: string) => f),
+}));
+
+import { MockPayPage } from "./MockPayPage";
+import * as driver from "@/api/driver";
+import { useAuth } from "@/store/auth";
+
+const wrap = () =>
+  render(
+    <MemoryRouter initialEntries={["/mock-pay/mock-1"]}>
+      <Routes>
+        <Route path="/mock-pay/:orderId" element={<MockPayPage />} />
+        <Route path="/pay/:orderId" element={<p>экран оплаты</p>} />
+      </Routes>
+    </MemoryRouter>
+  );
+
+describe("MockPayPage", () => {
+  beforeEach(() => { useAuth.getState().clear(); vi.clearAllMocks(); });
+
+  it("исход уходит на бэкенд и возвращает на настоящий экран оплаты", async () => {
+    useAuth.getState().setSession("t", 42, { impersonated: true, driverName: "Петров" });
+    wrap();
+    await userEvent.click(screen.getByRole("button", { name: /Банк отклонил/ }));
+    expect(driver.mockPayOutcome).toHaveBeenCalledWith("mock-1", "rejected");
+    expect(await screen.findByText("экран оплаты")).toBeInTheDocument();
+  });
+
+  it("водителю тут делать нечего", async () => {
+    useAuth.getState().setSession("t", 42);
+    wrap();
+    expect(screen.getByText(/Учебная оплата недоступна/)).toBeInTheDocument();
+    expect(driver.mockPayOutcome).not.toHaveBeenCalled();
+  });
+});

driver-pwa/frontend/src/pages/MockPayPage.tsx

@@ -0,0 +1,77 @@
+import { useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { toast } from "sonner";
+import { apiErrorText, mockPayOutcome } from "@/api/driver";
+import { useAuth } from "@/store/auth";
+import { Spinner } from "@/components/Spinner";
+
+/**
+ * Учебная «касса»: чем закончится платёж, который сотрудник создал под просмотром.
+ *
+ * Это подмена банка, а не экрана приложения. Настоящий экран оплаты
+ * (`/pay/:orderId`) остаётся тем же самым и разбирает те же статусы — иначе
+ * отладка проверяла бы поведение, которого у водителя не будет.
+ */
+const OUTCOMES = [
+  { key: "paid", label: "Оплата прошла", hint: "PAID — экран «Оплачено»" },
+  { key: "rejected", label: "Банк отклонил", hint: "REJECTED — «Оплата не прошла»" },
+  { key: "expired", label: "Счёт протух", hint: "DEADLINE_EXPIRED — «Срок оплаты истёк»" },
+  { key: "reversed", label: "Деньги вернулись", hint: "REVERSED — «Платёж возвращён»" },
+] as const;
+
+export function MockPayPage() {
+  const { orderId = "" } = useParams();
+  const nav = useNavigate();
+  const impersonated = useAuth((s) => s.impersonated);
+  const [busy, setBusy] = useState<string | null>(null);
+
+  async function choose(outcome: (typeof OUTCOMES)[number]["key"]) {
+    setBusy(outcome);
+    try {
+      await mockPayOutcome(orderId, outcome);
+      nav(`/pay/${orderId}`, { replace: true });
+    } catch (e: unknown) {
+      toast.error(await apiErrorText(e, "Не удалось разыграть исход"));
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  if (!impersonated) {
+    return (
+      <div className="pt-24 text-center">
+        <p className="text-sm font-semibold mb-1">Учебная оплата недоступна</p>
+        <p className="text-muted text-xs mb-6">Этот экран работает только при просмотре сотрудником.</p>
+        <button className="btn-ghost" onClick={() => nav("/")}>На главную</button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="pt-8">
+      <button className="text-muted text-xs mb-3" onClick={() => nav(-1)}>‹ Назад</button>
+      <h1 className="text-lg font-extrabold mb-1">Учебная оплата</h1>
+      <p className="text-muted text-xs mb-5">
+        Банка в этом платеже нет: ни списания, ни чека, ни проводки. Выберите, что
+        «ответит» банк — приложение покажет ровно то же, что увидел бы водитель.
+      </p>
+      <div className="card divide-y divide-line">
+        {OUTCOMES.map((o) => (
+          <button
+            key={o.key}
+            disabled={busy !== null}
+            onClick={() => choose(o.key)}
+            className="w-full text-left px-4 py-3 flex items-center justify-between gap-3 disabled:opacity-50"
+          >
+            <span>
+              <span className="block text-sm font-semibold">{o.label}</span>
+              <span className="block text-muted text-xs">{o.hint}</span>
+            </span>
+            {busy === o.key && <Spinner />}
+          </button>
+        ))}
+      </div>
+      <p className="text-muted text-xs mt-4">Заказ: {orderId}</p>
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/NotificationsPage.test.tsx

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+
+vi.mock("@/api/driver", () => ({
+  getNotifications: vi.fn(async () => ({
+    items: [
+      { id: 2, kind: "fine", title: "Новый штраф", body: "Постановление от 18.08.2026.",
+        url: "/fines/12", created_at: "2026-08-18T10:15:00+10:00", read_at: null },
+      { id: 1, kind: "topup", title: "Платёж получен", body: "Пополнение принято.",
+        url: "/", created_at: "2026-08-17T09:00:00+10:00", read_at: "2026-08-17T09:05:00+10:00" },
+    ],
+    unread: 1,
+  })),
+  markNotificationsRead: vi.fn(async () => ({ marked: 1 })),
+}));
+
+import { NotificationsPage } from "./NotificationsPage";
+import * as api from "@/api/driver";
+
+const show = () => render(<MemoryRouter><NotificationsPage /></MemoryRouter>);
+
+describe("лента уведомлений", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("показывает, что мы писали водителю", async () => {
+    show();
+    expect(await screen.findByText("Новый штраф")).toBeInTheDocument();
+    expect(screen.getByText("Платёж получен")).toBeInTheDocument();
+    // Дата человеку — ДД.ММ.ГГГГ, не ISO (текст постановления содержит её же).
+    expect(screen.getByText("18.08.2026 10:15")).toBeInTheDocument();
+  });
+
+  it("открытие ленты отмечает непрочитанное", async () => {
+    show();
+    await screen.findByText("Новый штраф");
+    // Это единственный честный источник отметки: пуш живёт до смахивания, а
+    // сообщение в боте тонет в переписке — там прочтения не видно вовсе.
+    expect(api.markNotificationsRead).toHaveBeenCalled();
+  });
+
+  it("без непрочитанного лишний запрос не делаем", async () => {
+    vi.mocked(api.getNotifications).mockResolvedValueOnce({ items: [], unread: 0 });
+    show();
+    expect(await screen.findByText(/Пока ничего не приходило/)).toBeInTheDocument();
+    expect(api.markNotificationsRead).not.toHaveBeenCalled();
+  });
+});

driver-pwa/frontend/src/pages/NotificationsPage.tsx

@@ -0,0 +1,122 @@
+import { useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { Bell } from "lucide-react";
+
+import { getNotifications, markNotificationsRead, type DriverNotification } from "@/api/driver";
+import { AppHeader } from "@/components/AppHeader";
+import { Spinner } from "@/components/Spinner";
+import { OperationIcon } from "@/components/operationIcon";
+
+// Значок берём тем же подбором, что и в выписке: событие приложения переводим
+// в тег 1С, чтобы штраф в ленте выглядел так же, как штраф в списке операций.
+const ICON_BY_KIND: Record<string, string> = {
+  fine: "Штраф ГИБДД",
+  topup: "Пополнение баланса",
+};
+
+/**
+ * Лента уведомлений водителя.
+ *
+ * Нужна не только водителю. Пуш живёт до первого смахивания, сообщение в боте
+ * тонет в переписке — и разговор «мне ничего не приходило» упирался в слово
+ * против слова. Здесь у водителя есть место, куда посмотреть, а у парка —
+ * честная отметка «прочитано»: она ставится ровно тогда, когда человек открыл
+ * этот экран или нажал на само уведомление, и ниоткуда больше.
+ *
+ * Отмечаем прочитанным ПОСЛЕ показа, а не при загрузке: иначе счётчик гаснет у
+ * того, кто просто мазнул по экрану и ушёл.
+ */
+export function NotificationsPage() {
+  const nav = useNavigate();
+  const [items, setItems] = useState<DriverNotification[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    getNotifications()
+      .then((r) => {
+        if (!alive) return;
+        setItems(r.items);
+        if (r.unread > 0) void markNotificationsRead();
+      })
+      .catch(() => alive && setError("Не удалось загрузить уведомления"));
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  return (
+    <div className="p-4">
+      <AppHeader />
+      <h1 className="text-lg font-bold mb-3">Уведомления</h1>
+
+      {error && <div className="text-sm text-muted">{error}</div>}
+      {!items && !error && <Spinner />}
+
+      {items && items.length === 0 && (
+        <div className="text-sm text-muted">
+          Пока ничего не приходило. Здесь будут появляться сообщения о штрафах и платежах.
+        </div>
+      )}
+
+      <div className="flex flex-col gap-2">
+        {items?.map((n) => (
+          <button
+            key={n.id}
+            type="button"
+            className="flex gap-3 items-start text-left bg-surface border border-line rounded-xl p-3"
+            onClick={() => n.url && nav(n.url)}
+          >
+            <OperationIcon title={ICON_BY_KIND[n.kind] ?? ""} />
+            <span className="flex-1 min-w-0">
+              <span className="flex items-baseline gap-2">
+                <span className="font-semibold text-sm">{n.title}</span>
+                {!n.read_at && <span className="w-2 h-2 rounded-full bg-accent shrink-0" />}
+              </span>
+              <span className="block text-sm text-muted mt-0.5">{n.body}</span>
+              <span className="block text-xs text-muted mt-1">{when(n.created_at)}</span>
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/** Дата человеку — ДД.ММ.ГГГГ и время, без ISO. */
+function when(ts: string | null): string {
+  if (!ts) return "";
+  const d = new Date(ts);
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${p(d.getDate())}.${p(d.getMonth() + 1)}.${d.getFullYear()} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** Колокольчик со счётчиком непрочитанного — для шапки главного экрана. */
+export function NotificationsBell() {
+  const nav = useNavigate();
+  const [unread, setUnread] = useState(0);
+
+  useEffect(() => {
+    let alive = true;
+    getNotifications()
+      .then((r) => alive && setUnread(r.unread))
+      // Молча: колокольчик — не тот элемент, ради которого стоит показывать ошибку.
+      .catch(() => undefined);
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  return (
+    <button type="button" className="relative p-1 -m-1" aria-label="Уведомления"
+            onClick={() => nav("/notifications")}>
+      <Bell size={22} strokeWidth={1.5} />
+      {unread > 0 && (
+        <span className="absolute -top-0.5 -right-0.5 min-w-4 h-4 px-1 rounded-full bg-accent
+                         text-white text-[10px] leading-4 text-center">
+          {unread > 9 ? "9+" : unread}
+        </span>
+      )}
+    </button>
+  );
+}

driver-pwa/frontend/src/pages/OnboardingPage.test.tsx

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { OnboardingPage } from "./OnboardingPage";
+import { savePairing, clearPairing } from "@/lib/pairing";
+
+describe("OnboardingPage", () => {
+  beforeEach(() => {
+    clearPairing();
+    sessionStorage.setItem("pp-onboarding", JSON.stringify({ tg: "https://t.me/b?start=x", max: "https://max.ru/b?start=x", phone: "9143054400" }));
+  });
+
+  it("shows both bot links + back to login", () => {
+    render(<MemoryRouter><OnboardingPage /></MemoryRouter>);
+    expect(screen.getByText(/Подключите бот/i)).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /Telegram/i })).toHaveAttribute("href", "https://t.me/b?start=x");
+    expect(screen.getByRole("link", { name: /MAX/i })).toHaveAttribute("href", "https://max.ru/b?start=x");
+    expect(screen.getByRole("button", { name: /Назад ко входу/i })).toBeInTheDocument();
+  });
+
+  it("renders only Telegram when max is absent", () => {
+    sessionStorage.setItem("pp-onboarding", JSON.stringify({ tg: "https://t.me/ppdriver_bot?start=x", phone: "9143054400" }));
+    render(<MemoryRouter><OnboardingPage /></MemoryRouter>);
+    expect(screen.getByRole("link", { name: /Telegram/i })).toBeInTheDocument();
+    expect(screen.queryByRole("link", { name: /MAX/i })).toBeNull();
+  });
+
+  it("shows the confirm code the bot must repeat", () => {
+    // Защита от фишинга: если ссылку прислал посторонний, у человека этого числа
+    // на экране нет — значит и делиться номером не нужно.
+    savePairing({ pair_session: "S", poll_secret: "SEC", confirm_code: "4217", deep_link: "https://t.me/b?start=S" });
+    render(<MemoryRouter><OnboardingPage /></MemoryRouter>);
+    expect(screen.getByText("4217")).toBeInTheDocument();
+  });
+
+  it("no longer asks the driver to come back for a code", () => {
+    // Онбординг идёт той же pairing-сессией: Telegram подтверждает номер, и
+    // приложение забирает токен опросом — второй раз номер вводить не нужно.
+    render(<MemoryRouter><OnboardingPage /></MemoryRouter>);
+    expect(screen.queryByRole("button", { name: /запросить код/i })).toBeNull();
+  });
+});

driver-pwa/frontend/src/pages/OnboardingPage.tsx

@@ -0,0 +1,48 @@
+import { useNavigate } from "react-router-dom";
+import { loadPairing } from "@/lib/pairing";
+
+export function OnboardingPage() {
+  const nav = useNavigate();
+  const raw = sessionStorage.getItem("pp-onboarding");
+  const data = raw ? (JSON.parse(raw) as { tg?: string; max?: string; phone: string }) : null;
+  const pairing = loadPairing();
+  if (!data) return null;
+
+  return (
+    <div className="pt-16">
+      <h1 className="text-xl font-extrabold mb-1">Подключите бот</h1>
+      <p className="text-muted text-sm mb-8">
+        Откройте бот и поделитесь своим номером — Telegram подтвердит его, и вход
+        произойдёт автоматически. Возвращаться за кодом не нужно.
+      </p>
+      {pairing?.confirmCode && (
+        <div className="card p-4 mb-6 text-center">
+          <p className="text-muted text-xs mb-1">Код подтверждения</p>
+          <p className="text-2xl font-extrabold tracking-widest">{pairing.confirmCode}</p>
+          <p className="text-muted text-xs mt-2">
+            Бот назовёт это число. Не совпало — закройте бот и не делитесь номером.
+          </p>
+        </div>
+      )}
+      {data.tg && (
+        <a
+          href={data.tg}
+          target="_blank"
+          rel="noopener"
+          className="btn-primary mb-3 no-underline block"
+          onClick={() => nav("/tg-wait")}
+        >
+          Подключить Telegram
+        </a>
+      )}
+      {data.max && (
+        <a href={data.max} target="_blank" rel="noopener" className="btn-ghost mb-6 no-underline block">
+          Подключить MAX
+        </a>
+      )}
+      <button className="btn-ghost" onClick={() => nav("/login")}>
+        Назад ко входу
+      </button>
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/PaymentPage.test.tsx

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter, Routes, Route } from "react-router-dom";
+
+const states = ["FORM", "PAID"];
+vi.mock("@/api/driver", () => ({
+  getPaymentState: vi.fn(async () => ({ order_id: "o9", status: states.shift() ?? "PAID" })),
+}));
+import { PaymentPage } from "./PaymentPage";
+
+function wrap() {
+  const qc = new QueryClient();
+  return render(
+    <QueryClientProvider client={qc}>
+      <MemoryRouter initialEntries={[{ pathname: "/pay/o9", state: { payUrl: "https://qr.nspk.ru/x", total: 1052, bucket: "Долг аренда", base: 1000 } }]}>
+        <Routes><Route path="/pay/:orderId" element={<PaymentPage />} /></Routes>
+      </MemoryRouter>
+    </QueryClientProvider>
+  );
+}
+
+describe("PaymentPage", () => {
+  it("shows pay button and flips to success on PAID", async () => {
+    wrap();
+    expect(screen.getByRole("link", { name: /Оплатить/i })).toHaveAttribute("href", "https://qr.nspk.ru/x");
+    await waitFor(() => expect(screen.getByText(/Оплачено/i)).toBeInTheDocument(), { timeout: 3000 });
+  });
+});

driver-pwa/frontend/src/pages/PaymentPage.tsx

@@ -0,0 +1,136 @@
+import { useEffect } from "react";
+import { useLocation, useNavigate, useParams } from "react-router-dom";
+import { useQueryClient } from "@tanstack/react-query";
+import { Check, Clock, Undo2, WifiOff, X } from "lucide-react";
+import { formatMoney } from "@/lib/format";
+import { markPaymentActivity } from "@/lib/paymentWatch";
+import { Spinner } from "@/components/Spinner";
+import { usePaymentStatus } from "@/hooks/usePaymentStatus";
+
+// платёж не состоялся, деньги не ушли — помогает только новая попытка.
+// ATTEMPTS_EXPIRED — исчерпаны попытки ввода на форме банка, тот же исход для водителя
+const FAILED = new Set(["REJECTED", "AUTH_FAIL", "ERROR", "CANCELED", "ATTEMPTS_EXPIRED"]);
+// деньги дошли и вернулись обратно — новая попытка тут ни при чём, человеку нужен другой текст
+const RETURNED = new Set(["REVERSED", "REFUNDED", "PARTIAL_REVERSED", "PARTIAL_REFUNDED"]);
+// сколько неудач подряд терпим, прежде чем сказать вслух, что связи нет: ~15 секунд опроса.
+// одиночный сбой пережидаем молча — следующий опрос обычно всё чинит
+const FAIL_LIMIT = 10;
+
+export function PaymentPage() {
+  const { orderId = "" } = useParams();
+  const nav = useNavigate();
+  const qc = useQueryClient();
+  const st = (useLocation().state as
+    { payUrl?: string; total?: number; bucket?: string; base?: number; method?: string } | null) ?? {};
+  const { data, lastFailed, failStreak, refetch } = usePaymentStatus(orderId);
+  // Учебный платёж узнаётся по номеру заказа, а не по state роутера: state
+  // теряется при перезагрузке, а префикс — нет (см. backend mock_pay).
+  const mock = orderId.startsWith("mock-");
+  const status = data?.status ?? "";
+  const paid = status === "PAID";
+  // пока метод не передан в state — узнаём по ссылке: СБП отдаёт платёжку qr.nspk.ru, карта — форму банка
+  const card = st.method ? st.method === "card" : !!st.payUrl && !st.payUrl.includes("qr.nspk.ru");
+
+  useEffect(() => {
+    if (paid) {
+      // Отметка продлевает окно опроса баланса от ФАКТА оплаты: путь до нового
+      // итога (запись в 1С + снимок) начинается только теперь.
+      markPaymentActivity();
+      qc.invalidateQueries({ queryKey: ["balance"] });
+    }
+  }, [paid, qc]);
+
+  const retry = (
+    <button className="btn-primary mt-8" onClick={() => nav("/topup", { state: { bucket: st.bucket }, replace: true })}>
+      Пополнить ещё раз
+    </button>
+  );
+
+  if (paid) {
+    return (
+      <div className="pt-24 flex flex-col items-center text-center">
+        <span className="w-14 h-14 rounded-full bg-pos text-white flex items-center justify-center mb-3"><Check size={28} /></span>
+        <p className="text-lg font-extrabold">Оплачено</p>
+        <p className="text-muted text-xs mt-1">
+          {st.base != null ? `${st.bucket ?? "Баланс"} пополнен на ${formatMoney(st.base)}` : "Баланс пополнен"}
+        </p>
+        <button className="btn-primary mt-8" onClick={() => nav("/")}>На главную</button>
+      </div>
+    );
+  }
+
+  // без этих веток человек оставался на «Ожидаем оплату…» навсегда: опрос уже остановлен
+  if (status === "DEADLINE_EXPIRED") {
+    return (
+      <div className="pt-24 flex flex-col items-center text-center">
+        <span className="w-14 h-14 rounded-full bg-neg text-white flex items-center justify-center mb-3"><Clock size={28} /></span>
+        <p className="text-lg font-extrabold">Срок оплаты истёк</p>
+        <p className="text-muted text-xs mt-1">Счёт больше не действует. Деньги не списаны — создайте новый.</p>
+        {retry}
+      </div>
+    );
+  }
+
+  if (FAILED.has(status)) {
+    return (
+      <div className="pt-24 flex flex-col items-center text-center">
+        <span className="w-14 h-14 rounded-full bg-neg text-white flex items-center justify-center mb-3"><X size={28} /></span>
+        <p className="text-lg font-extrabold">Оплата не прошла</p>
+        <p className="text-muted text-xs mt-1">Банк не провёл перевод. Деньги не списаны — попробуйте ещё раз.</p>
+        {retry}
+      </div>
+    );
+  }
+
+  if (RETURNED.has(status)) {
+    return (
+      <div className="pt-24 flex flex-col items-center text-center">
+        <span className="w-14 h-14 rounded-full bg-neg text-white flex items-center justify-center mb-3"><Undo2 size={28} /></span>
+        <p className="text-lg font-extrabold">Платёж возвращён</p>
+        <p className="text-muted text-xs mt-1">Деньги вернулись на счёт, с которого платили. Баланс пересчитаем.</p>
+        <button className="btn-primary mt-8" onClick={() => nav("/")}>На главную</button>
+      </div>
+    );
+  }
+
+  // раньше упавший бэкенд выглядел ровно как честное ожидание оплаты — крутился спиннер.
+  // сам опрос не прекращаем: как только бэкенд ответит, экран вернётся к оплате
+  if (lastFailed && failStreak >= FAIL_LIMIT) {
+    return (
+      <div className="pt-24 flex flex-col items-center text-center">
+        <span className="w-14 h-14 rounded-full bg-muted text-white flex items-center justify-center mb-3"><WifiOff size={28} /></span>
+        <p className="text-lg font-extrabold">Не удаётся проверить оплату</p>
+        <p className="text-muted text-xs mt-1">Похоже, пропала связь. Если вы уже оплатили, деньги дойдут.</p>
+        <button className="btn-primary mt-8" onClick={() => refetch()}>Проверить ещё раз</button>
+        <button className="btn-ghost mt-3" onClick={() => nav("/")}>На главную</button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="pt-10 flex flex-col items-center text-center">
+      <span className="px-4 py-2.5 rounded-xl2 bg-ink text-white text-sm font-extrabold mb-4">{card ? "Картой" : "СБП"}</span>
+      <div className="mb-6">
+        {/* после перезагрузки суммы в state нет: лучше не показать ничего, чем показать 0 ₽ */}
+        {st.total != null && <p className="text-lg font-extrabold">{formatMoney(st.total)}</p>}
+        {st.bucket && <p className="text-muted text-xs">{st.bucket}</p>}
+      </div>
+      {mock ? (
+        <>
+          <button className="btn-primary" onClick={() => nav(`/mock-pay/${orderId}`)}>
+            Выбрать исход
+          </button>
+          <p className="text-muted text-xs mt-2">Учебный платёж — банк не задействован</p>
+        </>
+      ) : st.payUrl ? (
+        <>
+          <a className="btn-primary no-underline" href={st.payUrl} target="_blank" rel="noopener">Оплатить</a>
+          <p className="text-muted text-xs mt-2">Откроется ваше приложение банка</p>
+        </>
+      ) : (
+        <p className="text-muted text-xs">Завершите оплату в приложении банка — экран обновится сам</p>
+      )}
+      <div className="flex items-center gap-2 mt-6 text-muted text-xs"><Spinner /> Ожидаем оплату…</div>
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/TgWaitPage.tsx

@@ -0,0 +1,57 @@
+import { useEffect } from "react";
+import { useNavigate } from "react-router-dom";
+import { usePairPoll } from "@/hooks/usePairPoll";
+import { clearPairing, loadPairing } from "@/lib/pairing";
+import { takeReturnTo } from "@/lib/returnTo";
+import { Spinner } from "@/components/Spinner";
+
+export function TgWaitPage() {
+  const nav = useNavigate();
+  const pairing = loadPairing();
+  const { status } = usePairPoll(pairing?.pairSession ?? null, pairing?.pollSecret ?? null);
+
+  useEffect(() => {
+    if (!pairing) { nav("/login", { replace: true }); }
+  }, [pairing, nav]);
+
+  useEffect(() => {
+    if (status === "authenticated") {
+      clearPairing();
+      // Возврат туда, откуда пришёл (напр. ссылка на оплату), иначе на баланс.
+      nav(takeReturnTo(), { replace: true });
+    }
+    if (status === "expired") {
+      clearPairing();
+      nav("/login", { replace: true, state: { expired: true } });
+    }
+  }, [status, nav]);
+
+  return (
+    <div className="pt-16 text-center">
+      <h1 className="text-xl font-extrabold mb-2">Премиум Водитель</h1>
+      <p className="text-muted text-sm mb-6">
+        Бот назовёт число ниже и попросит подтвердить вход — нажмите «Это я, войти»
+        (или поделитесь номером, если входите впервые). Затем вернитесь сюда, вход
+        произойдёт автоматически.
+      </p>
+      {pairing?.confirmCode && (
+        // Число сверки: бот называет его в своём сообщении. Если человек попал в
+        // бот по чужой ссылке, у него на экране этого числа нет — подтверждать
+        // нечего, и токен не выдаётся.
+        <div className="card p-4 mb-6">
+          <p className="text-muted text-xs mb-1">Код подтверждения</p>
+          <p className="text-2xl font-extrabold tracking-widest">{pairing.confirmCode}</p>
+          <p className="text-muted text-xs mt-2">
+            Это же число должен назвать бот. Не совпало — нажмите в боте «Это не я».
+          </p>
+        </div>
+      )}
+      {pairing?.deepLink && (
+        <a href={pairing.deepLink} target="_blank" rel="noopener noreferrer" className="btn-primary block text-center mb-6">
+          Открыть Telegram
+        </a>
+      )}
+      <Spinner />
+    </div>
+  );
+}

driver-pwa/frontend/src/pages/TopupPage.test.tsx

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("@/api/driver", () => ({
+  topup: vi.fn(async () => ({ order_id: "o9", pay_url: "https://qr.nspk.ru/x", commission: 52,
+                              total: 1052, mock: false })),
+  getCommission: vi.fn(async () => ({ rate: 0.052 })),
+  getBuckets: vi.fn(async () => ({
+    buckets: ["Долг аренда", "Долг по штрафам"], with_debt: ["Долг аренда"],
+  })),
+  apiErrorText: vi.fn(async (_e: unknown, fallback: string) => fallback),
+}));
+import { TopupPage } from "./TopupPage";
+import * as driver from "@/api/driver";
+
+const wrap = () => {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={qc}>
+      <MemoryRouter><TopupPage /></MemoryRouter>
+    </QueryClientProvider>
+  );
+};
+
+describe("TopupPage", () => {
+  it("keypad builds amount, shows total, and submits topup", async () => {
+    wrap();
+    await userEvent.click(screen.getByRole("button", { name: "1" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    expect(screen.getByTestId("amount").textContent).toBe("1 000 ₽");
+    expect(screen.getByTestId("total").textContent).toContain("1 052");
+    await userEvent.click(screen.getByRole("button", { name: /Оплатить/i }));
+    expect(driver.topup).toHaveBeenCalledWith("Долг аренда", 1000, "qr", false);
+  });
+
+  it("decimal key builds kopecks and they reach the backend", async () => {
+    // Клавиша разделителя была нарисована, но ничего не делала: заплатить точный
+    // долг вроде 1234,56 было нечем.
+    wrap();
+    for (const k of ["1", "0", "0", ",", "5", "2"]) {
+      await userEvent.click(screen.getByRole("button", { name: k }));
+    }
+    expect(screen.getByTestId("amount").textContent).toBe("100,52 ₽");
+    await userEvent.click(screen.getByRole("button", { name: /Оплатить/i }));
+    expect(driver.topup).toHaveBeenCalledWith("Долг аренда", 100.52, "qr", false);
+  });
+
+  it("lets the driver choose the debt category instead of hardcoding rent", async () => {
+    wrap();
+    await screen.findByRole("button", { name: "Долг по штрафам" });
+    await userEvent.click(screen.getByRole("button", { name: "Долг по штрафам" }));
+    await userEvent.click(screen.getByRole("button", { name: "5" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: /Оплатить/i }));
+    expect(driver.topup).toHaveBeenCalledWith("Долг по штрафам", 500, "qr", false);
+  });
+});
+
+describe("боевая оплата под просмотром", () => {
+  it("по умолчанию платёж учебный — флаг в запрос уходит выключенным", async () => {
+    const { useStaff } = await import("@/store/staff");
+    useStaff.getState().clear();
+    wrap();
+    await userEvent.click(screen.getByRole("button", { name: "5" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: /Оплатить/i }));
+    expect(driver.topup).toHaveBeenLastCalledWith("Долг аренда", 500, "qr", false);
+  });
+
+  it("включённая боевая оплата предупреждает и уходит с флагом", async () => {
+    const { useStaff } = await import("@/store/staff");
+    useStaff.getState().setLivePay(true);
+    wrap();
+    expect(screen.getByText(/деньги спишутся по-настоящему/i)).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: "5" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: "0" }));
+    await userEvent.click(screen.getByRole("button", { name: /Оплатить/i }));
+    expect(driver.topup).toHaveBeenLastCalledWith("Долг аренда", 500, "qr", true);
+    useStaff.getState().clear();
+  });
+});

driver-pwa/frontend/src/pages/TopupPage.tsx

@@ -0,0 +1,134 @@
+import { useState } from "react";
+import { useLocation, useNavigate } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
+import { Delete } from "lucide-react";
+import { toast } from "sonner";
+import { apiErrorText, topup, getCommission, getBuckets } from "@/api/driver";
+import { keypadReduce, parseAmount, withCommission } from "@/lib/amount";
+import { formatMoney } from "@/lib/format";
+import { markPaymentActivity } from "@/lib/paymentWatch";
+import { useStaff } from "@/store/staff";
+import { Segment } from "@/components/Segment";
+import { Spinner } from "@/components/Spinner";
+
+const QUICK = ["500", "1000", "2000"];
+const KEYS = ["1", "2", "3", "4", "5", "6", "7", "8", "9", ",", "0", "back"];
+
+export function TopupPage() {
+  const nav = useNavigate();
+  const livePay = useStaff((s) => s.livePay);
+  const loc = useLocation();
+  const fromBalance = (loc.state as { bucket?: string } | null)?.bucket;
+  // Список категорий приходит с сервера — там же он и проверяется. Хардкод
+  // «Долг аренда» отправлял платёж в аренду даже тем, у кого её нет.
+  const { data: bucketData } = useQuery({ queryKey: ["buckets"], queryFn: getBuckets });
+  const options = bucketData?.buckets ?? (fromBalance ? [fromBalance] : []);
+  const [picked, setPicked] = useState<string | null>(null);
+  const bucket = picked ?? fromBalance ?? bucketData?.with_debt[0] ?? options[0] ?? "";
+
+  const [raw, setRaw] = useState("");
+  const [method, setMethod] = useState("qr");
+  const [busy, setBusy] = useState(false);
+  const { data: commission } = useQuery({ queryKey: ["commission"], queryFn: getCommission });
+  const rate = commission?.rate ?? 0.052; // fallback only while loading
+
+  const base = parseAmount(raw);
+  const { commission: fee, total } = withCommission(base, rate);
+
+  function press(k: string) {
+    setRaw((r) => keypadReduce(r, k));
+  }
+
+  async function pay() {
+    if (base <= 0 || !bucket || busy) return;
+    setBusy(true);
+    try {
+      const r = await topup(bucket, base, method as "qr" | "card", livePay);
+      // Учебный платёж (сотрудник смотрит от чужого лица): банка нет, платить
+      // негде — сразу на экран выбора исхода, дальше всё как у водителя.
+      if (r.mock) {
+        nav(`/mock-pay/${r.order_id}`, { state: { total: r.total, bucket, base, method } });
+        return;
+      }
+      // Отметка ДО ухода на оплату: вернись водитель на баланс жестом «назад»
+      // раньше вебхука банка, экран обязан опрашивать себя и подхватить платёж.
+      markPaymentActivity();
+      nav(`/pay/${r.order_id}`, { state: { payUrl: r.pay_url, total: r.total, bucket, base, method } });
+    } catch (err: unknown) {
+      // Текст с сервера, а не глухое «не удалось»: минимум СБП, потолок суммы и
+      // неизвестная категория объясняются словами, иначе экран молча не реагирует.
+      toast.error(await apiErrorText(err, "Не удалось создать платёж"));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="pt-2">
+      <button className="text-muted text-xs mb-3" onClick={() => nav(-1)}>‹ Назад</button>
+
+      {/* Категорию выбирают в шторке на главном экране. Пришли оттуда — показываем
+          выбранное строкой, а не рядом чипов: второй выбор того же самого сбивает
+          с толку. Чипы остаются для входа сюда напрямую (кнопка «Пополнить» без
+          категории, возврат «пополнить ещё раз» с экрана оплаты). */}
+      {fromBalance ? (
+        <p className="text-muted text-xs mb-3">Пополняем: <b className="text-ink">{bucket}</b></p>
+      ) : options.length > 1 ? (
+        <div className="flex gap-1.5 mb-3 overflow-x-auto">
+          {options.map((b) => (
+            <button
+              key={b}
+              onClick={() => setPicked(b)}
+              className={`shrink-0 px-3 py-2 rounded-xl2 text-xs border ${
+                b === bucket ? "border-line bg-surface font-semibold" : "border-line text-muted"
+              }`}
+            >
+              {b}
+            </button>
+          ))}
+        </div>
+      ) : null}
+
+      <p data-testid="amount" className="text-3xl font-extrabold text-center mt-2">{formatMoney(base)}</p>
+      <p data-testid="total" className="text-muted text-xs text-center mb-3">
+        к оплате {formatMoney(total)} (комиссия {formatMoney(fee)})
+      </p>
+
+      <div className="flex gap-1.5 mb-3">
+        {QUICK.map((q) => (
+          <button key={q} className="flex-1 py-2 rounded-xl2 text-xs bg-surface border border-line" onClick={() => setRaw(q)}>
+            {q}
+          </button>
+        ))}
+      </div>
+
+      <div className="grid grid-cols-3 gap-2 mb-4">
+        {KEYS.map((k) => (
+          <button
+            key={k}
+            aria-label={k}
+            className="bg-surface border border-line rounded-xl2 py-3 text-lg font-semibold flex items-center justify-center"
+            onClick={() => press(k)}
+          >
+            {k === "back" ? <Delete size={18} /> : k}
+          </button>
+        ))}
+      </div>
+
+      <div className="mb-4">
+        <Segment value={method} onChange={setMethod} options={[{ value: "qr", label: "СБП" }, { value: "card", label: "Картой" }]} />
+      </div>
+
+      {livePay && (
+        // Предупреждение прямо над кнопкой: под чужим лицом ошибиться легко, а
+        // отыграть боевой платёж — это возврат в банке и правка в 1С.
+        <p className="text-neg text-xs mb-2 text-center">
+          Боевая оплата: деньги спишутся по-настоящему и зачислятся водителю
+        </p>
+      )}
+      <button className="btn-primary" disabled={busy || base <= 0 || !bucket} onClick={pay}>
+        {busy ? <Spinner /> : "Оплатить"}
+      </button>
+    </div>
+  );
+}

driver-pwa/frontend/src/store/auth.ts

@@ -0,0 +1,79 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+/** Кем открыт сеанс: сам водитель или сотрудник, смотрящий от его лица.
+ * Признак приезжает из токена (claim `imp`), здесь он только продублирован для
+ * интерфейса — проверять его на бэкенде по этому полю нельзя и не нужно. */
+export interface ViewAs {
+  impersonated: boolean;
+  /** ФИО водителя — показывать в плашке. У обычного входа неизвестно и не нужно. */
+  driverName: string | null;
+}
+
+/** Собственный сеанс, отложенный на время просмотра чужого. */
+interface OwnSession {
+  token: string;
+  driverId: number | null;
+}
+
+interface AuthState extends ViewAs {
+  token: string | null;
+  driverId: number | null;
+  /** Сеанс, к которому вернёт «выйти из просмотра». null — возвращаться некуда. */
+  own: OwnSession | null;
+  setSession: (token: string, driverId: number, view?: Partial<ViewAs>) => void;
+  /** Начать просмотр от лица водителя, отложив собственный вход. */
+  startImpersonation: (token: string, driverId: number, driverName: string) => void;
+  /** Вернуться к себе. true — вернулись, false — своего входа не было. */
+  stopImpersonation: () => boolean;
+  clear: () => void;
+}
+
+export const useAuth = create<AuthState>()(
+  persist(
+    (set, get) => ({
+      token: null,
+      driverId: null,
+      impersonated: false,
+      driverName: null,
+      own: null,
+      setSession: (token, driverId, view) =>
+        set({
+          token,
+          driverId,
+          impersonated: view?.impersonated ?? false,
+          driverName: view?.driverName ?? null,
+        }),
+      startImpersonation: (token, driverId, driverName) => {
+        const s = get();
+        // Свой вход откладываем ОДИН раз — при переходе из обычного сеанса. Смена
+        // водителя внутри просмотра не должна затирать отложенное собственным
+        // чужим токеном, иначе «вернуться к себе» вернёт к предыдущему водителю.
+        const own = s.impersonated
+          ? s.own
+          : s.token
+            ? { token: s.token, driverId: s.driverId }
+            : null;
+        set({ token, driverId, impersonated: true, driverName, own });
+      },
+      stopImpersonation: () => {
+        const own = get().own;
+        if (!own) {
+          set({ token: null, driverId: null, impersonated: false, driverName: null });
+          return false;
+        }
+        set({
+          token: own.token,
+          driverId: own.driverId,
+          impersonated: false,
+          driverName: null,
+          own: null,
+        });
+        return true;
+      },
+      clear: () =>
+        set({ token: null, driverId: null, impersonated: false, driverName: null, own: null }),
+    }),
+    { name: "pp-driver-auth" }
+  )
+);

driver-pwa/frontend/src/store/staff.ts

@@ -0,0 +1,36 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+/**
+ * Сеанс СОТРУДНИКА — учётка CRM, которой берут просмотр от лица водителя.
+ *
+ * Хранится отдельно от водительского: это два разных токена с разным смыслом.
+ * «Перестать смотреть за водителя» обязано оставлять сотрудника залогиненным,
+ * иначе смена водителя каждый раз означала бы новый ввод пароля; и наоборот —
+ * `clear()` водительского сеанса не должен трогать сотрудника.
+ */
+interface StaffState {
+  token: string | null;
+  username: string | null;
+  /** Боевая оплата под просмотром: платёж уходит в банк и зачисляется водителю.
+   *  Выключено по умолчанию — под чужим лицом легко забыть, кого пополняешь. */
+  livePay: boolean;
+  setStaff: (token: string, username: string) => void;
+  setLivePay: (on: boolean) => void;
+  clear: () => void;
+}
+
+export const useStaff = create<StaffState>()(
+  persist(
+    (set) => ({
+      token: null,
+      username: null,
+      livePay: false,
+      setStaff: (token, username) => set({ token, username }),
+      setLivePay: (livePay) => set({ livePay }),
+      // Выход сотрудника гасит и боевой режим: следующий раз он включается осознанно.
+      clear: () => set({ token: null, username: null, livePay: false }),
+    }),
+    { name: "pp-driver-staff" }
+  )
+);

driver-pwa/frontend/src/sw.ts

@@ -0,0 +1,76 @@
+/// <reference lib="webworker" />
+import { cleanupOutdatedCaches, precacheAndRoute } from "workbox-precaching";
+import { clientsClaim } from "workbox-core";
+
+/**
+ * Сервис-воркер приложения.
+ *
+ * Свой, а не сгенерированный: `generateSW` умеет только кэш, а нам нужны
+ * обработчики `push` и `notificationclick` — уведомления показывает именно
+ * воркер, страница для этого может быть закрыта.
+ *
+ * Кэш остаётся прежним (precache от workbox), поведение обновления тоже:
+ * `skipWaiting` + `clientsClaim`, как было при registerType: "autoUpdate".
+ */
+declare const self: ServiceWorkerGlobalScope;
+
+precacheAndRoute(self.__WB_MANIFEST);
+cleanupOutdatedCaches();
+self.skipWaiting();
+clientsClaim();
+
+interface PushPayload {
+  title?: string;
+  body?: string;
+  url?: string;
+  tag?: string;
+  /** Номер уведомления в журнале — по нему отмечается прочтение. */
+  id?: number;
+}
+
+self.addEventListener("push", (event: PushEvent) => {
+  let data: PushPayload = {};
+  try {
+    data = event.data ? (event.data.json() as PushPayload) : {};
+  } catch {
+    // Пуш без разбираемой нагрузки: показать что-то всё равно надо — молчание
+    // выглядит как «уведомления не работают».
+    data = {};
+  }
+  const title = data.title || "Премиум Водитель";
+  event.waitUntil(
+    self.registration.showNotification(title, {
+      body: data.body || "",
+      icon: "/icons/icon-192.png",
+      badge: "/icons/icon-192.png",
+      // tag схлопывает однотипные: пять штрафов подряд не завалят шторку.
+      tag: data.tag,
+      data: { url: data.url || "/", id: data.id },
+    }),
+  );
+});
+
+self.addEventListener("notificationclick", (event: NotificationEvent) => {
+  event.notification.close();
+  const url = (event.notification.data?.url as string) || "/";
+  const id = event.notification.data?.id as number | undefined;
+  // Нажатие — единственный честный признак, что уведомление увидели. Отметить
+  // его прямо отсюда нельзя: токен водителя лежит в хранилище страницы, а
+  // воркеру оно недоступно. Поэтому номер едет параметром, а отмечает страница.
+  const target = id ? `${url}${url.includes("?") ? "&" : "?"}n=${id}` : url;
+  event.waitUntil(
+    (async () => {
+      const all = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
+      // Уже открытое окно приложения переиспользуем: второй экземпляр рядом с
+      // первым сбивает с толку, и водитель теряет то, что было на экране.
+      for (const client of all) {
+        if ("focus" in client) {
+          await client.focus();
+          if ("navigate" in client) await client.navigate(target);
+          return;
+        }
+      }
+      await self.clients.openWindow(target);
+    })(),
+  );
+});

driver-pwa/frontend/src/test/setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest";

driver-pwa/frontend/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_BASE?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+
+// Подставляются на сборке (vite.config.ts → define). Нужны экрану отладки:
+// показывают, какой именно бандл сейчас открыт.
+declare const __BUILD_COMMIT__: string;
+declare const __BUILD_TIME__: string;

driver-pwa/frontend/tailwind.config.js

@@ -0,0 +1,38 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ["./index.html", "./src/**/*.{ts,tsx}"],
+  theme: {
+    extend: {
+      /**
+       * Палитра сайта pptaxi.ru — снята с ЖИВОГО сайта (переменные --s-* в его
+       * инлайн-CSS), а не из локального чекаута: тот отстал на редизайн и
+       * предлагал тёмно-синюю тему, которой на сайте давно нет.
+       *
+       * Имена — роли, а не краски: «canvas» останется фоном страницы, даже если
+       * однажды перестанет быть светлым.
+       */
+      colors: {
+        canvas: "#EEF1F5",       // --s-bg — фон страницы
+        "canvas-soft": "#F5F7FA", // --s-bg-soft — подложка под блоками
+        surface: "#FFFFFF",      // --s-paper — карточки, поля ввода
+        line: "#DDE3EC",         // --s-line — границы и разделители
+        "line-soft": "#E5EAF1",
+        ink: "#0F172A",          // --s-ink — основной текст
+        "ink-soft": "#475569",   // --s-ink-soft — вторичный текст
+        muted: "#94A3B8",        // --s-ink-mute — подписи
+        accent: "#DC2626",       // --s-accent — фирменный красный, кнопка действия
+        "accent-press": "#B91C1C",
+        "accent-soft": "#FEF2F2",
+        warn: "#D97706",         // --s-warn
+        // Деньги: приход зелёным (--s-ok), долг — фирменным красным. Свой оттенок
+        // тут заводить не стали: у долга и главного действия один цвет намеренно,
+        // это то, ради чего экран открывают.
+        pos: "#059669",
+        neg: "#DC2626",
+      },
+      fontFamily: { sans: ["Inter", "system-ui", "sans-serif"] },
+      borderRadius: { xl2: "12px" },  // --s-radius-md
+    },
+  },
+  plugins: [],
+};

driver-pwa/frontend/tsconfig.app.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2021", "useDefineForClassFields": true, "lib": ["ES2021", "DOM", "DOM.Iterable", "WebWorker"],
+    "module": "ESNext", "skipLibCheck": true, "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true, "resolveJsonModule": true, "isolatedModules": true,
+    "noEmit": true, "jsx": "react-jsx", "strict": true, "noUnusedLocals": true,
+    "noUnusedParameters": true, "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".", "paths": { "@/*": ["src/*"] }, "types": ["vite-plugin-pwa/client", "vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": ["src"]
+}

driver-pwa/frontend/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "files": [],
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}

driver-pwa/frontend/tsconfig.node.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "lib": ["ES2023"], "module": "ESNext", "skipLibCheck": true,
+    "moduleResolution": "bundler", "allowImportingTsExtensions": true, "isolatedModules": true,
+    "noEmit": true, "strict": true
+  },
+  "include": ["vite.config.ts", "vitest.config.ts", "dev-proxy.test.ts"]
+}

driver-pwa/frontend/vite.config.ts

@@ -0,0 +1,83 @@
+import { execSync } from "child_process";
+import { defineConfig, loadEnv } from "vite";
+import react from "@vitejs/plugin-react";
+import { VitePWA } from "vite-plugin-pwa";
+import path from "path";
+
+/**
+ * Что именно сейчас открыто — видно на вкладке «Отладка».
+ *
+ * Без этого «правка не приехала» и «приехала, но кэш старый» выглядят
+ * одинаково, а проверяются по-разному. Коммит берём из git; вне репозитория
+ * (сборка из архива, CI без .git) — честный «unknown», а не падение сборки.
+ */
+function buildCommit(): string {
+  try {
+    return execSync("git rev-parse --short HEAD", { stdio: ["ignore", "pipe", "ignore"] })
+      .toString().trim() || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Локальная разработка ходит в бэкенд ЧЕРЕЗ ПРОКСИ dev-сервера, а не напрямую.
+ *
+ * Почему не «разрешить localhost в CORS бэкенда»: через прокси запрос уходит с
+ * того же origin, что и страница (http://localhost:5174/api/...), поэтому CORS
+ * в разработке не участвует вообще — ни preflight, ни credentials. Боевой
+ * список origin'ов на бэкенде остаётся закрытым, и CORS_ALLOW_LOCALHOST ради
+ * этого фронта включать не нужно.
+ *
+ * Дефолтная цель прокси — ЛОКАЛЬНЫЙ бэкенд, а не crm.pptaxi.ru. Контур боевой:
+ * «по умолчанию проксировать в прод» означало бы, что первый же тычок в
+ * «Пополнить» на машине разработчика создаёт платёж на живом терминале и живой
+ * чек 54-ФЗ. Другой адрес задаётся VITE_API_TARGET — тем же именем, что в CRM
+ * (crm2/frontend/vite.config.ts), чтобы рецепт был один на оба фронта.
+ */
+export default defineConfig(({ command, mode }) => {
+  // База для ky (src/api/client.ts): в dev — свой же origin, дальше прокси.
+  // Ставим ТОЛЬКО если разработчик не задал базу сам (.env.local, .env,
+  // VITE_API_BASE=... перед командой): loadEnv отдаёт и файлы, и process.env,
+  // причём process.env приоритетнее файлов — без этой проверки собственная
+  // настройка молча перебивалась бы нашим дефолтом.
+  // В сборку (command === "build") не лезем никогда: там база остаётся боевой —
+  // из .env, либо из дефолта в client.ts.
+  if (command === "serve" && !loadEnv(mode, __dirname, "VITE_").VITE_API_BASE) {
+    process.env.VITE_API_BASE = "/api";
+  }
+
+  return {
+    define: {
+      __BUILD_COMMIT__: JSON.stringify(buildCommit()),
+      __BUILD_TIME__: JSON.stringify(new Date().toISOString().slice(0, 16).replace("T", " ")),
+    },
+    plugins: [
+      react(),
+      // injectManifest, а не generateSW: воркер свой, потому что уведомления
+      // показывает он (см. src/sw.ts), а сгенерированный умеет только кэш.
+      VitePWA({
+        strategies: "injectManifest",
+        srcDir: "src",
+        filename: "sw.ts",
+        registerType: "autoUpdate",
+        manifest: false,
+        includeAssets: ["icons/*.png"],
+        injectManifest: { globPatterns: ["**/*.{js,css,html,png,svg,webmanifest}"] },
+      }),
+    ],
+    resolve: { alias: { "@": path.resolve(__dirname, "src") } },
+    server: {
+      port: 5174,
+      proxy: {
+        "/api": {
+          // secure: false нужен только для VITE_API_TARGET на https-цель с
+          // самоподписанным сертификатом; на дефолтную http-цель не влияет.
+          target: process.env.VITE_API_TARGET || "http://127.0.0.1:8000",
+          changeOrigin: true,
+          secure: false,
+        },
+      },
+    },
+  };
+});

driver-pwa/frontend/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+import path from "path";
+
+export default defineConfig({
+  // Те же подстановки, что и в боевой сборке (vite.config.ts): без них модуль с
+  // __BUILD_COMMIT__ падает в тестах на ReferenceError, хотя в приложении работает.
+  define: {
+    __BUILD_COMMIT__: JSON.stringify("test"),
+    __BUILD_TIME__: JSON.stringify("test"),
+  },
+  plugins: [react()],
+  resolve: { alias: { "@": path.resolve(__dirname, "src") } },
+  test: { globals: true, environment: "jsdom", setupFiles: ["./src/test/setup.ts"] },
+});

mechanic-pwa/frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

mechanic-pwa/frontend/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

mechanic-pwa/frontend/components.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "slate",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}

mechanic-pwa/frontend/eslint.config.js

@@ -0,0 +1,22 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      globals: globals.browser,
+    },
+  },
+])

mechanic-pwa/frontend/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" type="image/png" sizes="16x16" href="/icons/favicon-16.png" />
+    <link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32.png" />
+    <link rel="icon" type="image/png" sizes="48x48" href="/icons/favicon-48.png" />
+    <link rel="icon" type="image/png" sizes="192x192" href="/icons/icon-192.png" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon.png" />
+    <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover" />
+    <meta name="theme-color" content="#000000" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <meta name="apple-mobile-web-app-title" content="Mechanic" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <title>Premium Механик</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

mechanic-pwa/frontend/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@tanstack/react-query": "^5.100.10",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "ky": "^1.14.3",
+    "lucide-react": "^0.400.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-hook-form": "^7.76.0",
+    "react-router-dom": "^7.15.1",
+    "sonner": "^1.7.4",
+    "tailwind-merge": "^2.6.1",
+    "vite-plugin-pwa": "^1.3.0",
+    "zod": "^3.25.76",
+    "zustand": "^5.0.13"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^24.12.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "autoprefixer": "^10.5.0",
+    "eslint": "^10.3.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "jsdom": "^29.1.1",
+    "postcss": "^8.5.14",
+    "tailwindcss": "^3.4.19",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.59.2",
+    "vite": "^8.0.12",
+    "vitest": "^4.1.8"
+  }
+}

mechanic-pwa/frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

mechanic-pwa/frontend/public/data/damage_vocabulary.json

@@ -0,0 +1,90 @@
+{
+  "_meta": {
+    "source": "Ttc.dll #US heap, contiguous block at offsets 0xc2e24–0xc3084",
+    "confidence": "HIGH — full block scanned; order is the binary storage order which matches app display order (repository pattern typically loads in definition order)",
+    "notes": [
+      "Items 0–12 are general exterior damage types (user-selectable for any zone)",
+      "Items 13–18 appear to be salon-specific (Грязный салон, Запах табака, etc.) — shown only for interior zones (44–46 seats, salon)",
+      "Установлено/Снято (19–20) and Контроль (21) are semi-system states used for equipment completeness zones (33–48 area)",
+      "Штат (25) appears to be a system/staff marker, not user-selectable",
+      "Порез, Прокол, Порвано are tire-specific damage types for zones 17–20",
+      "Есть/Нет повреждений found in binary (0x4599a/0x4597a) — likely used for salon damage yes/no toggle, not in the standard list"
+    ]
+  },
+  "damage_types_ordered": [
+    "Вмятина",
+    "Царапина",
+    "Трещина",
+    "Повреждено",
+    "Скол",
+    "Отсутствует",
+    "Прожжено",
+    "Погнуто",
+    "Требуется мойка",
+    "Не работает",
+    "Порез",
+    "Прокол",
+    "Порвано",
+    "Пятна",
+    "Грязный салон",
+    "Запах табака",
+    "Повреждение салонных ковриков",
+    "Повреждение обшивки дверей",
+    "Сломанные ручки",
+    "Установлено",
+    "Снято",
+    "Контроль",
+    "Требуется химчистка",
+    "Затертость",
+    "Грыжа",
+    "Штат"
+  ],
+  "exterior_selectable": [
+    "Вмятина",
+    "Царапина",
+    "Трещина",
+    "Повреждено",
+    "Скол",
+    "Отсутствует",
+    "Прожжено",
+    "Погнуто",
+    "Требуется мойка",
+    "Не работает",
+    "Порез",
+    "Прокол",
+    "Порвано",
+    "Пятна",
+    "Затертость",
+    "Грыжа"
+  ],
+  "salon_selectable": [
+    "Вмятина",
+    "Царапина",
+    "Трещина",
+    "Повреждено",
+    "Скол",
+    "Отсутствует",
+    "Прожжено",
+    "Погнуто",
+    "Требуется мойка",
+    "Не работает",
+    "Пятна",
+    "Грязный салон",
+    "Запах табака",
+    "Повреждение салонных ковриков",
+    "Повреждение обшивки дверей",
+    "Сломанные ручки",
+    "Требуется химчистка",
+    "Затертость",
+    "Грыжа"
+  ],
+  "severity_scale": {
+    "positions": 3,
+    "labels": ["Легкое", "Среднее", "Тяжелое"],
+    "values": [0, 1, 2],
+    "widget": "SeekBar (vehicleInspectionDegreeSelect / newDamageSeekBarDamageDegree)",
+    "api_field": "degree (lowercase, in JSON contract)",
+    "default": "Легкое (index 0)",
+    "source_note": "Легкое found at 0x59d79 (adjacent to 'Добавить повреждение' button label = default/initial value); Среднее+Тяжелое found together at 0xc39e8–0xc39f8 (loading state transitions)"
+  }
+}

mechanic-pwa/frontend/public/data/zone_bboxes.json

@@ -0,0 +1,401 @@
+{
+  "0": {
+    "x": 278.11,
+    "y": 88.77,
+    "w": 262.74,
+    "h": 45.43,
+    "rotation": 0
+  },
+  "52": {
+    "x": 699.8,
+    "y": 296.93,
+    "w": 41.31,
+    "h": 70.61,
+    "rotation": -90
+  },
+  "51": {
+    "x": 81.04,
+    "y": 295.79,
+    "w": 41.4,
+    "h": 71.68,
+    "rotation": 90
+  },
+  "1": {
+    "x": 488.5,
+    "y": 132.88,
+    "w": 50.92,
+    "h": 20.77,
+    "rotation": 0
+  },
+  "2": {
+    "x": 279.61,
+    "y": 132.82,
+    "w": 50.93,
+    "h": 21.24,
+    "rotation": 0
+  },
+  "3": {
+    "x": 350.0,
+    "y": 130.0,
+    "w": 120.0,
+    "h": 22.0,
+    "rotation": 0
+  },
+  "30": {
+    "x": 509.22,
+    "y": 734.61,
+    "w": 130.89,
+    "h": 41.63,
+    "rotation": 0
+  },
+  "31": {
+    "x": 182.12,
+    "y": 734.5,
+    "w": 129.26,
+    "h": 41.56,
+    "rotation": 0
+  },
+  "28": {
+    "x": 170.41,
+    "y": 496.19,
+    "w": 6.35,
+    "h": 8.34,
+    "rotation": 90
+  },
+  "29": {
+    "x": 645.28,
+    "y": 496.19,
+    "w": 6.53,
+    "h": 8.58,
+    "rotation": -90
+  },
+  "11": {
+    "x": 278.5,
+    "y": 477.86,
+    "w": 465.53,
+    "h": 152.09,
+    "rotation": 0
+  },
+  "10": {
+    "x": 78.52,
+    "y": 478.98,
+    "w": 91.6,
+    "h": 150.99,
+    "rotation": 90
+  },
+  "4": {
+    "x": 300.72,
+    "y": 311.52,
+    "w": 219.3,
+    "h": 146.72,
+    "rotation": 0
+  },
+  "5": {
+    "x": 305.05,
+    "y": 442.76,
+    "w": 210.67,
+    "h": 127.13,
+    "rotation": 0
+  },
+  "22": {
+    "x": 281.48,
+    "y": 1063.81,
+    "w": 260.16,
+    "h": 59.34,
+    "rotation": 0
+  },
+  "49": {
+    "x": 87.78,
+    "y": 826.98,
+    "w": 50.54,
+    "h": 99.5,
+    "rotation": 90
+  },
+  "50": {
+    "x": 684.83,
+    "y": 827.25,
+    "w": 49.78,
+    "h": 99.71,
+    "rotation": -90
+  },
+  "33": {
+    "x": 284.24,
+    "y": 1038.88,
+    "w": 29.65,
+    "h": 22.7,
+    "rotation": 0
+  },
+  "32": {
+    "x": 507.74,
+    "y": 1038.78,
+    "w": 29.66,
+    "h": 22.69,
+    "rotation": 0
+  },
+  "21": {
+    "x": 303.29,
+    "y": 841.39,
+    "w": 215.88,
+    "h": 236.13,
+    "rotation": 0
+  },
+  "38": {
+    "x": 510.42,
+    "y": 195.83,
+    "w": 26.67,
+    "h": 821.6,
+    "rotation": -90
+  },
+  "39": {
+    "x": 281.9,
+    "y": 195.94,
+    "w": 26.67,
+    "h": 14.24,
+    "rotation": 0
+  },
+  "23": {
+    "x": 316.23,
+    "y": 766.98,
+    "w": 187.94,
+    "h": 89.25,
+    "rotation": 0
+  },
+  "6": {
+    "x": 78.13,
+    "y": 314.95,
+    "w": 91.98,
+    "h": 168.83,
+    "rotation": 90
+  },
+  "7": {
+    "x": 651.97,
+    "y": 314.84,
+    "w": 92.1,
+    "h": 168.93,
+    "rotation": -90
+  },
+  "8": {
+    "x": 81.05,
+    "y": 734.43,
+    "w": 104.0,
+    "h": 176.79,
+    "rotation": 90
+  },
+  "9": {
+    "x": 590.75,
+    "y": 666.97,
+    "w": 150.45,
+    "h": 244.25,
+    "rotation": -90
+  },
+  "12": {
+    "x": 81.53,
+    "y": 628.12,
+    "w": 99.38,
+    "h": 147.01,
+    "rotation": 90
+  },
+  "13": {
+    "x": 641.53,
+    "y": 627.6,
+    "w": 99.42,
+    "h": 147.14,
+    "rotation": -90
+  },
+  "16": {
+    "x": 325.94,
+    "y": 563.11,
+    "w": 168.93,
+    "h": 208.89,
+    "rotation": 90
+  },
+  "14": {
+    "x": 72.11,
+    "y": 471.33,
+    "w": 5.0,
+    "h": 161.47,
+    "rotation": 90
+  },
+  "47": {
+    "x": 72.83,
+    "y": 615.64,
+    "w": 5.6,
+    "h": 124.59,
+    "rotation": 90
+  },
+  "15": {
+    "x": 744.0,
+    "y": 461.0,
+    "w": 6.0,
+    "h": 171.5,
+    "rotation": -90
+  },
+  "48": {
+    "x": 744.0,
+    "y": 632.5,
+    "w": 6.0,
+    "h": 107.5,
+    "rotation": -90
+  },
+  "27": {
+    "x": 596.56,
+    "y": 643.76,
+    "w": 50.37,
+    "h": 84.35,
+    "rotation": -90
+  },
+  "26": {
+    "x": 175.44,
+    "y": 643.75,
+    "w": 50.57,
+    "h": 84.4,
+    "rotation": 90
+  },
+  "24": {
+    "x": 171.07,
+    "y": 526.12,
+    "w": 53.81,
+    "h": 105.33,
+    "rotation": 90
+  },
+  "25": {
+    "x": 597.45,
+    "y": 526.06,
+    "w": 53.57,
+    "h": 105.33,
+    "rotation": -90
+  },
+  "18": {
+    "x": 42.7,
+    "y": 369.77,
+    "w": 89.47,
+    "h": 88.82,
+    "rotation": 0
+  },
+  "43": {
+    "x": 56.05,
+    "y": 382.97,
+    "w": 63.97,
+    "h": 63.6,
+    "rotation": 0
+  },
+  "17": {
+    "x": 688.66,
+    "y": 369.75,
+    "w": 89.51,
+    "h": 88.83,
+    "rotation": 0
+  },
+  "42": {
+    "x": 702.04,
+    "y": 382.95,
+    "w": 63.97,
+    "h": 63.61,
+    "rotation": 0
+  },
+  "20": {
+    "x": 42.55,
+    "y": 751.33,
+    "w": 90.63,
+    "h": 88.87,
+    "rotation": 0
+  },
+  "40": {
+    "x": 56.71,
+    "y": 764.4,
+    "w": 61.8,
+    "h": 62.63,
+    "rotation": 0
+  },
+  "19": {
+    "x": 688.96,
+    "y": 751.25,
+    "w": 89.2,
+    "h": 88.92,
+    "rotation": 0
+  },
+  "41": {
+    "x": 701.6,
+    "y": 763.49,
+    "w": 64.65,
+    "h": 64.46,
+    "rotation": 0
+  },
+  "44": {
+    "x": 42.66,
+    "y": 0.0,
+    "w": 426.67,
+    "h": 512.0,
+    "rotation": 90
+  },
+  "45": {
+    "x": 42.66,
+    "y": 0.0,
+    "w": 426.67,
+    "h": 512.0,
+    "rotation": 90
+  },
+  "46": {
+    "x": 42.66,
+    "y": 0.0,
+    "w": 426.67,
+    "h": 512.0,
+    "rotation": 90
+  },
+  "34": {
+    "x": 0.0,
+    "y": 76.0,
+    "w": 512.0,
+    "h": 360.0,
+    "rotation": 0
+  },
+  "35": {
+    "x": 0.0,
+    "y": 76.0,
+    "w": 512.0,
+    "h": 360.0,
+    "rotation": 0
+  },
+  "36": {
+    "x": 0.0,
+    "y": 76.0,
+    "w": 512.0,
+    "h": 360.0,
+    "rotation": 0
+  },
+  "37": {
+    "x": 0.0,
+    "y": 76.0,
+    "w": 512.0,
+    "h": 360.0,
+    "rotation": 0
+  },
+  "53": {
+    "x": 185.83,
+    "y": 719.15,
+    "w": 42.97,
+    "h": 94.96,
+    "rotation": 90
+  },
+  "54": {
+    "x": 594.89,
+    "y": 723.2,
+    "w": 46.0,
+    "h": 101.37,
+    "rotation": -90
+  },
+  "55": {
+    "x": 170.0,
+    "y": 450.0,
+    "w": 60.0,
+    "h": 130.0,
+    "rotation": 90
+  },
+  "56": {
+    "x": 595.0,
+    "y": 450.0,
+    "w": 55.0,
+    "h": 130.0,
+    "rotation": -90
+  }
+}

mechanic-pwa/frontend/public/data/zone_labels.json

@@ -0,0 +1,66 @@
+{
+  "_meta": {
+    "source": "Ttc.dll #US heap, offsets 0x751c7–0x75a81 (consecutive UTF-16 LE strings)",
+    "confidence": "HIGH — 57 strings appear in exact sequential order in a single contiguous block, matching the 57 class IDs (0..56) in exterior_scheme_complete.svg",
+    "geographic_check": "confirmed: zone 0 (front bumper) at SVG Y=119 (top), zone 22 (rear bumper) at Y=1064 (bottom); left-side zones have small X, right-side zones have large X",
+    "note_typo": "zone 15 has a typo in the vendor binary: 'правй порог' (missing 'ы') — preserve as-is for matching but display as 'правый порог'",
+    "note_zones_34_57": "zones 34–37 are fog lights (противотуманки), zones 38–39 mirrors, 40–43 disks, 44–46 salon seats, 47–48 rear sill extensions, 49–56 bumper sub-parts and pillars"
+  },
+  "0": "передний бампер",
+  "1": "передняя правая фара",
+  "2": "передняя левая фара",
+  "3": "радиатор",
+  "4": "капот",
+  "5": "лобовое стекло",
+  "6": "переднее левое крыло",
+  "7": "переднее правое крыло",
+  "8": "заднее левое крыло",
+  "9": "заднее правое крыло",
+  "10": "передняя левая дверь",
+  "11": "передняя правая дверь",
+  "12": "задняя левая дверь",
+  "13": "задняя правая дверь",
+  "14": "левый порог",
+  "15": "правый порог",
+  "16": "крыша",
+  "17": "передняя правая резина",
+  "18": "передняя левая резина",
+  "19": "задняя правая резина",
+  "20": "задняя левая резина",
+  "21": "багажник",
+  "22": "задний бампер",
+  "23": "заднее стекло",
+  "24": "переднее левое стекло",
+  "25": "переднее правое стекло",
+  "26": "заднее левое стекло",
+  "27": "заднее правое стекло",
+  "28": "передняя левая форточка",
+  "29": "передняя правая форточка",
+  "30": "задняя правая форточка",
+  "31": "задняя левая форточка",
+  "32": "задняя правая фара",
+  "33": "задняя левая фара",
+  "34": "передняя правая противотуманка",
+  "35": "передняя левая противотуманка",
+  "36": "задняя правая противотуманка",
+  "37": "задняя левая противотуманка",
+  "38": "правое зеркало",
+  "39": "левое зеркало",
+  "40": "задний левый диск",
+  "41": "задний правый диск",
+  "42": "передний правый диск",
+  "43": "передний левый диск",
+  "44": "водительское сидение",
+  "45": "пассажирское сидение",
+  "46": "задний диван",
+  "47": "задний левый порог",
+  "48": "задний правый порог",
+  "49": "задняя левая часть бампера",
+  "50": "задняя правая часть бампера",
+  "51": "передняя левая часть бампера",
+  "52": "передняя правая часть бампера",
+  "53": "задняя левая стойка",
+  "54": "задняя правая стойка",
+  "55": "передняя левая стойка",
+  "56": "передняя правая стойка"
+}