# Состояние проекта

**Репозиторий:** [TestingWebApp](https://git.pirogov.ai/l_konstantin/TestingWebApp) · ветка разработки **`dev`**
**Прод:** **[https://edullm.pirogov.ai/](https://edullm.pirogov.ai/)**
**Дата среза:** 2026-04-28

Не дубль ТЗ, а карта «что реально работает в коде, на каком контуре,
и что логично сделать дальше».

---

## TL;DR

- Прод и dev работают **только на Flask-контуре** (`flask_app/`,
  Python 3.11 + Flask 3 + Jinja2 + Tailwind CDN + SQLAlchemy).
- Каталоги `backend/` (Express) и `frontend/` (React) — архив, не
  разворачиваются и не используются; удаление запланировано в
  спринте **E1.6**.
- БД — **`clinic_tests`** (PostgreSQL). Схема в Этапе 1 не меняется.
- Этап 2 (слияние с `HR_TG_Bot/tgFlaskForm`) пока не делаем —
  [`migration-to-tgflaskform.md`](migration-to-tgflaskform.md).

Главный трекер по спринтам — [`migration-final.md`](migration-final.md).

---

## Что уже работает на новом контуре (E1.0–E1.3, E1.8)

### Вход
- `/login` (форма) и `/api/auth/login` (JSON), `/api/auth/logout`,
  `/api/auth/me`.
- По умолчанию — bcrypt-хеши из `clinic_tests.users`.
- `HR_AUTH=1` + `HR_DATABASE_URL` — вход через `hr_bot_test.users`
  (Werkzeug); запись синхронизируется в `clinic_tests.users` UPSERT-ом по
  `staff_id`. Сценарий «пользователь без `staff_id`» — пропускается с
  предупреждением в логах.

### Каталог тестов (`/tests`)
- Видны цепочки, где вы автор, и активные публичные.
- Создание теста через модалку («Название» + «Описание»).
- Кнопка «Скрыть» / «Вернуть» работает на цепочку целиком.

### Редактор теста (`/tests/<id>/edit`)
- Поля шапки: название, описание, проходной балл, переключатель
  «Цепочка активна».
- Вопросы и варианты: добавить / удалить / переместить, отметить верные.
- **Версионирование.** Пока по цепочке нет завершённых попыток —
  правки идут «на месте». После первой попытки любое содержательное
  сохранение делает форк (`version + 1`, `parent_id` = прежняя),
  старая версия остаётся в БД и не видна в каталоге.
- Подробная модель поведения и проверочные сценарии —
  [`QA-versioning-and-ai.md`](QA-versioning-and-ai.md).

### AI-помощник в редакторе
| Кнопка | Что делает |
|---|---|
| По названию | Генерирует весь набор вопросов по теме. Параметры — кол-во вопросов и вариантов. |
| По текущей сетке | Дописывает варианты для уже расставленных карточек. |
| Проверить | Рецензирует тест: вердикт + блоки рекомендаций. |
| Улучшить | «Было → стало» по каждому вопросу/варианту с чекбоксами. |
| AI: вопрос | На карточке вопроса — переформулировка / генерация дистракторов. |

При отсутствии ключа — единая ошибка с ссылкой на `/settings`.

### Импорт документа
- PDF / DOCX / TXT / MD до 16 МБ.
- `pypdf` для PDF, `python-docx` для DOCX, плоский текст — как есть.
- Извлечённый текст идёт в LLM, на выходе — черновик теста, который
  открывается в редакторе.

### Настройки (`/settings`)
- Статус общего LLM-ключа (берётся из ENV: `DEEPSEEK_API_KEY` →
  `OPENAI_API_KEY`).
- Провайдер, модель, base URL.
- Кнопка «Проверить подключение» — пинг `/v1/chat/completions` через
  `ping_llm()`.
- Ключ на клиента не уходит и в БД не пишется.

---

## Чего на Flask пока нет

Эти сценарии будут реализованы в E1.4–E1.5. До этого в приложении они
просто отсутствуют (старый Express-контур не используется и не
поднимается):

- **Назначение теста сотруднику** — поиск по справочнику, «Выбрать
  всех», фильтры по подразделениям.
- **Прохождение** — экран вопросов, таймер, сохранение попытки.
- **Результат и разбор ошибок** — отдельная страница с ответами
  пользователя и правильными вариантами.
- **Трекер попыток** — единый список завершённых попыток с фильтрами
  (подразделение / сотрудник / тест / статус / результат).

---

## Что в работе и в планах

### Этап 1 — паритет внутри TestingWebApp

| Спринт | Содержание | Статус |
|---|---|---|
| E1.0 | База Flask-приложения (БД-пул, сессии, `base.html`). | ✅ |
| E1.1 | Auth + `/api/me` (bcrypt + Werkzeug, опц. `HR_AUTH`). | ✅ |
| E1.2 | Каталог тестов и редактор (функциональный минимум). | ✅ |
| E1.3 | Импорт документов (PDF / DOCX / TXT / MD). | ✅ |
| E1.4 | Назначения и прохождение тестов. | ⬜ Следующий. |
| E1.5 | Трекер попыток + страница настроек цепочки. | ⬜ |
| E1.6 | Cutover внутри репозитория (удаление `backend/` + `frontend/`). | ⬜ |
| E1.7 | UX-полировка редактора: 4 аккордеона + drag-n-drop. | ⬜ |
| E1.8 | AI-функции v2 (`/settings`, generate-by-title, check, improve). | ✅ |

Подробности — [`migration-final.md`](migration-final.md).

### Этап 2 — слияние с HR-кабинетом (на будущее)

- Перенос blueprint'ом в `HR_TG_Bot/tgFlaskForm` под путь
  `/cabinet/testing`.
- ETL `clinic_tests → hr_bot_test`. Скрипт-заготовка:
  [`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`).
- Авторизация — через сессию HR-кабинета.
- Подробности и риски — [`migration-to-tgflaskform.md`](migration-to-tgflaskform.md)
  (и [простыми словами](migration-to-tgflaskform-plain.md)).

### Долгий бэклог

| Направление | Суть |
|---|---|
| Дашборды (ТЗ этап 2) | Единая картина по отделу / клинике, фильтры, история. |
| MAX / мини-приложение | Встраивание в общий HR-контур клиники. |
| Таймер, подсказки, медиа в вопросах | Режимы прохождения и вложения — отдельные этапы ТЗ. |
| E2E и интеграционные тесты | Расширение `V.9`, стабильный CI. |
| Назначения по отделу | Сроки, лимит попыток, групповые назначения. |

---

## Связанные документы

- [README репозитория](../README.md)
- [Главный трекер миграции — `migration-final.md`](migration-final.md)
- [Карта Express + gap-analysis с `tgFlaskForm` — `migration-final-inventory.md`](migration-final-inventory.md)
- [План Этапа 2 — `migration-to-tgflaskform.md`](migration-to-tgflaskform.md)
- [Инструкция тестировщику — `QA-versioning-and-ai.md`](QA-versioning-and-ai.md)
- [Спринты мобильного UX редактора](СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md)
- [Кратко для врачей-кураторов](РУКОВОДСТВО_КАБИНЕТ_ТЕСТОВ.md)
- [Руководство по dev-контуру](DEV_CONTOUR_USER_GUIDE.md)
- [ТЗ заказчика](ТЗ.md)