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/auth/__init__.py

@@ -0,0 +1,5 @@
+"""Auth: логин/логаут/me — пара UI-страниц и JSON-API.
+
+См. routes.py, services.py, decorators.py.
+"""
+from .routes import auth_bp  # noqa: F401

flask_app/app/auth/decorators.py

@@ -0,0 +1,69 @@
+"""Декораторы доступа: подгружают пользователя из сессии.
+
+`g.current_user` доступен в шаблонах как `current_user` (см. context_processor в `app/__init__.py`).
+"""
+from __future__ import annotations
+
+from functools import wraps
+from typing import Iterable
+
+from flask import g, jsonify, redirect, request, session, url_for
+
+from ..messages import RU
+from .services import AuthUser, load_user_by_id
+
+
+def _wants_json() -> bool:
+    if request.path.startswith('/api/'):
+        return True
+    accept = request.headers.get('Accept', '')
+    return 'application/json' in accept and 'text/html' not in accept
+
+
+def _load_current_user() -> AuthUser | None:
+    if hasattr(g, 'current_user'):
+        return g.current_user
+    user_id = session.get('user_id')
+    user = load_user_by_id(user_id) if user_id else None
+    g.current_user = user
+    return user
+
+
+def login_required(fn):
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        user = _load_current_user()
+        if user is None:
+            if _wants_json():
+                return jsonify(error=RU['authRequired']), 401
+            return redirect(url_for('auth.login_page', next=request.full_path or '/'))
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+def require_role(roles: str | Iterable[str]):
+    allowed = {roles} if isinstance(roles, str) else set(roles)
+
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            user = _load_current_user()
+            if user is None:
+                if _wants_json():
+                    return jsonify(error=RU['authRequired']), 401
+                return redirect(url_for('auth.login_page', next=request.full_path or '/'))
+            if user.role not in allowed:
+                if _wants_json():
+                    return jsonify(error=RU['insufficientPermissions']), 403
+                return ('Доступ запрещён.', 403)
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def current_user() -> AuthUser | None:
+    """Хелпер для шаблонов и view-функций."""
+    return _load_current_user()

flask_app/app/auth/hr_role.py

@@ -0,0 +1,13 @@
+"""Маппинг роли HR → роль модуля тестов (порт `backend/src/utils/hrRoleMap.js`)."""
+from __future__ import annotations
+
+
+def map_hr_role_to_app(hr_role: str | None) -> str:
+    r = (hr_role or '').strip().lower()
+    if not r:
+        return 'employee'
+    if r == 'admin' or 'hr' in r or 'дире' in r:
+        return 'hr'
+    if 'manager' in r or 'рук' in r or 'завед' in r:
+        return 'manager'
+    return 'employee'

flask_app/app/auth/routes.py

@@ -0,0 +1,107 @@
+"""Маршруты auth: HTML (`/login`, `/logout`) и JSON (`/api/auth/*`)."""
+from __future__ import annotations
+
+import logging
+
+from flask import (
+    Blueprint,
+    flash,
+    jsonify,
+    redirect,
+    render_template,
+    request,
+    session,
+    url_for,
+)
+
+from ..config import is_assignment_feature_enabled, is_dev_ui
+from ..messages import RU
+from .decorators import login_required, current_user
+from .services import AuthError, authenticate_credentials
+
+log = logging.getLogger(__name__)
+
+auth_bp = Blueprint('auth', __name__)
+
+
+def _safe_next(default: str = '/') -> str:
+    """Защита от open-redirect: разрешаем только относительные пути."""
+    nxt = request.values.get('next') or default
+    if not nxt.startswith('/') or nxt.startswith('//'):
+        return default
+    return nxt
+
+
+def _do_login(login: str, password: str):
+    user = authenticate_credentials(login, password)
+    session.clear()
+    session['user_id'] = user.id
+    session.permanent = True
+    return user
+
+
+# ─── HTML ────────────────────────────────────────────────────────────
+
+@auth_bp.route('/login', methods=['GET'])
+def login_page():
+    if current_user() is not None:
+        return redirect(_safe_next('/'))
+    return render_template('auth/login.html', next=_safe_next('/'))
+
+
+@auth_bp.route('/login', methods=['POST'])
+def login_submit():
+    login = (request.form.get('login') or '').strip()
+    password = request.form.get('password') or ''
+    try:
+        _do_login(login, password)
+    except AuthError as e:
+        flash(e.message, 'error')
+        return render_template('auth/login.html', next=_safe_next('/'), login=login), e.status
+    except Exception:
+        log.exception('login_submit failed')
+        flash(RU['loginFailed'], 'error')
+        return render_template('auth/login.html', next=_safe_next('/'), login=login), 500
+    return redirect(_safe_next('/'))
+
+
+@auth_bp.route('/logout', methods=['POST', 'GET'])
+def logout():
+    session.clear()
+    if request.method == 'GET':
+        return redirect(url_for('auth.login_page'))
+    return redirect(url_for('auth.login_page'))
+
+
+# ─── JSON API ────────────────────────────────────────────────────────
+
+@auth_bp.route('/api/auth/login', methods=['POST'])
+def api_login():
+    data = request.get_json(silent=True) or {}
+    login = (data.get('login') or '').strip()
+    password = data.get('password') or ''
+    try:
+        user = _do_login(login, password)
+    except AuthError as e:
+        return jsonify(error=e.message), e.status
+    except Exception:
+        log.exception('api_login failed')
+        return jsonify(error=RU['loginFailed']), 500
+    return jsonify(user=user.to_public_dict())
+
+
+@auth_bp.route('/api/auth/logout', methods=['POST'])
+def api_logout():
+    session.clear()
+    return jsonify(message=RU['loggedOut'])
+
+
+@auth_bp.route('/api/auth/me', methods=['GET'])
+@login_required
+def api_me():
+    user = current_user()
+    return jsonify(
+        user=user.to_public_dict() if user else None,
+        devUi=is_dev_ui(),
+        assignmentUi=is_assignment_feature_enabled(),
+    )

