Initial commit: backend scaffold, auth, frontend login

- FastAPI + SQLAlchemy async + Alembic + Postgres backend
- Auth: JWT access + rotating refresh tokens, argon2, roles, audit log
- React 19 + Vite frontend: login page, protected route, auth context
- Docker Compose: postgres, redis, migrate, api, worker (placeholder), frontend/nginx

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

backend/app/db/base.py

@@ -0,0 +1,45 @@
+"""Базовый класс моделей и общие типы колонок."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, MetaData, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+# Явные шаблоны имён — без них Alembic генерирует безымянные constraint'ы,
+# которые потом невозможно удалить в миграции отката.
+NAMING_CONVENTION = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+
+
+class UUIDPrimaryKeyMixin:
+    """PK-идентификатор, генерируемый приложением.
+
+    Генерируем на стороне Python, а не в БД: для чеков UUID должен быть известен
+    ДО обращения к Checkbox — он служит ключом идемпотентности.
+    """
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+
+
+class TimestampMixin:
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )

backend/app/db/models/__init__.py

@@ -0,0 +1,18 @@
+"""Реестр моделей.
+
+Alembic автогенерирует миграции по `Base.metadata`, поэтому каждая модель
+обязана быть импортирована здесь — иначе её таблица молча не попадёт в миграцию.
+"""
+
+from app.db.base import Base
+from app.db.models.audit import AuditAction, AuditLog
+from app.db.models.user import RefreshToken, User, UserRole
+
+__all__ = [
+    "AuditAction",
+    "AuditLog",
+    "Base",
+    "RefreshToken",
+    "User",
+    "UserRole",
+]

backend/app/db/models/audit.py

@@ -0,0 +1,58 @@
+"""Журнал аудита.
+
+Для фискального приложения это не опциональная возможность: по каждому чеку
+должно быть видно, кто и когда его инициировал. Записи только добавляются —
+API на изменение и удаление не существует.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from sqlalchemy import DateTime, ForeignKey, Index, String, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base, UUIDPrimaryKeyMixin
+
+
+class AuditAction(str):
+    """Значения действий. Намеренно обычные строки, а не Enum.
+
+    Добавление нового типа события не должно требовать миграции БД.
+    """
+
+    LOGIN_SUCCESS = "auth.login.success"
+    LOGIN_FAILED = "auth.login.failed"
+    LOGOUT = "auth.logout"
+    TOKEN_REFRESH = "auth.token.refresh"
+    TOKEN_REUSE_DETECTED = "auth.token.reuse_detected"
+    USER_CREATED = "user.created"
+    USER_UPDATED = "user.updated"
+    USER_DEACTIVATED = "user.deactivated"
+
+
+class AuditLog(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "audit_log"
+
+    # Пользователь может быть удалён, журнал — нет: ondelete=SET NULL,
+    # а человекочитаемый актор дублируется в actor_label.
+    user_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), index=True
+    )
+    actor_label: Mapped[str | None] = mapped_column(String(320))
+    action: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    entity_type: Mapped[str | None] = mapped_column(String(64))
+    entity_id: Mapped[str | None] = mapped_column(String(64))
+    payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
+    ip: Mapped[str | None] = mapped_column(String(64))
+    user_agent: Mapped[str | None] = mapped_column(String(512))
+    created_at: Mapped[Any] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )
+
+    __table_args__ = (
+        # Основной запрос админки: «покажи историю по этой сущности».
+        Index("ix_audit_log_entity", "entity_type", "entity_id"),
+    )

backend/app/db/models/user.py

@@ -0,0 +1,74 @@
+"""Пользователи, роли и refresh-токены."""
+
+from __future__ import annotations
+
+import enum
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, Enum, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+
+class UserRole(enum.StrEnum):
+    """Роли фиксированы кодом: набор прав завязан на фискальную ответственность."""
+
+    ADMIN = "admin"      # всё, включая админку, кассы и ключи
+    CASHIER = "cashier"  # очередь и пробитие чеков
+    VIEWER = "viewer"    # только чтение
+
+
+class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "users"
+
+    email: Mapped[str] = mapped_column(String(320), unique=True, index=True, nullable=False)
+    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
+    full_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    role: Mapped[UserRole] = mapped_column(
+        Enum(UserRole, name="user_role", values_callable=lambda e: [i.value for i in e]),
+        nullable=False,
+        default=UserRole.CASHIER,
+    )
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    last_login_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    refresh_tokens: Mapped[list[RefreshToken]] = relationship(
+        back_populates="user", cascade="all, delete-orphan"
+    )
+
+    def __repr__(self) -> str:
+        return f"<User {self.email} ({self.role.value})>"
+
+
+class RefreshToken(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    """Выданные refresh-токены.
+
+    Храним SHA-256 хеш, а не сам токен: утечка дампа БД не должна давать
+    возможность войти. Ротация — выдача нового токена с проставлением
+    `replaced_by_id` у старого, что позволяет обнаружить повторное
+    использование уже израсходованного токена.
+    """
+
+    __tablename__ = "refresh_tokens"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    token_hash: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    replaced_by_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("refresh_tokens.id", ondelete="SET NULL")
+    )
+    user_agent: Mapped[str | None] = mapped_column(String(512))
+    ip: Mapped[str | None] = mapped_column(String(64))
+
+    user: Mapped[User] = relationship(back_populates="refresh_tokens")
+
+    @property
+    def is_active(self) -> bool:
+        from datetime import UTC
+
+        return self.revoked_at is None and self.expires_at > datetime.now(UTC)

backend/app/db/session.py

@@ -0,0 +1,47 @@
+"""Фабрика асинхронных сессий SQLAlchemy."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.core.config import settings
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,
+    pool_pre_ping=True,  # VPS-соединения умеют отваливаться молча
+    pool_size=10,
+    max_overflow=20,
+)
+
+SessionFactory = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,  # объекты остаются пригодными после commit
+    autoflush=False,
+)
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    """Зависимость FastAPI. Откатывает транзакцию при любом исключении."""
+    async with SessionFactory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+
+@asynccontextmanager
+async def session_scope() -> AsyncGenerator[AsyncSession, None]:
+    """Сессия для воркеров и CLI, где механизма зависимостей FastAPI нет."""
+    async with SessionFactory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise