feat(flask): E1.0–E1.3, E1.8 — миграция на Python/Flask + AI v2

Этап 1 миграции TestingWebApp на целевой стек (Python/Flask/Jinja),
БД остаётся clinic_tests.

E1.0 — База Flask-приложения: SQLAlchemy/psycopg2 пул, Flask sessions,
фабрика create_app, blueprint main с / и /health, base.html в стиле
кабинета HR (Tailwind CDN + Manrope + Material Symbols), 404/500.

E1.1 — Auth + /api/me: Flask sessions (signed cookie) вместо JWT,
bcrypt + Werkzeug, опц. HR_AUTH=1 с UPSERT в clinic_tests.users по
staff_id. UI /login, JSON /api/auth/{login,logout,me}, декораторы
@login_required / @require_role.

E1.2 — Тесты: список + редактор. 10 эндпоинтов, сервисы test_draft,
test_access, test_chain, ai_editor, llm_client, draft_validator,
editor_content. UI /tests (каталог + создание) и /tests/<id>/edit
(редактор с AI). Полный мобильный UX (аккордеоны/drag-n-drop) — в E1.7.

E1.3 — Импорт документов: pypdf + python-docx, эндпоинт
POST /api/tests/import/document, кнопка «Импорт документа» в
AI-панели редактора, лимит 16 МБ.

E1.8 — AI v2: страница /settings (статус ENV-ключа + ping),
ai/generate-by-title (без сетки), ai/check (рецензия), ai/improve
(массовое было→стало с чекбоксами). Унифицированный ответ AI-ошибок:
{ error, code, settingsUrl }.

Docker:
- docker-compose.dev.yml: добавлены DATABASE_URL, HR_AUTH/HR_DATABASE_URL,
  DEEPSEEK_API_KEY/OPENAI_API_KEY/LLM_BASE_URL/LLM_MODEL и сеть postgres
  для testing-flask.

Документация:
- docs/migration-final.md — двух-этапный план (Этап 1: унификация
  стека внутри TestingWebApp; Этап 2: слияние с tgFlaskForm).
- docs/migration-final-inventory.md — карта 22 эндпоинтов Express.

Made-with: Cursor

flask_app/app/services/test_draft.py

