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

docs/PROJECT_STATUS.md

@@ -1,78 +1,148 @@
-# Состояние проекта (человеческий обзор)
+# Состояние проекта
 
-**Репозиторий:** [TestingWebApp](https://git.pirogov.ai/l_konstantin/TestingWebApp) · ветка разработки: **`dev`**  
-**Дата среза:** 2026-04-24
+**Репозиторий:** [TestingWebApp](https://git.pirogov.ai/l_konstantin/TestingWebApp) · ветка разработки **`dev`**
+**Прод:** **[https://edullm.pirogov.ai/](https://edullm.pirogov.ai/)**
+**Дата среза:** 2026-04-28
 
-Этот документ — не дублирование ТЗ, а **короткое объяснение**, что уже работает в коде и что логично делать дальше. Подробные задачи: [revision_task/card1.md](revision_task/card1.md), [revision_task/BACKLOG.md](revision_task/BACKLOG.md).
+Не дубль ТЗ, а карта «что реально работает в коде, на каком контуре,
+и что логично сделать дальше».
 
 ---
 
-## Что уже сделано (как это устроено)
+## 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).
 
-- Сотрудник входит по **логину и паролю** (сессия через cookie + JWT).
-- В шапке показываются **роль** и **Фамилия с инициалами** (например, *Иванов И. О.*), полное ФИО — во всплывающей подсказке.
-- В **режиме разработки** (`NODE_ENV=development`) у удобного тестирования могут быть дополнительные кнопки (например, создание теста сотрудником — `devUi` в ответе `/api/auth/me`).
-
-### «Цепочка» теста и черновики
-
-- У каждого теста есть **одна логическая цепочка** в базе: все правки вопросов относятся к ней, но **версия контента** (`v1`, `v2`, …) может расти.
-- **Пока никто не проходил** этот тест — автор правит **на месте**: сохраняет черновик, и меняется текущая активная версия **без** лишнего дублирования строк в истории.
-- **Как только по цепочке появилась хотя бы одна завершённая попытка** — каждое **содержательное** сохранение с изменениями создаёт **новую версию** (новый номер, старая остаётся в истории). Старые результаты остаются привязаны к **той** версии, с которой человек реально отвечал.
-- **Активная версия** — та, с которой сейчас стартуют новые попытки. Автор может **вручную** переключить активную версию в таблице истории (с подтверждением), если бизнесу так нужно.
-- **Публикация / видимость:** в кабинете (аккордеон **«Показ в каталоге»**, подсекция **«Видимость»**) тест можно **скрыть из общего списка** (цепочка остаётся в базе) или **снова показать**; **назначения** (подсекция **«Кому выдать»**) — при включённой фиче, см. раздел «Назначения» ниже.
-- **Мобильный UI** кабинета (колонка списка на узком экране, фикс-футер, группировка разделов, копи): [СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md](СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md) · [РУКОВОДСТВО_КАБИНЕТ_ТЕСТОВ.md](РУКОВОДСТВО_КАБИНЕТ_ТЕСТОВ.md) (тезисы для врачей/кураторов).
-- **Унификация стека (Этап 1, текущий)**: Express → Flask + React → Jinja **внутри TestingWebApp** (`flask_app/`). БД остаётся `clinic_tests`, схема не меняется. План и журнал — [migration-final.md](migration-final.md).
-- **Слияние с HR-кабинетом (Этап 2, на будущее, без сроков)**: перенос в `HR_TG_Bot/tgFlaskForm` как blueprint `cabinet/testing`, ETL `clinic_tests → hr_bot_test`. План — [migration-to-tgflaskform.md](migration-to-tgflaskform.md). Карта Express-функционала и справочный gap-analysis с уже существующим модулем HR-кабинета — [migration-final-inventory.md](migration-final-inventory.md).
-
-### Список тестов и доступ
-
-- В каталоге **«Тесты»** видны цепочки, где вы **автор**, и тесты, **назначенные вам** (через назначение на пользователя; в dev назначения обычно **включены**).
-- Под названием показывается **«Автор: Вы»** для своих тестов и **«Автор: Фамилия И. О.»** для чужих (назначенных).
-- **Пройти** тест — кнопка **справа** в строке; **карточка** теста — клик по названию **слева** (попытка с карточки не стартует сама).
-
-### Прохождение и результат
-
-- Открывается экран вопросов (один или несколько верных вариантов); после **«Завершить тест»** — итог: сколько верно, процент, **зачёт** по порогу.
-- **Разбор:** после сдачи показывается, по **каждому вопросу**, что выбрал пользователь и какие варианты верны. Отдельная страница разбора доступна по ссылке; **автор** в аккордеоне **«История»** (подсекция **«Прохождения»**) видит **завершённые** попытки и кнопку **«Разбор»** (раньше секция называлась **«Прогоны и разбор»**).
-
-### Импорт и ИИ (MVP)
-
-- Можно загрузить **файл** (PDF, DOCX, текст): сервер **извлекает текст** и при настроенном ключе **LLM** (например, `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` в окружении) предлагает **черновик** вопросов. В UI: подсекция **«Документ в вопросы»** внутри **«Вопросы»** (раньше — отдельный блок «Импорт из файла»). Дальше тот же поток, что и при ручном редактировании: правки → **сохранить черновик** (с учётом правил версий выше).
-- **Полный** набор сценариев из ТЗ (отдельная страница настроек ключа, «проверить тест целиком», модалки с чекбоксами и т.д.) — в [sprint-02](revision_task/sprint-02.md); часть уже заложена в сервисах, UI доводится.
-
-### Назначения (MVP)
-
-- **Автор** в **«Показ в каталоге»** → **«Кому выдать»** может **назначить** сотрудников из справочника (поиск, фильтры, **«Выбрать всех»** в текущем списке; в dev — при включённой фиче в `docker-compose` / `.env`). Назначение **не** перепривязывается автоматически к каждой новой версии контента: **старт попытки** всегда берёт **текущую активную** версию на момент нажатия **«Пройти»**.
-
-### Интеграция с HR (в зачатке)
-
-- Поддержан сценарий **входа через учётки HR** (`HR_AUTH` + `HR_DATABASE_URL`) для проверок на одном кластере Postgres с экосистемой `Postgres_TG_Bots` (см. [README — установка](../README.md)).  
-- Целевой **RBAC** из HR-таблиц — [card1, часть A](revision_task/card1.md#часть-a--авторизация-по-паролю-бд-postgres_tg_bots); сейчас — упрощённое сопоставление ролей.
+Главный трекер по спринтам — [`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)).
+
+### Долгий бэклог
 
 | Направление | Суть |
-|-------------|------|
-| **AI по ТЗ §4.2** | Ключ в настройках (не на клиенте), кнопки «сгенерировать/проверить/улучшить» с превью и подтверждением, регресс с версиями. |
-| **Дашборды (ТЗ этап 2)** | Единая картина по отделу / клинике, фильтры, история. |
-| **MAX / мини-приложение** | Встраивание в общий HR-контур клиники. |
-| **Таймер, подсказки, медиа в вопросах** | Режимы прохождения и вложения — отдельные этапы ТЗ. |
-| **E2E и интеграционные тесты** | Расширение `V.9`, стабильный CI. |
-| **Назначения** | Сроки, лимит попыток, назначения «по отделу» (частично в бэклоге [BACKLOG_IDEAS](revision_task/BACKLOG_IDEAS.md)). |
-
-Журнал приёмок и чек-листы: [TESTING_JOURNAL.md](revision_task/TESTING_JOURNAL.md).
+|---|---|
+| Дашборды (ТЗ этап 2) | Единая картина по отделу / клинике, фильтры, история. |
+| MAX / мини-приложение | Встраивание в общий HR-контур клиники. |
+| Таймер, подсказки, медиа в вопросах | Режимы прохождения и вложения — отдельные этапы ТЗ. |
+| E2E и интеграционные тесты | Расширение `V.9`, стабильный CI. |
+| Назначения по отделу | Сроки, лимит попыток, групповые назначения. |
 
 ---
 
-## Связанные файлы
+## Связанные документы
 
-- [Руководство пользователя dev-контура](DEV_CONTOUR_USER_GUIDE.md)
-- [Руководство кабинета (простыми словами)](РУКОВОДСТВО_КАБИНЕТ_ТЕСТОВ.md)
-- [Спринты: мобильный UI](СПРИНТЫ_МОБИЛЬНЫЙ_ДИЗАЙН.md)
-- [Предложение по дизайну (ист. + актуализация)](ПРЕДЛОЖЕНИЕ_ДИЗАЙН_СОЗДАНИЕ_ТЕСТА.md)
-- [README с установкой](../README.md)
-- [Карта задач card1](revision_task/card1.md)
+- [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)

docs/UX_аудит_и_новая_IA_—_страница_теста.md

@@ -0,0 +1,340 @@
+# UX-аудит страницы теста и предложение новой информационной архитектуры
+
+**Продукт:** HR system — модуль тестирования
+**Платформа:** Цифровые сервисы клиники им. Е. Н. Оленевой
+**Объект анализа:** страница `/tests/{id}` — создание/редактирование теста
+**Дата:** 29 апреля 2026
+
+---
+
+## Краткая сводка
+
+Текущая страница `/tests/{id}` совмещает три разные пользовательские задачи в одном экране:
+
+1. **Авторскую** — придумать и оформить тест (название, описание, вопросы, варианты).
+2. **Управленческую** — назначить тест 1–N сотрудникам.
+3. **Аналитическую** — посмотреть, кто из сотрудников и какие версии проходил.
+
+Эти задачи различаются по ролям, частоте, объёму данных и контексту. Сейчас они смешаны в одном длинном аккордеоне, что приводит к ряду проблем — от потери изменений до невозможности масштабировать список аудитории за пределы 100–200 человек.
+
+Документ состоит из двух частей:
+
+- **Часть 1** — аудит текущей страницы с приоритизированными проблемами (critical / major / minor) и ссылками на скриншоты.
+- **Часть 2** — предложение новой IA с раздельными разделами «Тесты», «Назначения», «Отчёты», ролевой моделью и описанием жизненного цикла версии теста.
+
+---
+
+# Часть 1. Аудит текущей страницы
+
+Все скриншоты сделаны 29.04.2026 на странице `https://edullm.pirogov.ai/tests/298a64af-...` под ролью `employee` (см. п. M-3).
+
+## 1.1. Шапка, заголовок и баннер версионирования
+
+![Шапка и баннер](screens/01_header_intro.jpg)
+
+Что мы видим: глобальная шапка «Тестирование», подпись пользователя `Разорвин А. М. · employee`, кнопка «Выйти». Ниже — хлебная крошка «← к списку», название теста, автор, дата обновления, **жёлтый баннер «При сохранении будет создана новая версия теста.»** и схлопнутый аккордеон «О тесте».
+
+Замечания:
+
+- **C-1 [critical] Баннер о новой версии показывается ВСЕГДА**, независимо от того, изменил ли пользователь хоть что-то. Это сбивает с толку: автор открывает существующий тест, ничего не трогает — и думает, что версия уже создана. Должен показываться только при наличии несохранённых изменений (dirty state).
+- **m-2 [minor] Роль `employee` написана по-английски** в шапке. В русском интерфейсе должно быть «сотрудник» / «автор» / другое (см. ролевую модель в Части 2).
+- **m-3 [minor] Опечатка** в `<title>` вкладки: «Система тестирования» (нет «и»). Влияет на закладки, историю, поиск.
+
+---
+
+## 1.2. Секция «О тесте»
+
+![О тесте раскрытый](screens/02_about_test.jpg)
+
+Замечания:
+
+- **M-1 [major] Аккордеон по умолчанию схлопнут.** Чтобы начать редактировать главный объект страницы (вопросы), нужно сделать лишний клик. На странице редактирования теста раздел «Вопросы» (а возможно, и «О тесте») должен быть открыт по умолчанию.
+- **M-2 [major] Поле «Порог зачёта, %» не имеет валидации min/max.** Что произойдёт при вводе 0, 100, 150, –5, 70.5, или вообще буквы? Минимум: подсказка «от 1 до 100», атрибуты `min/max/step` на input, инлайн-ошибка при некорректном вводе.
+
+---
+
+## 1.3. Раздел «Вопросы» — генерация и Вопрос 1
+
+![Генерация и Вопрос 1](screens/03_questions_top.jpg)
+
+Что мы видим: блок **«Генерация сетки вопросов (ИИ)»** с полями «Тема», «Вопросов: 7», «Вариантов: 3» и кнопкой «Сгенерировать тест (ИИ)». Ниже — Вопрос 1 с собственной кнопкой «Сгенерировать вопрос (ИИ)» в правом верхнем углу, чекбоксом «Несколько верных ответов», тремя вариантами с радиокнопками и крестиками «удалить».
+
+Замечания:
+
+- **C-2 [critical] ИИ-генерация без подтверждения и без отображения хода работы.** Кнопка «Сгенерировать тест (ИИ)» одной нажатием перезаписывает существующие вопросы — а они уже могут быть наполовину написаны вручную. То же касается кнопки «Сгенерировать вопрос (ИИ)» рядом с уже заполненным вопросом.
+  - Нужно: confirm-диалог «Заменить текущие N вопросов?», индикатор прогресса генерации, возможность откатить (undo) последний результат генерации.
+- **M-3 [major] Чекбокс «Несколько верных ответов» меняет семантику варианта без явного намёка.** Когда выкл — радиокнопки (один верный), когда вкл — должны стать чекбоксами (несколько). Лучше переписать подпись в зависимости от состояния: «один верный» / «несколько верных», и/или показать рядом подсказку, как изменится контрол.
+
+---
+
+## 1.4. Вопросы 3–5
+
+![Вопросы 3-5](screens/04_questions_mid.jpg)
+
+Замечания:
+
+- **M-4 [major] Нет нумерации/перетаскивания вопросов.** «Вопрос 1, 2, 3…» — порядок фиксирован тем, в каком порядке добавляли. Для длинных тестов нужен drag-handle или хотя бы стрелки «вверх / вниз».
+- **M-5 [major] «Удалить вопрос» без подтверждения.** Случайный клик уничтожит написанный вопрос. Минимум — confirm-диалог; лучше — undo-toast «Вопрос удалён · Отменить».
+- **m-4 [minor] Маленькая видимая «вода» между вопросами.** Карточки вопросов мало отделены друг от друга визуально, при пролистывании они сливаются в стену форм. Стоит увеличить вертикальный отступ между карточками или добавить разделитель.
+
+---
+
+## 1.5. Вопрос 7 — обрыв длинного варианта
+
+![Q7 с обрезанным вариантом + загрузка файла](screens/05_questions_bottom.jpg)
+
+Это один из самых наглядных багов:
+
+- **M-6 [major] Длинный текст варианта обрезается.** В Q7 первый вариант отображается как «Максимальное количество токенов, которое модель может о…» — текст уходит за правый край однострочного `<input>`. Для содержательных тестов (особенно медицинских) ответы часто длинные. Нужно: либо `<textarea>` с автовысотой, либо горизонтальный скролл с tooltip всего текста на ховере.
+- **m-5 [minor] Загрузка файла «Документ в вопросы» — без drag-and-drop, без ограничений по размеру/формату на UI, без обратной связи.** Подсказка «PDF, Word или текст — вставьте в черновик вопросов» — хорошая по-человечески, но не объясняет, что произойдёт после загрузки: заменит ли существующие вопросы, добавит ли в конец, есть ли превью результата.
+
+---
+
+## 1.6. Кнопка «Сохранить черновик» в середине + История
+
+![Сохранить + История](screens/06_save_history.jpg)
+
+Здесь главная архитектурная проблема страницы:
+
+- **C-3 [critical] Кнопка «Сохранить черновик» расположена в середине страницы.** Сразу после неё ниже идут ещё две большие секции — «История» и «Показ в каталоге». Пользователь, открывший «Показ в каталоге» и поменявший там аудиторию, психологически ищет «Сохранить» внизу страницы — но там его нет. Очень высокий риск потерять изменения.
+  - Решения, любое или все: (а) sticky-панель сохранения внизу страницы; (б) дубль кнопки после последней секции; (в) автосохранение черновика; (г) предупреждение перед уходом со страницы при наличии несохранённых изменений.
+- **M-7 [major] Раздел «Прохождения» показывает сырые ENUM-значения.** Видно `v1 · in_progress` — это техническое значение, а не пользовательский текст. Должно быть «в процессе» / «пройдено» / «не пройдено», лучше с цветной плашкой-индикатором.
+- **M-8 [major] Дубль кнопки «К списку».** Хлебная крошка «← к списку» наверху + кнопка «К списку» рядом с «Сохранить черновик» — две точки выхода с разным визуальным весом. Кнопка справа от primary-кнопки создаёт ложное ощущение симметричности с действием. Оставить либо крошку, либо превратить вторую кнопку в текстовую ссылку «Отмена».
+
+---
+
+## 1.7. «Показ в каталоге» — Видимость и фильтры
+
+![Видимость](screens/07_catalog_visibility.jpg)
+
+- **M-9 [major] Контрол «Видимость» неясен по текущему состоянию.** Кнопка «Скрыть из списка» — это сейчас действие или текущее состояние? Если тест уже скрыт — кнопка должна называться «Показать в списке». Лучше — переключатель (toggle/switch) с подписью «Тест виден в каталоге», чтобы текущее состояние читалось без действий.
+- **m-6 [minor] Поле поиска и два селекта** «Все отделы» / «Все» расположены без подписей — что делает второй селект, без раскрытия не понятно. Нужны явные label или persistent placeholder.
+
+---
+
+## 1.8. Список «Кому выдать» — 147 сотрудников
+
+![Список сотрудников](screens/08_catalog_employees.jpg)
+
+Этот блок — корень главной IA-проблемы (см. Часть 2):
+
+- **C-4 [critical] Назначение тестов не должно жить на странице теста.** Это управленческая задача отдельной роли (HR-менеджер, руководитель отделения), а не авторская. Подробно — в Часть 2.
+- **M-10 [major] Список из 147 человек без виртуализации и счётчика выбранных.** Нужно как минимум: счётчик «выбрано N из 147», фильтр «только выбранные», сохранение выбранного при изменении фильтра, виртуальный скролл (на 1000+ сотрудников страница встанет колом).
+- **M-11 [major] «Назначить выбранных» внутри контейнера списка.** Кнопка стоит на нижней границе скролл-контейнера — её очень легко не заметить. И непонятно: «Назначить» — это отдельное действие или часть общего «Сохранить черновик» наверху?
+- **m-7 [minor] Подпись «нет учётки (создадим при назначении)»** — хорошая идея (ленивая выдача учёток), но требует пояснения: что значит «при назначении», что получит сотрудник после, как ему придёт первый пароль.
+
+---
+
+## 1.9. Сводная таблица замечаний
+
+| ID | Приоритет | Что | Место |
+|---|---|---|---|
+| C-1 | critical | Баннер «новая версия» виден всегда, не только при изменениях | 1.1 |
+| C-2 | critical | ИИ-генерация без confirm и без прогресса | 1.3 |
+| C-3 | critical | Кнопка «Сохранить» в середине страницы | 1.6 |
+| C-4 | critical | Назначение сотрудников не должно жить на странице теста | 1.8 |
+| M-1 | major | Аккордеоны схлопнуты по умолчанию, включая «Вопросы» | 1.2 |
+| M-2 | major | «Порог зачёта» без валидации min/max | 1.2 |
+| M-3 | major | Чекбокс «Несколько верных» меняет семантику без подсказки | 1.3 |
+| M-4 | major | Нет переупорядочивания вопросов | 1.4 |
+| M-5 | major | «Удалить вопрос» без подтверждения и undo | 1.4 |
+| M-6 | major | Длинный текст варианта ответа обрезается | 1.5 |
+| M-7 | major | Сырые ENUM-значения в статусах прохождений | 1.6 |
+| M-8 | major | Дубль точек выхода («← к списку» + «К списку») | 1.6 |
+| M-9 | major | Контрол «Видимость» неясен по состоянию | 1.7 |
+| M-10 | major | Список 147 сотрудников без виртуализации/счётчиков | 1.8 |
+| M-11 | major | «Назначить выбранных» теряется внутри контейнера | 1.8 |
+| m-1 | minor | Логотип на странице логина обрезан | вне скрина |
+| m-2 | minor | Роль `employee` латиницей в шапке | 1.1 |
+| m-3 | minor | Опечатка «тестирования» в `<title>` | 1.1 |
+| m-4 | minor | Карточки вопросов слабо отделены друг от друга | 1.4 |
+| m-5 | minor | Загрузка файла без drag-and-drop и описания результата | 1.5 |
+| m-6 | minor | Селекты в фильтрах без явных label | 1.7 |
+| m-7 | minor | «Нет учётки (создадим при назначении)» — нужно пояснение | 1.8 |
+
+Не проверено и стоит протестировать отдельно: валидация при сохранении пустого вопроса/вариантов, мобильная вёрстка, клавиатурная навигация и focus ring, контрастность по WCAG 2.2, поведение под другими ролями (руководитель, HR, директор).
+
+---
+
+# Часть 2. Предлагаемая новая IA
+
+## 2.1. Что не так с текущей IA
+
+Сейчас одна страница `/tests/{id}` решает три разные задачи разных ролей:
+
+| Задача | Кто делает | Как часто | Какие данные |
+|---|---|---|---|
+| Сочинить тест | автор / методолог | один раз при создании, далее редко | вопросы, варианты, порог |
+| Назначить кому проходить | автор (иногда) или HR / руководитель | каждый раз для нового сотрудника или потока | список из 100–10 000 сотрудников, фильтры |
+| Посмотреть кто прошёл | руководитель / HR / директор | регулярно | результаты, динамика, агрегаты |
+
+Это три разных пользовательских ритма, три разных набора фильтров, три разных уровня доступа. Складывать их в один аккордеон — экономия на маршрутизации и проигрыш во всём остальном (см. C-3, C-4, M-9, M-10, M-11).
+
+## 2.2. Карта разделов после редизайна
+
+```
+HR system (модуль «Тестирование»)
+│
+├── Главная / Дашборд
+│       сводка: «назначено N тестов, X% прошли, Y просрочены»
+│       (вид зависит от роли — см. 2.4)
+│
+├── Тесты
+│   ├── Каталог тестов            ← список, поиск, фильтры
+│   ├── Создать тест              ← минимальный wizard: название → пустой черновик
+│   └── /tests/{id}               ← страница теста
+│       ├── Просмотр              ← все, у кого есть доступ
+│       │     краткая сводка прохождений (89 / 147, средний 6.2/7)
+│       │     кнопка «Назначить» (открывает модалку из 2.3)
+│       │     кнопка «Редактировать» (если есть права)
+│       └── Редактирование        ← только автор / методолог
+│           ├── О тесте
+│           ├── Вопросы
+│           └── Версии теста      ← (вместо «История» — только версии)
+│
+├── Назначения                    ← новый раздел
+│   ├── Список назначений         ← таблица «тест × сотрудник × срок × статус»
+│   ├── Создать назначение        ← массовый wizard (см. 2.3)
+│   └── /assignments/{id}         ← страница назначения, где можно отозвать,
+│                                   продлить срок, посмотреть прогресс
+│
+├── Отчёты                        ← новый раздел
+│   ├── По тесту                  ← кто прошёл, средний балл, кривые
+│   ├── По сотруднику             ← все тесты сотрудника, история
+│   └── По отделу                 ← агрегаты для руководителей
+│
+├── Сотрудники                    ← справочник, синхронизация с кадрами
+│
+└── Настройки                     ← роли, подразделения, шаблоны уведомлений
+```
+
+## 2.3. Сценарий «Назначить тест» через модалку
+
+Поскольку автор иногда сам назначает тест, а иногда передаёт это HR/руководителю, кнопка «Назначить» нужна **в двух местах**:
+
+- На странице теста (для автора, который сразу выдаёт тест).
+- В разделе «Назначения → Создать» (для HR/руководителя, который отбирает аудиторию массово).
+
+Обе точки открывают **одну и ту же модалку / визард** с шагами:
+
+1. **Кому.** Сначала фильтры по отделу/должности → одной кнопкой «Все из отделения хирургии (38)» или вручную чекбоксами. Сохранение выбранного при смене фильтра. Виртуализированный список.
+2. **Когда.** Дедлайн, опционально дата старта (например, новый сотрудник получает тест на 3-й рабочий день).
+3. **Параметры.** Сколько попыток допустимо, нужен ли пересдача после неуспеха, кому уведомления о результате.
+4. **Подтверждение.** «Назначить тест „Введение про LLM v1“ 38 сотрудникам отделения хирургии до 15 мая 2026 — назначить?»
+
+После назначения автор/HR попадает на страницу созданного назначения, где видит прогресс: кто открыл, кто проходит, кто завершил.
+
+## 2.4. Ролевая модель и матрица доступа
+
+Четыре роли из ваших пояснений: **сотрудник**, **руководитель подразделения**, **HR-менеджер**, **директор**. Плюс отдельно — **методолог/автор**, которая может присваиваться поверх любой из роли (директор, HR или руководитель могут также быть авторами).
+
+| Раздел / действие | Сотрудник | Рук. подр. | HR | Директор | Автор |
+|---|---|---|---|---|---|
+| Главная | свои назначения | свой отдел | вся клиника | вся клиника | свои тесты |
+| Каталог тестов — просмотр | да (только видимые) | да | да | да | да |
+| Создать тест | — | — | да | да | да |
+| Редактировать тест | — | — | (свои) | да | свои |
+| Опубликовать новую версию | — | — | (свои) | да | свои |
+| Удалить/архивировать тест | — | — | (свои) | да | свои |
+| Назначить тест | — | свой отдел | вся клиника | вся клиника | (если сам назначает) |
+| Отозвать назначение | — | свои | свои + HR-уровня | все | свои |
+| Отчёты по сотруднику | свои | подчинённые | все | все | свои тесты |
+| Отчёты по отделу | — | свой отдел | все | все | — |
+| Настройки ролей | — | — | да | да | — |
+
+«—» — действие не доступно. Точные границы (например, может ли HR редактировать чужой тест) уточняются на этапе требований.
+
+## 2.5. Жизненный цикл версии теста и поведение при активных прохождениях
+
+Версионирование уже сделано правильно — оно фиксирует, какую именно версию проходил сотрудник, и не ломает прошлые результаты. Но в UI нужно явно показать состояния и поведение при апдейте.
+
+```
+                  ┌──────────┐
+                  │ Черновик │ ← автор может править свободно,
+                  └────┬─────┘   назначения нельзя выдать
+                       │
+              «Опубликовать как v2»
+                       │
+                       ▼
+                  ┌──────────┐
+                  │ Активная │ ← новые назначения идут на эту версию;
+                  └────┬─────┘   уже идущие прохождения остаются на старой
+                       │
+            «Опубликовать как v3»
+                       │
+                       ▼
+                  ┌──────────┐
+                  │  Архив   │ ← новые назначения нельзя; старые
+                  └──────────┘   прохождения видны в отчётах
+```
+
+Что должно быть видно в UI:
+
+- **Бейдж версии** рядом с названием теста: `Введение про LLM · v2 (активна)`.
+- **На странице редактирования** — явно: «Редактируется черновик v3 на основе активной v2».
+- **При публикации новой версии** — диалог: «Сейчас тест проходят 12 сотрудников на v2. Они закончат на v2; новые назначения пойдут на v3. Опубликовать v3?»
+- **В отчётах** — фильтр по версии теста.
+- **В назначении** — версия зафиксирована: «Назначен на тесте Введение про LLM v2».
+
+## 2.6. Состояние «черновик» страницы теста
+
+Сейчас единственная кнопка — «Сохранить черновик». Лучше добавить два глагола:
+
+- **«Сохранить черновик»** — сохранить промежуточно, не публиковать. Не создаёт новой версии.
+- **«Опубликовать как новую версию»** — фиксирует версию, делает её активной, открывает диалог из 2.5.
+
+Тогда жёлтый баннер из C-1 превращается в осмысленную подсказку: он показывается **только при наличии несохранённых изменений** и говорит «Чтобы изменения попали в назначения — опубликуйте новую версию».
+
+---
+
+# Часть 3. Чеклист изменений
+
+Разбит на три волны по приоритету и независимости работ.
+
+## Волна 1 — быстрые правки на текущей странице (1–2 спринта)
+
+Не требуют структурных изменений, можно делать параллельно с разработкой новой IA:
+
+- [ ] **C-1** Скрыть баннер версионирования при отсутствии изменений (dirty state).
+- [ ] **C-2** Confirm-диалог + прогресс для ИИ-генерации, undo последнего результата.
+- [ ] **C-3** Sticky-панель «Сохранить» внизу + предупреждение `beforeunload` при unsaved changes.
+- [ ] **M-1** Аккордеон «Вопросы» открыт по умолчанию.
+- [ ] **M-2** Валидация порога зачёта (1–100, целое число).
+- [ ] **M-3** Поясняющий текст для «Несколько верных ответов».
+- [ ] **M-5** Confirm + undo для «Удалить вопрос».
+- [ ] **M-6** Длинные варианты — `textarea` с автовысотой.
+- [ ] **M-7** Перевод ENUM-значений статусов прохождения.
+- [ ] **M-9** Toggle-switch для «Видимость» вместо одной кнопки.
+- [ ] **m-1, m-2, m-3** Косметика: логотип логина, роль, опечатка title.
+
+## Волна 2 — выделение разделов (новая IA)
+
+- [ ] Выделить раздел «Назначения» с собственной таблицей и фильтрами.
+- [ ] Перенести «Кому выдать» со страницы теста в модалку «Назначить» из 2.3.
+- [ ] Выделить раздел «Отчёты» из секции «История», расширить фильтрами и агрегатами.
+- [ ] Реализовать ролевую модель из 2.4 (RBAC): меню, разделы и действия зависят от роли.
+- [ ] Реализовать жизненный цикл версии (2.5) и явную публикацию.
+
+## Волна 3 — масштабирование и качество
+
+- [ ] Виртуализация списков сотрудников (поддержка 5 000+).
+- [ ] Drag-and-drop для перестановки вопросов (M-4).
+- [ ] Drag-and-drop загрузка файла с превью результата (m-5).
+- [ ] Аудит доступности (WCAG 2.2 AA): клавиатурная навигация, focus-ring, контрастность.
+- [ ] Адаптивная вёрстка для мобильных и планшетов.
+- [ ] Уведомления (e-mail, в системе) для назначений, дедлайнов, результатов.
+- [ ] Связка с курсами/треками (когда появятся).
+
+---
+
+# Что дальше
+
+После согласования этого документа имеет смысл:
+
+1. Сделать кликабельный прототип в Figma на 2 ключевых сценария: «автор создаёт и сразу назначает тест», «HR назначает существующий тест 200 сотрудникам». Это покажет, как именно ложится новая IA на реальные действия и где остались дыры.
+2. Прогнать прототип на 2–3 пользователях каждой роли (автор, HR, руководитель) — модерируемое юзабилити-тестирование на 30–40 минут. По итогам — финальные правки до старта разработки.
+3. Параллельно запустить Волну 1 — она независима от IA и сразу снимает большую часть пользовательской боли.
+
+---
+
+*Если по какому-то пункту нужно больше деталей или хочется, чтобы я подготовил визард-сценарий «Назначить» в виде последовательных макетов — скажите.*

docs/Рекомендации UX по экранам теста.md

@@ -0,0 +1,72 @@
+# Рекомендации UX по экранам редактирования теста
+
+*Основание: скриншоты в `docs/screens`, словарь `docs/Словарь UX-UI-IA терминов.md`. Дата фиксации: 29.04.2026.*
+
+---
+
+## Навигация и IA
+
+- **Хлебные крошки.** Сейчас только «← к списку». Имеет смысл добавить полную цепочку вроде «Тесты → Введение про LLM → Редактирование», чтобы снизить когнитивную нагрузку и отразить иерархию сущностей (Тест → Версия).
+- **Якоря по длинной странице.** Блоки «О тесте», «Вопросы», «История», «Показ в каталоге» образуют длинную вертикаль. Полезны боковое оглавление или «прыжки» по разделам / закреплённая поднавигация внутри страницы теста, чтобы не терять контекст при работе с нижними вопросами и назначением.
+
+---
+
+## Состояния интерфейса и обратная связь
+
+- **ИИ-кнопки.** Для «Сгенерировать тест (ИИ)» и «Сгенерировать вопрос (ИИ)» нужны явные состояния: загрузка (спиннер, disabled), успех/ошибка, при необходимости — отмена длительной операции (видимость статуса системы).
+- **Черновик и риск потери данных.** Уже есть заметный «Сохранить черновик» и жёлтый баннер про новую версию — хорошо. Дополнительно: предупреждение при уходе со страницы с несохранёнными изменениями; для длинной формы — **закреплённая панель** с сохранением (или дублирование primary-действия после блока вопросов), чтобы не скроллить вниз каждый раз.
+
+---
+
+## Редактор вопросов (UI и логика)
+
+- **Один vs несколько верных ответов.** При включённом «Несколько верных ответов» визуально должны быть **чекбоксы**, а не радиокнопки — соответствие метафоре, ожиданиям пользователя и доступности (скринридер, множественный выбор).
+- **Разделение действий.** «+ вариант» и «Удалить вопрос» сейчас визуально близки по весу — риск ошибочного клика. Деструктивное действие: вторичный стиль, отступ, по желанию подтверждение или «Удалить» в меню «⋯».
+- **Иерархия ИИ vs ручное редактирование.** Блок «Генерация сетки (ИИ)» логично оформить как сворачиваемый «продвинутый» блок или визуально отделить (заголовок, граница), чтобы отличать массовую генерацию от точечной «Сгенерировать вопрос» у карточки.
+- **Длинные варианты ответа.** Обрезка текста в однострочном поле мешает автору. Варианты: многострочное поле с авто-ростом по высоте или предпросмотр полной строки при фокусе/hover.
+
+---
+
+## Локализация и терминология
+
+- В истории статус **`in_progress` на английском** при русском интерфейсе — заменить на «В процессе» или единый глоссарий статусов прохождения.
+- В шапке роль **`employee`** — унифицировать с русскими названиями ролей из словаря проекта (сотрудник, HR и т.д.).
+
+---
+
+## «Показ в каталоге» и список сотрудников
+
+- **Кнопка «Назначить выбранных».** Сейчас выглядит как вторичная; это главное действие сценария выдачи теста. Имеет смысл сделать её **заполненной primary** при наличии выбора и **disabled с подсказкой**, если никто не выбран.
+- **Повтор строки «нет учётки (создадим при назначении)».** На каждой строке создаётся шум. Лучше: один информационный блок над списком; в строке — компактный бейдж/иконка только где уместно.
+- **Крайний случай: много сотрудников.** При сотнях/тысячах записей — виртуализация, пагинация или «выбрать всех по фильтру» с явным числом «будет назначено N человек».
+
+---
+
+## История и версии
+
+- При росте списка карточки версий и прохождений превращаются в длинную простыню — предусмотреть **свёрнутый список**, пагинацию или табы «Версии» / «Прохождения» с фильтром по версии и статусу.
+
+---
+
+## Доступность и плотность
+
+- Мелкий серый текст в списке сотрудников — проверить контраст (WCAG).
+- Чекбоксы и переключатели: достаточная зона клика, связь подписи с полем, логичный порядок табуляции.
+
+---
+
+## Пустые состояния
+
+- Пустая история, нет вопросов, поиск «никого не нашёл» — короткий текст **почему пусто** и **следующий шаг** («Добавьте вопрос», «Измените фильтр»).
+
+---
+
+## Приоритизация внедрения
+
+1. **Высокий эффект / низкий риск:** локализация статусов и ролей; визуальное различие «Удалить вопрос» vs «+ вариант»; primary для «Назначить выбранных»; убрать повтор длинного текста про учётку в каждой строке.
+2. **Средний:** чекбоксы при нескольких верных ответах; многострочные варианты; состояния загрузки для ИИ; закреплённое сохранение.
+3. **Стратегический:** хлебные крошки и внутренняя навигация по разделу; масштабирование списка назначений; пустые состояния; продуктовая аналитика (например, доходят ли авторы до «Показ в каталоге»).
+
+---
+
+*Документ можно дополнять по мере внедрения и новых скринов.*

docs/Словарь UX-UI-IA терминов.md

@@ -0,0 +1,298 @@
+# Словарь терминов проектирования
+
+**UX · UI · IA и смежные понятия**
+
+*Контекст: HR system / Платформа Цифровых Сервисов клиники им. Е. Н. Оленевой*
+
+---
+
+Короткий справочник, чтобы команда говорила на одном языке. Для каждого термина: русское название, английский эквивалент, короткое определение и пример из вашего продукта, чтобы было понятно, как термин применяется в реальной работе.
+
+Файл живой: добавляйте сюда термины, которые регулярно всплывают в обсуждениях.
+
+---
+
+## 1. Три основных слоя проектирования
+
+Три понятия, которые часто путают друг с другом. Это не синонимы и не одно и то же — это три разных профессиональных взгляда на один и тот же продукт.
+
+### UX (User Experience) — *опыт взаимодействия / пользовательский опыт*
+
+Совокупность ощущений пользователя от взаимодействия с продуктом: насколько просто понять, как достичь цели, насколько быстро это получается, насколько мало раздражения по дороге. UX — это про задачу пользователя, а не про конкретный экран.
+
+> *Пример из HR system:* HR-менеджер хочет назначить тест 50 сотрудникам отделения. Хороший UX — он делает это в три клика через фильтр по отделу. Плохой UX — он скроллит список из 147 человек и отмечает чекбоксами вручную.
+
+### UI (User Interface) — *пользовательский интерфейс*
+
+Видимая и кликабельная часть продукта: кнопки, поля, цвета, иконки, типографика, состояния (наведение, фокус, ошибка). UI — это про то, как продукт выглядит и как откликается на действия.
+
+> *Пример из HR system:* Кнопка «Сохранить черновик» на странице теста — её цвет, размер, скруглённые углы, текст внутри, реакция на наведение курсора — это всё UI.
+
+### IA (Information Architecture) — *информационная архитектура*
+
+Структура продукта на уровне «что где лежит и как связано»: какие есть разделы, какие сущности живут внутри, по какой логике пользователь переходит с одной страницы на другую. IA — это скелет, на который потом натягиваются UX и UI.
+
+> *Пример из HR system:* Решение «авторская работа над тестом, назначение и отчётность — это три разных раздела меню, а не один длинный аккордеон» — это IA-решение.
+
+---
+
+## 2. Исследования и работа с пользователем
+
+### Целевая аудитория — *target audience*
+
+Группы людей, для которых проектируется продукт. У каждой группы своя задача и контекст использования.
+
+> *Пример из HR system:* В вашей системе четыре аудитории: сотрудник, руководитель подразделения, HR-менеджер, директор. У них разные потребности и разные роли в системе.
+
+### Персона — *persona*
+
+Собирательный образ типичного представителя аудитории: имя, должность, цели, ограничения, частые сценарии. Помогает команде договориться, для кого мы решаем задачу.
+
+> *Пример из HR system:* «Ольга, HR-менеджер, 35 лет. Раз в квартал назначает массовое обучение 200 сотрудникам. Не любит интерфейсы, где надо кликать каждого по отдельности. Открывает систему с рабочего ноутбука и иногда с телефона на ходу.»
+
+### Сценарий использования — *user scenario / use case*
+
+История: пользователь приходит с какой-то задачей и проходит шаги, чтобы её решить. Сценарий описывает, что он делает и какие ожидания у него есть.
+
+> *Пример из HR system:* «Руководитель отделения хочет, чтобы все его подчинённые прошли тест по пожарной безопасности до конца квартала. Он входит в систему, выбирает свой отдел, выбирает тест, ставит дедлайн, отправляет.»
+
+### Пользовательский путь / CJM — *Customer Journey Map*
+
+Развёрнутая визуализация пути пользователя: шаги, точки контакта, эмоции на каждом этапе, где возникают проблемы (pain points) и где можно улучшить.
+
+> *Пример из HR system:* CJM сотрудника: получил уведомление → открыл письмо → перешёл по ссылке → ввёл логин → увидел список назначенных тестов → выбрал → прошёл → получил результат. На каждом шаге — что ему легко, а что мешает.
+
+### JTBD (Jobs To Be Done) — *работы, которые нужно выполнить*
+
+Подход: люди не «пользуются продуктом», они «нанимают» его, чтобы сделать конкретную работу. Помогает увидеть истинную мотивацию, а не поверхностный запрос.
+
+> *Пример из HR system:* HR не «нанимает» вашу систему, чтобы кликать по чекбоксам. Он нанимает её, чтобы доказать аудиту, что 100% персонала прошли инструктаж в срок.
+
+### Pain point — *болевая точка*
+
+Конкретное место, где пользователю плохо: непонятно, медленно, страшно, обидно. Pain points — главные кандидаты на улучшение.
+
+> *Пример из HR system:* На странице теста пользователь не понимает, где кнопка «Сохранить», и боится потерять изменения — это pain point.
+
+---
+
+## 3. Информационная архитектура и навигация
+
+### Карта сайта / структура продукта — *sitemap*
+
+Иерархическое описание всех экранов и разделов продукта. Показывает, что есть в продукте и в каких отношениях разделы стоят друг к другу.
+
+> *Пример из HR system:* Главная → Тесты → [страница теста] → Назначения → Отчёты → Сотрудники → Настройки.
+
+### Навигация — *navigation*
+
+Способ перемещаться по продукту: главное меню, хлебные крошки, ссылки, табы, кнопки «назад». Навигация бывает первичной (основной), вторичной и контекстной.
+
+> *Пример из HR system:* Шапка с логотипом «Тестирование», меню справа («Тесты», «Назначения», «Отчёты»), ссылка «← к списку» наверху страницы — всё это элементы навигации.
+
+### Хлебные крошки — *breadcrumbs*
+
+Цепочка ссылок, показывающая, где пользователь находится в иерархии и куда можно вернуться: «Тесты / Введение про LLM / Редактирование».
+
+> *Пример из HR system:* Сейчас на странице теста есть только «← к списку». Полные крошки помогли бы быстрее ориентироваться.
+
+### Таксономия — *taxonomy*
+
+Набор категорий и тегов, по которым классифицируются объекты. Хорошая таксономия позволяет быстро находить нужное и не плодит дубликаты.
+
+> *Пример из HR system:* Тест может иметь категории: «обязательные», «рекомендованные», «по специальности», «обучающие». Это таксономия.
+
+### Сущность / объект предметной области — *entity / domain object*
+
+Главные «существительные» вашей системы: Тест, Версия теста, Вопрос, Вариант, Сотрудник, Назначение, Прохождение, Отчёт. Дизайн начинается с понимания, какие сущности есть и как они связаны.
+
+> *Пример из HR system:* Связь «Тест → Версия → Прохождение» позволяет фиксировать результаты конкретной версии, даже если автор потом изменил вопросы.
+
+---
+
+## 4. Проектирование интерфейса
+
+### Вайрфрейм — *wireframe*
+
+Скелетный набросок экрана без цвета и стилей: просто блоки, поля, кнопки, чтобы показать структуру и иерархию. Используется на ранних этапах для быстрого обсуждения.
+
+> *Пример из HR system:* Перед прорисовкой страницы создания теста — простой набросок: «слева 70% — форма, справа 30% — превью теста».
+
+### Макет — *mockup*
+
+Визуально проработанный вариант экрана: с реальными цветами, шрифтами, иконками, но обычно статичный (не кликается).
+
+> *Пример из HR system:* Готовый Figma-макет страницы теста, согласованный с вашим зелёным брендом и шрифтом.
+
+### Прототип — *prototype*
+
+Кликабельная модель продукта: можно жать на кнопки, переходить между экранами, увидеть переходы. Прототип бывает разной степени проработанности — от карандашных набросков до почти-настоящего продукта.
+
+> *Пример из HR system:* Кликабельный прототип в Figma, на котором можно «пройти» сценарий «создал тест → назначил отделению → получил уведомление о результате».
+
+### Состояния интерфейса — *states*
+
+Один и тот же элемент или экран в разных ситуациях: пустой, загрузка, ошибка, успех, наведение, фокус, отключённый. Хорошие проекты прорисовывают все состояния, а не только «всё хорошо».
+
+> *Пример из HR system:* Кнопка «Назначить выбранных» имеет состояния: disabled (никто не выбран), normal, hover, loading (отправка идёт), success (готово).
+
+### Empty state — *пустое состояние*
+
+Что пользователь видит, когда данных нет: список пуст, поиск ничего не нашёл, ещё ничего не назначено. Хороший empty state объясняет, почему пусто, и предлагает следующий шаг.
+
+> *Пример из HR system:* Сотрудник заходит и видит пустой список «Мои тесты». Empty state: «Сейчас вам ничего не назначено. Когда руководитель добавит тест — он появится здесь.»
+
+### Edge case — *крайний случай*
+
+Редкая, но возможная ситуация: ноль элементов, тысяча элементов, очень длинный текст, обрыв сети. Игнорирование edge cases ломает интерфейс именно тогда, когда пользователь меньше всего этого ожидает.
+
+> *Пример из HR system:* Что если в клинике 5000 сотрудников, а не 147? Список «Кому выдать» сегодня этого не выдержит — это edge case, который нужно учесть.
+
+### Happy path — *счастливый сценарий*
+
+Идеальное прохождение сценария без ошибок и непредвиденных ситуаций. Полезно как стартовая точка, но проектирование только под happy path — частая ошибка.
+
+> *Пример из HR system:* «Автор создаёт тест, заполняет 7 вопросов, сохраняет, назначает отделу, все проходят» — это happy path. А что если у автора оборвался интернет на полпути?
+
+---
+
+## 5. Дизайн-система и компоненты
+
+### Дизайн-система — *design system*
+
+Набор готовых правил, компонентов и токенов (цветов, отступов, шрифтов), которыми пользуется вся команда. Цель — единообразие и скорость: не изобретать каждый раз кнопку с нуля.
+
+> *Пример из HR system:* Внутри Платформы Цифровых Сервисов клиники должна быть единая дизайн-система: HR system, регистратура, эндовидеоплатформа выглядят как продукты одной семьи.
+
+### UI-кит — *UI kit*
+
+Библиотека готовых интерфейсных элементов (кнопки, поля, модалки, таблицы) в Figma или коде, которой пользуются дизайнеры и разработчики.
+
+> *Пример из HR system:* Если у вас есть UI-кит, новая страница «Назначения» собирается из готовых компонентов за день, а не за неделю.
+
+### Компонент — *component*
+
+Самостоятельный кусочек интерфейса с понятным API: входные параметры, состояния, поведение. Кнопка, поле ввода, аккордеон, модалка — всё это компоненты.
+
+> *Пример из HR system:* Аккордеон «О тесте» / «Вопросы» / «История» / «Показ в каталоге» — четыре экземпляра одного и того же компонента «аккордеон».
+
+### Токен дизайна — *design token*
+
+Атомарная переменная стиля: цвет, отступ, размер шрифта, радиус скругления. Токены позволяют менять оформление всего продукта централизованно.
+
+> *Пример из HR system:* Цвет `primary-green = #2E7D5B` — токен. Если решите перейти на другой оттенок зелёного, меняете в одном месте, и все кнопки обновляются.
+
+### Паттерн — *pattern*
+
+Типовое решение типовой задачи: «как реализовать поиск с фильтрами», «как показать длинный список». Паттерны — это коллективная мудрость комьюнити.
+
+> *Пример из HR system:* Паттерн «master-detail»: слева список тестов, справа детали выбранного. Хорошо ложится на ваш будущий раздел «Назначения».
+
+---
+
+## 6. Качество и проверка дизайна
+
+### Юзабилити — *usability*
+
+Свойство интерфейса быть простым и эффективным в использовании. Измеряется через эффективность (получилось ли), скорость и количество ошибок.
+
+> *Пример из HR system:* Если сотрудник не может с первого раза найти, как пройти тест — у интерфейса проблема с юзабилити.
+
+### Доступность — *accessibility / a11y*
+
+Возможность использовать продукт людям с особенностями: слабовидящим, незрячим (через скринридеры), людям с моторными ограничениями (только клавиатура), дальтоникам. Стандарт — WCAG.
+
+> *Пример из HR system:* Радиокнопки выбора правильного варианта должны быть доступны с клавиатуры (Tab + Space) и понятны скринридеру («Вариант 1 из 3, выбран»).
+
+### Юзабилити-тестирование — *usability testing*
+
+Метод исследования: реальный пользователь выполняет задание, исследователь наблюдает, где он спотыкается. Дешёвый способ найти большую часть проблем.
+
+> *Пример из HR system:* Дать HR-менеджеру задание «назначь этот тест всему отделению хирургии до 1 мая» и записать, где он зависнет.
+
+### Эвристическая оценка — *heuristic evaluation*
+
+Эксперт сверяет интерфейс с набором эвристик (правил хорошего дизайна, например, эвристиками Нильсена) и фиксирует нарушения. Быстрее теста с пользователями, но менее точно.
+
+> *Пример из HR system:* Анализ страницы теста, который мы делаем сейчас — это, по сути, эвристическая оценка.
+
+### A/B-тест — *A/B testing*
+
+Сравнение двух вариантов интерфейса на реальной аудитории: половина видит вариант A, половина — B; измеряем, какой работает лучше.
+
+> *Пример из HR system:* Сравнить две формулировки кнопки: «Сохранить черновик» vs «Сохранить и назначить» — что чаще ведёт к завершению задачи.
+
+### Аналитика продукта — *product analytics*
+
+Сбор и анализ данных о том, как пользователи реально пользуются продуктом: где кликают, где бросают, сколько времени проводят. Подсказывает, где искать проблемы.
+
+> *Пример из HR system:* Если в аналитике видно, что 40% авторов не доходят до раздела «Показ в каталоге» — это сигнал, что его упускают.
+
+---
+
+## 7. Технические понятия, нужные дизайнеру
+
+### Респонсив / адаптивность — *responsive design*
+
+Способность интерфейса корректно работать на разных размерах экрана: от телефона до большого монитора. Не путать с «мобильной версией».
+
+> *Пример из HR system:* Список «Кому выдать» должен оставаться удобным на 13-дюймовом ноутбуке руководителя и на телефоне HR-менеджера в дороге.
+
+### Брейкпойнт — *breakpoint*
+
+Ширина экрана, на которой меняется раскладка интерфейса. Типовые: 360, 768, 1024, 1440 px.
+
+> *Пример из HR system:* На брейкпойнте 768 px (планшет) две колонки на странице теста схлопываются в одну.
+
+### RBAC — *Role-Based Access Control / ролевая модель доступа*
+
+Правила, что какая роль видит и может делать в системе. Дизайн интерфейса должен учитывать роль: один и тот же экран показывается по-разному сотруднику, руководителю, HR и директору.
+
+> *Пример из HR system:* Сотрудник видит только «Мои тесты». Руководитель — ещё «Мой отдел». HR — все назначения. Директор — сводный отчёт.
+
+### Версионирование — *versioning*
+
+Подход, при котором у объекта (теста, документа) есть несколько версий, и история фиксируется. Полезно для аудита и неизменности результатов.
+
+> *Пример из HR system:* В вашей системе тест имеет версии v1, v2 и т.д. Прохождение всегда привязано к конкретной версии — изменения автора не «переписывают» прошлые результаты.
+
+### Состояние черновика — *draft state*
+
+Промежуточное состояние объекта: ещё не опубликован/не активирован, можно безопасно править.
+
+> *Пример из HR system:* Кнопка «Сохранить черновик» означает: тест сохранён, но пока не выдан сотрудникам. Можно ещё дорабатывать.
+
+### Уведомление — *notification*
+
+Сообщение системы пользователю: всплывающее (toast), баннер на странице, push, e-mail. Каждый канал имеет свои правила использования.
+
+> *Пример из HR system:* Тост «Тест сохранён» после нажатия кнопки. E-mail сотруднику с дедлайном по назначенному тесту.
+
+---
+
+## 8. Терминология этого проекта
+
+Чтобы команда не путалась, фиксируем основные сущности HR system явно.
+
+- **Тест** — учебный материал, состоящий из вопросов с вариантами ответов. Один тест может иметь несколько версий.
+- **Версия теста** — снимок содержимого теста на момент сохранения. Прохождение всегда привязано к конкретной версии.
+- **Вопрос** — отдельный пункт теста с формулировкой и набором вариантов. Может допускать один или несколько верных ответов.
+- **Вариант ответа** — один из предложенных ответов на вопрос. Помечается как верный или нет.
+- **Назначение** — связь «тест × сотрудник × срок». Формирует у сотрудника обязательство пройти этот тест.
+- **Прохождение** — попытка сотрудника пройти конкретную версию теста. Имеет статус (в процессе, пройдено, не пройдено) и результат (X из Y).
+- **Порог зачёта** — процент правильных ответов, начиная с которого прохождение засчитывается.
+- **Каталог** — общий список тестов, видимый сотрудникам с правами.
+- **Роль** — профиль доступа: сотрудник, руководитель подразделения, HR-менеджер, директор.
+
+---
+
+## Полезные ссылки и стандарты
+
+- **Эвристики Якоба Нильсена** — 10 базовых правил юзабилити: [nngroup.com](https://www.nngroup.com/articles/ten-usability-heuristics/)
+- **WCAG 2.2** — стандарт доступности: [w3.org/TR/WCAG22](https://www.w3.org/TR/WCAG22/)
+- **Material Design** — [m3.material.io](https://m3.material.io/) и **Apple HIG** — [developer.apple.com/design](https://developer.apple.com/design/human-interface-guidelines/) — два больших источника готовых паттернов и принципов.
+- **Refactoring UI** (Adam Wathan, Steve Schoger) — настольная книга по практическому UI-дизайну.
+
+---
+
+*— Справочник можно дополнять по мере появления новых терминов —*