From 4610a506676b00f71c24848868b4201b5a9435cb Mon Sep 17 00:00:00 2001
From: vladtechno <vladtechno@gmail.com>
Date: Sat, 16 May 2026 22:17:42 +1000
Subject: [PATCH] docs: record backend layout findings from Task A1 recon

---
 docs/backend-layout-notes.md | 50 ++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/backend-layout-notes.md

diff --git a/docs/backend-layout-notes.md b/docs/backend-layout-notes.md
new file mode 100644
index 0000000..21e4140
--- /dev/null
+++ b/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.