@@ -0,0 +1,234 @@
+"""Создание/правка теста, fork версии при наличии попыток (порт `testDraftService.js`)."""
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import text
+
+from ..db import get_engine
+from ..messages import RU
+from .test_access import is_test_author
+from .test_chain import has_any_attempt_for_test
+
+
+class HttpError(Exception):
+    def __init__(self, status: int, message: str):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+def create_test_with_version(author_id: str, *, title: str, description: str | None) -> dict:
+    eng = get_engine()
+    with eng.begin() as conn:
+        t = conn.execute(
+            text(
+                """
+                INSERT INTO tests (title, description, created_by, is_active, is_versioned)
+                VALUES (:title, :desc, :uid, true, true) RETURNING id
+                """
+            ),
+            {'title': title, 'desc': description or None, 'uid': author_id},
+        ).mappings().first()
+        test_id = t['id']
+        v = conn.execute(
+            text(
+                """
+                INSERT INTO test_versions (test_id, version, is_active, parent_id)
+                VALUES (:tid, 1, true, NULL) RETURNING id
+                """
+            ),
+            {'tid': test_id},
+        ).mappings().first()
+    return {'testId': str(test_id), 'versionId': str(v['id'])}
+
+
+def _get_active_version_row(conn, test_id: str) -> dict | None:
+    row = conn.execute(
+        text(
+            'SELECT * FROM test_versions WHERE test_id = :id AND is_active = true LIMIT 1'
+        ),
+        {'id': test_id},
+    ).mappings().first()
+    return dict(row) if row else None
+
+
+def _copy_question_tree(conn, from_version_id, to_version_id) -> None:
+    questions = conn.execute(
+        text(
+            'SELECT id, text, question_order, has_multiple_answers '
+            'FROM questions WHERE test_version_id = :v ORDER BY question_order'
+        ),
+        {'v': from_version_id},
+    ).mappings().all()
+    for q in questions:
+        new_q = conn.execute(
+            text(
+                """
+                INSERT INTO questions (test_version_id, text, question_order, has_multiple_answers)
+                VALUES (:v, :text, :ord, :multi) RETURNING id
+                """
+            ),
+            {
+                'v': to_version_id,
+                'text': q['text'],
+                'ord': q['question_order'],
+                'multi': q['has_multiple_answers'],
+            },
+        ).mappings().first()
+        nqid = new_q['id']
+        opts = conn.execute(
+            text(
+                'SELECT text, is_correct, option_order FROM answer_options '
+                'WHERE question_id = :q ORDER BY option_order'
+            ),
+            {'q': q['id']},
+        ).mappings().all()
+        for o in opts:
+            conn.execute(
+                text(
+                    """
+                    INSERT INTO answer_options (question_id, text, is_correct, option_order)
+                    VALUES (:q, :text, :ic, :ord)
+                    """
+                ),
+                {'q': nqid, 'text': o['text'], 'ic': o['is_correct'], 'ord': o['option_order']},
+            )
+
+
+def _replace_version_content(conn, test_version_id, payload: dict) -> None:
+    conn.execute(
+        text(
+            """
+            DELETE FROM answer_options WHERE question_id IN (
+              SELECT id FROM questions WHERE test_version_id = :v
+            )
+            """
+        ),
+        {'v': test_version_id},
+    )
+    conn.execute(
+        text('DELETE FROM questions WHERE test_version_id = :v'),
+        {'v': test_version_id},
+    )
+    questions = payload.get('questions') or []
+    for i, q in enumerate(questions):
+        ins_q = conn.execute(
+            text(
+                """
+                INSERT INTO questions (test_version_id, text, question_order, has_multiple_answers)
+                VALUES (:v, :text, :ord, :multi) RETURNING id
+                """
+            ),
+            {
+                'v': test_version_id,
+                'text': q.get('text'),
+                'ord': q.get('question_order') or (i + 1),
+                'multi': bool(q.get('hasMultipleAnswers')),
+            },
+        ).mappings().first()
+        qid = ins_q['id']
+        opts = q.get('options') or []
+        for j, o in enumerate(opts):
+            conn.execute(
+                text(
+                    """
+                    INSERT INTO answer_options (question_id, text, is_correct, option_order)
+                    VALUES (:q, :text, :ic, :ord)
+                    """
+                ),
+                {
+                    'q': qid,
+                    'text': o.get('text'),
+                    'ic': bool(o.get('isCorrect')),
+                    'ord': o.get('option_order') or (j + 1),
+                },
+            )
+
+
+def _fork_new_version(conn, test_id: str) -> dict:
+    av = _get_active_version_row(conn, test_id)
+    if not av:
+        raise HttpError(500, RU['internal'])  # invariant: должна быть активная версия
+    mx = conn.execute(
+        text(
+            'SELECT COALESCE(MAX(version), 0) AS v FROM test_versions WHERE test_id = :t'
+        ),
+        {'t': test_id},
+    ).mappings().first()
+    next_v = (mx['v'] or 0) + 1
+    conn.execute(
+        text('UPDATE test_versions SET is_active = false WHERE test_id = :t'),
+        {'t': test_id},
+    )
+    nv = conn.execute(
+        text(
+            """
+            INSERT INTO test_versions (test_id, version, is_active, parent_id)
+            VALUES (:t, :ver, true, :parent) RETURNING *
+            """
+        ),
+        {'t': test_id, 'ver': next_v, 'parent': av['id']},
+    ).mappings().first()
+    _copy_question_tree(conn, av['id'], nv['id'])
+    return dict(nv)
+
+
+def save_test_draft(author_id: str, test_id: str, payload: dict) -> dict:
+    if not isinstance(payload, dict):
+        payload = {}
+    eng = get_engine()
+    with eng.begin() as conn:
+        t = conn.execute(
+            text('SELECT id, created_by FROM tests WHERE id = :id'),
+            {'id': test_id},
+        ).mappings().first()
+        if not t:
+            raise HttpError(404, RU['testNotFound'] if 'testNotFound' in RU else 'Тест не найден.')
+        if not is_test_author(t['created_by'], author_id):
+            raise HttpError(403, 'Доступ запрещён.')
+
+        if payload.get('title') is not None or payload.get('description') is not None:
+            conn.execute(
+                text(
+                    """
+                    UPDATE tests
+                       SET title = COALESCE(:title, title),
+                           description = COALESCE(:desc, description),
+                           updated_at = CURRENT_TIMESTAMP
+                     WHERE id = :id
+                    """
+                ),
+                {
+                    'title': payload.get('title'),
+                    'desc': payload.get('description'),
+                    'id': test_id,
+                },
+            )
+        if payload.get('passingThreshold') is not None:
+            try:
+                raw = float(payload['passingThreshold'])
+                pt = max(0, min(100, round(raw)))
+                conn.execute(
+                    text(
+                        'UPDATE tests SET passing_threshold = :pt, updated_at = CURRENT_TIMESTAMP WHERE id = :id'
+                    ),
+                    {'pt': pt, 'id': test_id},
+                )
+            except (TypeError, ValueError):
+                pass
+
+        has_attempts = has_any_attempt_for_test(conn, test_id)
+        version_row = _get_active_version_row(conn, test_id)
+        if not version_row:
+            raise HttpError(500, 'Нет активной версии теста.')
+
+        forked = False
+        if has_attempts and 'questions' in payload and payload.get('questions') is not None:
+            version_row = _fork_new_version(conn, test_id)
+            forked = True
+
+        if payload.get('questions') is not None:
+            _replace_version_content(conn, version_row['id'], payload)
+
+    return {'testId': test_id, 'versionId': str(version_row['id']), 'forked': forked}