Константин Лебединский
201 lines
12 KiB
Markdown
201 lines
12 KiB
Markdown
# Система тестирования сотрудников клиники
|
||
|
||
Веб-приложение для проведения внутреннего тестирования сотрудников клиники.
|
||
Руководители подразделений и HR-менеджеры создают тесты и назначают их
|
||
сотрудникам. Все попытки и результаты сохраняются.
|
||
|
||
- **Прод:** **[https://edullm.pirogov.ai/](https://edullm.pirogov.ai/)**
|
||
- **Ветка разработки:** `dev`
|
||
- **ТЗ:** v1.2 от 2026-03-21 (статус — согласовано)
|
||
|
||
---
|
||
|
||
## Стек и состояние
|
||
|
||
**Целевой и единственный рабочий стек** — Python 3.11 + Flask 3 +
|
||
Jinja2 + Tailwind CDN + SQLAlchemy / psycopg2, код в
|
||
[`flask_app/`](flask_app/). На нём работает и прод, и dev (кабинетный UI,
|
||
порт **:3107** в Docker, см. ниже).
|
||
|
||
Старые каталоги `backend/` (Node.js / Express) и `frontend/`
|
||
(React + Vite) — **архив**: не разворачиваются, в `docker-compose.dev.yml`
|
||
поднимается сервис **`testing-flask`**, удаление папок запланировано
|
||
в спринте **E1.6**. Использовать их не надо, миграции и SQL-схема
|
||
сохранены в `backend/src/db/migrations/` исключительно как источник
|
||
структуры БД.
|
||
|
||
БД — **`clinic_tests`** (PostgreSQL, UUID-ключи). В Этапе 1 схема
|
||
не меняется.
|
||
|
||
**Этап 2** — слияние с общим HR-кабинетом `HR_TG_Bot/tgFlaskForm` —
|
||
запланирован на будущее, сейчас не делается. План:
|
||
[`docs/migration-to-tgflaskform.md`](docs/migration-to-tgflaskform.md)
|
||
([простыми словами](docs/migration-to-tgflaskform-plain.md)).
|
||
|
||
---
|
||
|
||
## Интерфейс (кабинет)
|
||
|
||
Единственный вариант UI — **как у основного HR-веба**: в
|
||
[`base.html`](flask_app/app/templates/base.html) корень
|
||
`cabinet-app` → шапка `cabinet-header` → контент `cabinet-main`; на
|
||
`<body>` всегда класс **`ui-legacy`**, стили в [`app.css`](flask_app/app/static/css/app.css)
|
||
с префиксом **`body.ui-legacy`** (primary/teal, `.btn`, `.surface-card`,
|
||
`legacy-list-shell`, `test-detail-page` и т.д.).
|
||
|
||
В [`docker-compose.dev.yml`](docker-compose.dev.yml) один сервис
|
||
**`testing-flask`** (`container_name: testing_webapp_flask`), порт **3107**.
|
||
|
||
---
|
||
|
||
## Что уже работает на новом (Flask) контуре
|
||
|
||
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).
|
||
|
||
## Что ещё не реализовано
|
||
|
||
| Спринт | Что включает |
|
||
|---|---|
|
||
| **E1.4** — Назначение и прохождение | Назначить тест сотруднику, экран прохождения, экран результата с разбором ошибок. |
|
||
| **E1.5** — Трекер и настройки модуля | Единый список попыток с фильтрами, страница настроек цепочки. |
|
||
| **E1.6** — Cutover внутри репозитория | Удаление `backend/` и `frontend/`, чистка `docker-compose.dev.yml` от архивных Node/React-сервисов. |
|
||
| **E1.7** — UX-полировка редактора | 4 аккордеона (Шапка / AI / Вопросы / Действия) и drag-n-drop из [Спринта 3](docs/СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md). |
|
||
|
||
---
|
||
|
||
## Установка и запуск
|
||
|
||
### Предпосылка: общий Postgres
|
||
|
||
Используется **тот же** PostgreSQL, что и в
|
||
[Postgres_TG_Bots](../Postgres_TG_Bots) (контейнер `hr_postgres_dev`,
|
||
сеть `hr_postgres_dev_net`, учётка `hr_bot_user`).
|
||
|
||
```bash
|
||
# (один раз) создать базу
|
||
psql "postgresql://hr_bot_user:hrbot123@localhost:5432/postgres" \
|
||
-c "CREATE DATABASE clinic_tests;"
|
||
|
||
# (один раз) внешняя сеть, если ещё не создана соседом
|
||
docker network create hr_postgres_dev_net || true
|
||
```
|
||
|
||
### Dev-стенд
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up -d --build
|
||
```
|
||
|
||
| Что | URL |
|
||
|---|---|
|
||
| Приложение (Flask) | <http://localhost:3107> |
|
||
| Health-check | <http://localhost:3107/health> |
|
||
|
||
`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 человек |
|
||
| Платформа | Веб, браузер; mobile-friendly |
|
||
| Доступность | Внутренняя сеть клиники |
|
||
| Язык интерфейса | Русский |
|
||
| Время отклика | < 2 секунды |
|
||
|
||
## Вне 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) | Исходное ТЗ заказчика. |
|