diff --git a/docs/superpowers/STATE.md b/docs/superpowers/STATE.md index afd9641..1a6659b 100644 --- a/docs/superpowers/STATE.md +++ b/docs/superpowers/STATE.md @@ -1,6 +1,6 @@ # Premium Mechanic PWA — Implementation State -> Last updated: 2026-05-16 (end of session 1) +> Last updated: 2026-05-16 (end of session 2 — Phase B done) ## What is done @@ -11,6 +11,14 @@ | 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) + +**Branch state:** `feat/mechanic-mvp` at `f0d7e83`. Stack: `be0553e` (A4) → `d2113a0` (B1) → `2739cc8` (B3) → `2fb978d` (B3-fix) → `f0d7e83` (B4). All pushed to `origin` (Gitea). + +**Test count on branch:** 62 mechanic tests pass (38 models + 15 schemas + 9 deps) in ~0.8s, no real DB needed. ## Where things live @@ -43,30 +51,60 @@ Existing `app/api/inspections.py` + model `CarInspection` (table `car_inspection - `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. + ## Next task -### **Task B1 — Mechanic module skeleton with healthz endpoint** +### **Task C1 — `GET /me` endpoint** -(From `docs/superpowers/plans/2026-05-16-premium-mechanic-phase1.md` Phase B.) +(From `docs/superpowers/plans/2026-05-16-premium-mechanic-phase1.md` Phase C.) -**Working dir:** `c:\NewProject\taxi-dashboard` (branch `feat/mechanic-mvp` already checked out) +**Working dir:** `c:\NewProject\taxi-dashboard` (branch `feat/mechanic-mvp`, HEAD `f0d7e83`) -**What to do:** -1. Create new file `backend/app/api/mechanic.py` (not a subpackage — TaxiDashboard uses flat `app/api/*.py` files): - ```python - from fastapi import APIRouter +**The endpoint** itself is trivial: +```python +@router.get("/me", response_model=MeOut) +async def me(user: User = Depends(require_mechanic)) -> MeOut: + perms = ["mechanic:inspect"] + if user.is_admin: + perms.insert(0, "admin") + return MeOut( + id=user.id, + name=user.full_name or user.username or f"user#{user.id}", + email=user.email, + permissions=perms, + ) +``` - router = APIRouter(prefix="/api/v1/mechanic", tags=["mechanic"]) +Add to `backend/app/api/mechanic.py` (the existing router from B1). Import `require_mechanic` from `app.api.mechanic_deps` and `MeOut` from `app.api.mechanic_schemas`. - @router.get("/healthz") - async def healthz() -> dict[str, str]: - return {"status": "ok"} - ``` -2. Register in `backend/app/main.py` — add `mechanic` to the `from app.api import (...)` tuple and call `app.include_router(mechanic.router)` where the other includes live. -3. Test: bring up the dev backend, hit `GET /api/v1/mechanic/healthz`, expect `{"status":"ok"}`. -4. Commit + push. +**⚠️ Open architecture decision before C1 (must resolve, not punt)** — see "Phase C testing-infrastructure decision" section below. The plan's tests for C1 assume `httpx.AsyncClient`, `pytest-asyncio`, `conftest.py` with `client` + `mechanic_user_token` fixtures, and a real test DB. **None of that exists.** Don't let the C1 implementer freelance — decide first, then dispatch. -Plan calls it Task B1 (see `Phase B` section in the plan). +## Phase C testing-infrastructure decision (UNRESOLVED — answer this before Task C1) + +Current `backend/tests/` contains zero fixtures: no `conftest.py`, no async client, no JWT minting, no test DB. Phases A and B got by with pure-unit and metadata tests. Phase C is the first phase that needs **endpoint-level** tests, which forces a choice: + +| Option | Scope | Pros | Cons | +|---|---|---|---| +| **A. Dependency-override mocks** (recommended) | ~30 lines: override `get_current_user` / `require_mechanic` / `get_db` on the FastAPI app, fake `db.execute` results in each test. Sync `TestClient`. | Tiny, fast, no DB, matches the TDD London School preference in CLAUDE.md. Already proven in `test_mechanic_deps.py`. | Won't catch real-DB query bugs; defers integration testing to Phase J e2e. | +| **B. Real DB fixture infrastructure** | ~250–400 lines: `conftest.py` with async SQLite (aiosqlite) or testcontainers Postgres, `Base.metadata.create_all`, seeded user+department+M2M, JWT mint helper, `pytest-asyncio` + `httpx.AsyncClient`. | Catches real-query bugs, e2e-ish from day one. | Big tangent, slows every PR, async fixture lifecycle is fiddly. | +| **C. Hybrid** | Start with A; add a tiny "DB smoke" subset (Option B) only for endpoints with non-trivial query logic. | Best of both, incrementally. | Two paradigms to maintain. | + +**Recommendation: A**, with the understanding that Phase J adds end-to-end against a real running backend (the plan's existing Phase J e2e + smoke test tasks already cover the real-DB path). + +If A is chosen, the controller's prompt for the C1 implementer should explicitly tell them: "use FastAPI `TestClient` (sync) + `app.dependency_overrides[require_mechanic]` to inject a fake user; don't add a conftest, don't add a real DB, don't introduce `pytest-asyncio`." ## How to resume in a new session @@ -75,22 +113,21 @@ In a new Claude Code chat in `c:\NewProject\`, paste this prompt: ``` Продолжаем проект Premium Mechanic PWA. -Контекст: -- Spec: PremiumDriverApp/docs/superpowers/specs/2026-05-16-premium-mechanic-design.md -- План: PremiumDriverApp/docs/superpowers/plans/2026-05-16-premium-mechanic-phase1.md -- Backend layout: PremiumDriverApp/docs/backend-layout-notes.md -- Текущее состояние: PremiumDriverApp/docs/superpowers/STATE.md +Прочитай PremiumDriverApp/docs/superpowers/STATE.md — там полное состояние и следующая задача. -Phase A полностью завершён (A1–A4, последний коммит be0553e). Следующая задача — Task B1 (mechanic module skeleton + healthz endpoint) из плана. +Phase B полностью завершён (B1–B4, последний коммит f0d7e83). Следующая — +Task C1 (GET /me) из плана PremiumDriverApp/docs/superpowers/plans/2026-05-16-premium-mechanic-phase1.md, +НО сначала надо разрешить "Phase C testing-infrastructure decision" в STATE.md (Option A / B / C). -Используй subagent-driven-development skill. Прочитай STATE.md, спавни первого implementer-subagent на Task B1. +Используй superpowers:subagent-driven-development skill. Реши test-infra вопрос, потом +спавни первого implementer-subagent на C1 со специфической инструкцией про тестовый подход. ``` -That prompt is the **single entry point** for the next session — Claude will read STATE.md, ground itself, and continue dispatching subagents from Task B1 onward. +That prompt is the **single entry point** for the next session — Claude will read STATE.md, ground itself, resolve the test-infrastructure fork, and continue dispatching subagents from Task C1 onward. ## Remaining roadmap (Phase 1 MVP) -- **Phase B** (4 tasks): module skeleton, models registered, schemas, auth deps +- ~~**Phase B** (4 tasks)~~ ✅ done — module skeleton, models, schemas, auth deps - **Phase C** (3 tasks): GET /me, GET /vehicles, GET /vehicles/{id} - **Phase D** (3 tasks): inspections CRUD with carry-over markers logic - **Phase E** (5 tasks): MinIO storage layer + presigned upload/confirm + 302 read + celery thumbnail @@ -100,7 +137,7 @@ That prompt is the **single entry point** for the next session — Claude will r - **Phase I** (6 tasks): CameraCapture + PhotoSlot + VehicleScheme + InspectionEditor + InspectionReview - **Phase J** (4 tasks): e2e test + deploy backend + deploy frontend + smoke test -≈ 35 tasks left until MVP live on `mechanic.pptaxi.ru`. +≈ 31 tasks left until MVP live on `mechanic.pptaxi.ru`. ## Known external dependencies @@ -114,4 +151,7 @@ That prompt is the **single entry point** for the next session — Claude will r - 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) -- Backend tests are synchronous metadata-style for now (no async fixtures exist yet); when API endpoint tests start in Phase C, they'll need a real DB session — implementer-subagent should propose minimal `conftest.py` additions if needed. +- 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.