flask_app/app/auth/services.py

@@ -0,0 +1,217 @@
+"""Бизнес-логика логина — порт `backend/src/routes/auth.js` + `utils/auth.js`.
+
+Поддерживает оба режима:
+- Локальный (по умолчанию): bcrypt в `clinic_tests.users.password_hash`.
+- HR_AUTH=1: пароль проверяется в `hr_bot_test.users` (Werkzeug scrypt/pbkdf2),
+  затем находим запись `staff_members` по `web_login` и UPSERT-им в
+  `clinic_tests.users` по `staff_id`.
+
+Werkzeug-хеши проверяются через `werkzeug.security.check_password_hash`,
+bcrypt-хеши — через пакет `bcrypt`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import bcrypt
+from sqlalchemy import text
+from werkzeug.security import check_password_hash as _werkzeug_check
+
+from ..config import (
+    HR_MANAGED_PASSWORD_PLACEHOLDER,
+    is_hr_auth_enabled,
+)
+from ..db import get_engine, get_hr_engine
+from ..messages import RU
+from .hr_role import map_hr_role_to_app
+
+
+@dataclass
+class AuthUser:
+    id: str  # UUID в виде строки
+    login: str
+    full_name: str | None
+    role: str
+    department_id: Optional[str]
+    staff_id: Optional[int]
+
+    def to_public_dict(self) -> dict:
+        out = {
+            'id': str(self.id),
+            'login': self.login,
+            'fullName': self.full_name,
+            'role': self.role,
+            'departmentId': self.department_id,
+        }
+        out['staffId'] = self.staff_id
+        return out
+
+
+class AuthError(Exception):
+    """Ошибка авторизации с HTTP-кодом и сообщением для пользователя."""
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+def _verify_password(plain: str, hashed: str | None) -> bool:
+    """Универсальная проверка пароля: bcrypt + Werkzeug (scrypt/pbkdf2)."""
+    if not hashed:
+        return False
+    if hashed == HR_MANAGED_PASSWORD_PLACEHOLDER:
+        return False
+    if hashed.startswith('scrypt:') or hashed.startswith('pbkdf2:'):
+        try:
+            return _werkzeug_check(hashed, plain)
+        except Exception:
+            return False
+    if hashed.startswith('$2'):
+        try:
+            return bcrypt.checkpw(plain.encode('utf-8'), hashed.encode('utf-8'))
+        except Exception:
+            return False
+    try:
+        return _werkzeug_check(hashed, plain)
+    except Exception:
+        return False
+
+
+def authenticate_credentials(login: str, password: str) -> AuthUser:
+    """Главная точка входа. Возвращает AuthUser или поднимает AuthError."""
+    login = (login or '').strip()
+    password = password or ''
+    if not login or not password:
+        raise AuthError(400, RU['loginAndPasswordRequired'])
+
+    if is_hr_auth_enabled():
+        return _authenticate_via_hr(login, password)
+    return _authenticate_local(login, password)
+
+
+# ─── локальный режим ────────────────────────────────────────────────
+
+def _authenticate_local(login: str, password: str) -> AuthUser:
+    eng = get_engine()
+    with eng.connect() as conn:
+        row = conn.execute(
+            text(
+                'SELECT id, login, password_hash, full_name, role, department_id, staff_id '
+                'FROM users WHERE login = :login AND is_active = true'
+            ),
+            {'login': login},
+        ).mappings().first()
+
+    if not row:
+        raise AuthError(401, RU['invalidCredentials'])
+
+    if row['password_hash'] == HR_MANAGED_PASSWORD_PLACEHOLDER:
+        raise AuthError(401, RU['useHrLogin'])
+
+    if not _verify_password(password, row['password_hash']):
+        raise AuthError(401, RU['invalidCredentials'])
+
+    return AuthUser(
+        id=str(row['id']),
+        login=row['login'],
+        full_name=row['full_name'],
+        role=row['role'],
+        department_id=row['department_id'],
+        staff_id=row['staff_id'],
+    )
+
+
+# ─── HR_AUTH=1 ──────────────────────────────────────────────────────
+
+def _authenticate_via_hr(login: str, password: str) -> AuthUser:
+    hr_eng = get_hr_engine()
+    if hr_eng is None:
+        raise AuthError(500, RU['hrDatabaseUrlMissing'])
+
+    with hr_eng.connect() as hr_conn:
+        u = hr_conn.execute(
+            text(
+                'SELECT id, username, password_hash, role FROM users '
+                'WHERE LOWER(TRIM(username)) = LOWER(TRIM(:login))'
+            ),
+            {'login': login},
+        ).mappings().first()
+        if not u or not u['password_hash']:
+            raise AuthError(401, RU['invalidCredentials'])
+        if not _verify_password(password, u['password_hash']):
+            raise AuthError(401, RU['invalidCredentials'])
+
+        s = hr_conn.execute(
+            text(
+                'SELECT id, fio FROM staff_members '
+                "WHERE LOWER(TRIM(COALESCE(web_login, ''))) = LOWER(TRIM(:login))"
+            ),
+            {'login': login},
+        ).mappings().first()
+        if not s:
+            raise AuthError(403, RU['noStaffForLogin'])
+
+    staff_id = int(s['id'])
+    fio = s['fio'] or login
+    app_role = map_hr_role_to_app(u['role'])
+
+    eng = get_engine()
+    with eng.begin() as conn:
+        row = conn.execute(
+            text(
+                """
+                INSERT INTO users (login, password_hash, full_name, role,
+                                   department_id, is_active, staff_id)
+                VALUES (:login, :ph, :fn, :role, NULL, true, :staff_id)
+                ON CONFLICT (staff_id) DO UPDATE SET
+                  login = EXCLUDED.login,
+                  full_name = EXCLUDED.full_name,
+                  role = EXCLUDED.role,
+                  password_hash = EXCLUDED.password_hash
+                RETURNING id, login, full_name, role, department_id, staff_id
+                """
+            ),
+            {
+                'login': login,
+                'ph': HR_MANAGED_PASSWORD_PLACEHOLDER,
+                'fn': fio,
+                'role': app_role,
+                'staff_id': staff_id,
+            },
+        ).mappings().first()
+
+    return AuthUser(
+        id=str(row['id']),
+        login=row['login'],
+        full_name=row['full_name'],
+        role=row['role'],
+        department_id=row['department_id'],
+        staff_id=row['staff_id'],
+    )
+
+
+def load_user_by_id(user_id: str) -> Optional[AuthUser]:
+    """Догружает пользователя из `clinic_tests.users` (используется при каждом запросе)."""
+    if not user_id:
+        return None
+    eng = get_engine()
+    with eng.connect() as conn:
+        row = conn.execute(
+            text(
+                'SELECT id, login, full_name, role, department_id, staff_id '
+                'FROM users WHERE id = :id AND is_active = true'
+            ),
+            {'id': user_id},
+        ).mappings().first()
+    if not row:
+        return None
+    return AuthUser(
+        id=str(row['id']),
+        login=row['login'],
+        full_name=row['full_name'],
+        role=row['role'],
+        department_id=row['department_id'],
+        staff_id=row['staff_id'],
+    )