Complete training workflow and acceptance hardening

2026-09-26 18:12:27 +03:00 · 2026-09-26 18:12:27 +03:00 · 7237265833
commit 7237265833
parent 4c4b91064f
243 changed files with 17014 additions and 1500 deletions
--- a/backend/app/db/base.py
+++ b/backend/app/db/base.py
@ -20,7 +20,15 @@ _sessionmaker: async_sessionmaker[AsyncSession] | None = None
 def get_engine():
    global _engine
    if _engine is None:
-        _engine = create_async_engine(get_settings().database_url, pool_pre_ping=True)
+        settings = get_settings()
+        _engine = create_async_engine(
+            settings.database_url,
+            pool_pre_ping=True,
+            pool_size=settings.db_pool_size,
+            max_overflow=settings.db_pool_max_overflow,
+            # SQLAlchemy exceptions/logs must not echo bound user/report values.
+            hide_parameters=True,
+        )
    return _engine


--- a/backend/app/db/migrations/versions/a8b5c2d9e1f4_student_scenario_submissions.py
+++ b/backend/app/db/migrations/versions/a8b5c2d9e1f4_student_scenario_submissions.py
@ -0,0 +1,55 @@
+"""student-authored scenario proposals with instructor moderation
+
+Revision ID: a8b5c2d9e1f4
+Revises: f7a3c9d1e2b4
+Create Date: 2026-09-24
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "a8b5c2d9e1f4"
+down_revision = "f7a3c9d1e2b4"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "scenario_submissions",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("author_trainee_id", sa.Uuid(), nullable=False),
+        sa.Column("group_id", sa.Uuid(), nullable=True),
+        sa.Column("title", sa.String(length=200), nullable=False),
+        sa.Column("incident_type", sa.String(length=20), nullable=False),
+        sa.Column("level", sa.String(length=4), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("address", sa.String(length=500), server_default="", nullable=False),
+        sa.Column("victims", sa.Integer(), nullable=True),
+        sa.Column("status", sa.String(length=16), server_default="pending", nullable=False),
+        sa.Column("review_comment", sa.Text(), server_default="", nullable=False),
+        sa.Column("reviewed_by", sa.String(length=80), nullable=True),
+        sa.Column("scenario_id", sa.String(length=80), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.ForeignKeyConstraint(["author_trainee_id"], ["trainees.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["group_id"], ["groups.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["scenario_id"], ["scenarios.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_scenario_submissions_group_status",
+        "scenario_submissions",
+        ["group_id", "status", "created_at"],
+    )
+    op.create_index(
+        "ix_scenario_submissions_author",
+        "scenario_submissions",
+        ["author_trainee_id", "created_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_scenario_submissions_author", table_name="scenario_submissions")
+    op.drop_index("ix_scenario_submissions_group_status", table_name="scenario_submissions")
+    op.drop_table("scenario_submissions")
--- a/backend/app/db/migrations/versions/b9c6d3e2f1a0_scenario_submission_kio.py
+++ b/backend/app/db/migrations/versions/b9c6d3e2f1a0_scenario_submission_kio.py
@ -0,0 +1,26 @@
+"""store the submitted KIO snapshot for instructor review
+
+Revision ID: b9c6d3e2f1a0
+Revises: a8b5c2d9e1f4
+Create Date: 2026-09-24
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision = "b9c6d3e2f1a0"
+down_revision = "a8b5c2d9e1f4"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "scenario_submissions",
+        sa.Column("kio", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("scenario_submissions", "kio")
--- a/backend/app/db/migrations/versions/c2d7e9f4a1b6_directory_accounts.py
+++ b/backend/app/db/migrations/versions/c2d7e9f4a1b6_directory_accounts.py
@ -0,0 +1,42 @@
+"""provision and identify local AD/LDAP accounts
+
+Revision ID: c2d7e9f4a1b6
+Revises: b9c6d3e2f1a0
+Create Date: 2026-09-24
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "c2d7e9f4a1b6"
+down_revision = "b9c6d3e2f1a0"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column(
+            "auth_provider",
+            sa.String(length=16),
+            server_default="local",
+            nullable=False,
+        ),
+    )
+    op.add_column(
+        "users", sa.Column("directory_subject", sa.String(length=256), nullable=True)
+    )
+    op.create_unique_constraint(
+        "uq_users_directory_subject", "users", ["directory_subject"]
+    )
+    op.create_check_constraint(
+        "ck_users_auth_provider", "users", "auth_provider IN ('local', 'ldap')"
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("ck_users_auth_provider", "users", type_="check")
+    op.drop_constraint("uq_users_directory_subject", "users", type_="unique")
+    op.drop_column("users", "directory_subject")
+    op.drop_column("users", "auth_provider")
--- a/backend/app/db/migrations/versions/d3a9f6b2c8e1_session_backend_owner.py
+++ b/backend/app/db/migrations/versions/d3a9f6b2c8e1_session_backend_owner.py
@ -0,0 +1,31 @@
+"""persist backend node ownership for active sessions
+
+Revision ID: d3a9f6b2c8e1
+Revises: c2d7e9f4a1b6
+Create Date: 2026-09-24
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "d3a9f6b2c8e1"
+down_revision = "c2d7e9f4a1b6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "sessions",
+        sa.Column("backend_node_id", sa.String(length=128), nullable=True),
+    )
+    op.create_index(
+        "ix_sessions_backend_node_active",
+        "sessions",
+        ["backend_node_id", "ended_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_sessions_backend_node_active", table_name="sessions")
+    op.drop_column("sessions", "backend_node_id")
--- a/backend/app/db/migrations/versions/e4b7c1d2a9f0_manual_grammar_review.py
+++ b/backend/app/db/migrations/versions/e4b7c1d2a9f0_manual_grammar_review.py
@ -0,0 +1,35 @@
+"""require a grammar check after manual scenario edits
+
+Revision ID: e4b7c1d2a9f0
+Revises: d3a9f6b2c8e1
+Create Date: 2026-09-25
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "e4b7c1d2a9f0"
+down_revision = "d3a9f6b2c8e1"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "scenarios",
+        sa.Column(
+            "manual_edit_pending",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.false(),
+        ),
+    )
+    op.add_column(
+        "scenarios",
+        sa.Column("grammar_check_hash", sa.String(length=64), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("scenarios", "grammar_check_hash")
+    op.drop_column("scenarios", "manual_edit_pending")
--- a/backend/app/db/migrations/versions/f5a7d2c9b3e1_backend_session_leases.py
+++ b/backend/app/db/migrations/versions/f5a7d2c9b3e1_backend_session_leases.py
@ -0,0 +1,35 @@
+"""add expiring backend ownership leases and fencing epochs
+
+Revision ID: f5a7d2c9b3e1
+Revises: e4b7c1d2a9f0
+Create Date: 2026-09-25
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "f5a7d2c9b3e1"
+down_revision = "e4b7c1d2a9f0"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "sessions",
+        sa.Column(
+            "backend_fencing_epoch",
+            sa.Integer(),
+            nullable=False,
+            server_default="0",
+        ),
+    )
+    op.add_column(
+        "sessions",
+        sa.Column("backend_lease_until", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("sessions", "backend_lease_until")
+    op.drop_column("sessions", "backend_fencing_epoch")
--- a/backend/app/db/models.py
+++ b/backend/app/db/models.py
@ -8,7 +8,18 @@
 from datetime import datetime
 from uuid import UUID, uuid4

-from sqlalchemy import DateTime, ForeignKey, Index, LargeBinary, String, Text, UniqueConstraint, func
+from sqlalchemy import (
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    LargeBinary,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column, relationship

@ -108,12 +119,46 @@ class Scenario(Base):
    # NULL означает базовую/унаследованную системную библиотеку.
    owner_login: Mapped[str | None] = mapped_column(String(80), nullable=True)
    body: Mapped[dict] = mapped_column(JSONB)
+    manual_edit_pending: Mapped[bool] = mapped_column(default=False, nullable=False)
+    grammar_check_hash: Mapped[str | None] = mapped_column(String(64), nullable=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
    )


+class ScenarioSubmission(Base):
+    """Student-authored KIO draft awaiting instructor moderation."""
+
+    __tablename__ = "scenario_submissions"
+
+    id: Mapped[UUID] = _uuid_pk()
+    author_trainee_id: Mapped[UUID] = mapped_column(ForeignKey("trainees.id", ondelete="CASCADE"))
+    group_id: Mapped[UUID | None] = mapped_column(
+        ForeignKey("groups.id", ondelete="SET NULL"), nullable=True
+    )
+    title: Mapped[str] = mapped_column(String(200))
+    incident_type: Mapped[str] = mapped_column(String(20))
+    level: Mapped[str] = mapped_column(String(4))
+    description: Mapped[str] = mapped_column(Text)
+    address: Mapped[str] = mapped_column(String(500), default="")
+    victims: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    kio: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    status: Mapped[str] = mapped_column(String(16), default="pending")
+    review_comment: Mapped[str] = mapped_column(Text, default="")
+    reviewed_by: Mapped[str | None] = mapped_column(String(80), nullable=True)
+    scenario_id: Mapped[str | None] = mapped_column(
+        ForeignKey("scenarios.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    reviewed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    __table_args__ = (
+        Index("ix_scenario_submissions_group_status", "group_id", "status", "created_at"),
+        Index("ix_scenario_submissions_author", "author_trainee_id", "created_at"),
+    )
+
+
 class Session(Base):
    """Одна попытка одного курсанта по одному сценарию.

@ -126,6 +171,9 @@ class Session(Base):
    id: Mapped[UUID] = _uuid_pk()
    scenario_id: Mapped[str] = mapped_column(ForeignKey("scenarios.id", ondelete="RESTRICT"))
    owner_login: Mapped[str | None] = mapped_column(String(80), nullable=True)
+    backend_node_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    backend_fencing_epoch: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    backend_lease_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    trainee_id: Mapped[UUID | None] = mapped_column(ForeignKey("trainees.id", ondelete="SET NULL"))
    group_id: Mapped[UUID | None] = mapped_column(ForeignKey("groups.id", ondelete="SET NULL"))
    mode: Mapped[str] = mapped_column(String(16))
@ -148,6 +196,7 @@ class Session(Base):
    __table_args__ = (
        Index("ix_sessions_trainee_scenario", "trainee_id", "scenario_id"),
        Index("ix_sessions_group_created", "group_id", "created_at"),
+        Index("ix_sessions_backend_node_active", "backend_node_id", "ended_at"),
    )


@ -270,18 +319,30 @@ class User(Base):
    service: Mapped[str | None] = mapped_column(String(120))
    trainee_id: Mapped[UUID | None] = mapped_column(ForeignKey("trainees.id", ondelete="SET NULL"))
    blocked: Mapped[bool] = mapped_column(default=False)
+    # Каталожные учётки создаются при первом успешном входе; их роль и DDS
+    # service синхронизируются с явной LDAP group mapping, пароль не хранится.
+    auth_provider: Mapped[str] = mapped_column(
+        String(16), default="local", server_default="local"
+    )
+    directory_subject: Mapped[str | None] = mapped_column(String(256), nullable=True)
    # Версия полномочий попадает в подписанную cookie. Смена роли, пароля или
    # блокировки увеличивает её и отзывает старые cookie даже после restart.
    auth_version: Mapped[int] = mapped_column(default=0)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())

+    __table_args__ = (
+        UniqueConstraint("directory_subject", name="uq_users_directory_subject"),
+        CheckConstraint("auth_provider IN ('local', 'ldap')", name="ck_users_auth_provider"),
+    )
+

 class AuditLog(Base):
    """Журнал действий. ТЗ требует хранения не менее шести месяцев, поэтому
    записи не удаляются вместе с сессией: `object_id` — строка, а не ссылка.

-    Пишется то, что меняет чужой результат или состав системы: запуск занятия,
-    оценка, коррекция оценки, правка сценария, вход и выход.
+    Пишется то, что меняет чужой результат или состав системы, и значимые
+    административные действия: запуск занятия, оценка, правка сценария,
+    резервное копирование, аналитический запрос, вход и выход.
    """

    __tablename__ = "audit_log"
--- a/backend/app/db/repo.py
+++ b/backend/app/db/repo.py
@ -1,5 +1,6 @@
 """Доступ к журналу. Всё, что не записано сюда, для оценки не существует."""

+from collections.abc import Callable
 from datetime import datetime
 from uuid import UUID

@ -8,6 +9,12 @@ from sqlalchemy.ext.asyncio import AsyncSession

 from app.db.models import Group, HintUse, InstructorNote, Session, Trainee, Utterance

+BeforeSessionCommit = Callable[[AsyncSession, Session], None]
+
+
+class SessionNodeConflict(PermissionError):
+    """The session is routed to a backend other than its persisted owner."""
+

 async def next_attempt(db: AsyncSession, trainee_id: UUID | None, scenario_id: str) -> int:
    """Номер попытки по этому сценарию. Отдельной таблицы попыток нет:
@ -31,11 +38,14 @@ async def create_session(
    group_id: UUID | None = None,
    session_id: UUID | None = None,
    owner_login: str | None = None,
+    backend_node_id: str | None = None,
+    before_commit: BeforeSessionCommit | None = None,
 ) -> Session:
    session = Session(
        scenario_id=scenario_id,
        mode=mode,
        owner_login=owner_login,
+        backend_node_id=backend_node_id,
        trainee_id=trainee_id,
        group_id=group_id,
        attempt=await next_attempt(db, trainee_id, scenario_id),
@ -43,6 +53,9 @@ async def create_session(
    if session_id is not None:
        session.id = session_id
    db.add(session)
+    if before_commit is not None:
+        await db.flush()
+        before_commit(db, session)
    await db.commit()
    return session

@ -57,24 +70,49 @@ async def ensure_session(
    trainee_id: UUID | None = None,
    group_name: str | None = None,
    owner_login: str | None = None,
+    backend_node_id: str | None = None,
+    before_commit: BeforeSessionCommit | None = None,
 ) -> Session:
    """Занятие, запущенное с пульта, должно иметь строку в журнале.

    Иначе реплики, подсказки и пометки не к чему привязать: они уходят
    в нарушение внешнего ключа, а профиль курсанта остаётся пустым.
    """
-    existing = await db.get(Session, session_id)
+    existing = await db.scalar(
+        select(Session)
+        .where(Session.id == session_id)
+        .with_for_update()
+    )
    if existing is not None:
        if existing.owner_login != owner_login:
            raise PermissionError("занятие принадлежит другому преподавателю")
+        if (
+            existing.backend_node_id is not None
+            and backend_node_id is not None
+            and existing.backend_node_id != backend_node_id
+        ):
+            raise SessionNodeConflict("занятие закреплено за другим backend-узлом")
+        changed = False
+        if existing.backend_node_id is None and backend_node_id is not None:
+            existing.backend_node_id = backend_node_id
+            changed = True
+        if before_commit is not None:
+            before_commit(db, existing)
+            await db.commit()
+        elif changed:
+            await db.commit()
        return existing

    group = await ensure_group(db, group_name, owner_login=owner_login) if group_name else None
    trainee = await db.get(Trainee, trainee_id) if trainee_id else None
    if trainee_id and trainee is None:
        raise ValueError(f"курсант {trainee_id} не найден")
+    if trainee is not None:
+        await _assert_trainee_scope(db, trainee, owner_login)
    if trainee is None and trainee_name:
-        trainee = await ensure_trainee(db, trainee_name, group)
+        trainee = await ensure_trainee(
+            db, trainee_name, group, owner_login=owner_login
+        )
    return await create_session(
        db,
        scenario_id=scenario_id,
@ -83,6 +121,8 @@ async def ensure_session(
        group_id=group.id if group else trainee.group_id if trainee else None,
        session_id=session_id,
        owner_login=owner_login,
+        backend_node_id=backend_node_id,
+        before_commit=before_commit,
    )


@ -164,23 +204,51 @@ async def history(


 async def ensure_group(
-    db: AsyncSession, name: str, *, owner_login: str | None = None
+    db: AsyncSession, name: str, *, owner_login: str | None = None, commit: bool = True
 ) -> Group:
    group = await db.scalar(select(Group).where(Group.name == name))
    if group is None:
        group = Group(name=name, owner_login=owner_login)
        db.add(group)
-        await db.commit()
+        if commit:
+            await db.commit()
+        else:
+            await db.flush()
    elif group.owner_login != owner_login:
        raise PermissionError("группа принадлежит другому преподавателю или администратору")
    return group


-async def ensure_trainee(db: AsyncSession, name: str, group: Group | None = None) -> Trainee:
+async def ensure_trainee(
+    db: AsyncSession,
+    name: str,
+    group: Group | None = None,
+    *,
+    owner_login: str | None = None,
+    commit: bool = True,
+) -> Trainee:
    query = select(Trainee).where(Trainee.name == name)
    trainee = await db.scalar(query)
    if trainee is None:
+        if group is not None and owner_login is not None and group.owner_login != owner_login:
+            raise PermissionError("курсант относится к другой группе")
        trainee = Trainee(name=name, group_id=group.id if group else None)
        db.add(trainee)
-        await db.commit()
+        if commit:
+            await db.commit()
+        else:
+            await db.flush()
+    else:
+        await _assert_trainee_scope(db, trainee, owner_login)
    return trainee
+
+
+async def _assert_trainee_scope(
+    db: AsyncSession, trainee: Trainee, owner_login: str | None
+) -> None:
+    """Prevent lesson creation from attaching a learner owned by another teacher."""
+    if owner_login is None or trainee.group_id is None:
+        return
+    group = await db.get(Group, trainee.group_id)
+    if group is None or group.owner_login != owner_login:
+        raise PermissionError("курсант относится к другой учебной группе")