Дорабоки интерфейса системы тестирования. Раздел 1 Шапка+Верхний brick

2026-04-29 14:55:43 +05:00
parent 1c4dacbc85
commit eff3fda5b0
34 changed files with 3339 additions and 576 deletions
@@ -1,202 +1,195 @@
 # Система тестирования сотрудников клиники

-Веб-приложение для проведения внутреннего тестирования сотрудников клиники. Руководители подразделений и HR-менеджеры создают тесты и назначают их сотрудникам. Система фиксирует все попытки и результаты.
+Веб-приложение для проведения внутреннего тестирования сотрудников клиники.
+Руководители подразделений и HR-менеджеры создают тесты и назначают их
+сотрудникам. Все попытки и результаты сохраняются.

-**Версия ТЗ:** 1.2  
-**Дата:** 2026-03-21  
-**Статус:** Согласовано
-
-**Актуальное состояние кода (не ТЗ, а «что уже есть»):** [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) · [инструкция для проверяющих на dev](docs/DEV_CONTOUR_USER_GUIDE.md) · [кабинет: коротко для врачей/кураторов](docs/РУКОВОДСТВО_КАБИНЕТ_ТЕСТОВ.md).  
-**Спринты мобильного UI (чек-лист для разработки):** [docs/СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md](docs/СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md).  
-**Унификация стека (текущий этап) и слияние с HR-кабинетом (на будущее):** план и журнал — [docs/migration-final.md](docs/migration-final.md). Этап 1 — Express → Flask + React → Jinja **внутри TestingWebApp** (БД остаётся `clinic_tests`). Этап 2 (на будущее) — слияние с `HR_TG_Bot/tgFlaskForm`: [docs/migration-to-tgflaskform.md](docs/migration-to-tgflaskform.md) · [простым языком](docs/migration-to-tgflaskform-plain.md). Карта Express-функционала и справочный gap-analysis с уже существующим модулем HR-кабинета: [docs/migration-final-inventory.md](docs/migration-final-inventory.md).  
-**Заготовка `flask_app/`** (отдельный Flask) больше **не развивается** — выбран сценарий «модуль внутри `tgFlaskForm`».
+- **Прод:** **[https://edullm.pirogov.ai/](https://edullm.pirogov.ai/)**
+- **Ветка разработки:** `dev`
+- **ТЗ:** v1.2 от 2026-03-21 (статус — согласовано)

 ---

-## Стек технологий
+## Стек и состояние

-### Этот репозиторий (TestingWebApp)
+**Целевой и единственный рабочий стек** — Python 3.11 + Flask 3 +
+Jinja2 + Tailwind CDN + SQLAlchemy / psycopg2, код в
+[`flask_app/`](flask_app/). На нём работает и прод, и dev (`:3108`).

-| Слой | Технологии |
-|------|------------|
-| **Backend** | Node.js (ESM), **Express** 4, **pg**, миграции SQL; аутентификация — cookie + **JWT** (**jsonwebtoken**), пароли **bcryptjs**; опционально вход через HR (`HR_AUTH`, отдельное подключение к БД HR). |
-| **Frontend** | **React** 18, **React Router** 6, сборка **Vite** 5; статика в проде через Nginx (см. `docker-compose.dev.yml`). |
-| **Данные** | **PostgreSQL**, отдельная БД **`clinic_tests`**: UUID-ключи, таблицы `tests`, `test_versions`, `questions`, `answer_options`, назначения, попытки (см. `backend/src/db/migrations/`). |
-| **Прочее** | Извлечение текста из PDF/DOCX (**pdf-parse**, **mammoth**), опционально LLM для черновиков тестов; **dotenv**, **cors**, **multer**. |
+Старые каталоги `backend/` (Node.js / Express) и `frontend/`
+(React + Vite) — **архив**: не разворачиваются, в `docker-compose.dev.yml`
+поднимается только сервис `testing-flask`, удаление папок запланировано
+в спринте **E1.6**. Использовать их не надо, миграции и SQL-схема
+сохранены в `backend/src/db/migrations/` исключительно как источник
+структуры БД.

-### Целевой стек (Flask, как в кабинете / мини-приложении)
+БД — **`clinic_tests`** (PostgreSQL, UUID-ключи). В Этапе 1 схема
+не меняется.

-Тот же класс технологий, что в **`HR_TG_Bot/tgFlaskForm`**: Python, Flask, шаблоны, Postgres. Сейчас допускается **отдельный деплой** нового контура из каталога [`flask_app/`](flask_app/README.md); позже — слияние с полным кабинетом при необходимости.
-
-Эталон реализации модуля в монорепозитории HR — общий веб-кабинет **`HR_TG_Bot/tgFlaskForm`**:
-
-| Слой | Технологии |
-|------|------------|
-| **Приложение** | **Python 3**, **Flask** 3, шаблоны **Jinja2** + **PyPug**, blueprint `/cabinet/testing`; прод-сервер типично **waitress**. |
-| **Данные** | **SQLAlchemy** 2, **psycopg2**, БД **`hr_bot_test`**: таблицы `testing_*`, связи с **`staff_members`**. |
-| **Клиент** | HTML-шаблоны кабинета, JS в `webApp/templates/static/js/cabinet/` (без отдельного SPA в этом репозитории). |
-| **Инфра** | Тот же кластер Postgres, что и у Postgres_TG_Bots / HR (см. раздел установки ниже). |
-
-Подробности переноса и миграции данных: [docs/migration-to-tgflaskform.md](docs/migration-to-tgflaskform.md).  
-Скрипт ETL в монорепозитории HR: [`../HR_TG_Bot/tgFlaskForm/tools/migrate_clinic_tests_to_hr.py`](../HR_TG_Bot/tgFlaskForm/tools/migrate_clinic_tests_to_hr.py) (`--dry-run` / `--apply`, переменные `CLINIC_TESTS_URL` и `HR_BOT_URL`).
+**Этап 2** — слияние с общим HR-кабинетом `HR_TG_Bot/tgFlaskForm` —
+запланирован на будущее, сейчас не делается. План:
+[`docs/migration-to-tgflaskform.md`](docs/migration-to-tgflaskform.md)
+([простыми словами](docs/migration-to-tgflaskform-plain.md)).

 ---

-## Содержание
+## Что уже работает на новом (Flask) контуре

- [Стек технологий](#стек-технологий) · [flask_app/ — новый контур](flask_app/README.md)
- [Состояние реализации (сводка)](#состояние-реализации-сводка)
- [Функциональные возможности](#функциональные-возможности)
- [Роли и права доступа](#роли-и-права-доступа)
- [Установка и запуск](#установка-и-запуск)
- [Данные, сотрудники, интеграция с HR](#данные-сотрудники-интеграция-с-hr)
- [Нефункциональные требования](#нефункциональные-требования)
- [Вне scope](#вне-scope-не-реализуется-в-данной-версии)
+E1.0–E1.3 и E1.8 закрыты. Чек-лист и журнал —
+[`docs/migration-final.md`](docs/migration-final.md).

---
+- **Авторизация** через куки-сессию Flask: bcrypt (локальные пользователи
+  `clinic_tests.users`) или Werkzeug-хеши при включённом `HR_AUTH=1`
+  (UPSERT в `clinic_tests.users` по `staff_id` из `hr_bot_test`).
+  UI: `/login`, JSON: `/api/auth/{login,logout,me}`.
+- **Каталог тестов** `/tests` (видны активные + блок «Скрытые вами»),
+  создание теста через модалку.
+- **Редактор** `/tests/<id>/edit`: правка названия/описания/проходного
+  балла, добавление/удаление/перемещение вопросов и вариантов,
+  переключатель «Цепочка активна», авто-форк новой версии при правке
+  после первой попытки.
+- **AI-помощник** в редакторе:
+  - «По названию» — генерация всего теста по теме (количество вопросов
+    и вариантов задаёт автор);
+  - «По текущей сетке» — генерация по уже расставленным карточкам;
+  - «Проверить» — рецензия теста с вердиктом и разделами рекомендаций;
+  - «Улучшить» — массовое «было → стало» с чекбоксами;
+  - «AI: вопрос/переформулировать» — на отдельной карточке вопроса.
+- **Импорт документа** в редакторе: PDF / DOCX / TXT / MD до 16 МБ,
+  через `pypdf` и `python-docx` → AI-черновик.
+- **Настройки** `/settings` — статус общего LLM-ключа из ENV (DeepSeek
+  или OpenAI-совместимый), кнопка «Проверить подключение».

-## Состояние реализации (сводка)
+Подробная инструкция для тестировщика (только UI, без консоли) —
+[`docs/QA-versioning-and-ai.md`](docs/QA-versioning-and-ai.md).

-Коротко и по-человечески: [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) (черновики и версии, разбор попыток, список тестов, dev-стенд).  
-Как пользоваться локальным **dev** без чтения кода: [docs/DEV_CONTOUR_USER_GUIDE.md](docs/DEV_CONTOUR_USER_GUIDE.md).
+## Что ещё не реализовано

---
-
-## Функциональные возможности
-
-### Управление пользователями и подразделениями
-
- Создание/редактирование/деактивация учётных записей сотрудников
- Каждый сотрудник принадлежит одному подразделению
- Создание/редактирование справочника подразделений
- Назначение роли сотруднику: HR-менеджер / Руководитель подразделения / Сотрудник
-
-### Создание и редактирование тестов
-
-**Тест содержит:**
- Название теста
- Описание (опционально)
- Список вопросов (минимум 7)
- Порог зачёта — минимальный % правильных ответов
- Таймер прохождения — лимит в минутах (опционально)
-
-**Вопрос содержит:**
- Текст вопроса
- Минимум 3 варианта ответа
- Один или несколько правильных ответов
-
-**Настройки теста:**
- Разрешить возврат к предыдущему вопросу: да / нет
-
-**Версионирование:**
- Автор может редактировать тест пока никто его не проходил
- Если тест уже проходили — создаётся новая версия (`version + 1`), старая сохраняется
- Все версии теста хранятся; результаты привязаны к конкретной версии
- Активная версия — та, которую видят сотрудники; автор может вручную переключить активную версию
- Тест можно деактивировать (скрыть из списка, не удалять)
-
-### Назначение теста
-
- Список получателей (отдел или конкретные сотрудники)
- Срок сдачи — дата дедлайна
- Допустимое количество попыток (1 или более)
-
-### Прохождение теста
-
- На главной странице сотрудник видит список назначенных тестов со статусами:
-  - `Не начат` — ещё не открывал
-  - `В процессе` — начал, не завершил
-  - `Завершён` — сдал/не сдал
-  - `Просрочен` — дедлайн прошёл, не сдан
- Если задан таймер — отображается обратный отсчёт, по истечении тест завершается автоматически
- Порядок вопросов **случайный** при каждом прохождении
- Возможность вернуться к предыдущему вопросу — определяется настройкой теста
-
-### Результаты после завершения теста
-
- Итоговый балл и процент правильных ответов
- Факт зачёта: **сдал / не сдал**
- Разбор ошибок: по каждому вопросу — его ответ и правильный ответ
-
-### Трекер попыток
-
-Единый интерфейс просмотра всех попыток прохождения тестов:
- Фильтрация по подразделению, сотруднику, тесту, статусу, результату
- Пагинация и сортировка
-
-### AI-помощник
-
-Интеграция с LLM для помощи при создании тестов:
-
-| Функция | Описание |
-|---------|----------|
-| Генерация теста | AI генерирует готовый набор вопросов с вариантами ответов по теме |
-| Улучшение формулировки | AI переформулирует выбранный вопрос более чётко |
-| Добавление дистракторов | AI генерирует правдоподобные неправильные варианты ответов |
-| Проверка качества | AI анализирует весь тест и выдаёт рекомендации |
-
---
-
-## Роли и права доступа
-
-| Роль | Кто | Создаёт тесты | Назначает тесты | Видит результаты |
-|------|-----|:---:|:---:|:---:|
-| **HR-менеджер** | Руководитель службы HR, Директор клиники | ✅ | Всем сотрудникам клиники | Всех сотрудников |
-| **Руководитель подразделения** | Главный врач, рук. службы администраторов | ✅ | Только своему подразделению | Только своего подразделения |
-| **Сотрудник** | Все остальные работники | ❌ | ❌ | Только свои |
+| Спринт | Что включает |
+|---|---|
+| **E1.4** — Назначение и прохождение | Назначить тест сотруднику, экран прохождения, экран результата с разбором ошибок. |
+| **E1.5** — Трекер и настройки модуля | Единый список попыток с фильтрами, страница настроек цепочки. |
+| **E1.6** — Cutover внутри репозитория | Удаление `backend/` и `frontend/`, чистка `docker-compose.dev.yml` от legacy-сервисов. |
+| **E1.7** — UX-полировка редактора | 4 аккордеона (Шапка / AI / Вопросы / Действия) и drag-n-drop из [Спринта 3](docs/СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md). |

 ---

 ## Установка и запуск

-### База данных (как в HR_TG_Bot / Postgres_TG_Bots)
+### Предпосылка: общий Postgres

-Используется **тот же** экземпляр PostgreSQL, что и в [Postgres_TG_Bots](../Postgres_TG_Bots) (`docker-compose.dev.yml`, контейнер `hr_postgres_dev`, учётка `hr_bot_user` / сеть `hr_postgres_dev_net` — см. [HR_TG_Bot docker-compose](../HR_TG_Bot/docker-compose.dev.yml)).
+Используется **тот же** PostgreSQL, что и в
+[Postgres_TG_Bots](../Postgres_TG_Bots) (контейнер `hr_postgres_dev`,
+сеть `hr_postgres_dev_net`, учётка `hr_bot_user`).

-Схема приложения (таблицы `users`, `tests`, `departments`, …) **не** совмещается с БД `hr_bot_test` — для TestingWebApp заведена отдельная база **`clinic_tests`**.
+```bash
+# (один раз) создать базу
+psql "postgresql://hr_bot_user:hrbot123@localhost:5432/postgres" \
+  -c "CREATE DATABASE clinic_tests;"

-1. Поднять Postgres из `Postgres_TG_Bots` (и при необходимости внешнюю сеть: `docker network create hr_postgres_dev_net` — как в compose этих репозиториев).
-2. Один раз создать базу:  
-   `psql "postgresql://hr_bot_user:hrbot123@localhost:5432/postgres" -c "CREATE DATABASE clinic_tests;"`
-3. Скопировать `backend/.env.example` в `backend/.env`, при необходимости поправить `DATABASE_URL` (внутри Docker кластера — хост `hr_postgres_dev`, порт `5432`).
-4. Миграции: из каталога `backend/`: `npm run migrate`, затем `npm start` (и фронт из `frontend/` — `npm run dev`).
+# (один раз) внешняя сеть, если ещё не создана соседом
+docker network create hr_postgres_dev_net || true
+```

-**Docker (UI + API + общий Postgres):** поднять `Postgres_TG_Bots` (сеть `hr_postgres_dev_net`), создать БД `clinic_tests`, затем из корня `TestingWebApp`:  
-`docker compose -f docker-compose.dev.yml up --build` — интерфейс **http://localhost:3107** (Nginx проксирует `/api` в backend), API с хоста **http://localhost:3001** (см. [docker-compose.dev.yml](docker-compose.dev.yml), миграции в entrypoint). **Новый Flask-контур** (тот же стек, что кабинет HR): **http://localhost:3108** — сервис `testing-flask`, см. [flask_app/README.md](flask_app/README.md). Локальный `npm run dev` фронта (Vite) — тоже **:3107**, прокси `/api` на **:3001**. В БД `clinic_tests` для локального логина нужен активный `users` с bcrypt-паролем, либо включите `HR_AUTH=1` + `HR_DATABASE_URL` в compose/`.env` (см. `backend/.env.example`). В `backend/.env` задайте `PORT=3001`, если поднимаете API отдельно от compose.
+### Dev-стенд

-`docker compose -f docker-compose.dev.yml down` — остановка.
+Выбор интерфейса задаётся через env-переменную `COMPOSE_PROFILES`:

-**Без общего кластера** (только отладка): `docker compose --profile standalone up -d` в TestingWebApp — Postgres на **5433**, тогда в `.env` укажите `DATABASE_URL=...localhost:5433/clinic_tests` или `DB_PORT=5433` с `DB_NAME`/`DB_USER` из compose.
+- `modern` — основной интерфейс на Flask/Jinja;
+- `legacy` — legacy-раскладка интерфейса на том же Flask-стеке.

-**Если `npm run migrate` пишет `ECONNREFUSED ...:5433`:** в `backend/.env` нет (или кривой) `DATABASE_URL` на **5432**, и сработал старый `DB_PORT=5433`. Задайте `DATABASE_URL` как в `backend/.env.example` для общего Postgres.
+```bash
+# Новый стек (рекомендуется)
+COMPOSE_PROFILES=modern docker compose -f docker-compose.dev.yml up -d --build

-### Данные, сотрудники, интеграция с HR
+# Legacy-раскладка (тот же Flask)
+COMPOSE_PROFILES=legacy docker compose -f docker-compose.dev.yml up -d --build
+```

- **Две роли кластера Postgres:** в **`clinic_tests`** — только сущности модуля тестирования (тесты, версии, назначения, попытки, локальные технические учётки при необходимости). В **`hr_bot_test`** (Postgres_TG_Bots / hr_web_viewer) — штат, справочники, существующий **RBAC** и веб-логины. Так мы не смешиваем схемы и не дублируем «источник правды» по людям.
- **Сотрудник в процессах** (назначения, дашборды, доступ к результатам) — везде по **`staff_members.id`**. Ссылки в `clinic_tests` храним как **тот же идентификатор** (логическая связь с `staff_members` в `hr_bot_test`); **ФИО, отдел, роли** подтягиваем из HR при отображении или кэшируем по согласованной политике, а не ведём второй кадровый учёт.
- **`telegram_id`** в данных сотрудника **не участвует** в бизнес-логике модуля: ни вход, ни проверка прав, ни выбор сотрудника в сценариях, ни фильтрация — только **справочная** информация при необходимости (отображение, история).
- **RBAC в перспективе:** единая система разрешений — та, что уже в HR (роли, `staff_role_assignments`, permissions). Модуль тестирования **не** развивает отдельную полную копию матрицы; проверка действий в целевом виде — через **HR** (внутренний API / токен / согласованные запросы к БД). Пока договор и API не готовы — допустимы временные флаги в `clinic_tests`, явно помечаемые как MVP.
+| Что | URL |
+|---|---|
+| Приложение (Flask modern) | <http://localhost:3108> |
+| Health-check | <http://localhost:3108/health> |
+| Приложение (Flask legacy) | <http://localhost:3107> |

-Детализация задач и варианты A.x: [docs/revision_task/card1.md](docs/revision_task/card1.md).
+`docker-compose.dev.yml` пробрасывает в `testing-flask`:
+- `DATABASE_URL` (по умолчанию на контейнерный Postgres `clinic_tests`);
+- `HR_AUTH=1` / `HR_DATABASE_URL` по умолчанию — вход через HR-кабинет;
+- `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` —
+  для AI-функций. Достаточно положить ключ в корневой `.env` репозитория.
+
+### Локально без Docker
+
+См. [`flask_app/README.md`](flask_app/README.md) — `venv` +
+`pip install -r requirements.txt` + `python run.py`.
+
+---
+
+## Данные и интеграция с HR
+
+- **Две роли кластера Postgres.** В **`clinic_tests`** — только сущности
+  модуля тестирования (тесты, версии, назначения, попытки, локальные
+  технические учётки). В **`hr_bot_test`** (Postgres_TG_Bots /
+  hr_web_viewer) — штат, справочники, RBAC и веб-логины. Схемы не
+  смешиваем, второй кадровый учёт в `clinic_tests` не ведём.
+- **Сотрудник** во всех бизнес-процессах — по
+  **`staff_members.id`** из `hr_bot_test`. В `clinic_tests` храним тот же
+  идентификатор; ФИО / отдел / роли подтягиваем из HR при отображении.
+- **`telegram_id` сотрудника** в бизнес-логике модуля **не участвует**
+  (ни вход, ни проверка прав, ни выбор сотрудника, ни фильтрация).
+- **Целевой RBAC** — единая система разрешений HR
+  (`staff_role_assignments`, `permissions`). Модуль тестирования
+  не дублирует матрицу; пока единый API не готов — в `clinic_tests`
+  допустимы временные флаги, явно помеченные как MVP.
+- **`HR_AUTH=1`**: в Flask-контуре включает вход через `hr_bot_test.users`
+  (Werkzeug-хеши) с UPSERT в `clinic_tests.users`. См.
+  [`flask_app/.env.example`](flask_app/.env.example).
+
+---
+
+## Роли и права (по ТЗ)
+
+| Роль | Кто | Создаёт тесты | Назначает | Видит результаты |
+|---|---|:---:|:---:|:---:|
+| **HR-менеджер** | Руководитель HR, директор | ✅ | Всем | Всех |
+| **Руководитель подразделения** | Главврач, рук. отделения | ✅ | Только своему подразделению | Только своего подразделения |
+| **Сотрудник** | Все остальные | ❌ | ❌ | Только свои |
+
+> На текущем Flask-контуре (E1.0–E1.3, E1.8) проверяется только
+> `@login_required`; разделение по ролям задействуется на E1.4–E1.5.

 ---

 ## Нефункциональные требования

 | Параметр | Значение |
-|----------|----------|
+|---|---|
 | Количество пользователей | 50–200 человек |
-| Платформа | Веб-приложение, браузер (desktop-first) |
+| Платформа | Веб, браузер; mobile-friendly |
 | Доступность | Внутренняя сеть клиники |
 | Язык интерфейса | Русский |
 | Время отклика | < 2 секунды |

+## Вне scope (в текущей версии не делаем)
+
+- Интеграция с AD / LDAP.
+- Нативное мобильное приложение.
+- Вопросы с вложениями (картинки, видео).
+- Экспорт отчётов в Excel / PDF.
+- Уведомления в MAX (отдельный спринт).
+
 ---

-## Вне scope (не реализуется в данной версии)
+## Документация

- Интеграция с AD/LDAP
- Мобильное приложение
- Вопросы с вложениями (изображения, видео)
- Экспорт отчётов в Excel / PDF
- Уведомления в MAX (отдельный спринт)
+| Файл | О чём |
+|---|---|
+| [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) | Что работает «прямо сейчас», что в работе, что в бэклоге. |
+| [`docs/migration-final.md`](docs/migration-final.md) | Главный трекер миграции: спринты Этапа 1, журнал, критерии готовности. |
+| [`docs/migration-final-inventory.md`](docs/migration-final-inventory.md) | Карта 22 эндпоинтов Express + gap-analysis с `tgFlaskForm`. |
+| [`docs/migration-to-tgflaskform.md`](docs/migration-to-tgflaskform.md) | План Этапа 2 (слияние с HR-кабинетом). |
+| [`docs/QA-versioning-and-ai.md`](docs/QA-versioning-and-ai.md) | Инструкция для тестировщика — только через сайт. |
+| [`docs/СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md`](docs/СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md) | Целевой мобильный UX редактора (база для E1.7). |
+| [`docs/РУКОВОДСТВО_КАБИНЕТ_ТЕСТОВ.md`](docs/РУКОВОДСТВО_КАБИНЕТ_ТЕСТОВ.md) | Кратко для врачей-кураторов. |
+| [`flask_app/README.md`](flask_app/README.md) | Конкретные команды для нового контура. |
+| [`docs/ТЗ.md`](docs/ТЗ.md) | Исходное ТЗ заказчика. |