Browse Source
- PROJECT_STATUS: что сделано (черновики, версии, разбор, каталог) и планы - DEV_CONTOUR_USER_GUIDE: сценарии для проверяющих на dev-стенде - README, ТЗ, card1, журнал, бэклоги, шаги 01–11+README, спринты, TEST_TABLES: ссылки и примечания - backend/PROGRESS: ссылка на PROJECT_STATUS Made-with: Cursordev
Константин Лебединский
2 weeks ago
27 changed files with 842 additions and 12 deletions
@ -0,0 +1,54 @@
|
||||
# Progress — миграция `001_initial` (историческая заметка) |
||||
|
||||
*Актуальное описание продукта и сценариев: [../docs/PROJECT_STATUS.md](../docs/PROJECT_STATUS.md).* |
||||
|
||||
# Progress - Шаг 2: Проектирование базы данных |
||||
|
||||
## Статус: ✅ ЗАВЕРШЕНО |
||||
|
||||
### Выполненные задачи: |
||||
|
||||
1. ✅ **Создание SQL-миграции** (`backend/src/db/migrations/001_initial.sql`) |
||||
- Созданы все таблицы: |
||||
- `departments` (Подразделения) |
||||
- `users` (Пользователи) |
||||
- `tests` (Тесты) |
||||
- `test_versions` (Версии тестов) |
||||
- `questions` (Вопросы) |
||||
- `answer_options` (Варианты ответов) |
||||
- `test_assignments` (Назначения тестов) |
||||
- `test_assignment_targets` (Получатели назначений) |
||||
- `test_attempts` (Попытки прохождения) |
||||
- `user_answers` (Ответы пользователя) |
||||
- `settings` (Настройки) |
||||
- Созданы ENUM типы: `user_role`, `target_type`, `attempt_status` |
||||
- Созданы индексы для оптимизации запросов |
||||
- Добавлены начальные данные в таблицу `settings` |
||||
|
||||
2. ✅ **Создание скрипта миграции** (`backend/src/db/migrate.js`) |
||||
- Поддержка выполнения SQL-миграций |
||||
- Отслеживание выполненных миграций в таблице `migrations` |
||||
- Транзакционное выполнение миграций |
||||
- Логирование процесса выполнения |
||||
|
||||
3. ✅ **Создание db.js** (`backend/src/db/db.js`) |
||||
- Подключение к PostgreSQL с использованием пула соединений |
||||
- Функции: `query()`, `transaction()`, `getClient()` |
||||
- Обработка ошибок пула |
||||
- Логирование запросов в режиме разработки |
||||
|
||||
4. ✅ **Применение миграций к БД** |
||||
- Миграция `001_initial.sql` успешно выполнена |
||||
- Все таблицы созданы в базе данных `clinic_tests` |
||||
|
||||
### Созданные файлы: |
||||
|
||||
``` |
||||
backend/src/db/ |
||||
├── migrations/ |
||||
│ └── 001_initial.sql # SQL-миграция с созданием всех таблиц |
||||
├── migrate.js # Скрипт для выполнения миграций |
||||
└── db.js # Модуль подключения к PostgreSQL |
||||
``` |
||||
|
||||
### Дата выполнения: 2026-03-21 |
||||
@ -0,0 +1,63 @@
|
||||
# Как пользоваться стендом **dev** (простыми словами) |
||||
|
||||
**Для кого:** тот, кто **проверяет** интерфейс на своей машине или на общем dev-сервере, без погрузки в код. |
||||
|
||||
**Адрес по умолчанию:** [http://localhost:8080](http://localhost:8080) — если вы подняли проект командой `docker compose -f docker-compose.dev.yml up` из корня репозитория. Страница и API с одного адреса: запросы к `/api/…` идут на бэкенд за прокси. |
||||
|
||||
Если кто-то дал **другой URL** (например, внутренний хост клиники) — откройте его; логика та же. |
||||
|
||||
--- |
||||
|
||||
## 1. Вход |
||||
|
||||
1. Откройте в браузере адрес стенда. Должна открыться **страница входа** (логин, пароль, кнопка «Войти»). |
||||
2. Введите **логин и пароль**, которые вам выдали для **этой** базы `clinic_tests` (или HR, если включён `HR_AUTH` — смотрите, что сказал разработчик). |
||||
3. После успешного входа вы попадаете в раздел **«Тесты»**. В **шапке** справа: **Фамилия с инициалами** и роль; слева — название портала. **«Выйти»** завершает сессию. |
||||
|
||||
Если не пускает — не подбирайте пароль: напишите тому, кто администрирует БД или `.env` на стенде. |
||||
|
||||
--- |
||||
|
||||
## 2. Список «Тесты» |
||||
|
||||
- Каждая **строка** — один тест (одна **цепочка**; номер версии в подписи внизу строки). |
||||
- **Слева** — **название** (клик открывает **карточку** теста: настройки, вопросы, назначения — если вы автор, или краткую информацию — если вам только **назначили**). |
||||
- **Справа** — кнопка **«Пройти»**: начать попытку **сразу** по **текущей активной** версии (именно с неё, а не с «старой из назначения»). |
||||
- Под названием: **Автор: Вы** — если вы создали тест; **Автор: Фамилия И. О.** — если тест чужой, но вам **назначен**. |
||||
|
||||
Пустой список: либо вам **ничего не назначили** и вы **не создавали** тесты, либо всё **скрыто** из списка (у автора внизу может быть блок «Скрытые вами»). |
||||
|
||||
--- |
||||
|
||||
## 3. Карточка теста (автор) |
||||
|
||||
- **Содержание:** название, порог зачёта, вопросы и варианты, отметка верных ответов. **Сохранить черновик** — записывает правки. Если по тесту **уже были прогоны**, при изменении **содержимого** система заведёт **новую версию** (и предупредит, что так и задумано). |
||||
- **История версий** — посмотреть все версии, **сделать активной** другую (с подтверждением). Новые «Пройти» пойдут с активной. |
||||
- **Публикация** — скрыть цепочку из общего списка или вернуть обратно. |
||||
- **Прогоны и разбор** (если есть завершённые попытки) — таблица; можно открыть **разбор** по вопросам. |
||||
- **Импорт из файла** (если на стенде настроен ключ к LLM) — загрузить документ, получить **черновик**, вставить в редактор, затем снова **сохранить черновик** по правилам версий. |
||||
|
||||
Автор **не** запускает экзамен **с карточки** в том же сценарии, что сотрудник: для самопрохождения — **«Пройти»** в **списке** «Тесты». |
||||
|
||||
--- |
||||
|
||||
## 4. Прохождение и разбор (сотрудник или самопроверка автора) |
||||
|
||||
1. В списке нажмите **«Пройти»** у нужного теста. |
||||
2. Ответьте на вопросы, нажмите **«Завершить тест»**. |
||||
3. Увидите **сводку** (сколько верно, процент, зачёт/незачёт) и **разбор по вопросам** (что отмечено, что было верно). Есть ссылка на **отдельную страницу разбора** — удобно, если нужно вернуться позже. |
||||
|
||||
--- |
||||
|
||||
## 5. Что сказать разработчику, если «что-то не так» |
||||
|
||||
- **«Белый экран» / ошибка** — сделайте скриншот и опишите, **на какой странице** (например, «после Войти» или «после Пройти»). |
||||
- **«Не вижу тест»** — уточните, вы **автор** или вам должны были **назначить**; проверьте блок **скрытых** тестов. |
||||
- **«Сохранил, а версия не та»** — скажите, были ли **уже** попытки у других: после первой попытки **любая** смена содержимого **увеличивает** номер версии **специально**, чтобы старые ответы не «переписывались». |
||||
|
||||
--- |
||||
|
||||
## 6. Где почитать подробности для разработки |
||||
|
||||
- [PROJECT_STATUS.md](PROJECT_STATUS.md) — что в целом сделано и что в планах. |
||||
- [../README.md](../README.md) — Docker, БД, переменные окружения. |
||||
@ -0,0 +1,72 @@
|
||||
# Состояние проекта (человеческий обзор) |
||||
|
||||
**Репозиторий:** [TestingWebApp](https://git.pirogov.ai/l_konstantin/TestingWebApp) · ветка разработки: **`dev`** |
||||
**Дата среза:** 2026-04-24 |
||||
|
||||
Этот документ — не дублирование ТЗ, а **короткое объяснение**, что уже работает в коде и что логично делать дальше. Подробные задачи: [revision_task/card1.md](revision_task/card1.md), [revision_task/BACKLOG.md](revision_task/BACKLOG.md). |
||||
|
||||
--- |
||||
|
||||
## Что уже сделано (как это устроено) |
||||
|
||||
### Вход и роли |
||||
|
||||
- Сотрудник входит по **логину и паролю** (сессия через cookie + JWT). |
||||
- В шапке показываются **роль** и **Фамилия с инициалами** (например, *Иванов И. О.*), полное ФИО — во всплывающей подсказке. |
||||
- В **режиме разработки** (`NODE_ENV=development`) у удобного тестирования могут быть дополнительные кнопки (например, создание теста сотрудником — `devUi` в ответе `/api/auth/me`). |
||||
|
||||
### «Цепочка» теста и черновики |
||||
|
||||
- У каждого теста есть **одна логическая цепочка** в базе: все правки вопросов относятся к ней, но **версия контента** (`v1`, `v2`, …) может расти. |
||||
- **Пока никто не проходил** этот тест — автор правит **на месте**: сохраняет черновик, и меняется текущая активная версия **без** лишнего дублирования строк в истории. |
||||
- **Как только по цепочке появилась хотя бы одна завершённая попытка** — каждое **содержательное** сохранение с изменениями создаёт **новую версию** (новый номер, старая остаётся в истории). Старые результаты остаются привязаны к **той** версии, с которой человек реально отвечал. |
||||
- **Активная версия** — та, с которой сейчас стартуют новые попытки. Автор может **вручную** переключить активную версию в таблице истории (с подтверждением), если бизнесу так нужно. |
||||
- **Публикация:** тест можно **скрыть из общего списка** (цепочка остаётся в базе; автор видит скрытые в отдельном блоке и может вернуть в список). |
||||
|
||||
### Список тестов и доступ |
||||
|
||||
- В каталоге **«Тесты»** видны цепочки, где вы **автор**, и тесты, **назначенные вам** (через назначение на пользователя; в dev назначения обычно **включены**). |
||||
- Под названием показывается **«Автор: Вы»** для своих тестов и **«Автор: Фамилия И. О.»** для чужих (назначенных). |
||||
- **Пройти** тест — кнопка **справа** в строке; **карточка** теста — клик по названию **слева** (попытка с карточки не стартует сама). |
||||
|
||||
### Прохождение и результат |
||||
|
||||
- Открывается экран вопросов (один или несколько верных вариантов); после **«Завершить тест»** — итог: сколько верно, процент, **зачёт** по порогу. |
||||
- **Разбор:** после сдачи показывается, по **каждому вопросу**, что выбрал пользователь и какие варианты верны. Отдельная страница разбора доступна по ссылке; **автор** на карточке теста видит раздел **«Прогоны и разбор»** по завершённым попыткам. |
||||
|
||||
### Импорт и ИИ (MVP) |
||||
|
||||
- Можно загрузить **файл** (PDF, DOCX, текст): сервер **извлекает текст** и при настроенном ключе **LLM** (например, `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` в окружении) предлагает **черновик** вопросов. Дальше тот же поток, что и при ручном редактировании: правки → **сохранить черновик** (с учётом правил версий выше). |
||||
- **Полный** набор сценариев из ТЗ (отдельная страница настроек ключа, «проверить тест целиком», модалки с чекбоксами и т.д.) — в [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); сейчас — упрощённое сопоставление ролей. |
||||
|
||||
--- |
||||
|
||||
## Что в планах (логичный следующий слой) |
||||
|
||||
| Направление | Суть | |
||||
|-------------|------| |
||||
| **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). |
||||
|
||||
--- |
||||
|
||||
## Связанные файлы |
||||
|
||||
- [Руководство пользователя dev-контура](DEV_CONTOUR_USER_GUIDE.md) |
||||
- [README с установкой](../README.md) |
||||
- [Карта задач card1](revision_task/card1.md) |
||||
@ -0,0 +1,380 @@
|
||||
# Анализ таблиц для тестирования сотрудников |
||||
|
||||
*Модуль **TestingWebApp** использует отдельную БД `clinic_tests` (см. [PROJECT_STATUS.md](PROJECT_STATUS.md) и [README.md](../README.md)). Ниже — разбор **наследуемых** / смежных сущностей в другой схеме, для сравнения и миграционных дискуссий.* |
||||
|
||||
## Обзор существующих таблиц |
||||
|
||||
В базе данных существуют следующие таблицы, связанные с тестированием: |
||||
|
||||
### 1. [`training_questions`](hr_web_viewer/models.py) - Вопросы обучения |
||||
|
||||
| Колонка | Тип | Описание | |
||||
|---------|-----|----------| |
||||
| `id` | integer | Первичный ключ | |
||||
| `position` | text | Должность/категория | |
||||
| `test_type` | text | Тип темы/теста | |
||||
| `question` | text | Текст вопроса | |
||||
| `answer_1` - `answer_12` | text | Варианты ответов | |
||||
| `answer_count` | smallint | Количество правильных ответов | |
||||
|
||||
**Проблемы:** |
||||
- Отсутствует явное указание правильного ответа |
||||
- Нет типа вопроса (одиночный/множественный выбор, текстовый, сопоставление) |
||||
- Нет баллов за вопрос |
||||
- Нет порядка вопросов |
||||
- Поле `position` используется как категория, но не связано с должностями |
||||
|
||||
### 2. [`training_results`](hr_web_viewer/models.py) - Результаты обучения |
||||
|
||||
| Колонка | Тип | Описание | |
||||
|---------|-----|----------| |
||||
| `id` | integer | Первичный ключ | |
||||
| `telegram_id` | bigint | ID сотрудника | |
||||
| `correct_answers` | integer | Правильные ответы | |
||||
| `total_questions` | integer | Всего вопросов | |
||||
| `score` | integer | Балл | |
||||
| `completed_at` | timestamp | Дата завершения | |
||||
| `passed` | boolean | Пройден/не пройден | |
||||
|
||||
**Индексы:** |
||||
- `idx_training_results_telegram_id` - по telegram_id |
||||
|
||||
**Проблемы:** |
||||
- Нет связи с конкретным тестом (test_type) |
||||
- Нет количества попыток |
||||
- Нет детализации по ответам |
||||
|
||||
### 3. [`training_settings`](hr_web_viewer/models.py) - Настройки обучения |
||||
|
||||
| Колонка | Тип | Описание | |
||||
|---------|-----|----------| |
||||
| `id` | integer | Первичный ключ | |
||||
| `position` | varchar(100) | Должность | |
||||
| `question_count` | integer | Количество вопросов (по умолчанию 10) | |
||||
| `passing_score` | integer | Проходной балл (по умолчанию 70) | |
||||
| `time_limit` | integer | Ограничение времени в минутах (по умолчанию 30) | |
||||
| `active` | boolean | Активен/неактивен | |
||||
|
||||
**Индексы:** |
||||
- `idx_training_settings_position` - по position |
||||
|
||||
**Проблемы:** |
||||
- Нет связи с категорией теста |
||||
- Нет ограничения количества попыток |
||||
- Нет настройки случайного порядка вопросов |
||||
|
||||
### 4. [`test_assignments`](hr_web_viewer/models.py) - Назначения тестов |
||||
|
||||
| Колонка | Тип | Описание | |
||||
|---------|-----|----------| |
||||
| `id` | integer | Первичный ключ | |
||||
| `la_name` | text | Название адаптации | |
||||
| `intern_fio` | text | ФИО стажера | |
||||
| `user_credentials` | text | Учетные данные | |
||||
| `test_theme` | text | Тема теста | |
||||
| `test_subtheme` | text | Подтема теста | |
||||
| `attempts_allowed` | integer | Количество попыток | |
||||
| `passing_score` | integer | Проходной балл | |
||||
| `la_id` | integer | Ссылка на адаптацию | |
||||
| `intern_id` | bigint | ID сотрудника (staff_members.id) | |
||||
| `deadline` | timestamp | Срок сдачи | |
||||
|
||||
**Внешние ключи:** |
||||
- `intern_id` -> `staff_members(id)` |
||||
- `la_id` -> `learning_adaptations(id)` |
||||
|
||||
**Проблемы:** |
||||
- Назначения привязаны к конкретным сотрудникам, а не к должностям |
||||
- Нет статуса прохождения |
||||
- Нет связи с результатами |
||||
|
||||
### 5. [`test_table`](hr_web_viewer/models.py) - Таблица тестов |
||||
|
||||
| Колонка | Тип | Описание | |
||||
|---------|-----|----------| |
||||
| `id` | integer | Первичный ключ | |
||||
| `name` | varchar(100) | Название теста | |
||||
|
||||
**Проблемы:** |
||||
- Минимальная структура, практически не используется |
||||
|
||||
### 6. [`corp_groups_tester`](hr_web_viewer/models.py) - Тестировщики (корпоративные группы) |
||||
|
||||
| Колонка | Тип | Описание | |
||||
|---------|-----|----------| |
||||
| `id` | integer | Первичный ключ | |
||||
| `fio` | text | ФИО | |
||||
| `telegram_id` | varchar(20) | Telegram ID | |
||||
| `position` | varchar(200) | Должность | |
||||
| `department` | varchar(200) | Отдел | |
||||
| `phone` | varchar(20) | Телефон | |
||||
| `email` | varchar(100) | Email | |
||||
| `hire_date` | date | Дата приема | |
||||
|
||||
**Проблемы:** |
||||
- Дублирует данные staff_members |
||||
- Не используется в текущей системе |
||||
|
||||
--- |
||||
|
||||
## Рекомендуемая расширенная схема для ClinicTestingApp |
||||
|
||||
### Новые таблицы |
||||
|
||||
#### 1. `tests` - Основные тесты |
||||
|
||||
```sql |
||||
CREATE TABLE tests ( |
||||
id SERIAL PRIMARY KEY, |
||||
name VARCHAR(255) NOT NULL, -- Название теста |
||||
description TEXT, -- Описание |
||||
category VARCHAR(100), -- Категория (тема) |
||||
position VARCHAR(100), -- Должность (nullable - для всех) |
||||
question_count INTEGER DEFAULT 10, -- Количество вопросов в тесте |
||||
time_limit_minutes INTEGER, -- Ограничение времени (null = без ограничений) |
||||
attempts_allowed INTEGER DEFAULT 3, -- Количество попыток |
||||
passing_score_percent INTEGER DEFAULT 70, -- Проходной процент |
||||
random_questions BOOLEAN DEFAULT FALSE, -- Случайный порядок вопросов |
||||
is_active BOOLEAN DEFAULT TRUE, -- Активен |
||||
created_by INTEGER, -- ID администратора |
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP |
||||
); |
||||
|
||||
CREATE INDEX idx_tests_category ON tests(category); |
||||
CREATE INDEX idx_tests_position ON tests(position); |
||||
``` |
||||
|
||||
#### 2. `test_questions` - Вопросы тестов |
||||
|
||||
```sql |
||||
CREATE TABLE test_questions ( |
||||
id SERIAL PRIMARY KEY, |
||||
test_id INTEGER NOT NULL REFERENCES tests(id) ON DELETE CASCADE, |
||||
question_text TEXT NOT NULL, -- Текст вопроса |
||||
question_type VARCHAR(50) NOT NULL, -- single_choice, multiple_choice, text, matching, ordering |
||||
points INTEGER DEFAULT 1, -- Баллы за вопрос |
||||
question_order INTEGER, -- Порядок вопроса |
||||
explanation TEXT, -- Пояснение к ответу |
||||
is_active BOOLEAN DEFAULT TRUE, |
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP |
||||
); |
||||
|
||||
CREATE INDEX idx_test_questions_test_id ON test_questions(test_id); |
||||
``` |
||||
|
||||
#### 3. `test_answers` - Ответы на вопросы |
||||
|
||||
```sql |
||||
CREATE TABLE test_answers ( |
||||
id SERIAL PRIMARY KEY, |
||||
question_id INTEGER NOT NULL REFERENCES test_questions(id) ON DELETE CASCADE, |
||||
answer_text TEXT NOT NULL, -- Текст ответа |
||||
is_correct BOOLEAN DEFAULT FALSE, -- Правильный ответ |
||||
answer_order INTEGER, -- Порядок (для сопоставления/порядка) |
||||
points_if_correct INTEGER DEFAULT 1 -- Баллы (если отличаются от question.points) |
||||
); |
||||
|
||||
CREATE INDEX idx_test_answers_question_id ON test_answers(question_id); |
||||
``` |
||||
|
||||
#### 4. `test_assignments_extended` - Расширенные назначения тестов |
||||
|
||||
```sql |
||||
CREATE TABLE test_assignments_extended ( |
||||
id SERIAL PRIMARY KEY, |
||||
test_id INTEGER NOT NULL REFERENCES tests(id) ON DELETE CASCADE, |
||||
staff_id INTEGER NOT NULL REFERENCES staff_members(id) ON DELETE CASCADE, |
||||
assigned_by INTEGER, -- ID администратора |
||||
assigned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
||||
deadline TIMESTAMP, -- Срок сдачи |
||||
attempts_allowed INTEGER, -- Переопределение количества попыток (null = из теста) |
||||
status VARCHAR(50) DEFAULT 'pending', -- pending, in_progress, completed, expired |
||||
UNIQUE(test_id, staff_id) |
||||
); |
||||
|
||||
CREATE INDEX idx_test_assignments_test_id ON test_assignments_extended(test_id); |
||||
CREATE INDEX idx_test_assignments_staff_id ON test_assignments_extended(staff_id); |
||||
``` |
||||
|
||||
#### 5. `test_attempts` - Попытки прохождения |
||||
|
||||
```sql |
||||
CREATE TABLE test_attempts ( |
||||
id SERIAL PRIMARY KEY, |
||||
assignment_id INTEGER NOT NULL REFERENCES test_assignments_extended(id) ON DELETE CASCADE, |
||||
attempt_number INTEGER NOT NULL, -- Номер попытки |
||||
started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
||||
completed_at TIMESTAMP, -- Завершена |
||||
score_points INTEGER, -- Набрано баллов |
||||
score_percent NUMERIC(5,2), -- Процент |
||||
passed BOOLEAN, -- Пройден/не пройден |
||||
time_spent_seconds INTEGER -- Потраченное время |
||||
); |
||||
|
||||
CREATE INDEX idx_test_attempts_assignment_id ON test_attempts(assignment_id); |
||||
``` |
||||
|
||||
#### 6. `test_answers_given` - Ответы пользователя |
||||
|
||||
```sql |
||||
CREATE TABLE test_answers_given ( |
||||
id SERIAL PRIMARY KEY, |
||||
attempt_id INTEGER NOT NULL REFERENCES test_attempts(id) ON DELETE CASCADE, |
||||
question_id INTEGER NOT NULL REFERENCES test_questions(id) ON DELETE CASCADE, |
||||
given_answer_ids INTEGER[], -- ID выбранных ответов (для choice) |
||||
given_text TEXT, -- Текстовый ответ |
||||
is_correct BOOLEAN, -- Правильный/неправильный |
||||
points_earned INTEGER, -- Полученные баллы |
||||
answered_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP |
||||
); |
||||
|
||||
CREATE INDEX idx_test_answers_given_attempt_id ON test_answers_given(attempt_id); |
||||
``` |
||||
|
||||
#### 7. `test_categories` - Категории тестов |
||||
|
||||
```sql |
||||
CREATE TABLE test_categories ( |
||||
id SERIAL PRIMARY KEY, |
||||
name VARCHAR(100) NOT NULL UNIQUE, |
||||
description TEXT, |
||||
parent_id INTEGER REFERENCES test_categories(id), |
||||
is_active BOOLEAN DEFAULT TRUE |
||||
); |
||||
``` |
||||
|
||||
#### 8. `test_reports` - Сформированные отчеты |
||||
|
||||
```sql |
||||
CREATE TABLE test_reports ( |
||||
id SERIAL PRIMARY KEY, |
||||
report_type VARCHAR(50) NOT NULL, -- department, employee, category |
||||
parameters JSONB, -- Параметры отчета |
||||
file_path VARCHAR(500), -- Путь к файлу |
||||
format VARCHAR(10), -- pdf, xlsx |
||||
generated_by INTEGER, -- ID администратора |
||||
generated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP |
||||
); |
||||
``` |
||||
|
||||
--- |
||||
|
||||
## Расширение существующих таблиц (миграции) |
||||
|
||||
### training_questions |
||||
|
||||
```sql |
||||
-- Добавить тип вопроса |
||||
ALTER TABLE training_questions ADD COLUMN IF NOT EXISTS question_type VARCHAR(50) DEFAULT 'single_choice'; |
||||
|
||||
-- Добавить баллы |
||||
ALTER TABLE training_questions ADD COLUMN IF NOT EXISTS points INTEGER DEFAULT 1; |
||||
|
||||
-- Добавить правильный ответ (индекс) |
||||
ALTER TABLE training_questions ADD COLUMN IF NOT EXISTS correct_answer_index INTEGER; |
||||
|
||||
-- Добавить порядок |
||||
ALTER TABLE training_questions ADD COLUMN IF NOT EXISTS sort_order INTEGER; |
||||
|
||||
-- Добавить пояснение |
||||
ALTER TABLE training_questions ADD COLUMN IF NOT EXISTS explanation TEXT; |
||||
``` |
||||
|
||||
### training_results |
||||
|
||||
```sql |
||||
-- Добавить связь с тестом |
||||
ALTER TABLE training_results ADD COLUMN IF NOT EXISTS test_id INTEGER REFERENCES tests(id); |
||||
|
||||
-- Добавить номер попытки |
||||
ALTER TABLE training_results ADD COLUMN IF NOT EXISTS attempt_number INTEGER DEFAULT 1; |
||||
|
||||
-- Добавить время прохождения |
||||
ALTER TABLE training_results ADD COLUMN IF NOT EXISTS time_spent_seconds INTEGER; |
||||
|
||||
-- Добавить детализацию ответов (JSON) |
||||
ALTER TABLE training_results ADD COLUMN IF NOT EXISTS answers_detail JSONB; |
||||
``` |
||||
|
||||
### training_settings |
||||
|
||||
```sql |
||||
-- Добавить связь с тестом |
||||
ALTER TABLE training_settings ADD COLUMN IF NOT EXISTS test_id INTEGER REFERENCES tests(id); |
||||
|
||||
-- Добавить категорию |
||||
ALTER TABLE training_settings ADD COLUMN IF NOT EXISTS category VARCHAR(100); |
||||
|
||||
-- Добавить случайный порядок |
||||
ALTER TABLE training_settings ADD COLUMN IF NOT EXISTS random_order BOOLEAN DEFAULT FALSE; |
||||
``` |
||||
|
||||
--- |
||||
|
||||
## Связь с staff_members |
||||
|
||||
Текущая проблема: используется `telegram_id` для связи с сотрудниками. |
||||
|
||||
Решение: перейти на использование `staff_members.id` как универсального идентификатора: |
||||
|
||||
```sql |
||||
-- Добавить staff_id в training_results |
||||
ALTER TABLE training_results ADD COLUMN IF NOT EXISTS staff_id INTEGER REFERENCES staff_members(id); |
||||
|
||||
-- Миграция данных |
||||
UPDATE training_results tr |
||||
SET staff_id = sm.id |
||||
FROM staff_members sm |
||||
WHERE tr.telegram_id = sm.telegram_id; |
||||
|
||||
-- Создать внешний ключ после миграции |
||||
ALTER TABLE training_results |
||||
ADD CONSTRAINT training_results_staff_id_fkey |
||||
FOREIGN KEY (staff_id) REFERENCES staff_members(id); |
||||
``` |
||||
|
||||
--- |
||||
|
||||
## Типы вопросов |
||||
|
||||
| Тип | Код | Описание | |
||||
|-----|-----|----------| |
||||
| Одиночный выбор | `single_choice` | Один правильный ответ из нескольких | |
||||
| Множественный выбор | `multiple_choice` | Несколько правильных ответов | |
||||
| Текстовый ответ | `text` | Свободный текст | |
||||
| Сопоставление | `matching` | Сопоставление пар | |
||||
| Порядок элементов | `ordering` | Расстановка в правильном порядке | |
||||
|
||||
--- |
||||
|
||||
## API Endpoints (рекомендуемые) |
||||
|
||||
### Тесты |
||||
- `GET /api/tests` - Список тестов |
||||
- `POST /api/tests` - Создать тест |
||||
- `GET /api/tests/{id}` - Получить тест с вопросами |
||||
- `PUT /api/tests/{id}` - Обновить тест |
||||
- `DELETE /api/tests/{id}` - Удалить тест |
||||
|
||||
### Вопросы |
||||
- `GET /api/tests/{test_id}/questions` - Список вопросов |
||||
- `POST /api/tests/{test_id}/questions` - Добавить вопрос |
||||
- `PUT /api/questions/{id}` - Обновить вопрос |
||||
- `DELETE /api/questions/{id}` - Удалить вопрос |
||||
|
||||
### Назначения |
||||
- `GET /api/assignments` - Список назначений |
||||
- `POST /api/assignments` - Назначить тест |
||||
- `GET /api/employees/{id}/assignments` - Назначения сотрудника |
||||
|
||||
### Прохождение |
||||
- `POST /api/tests/{id}/start` - Начать тест |
||||
- `POST /api/attempts/{id}/answer` - Ответить на вопрос |
||||
- `POST /api/attempts/{id}/complete` - Завершить тест |
||||
|
||||
### Отчеты |
||||
- `GET /api/reports/department` - Отчет по отделениям |
||||
- `GET /api/reports/employee/{id}` - Отчет по сотруднику |
||||
- `GET /api/reports/category/{id}` - Отчет по категории |
||||
- `GET /api/reports/export` - Экспорт отчета (PDF/Excel) |
||||
@ -0,0 +1,73 @@
|
||||
# Спринт 2 — тестирование (AI-помощники) |
||||
|
||||
**Состояние продукта:** [../PROJECT_STATUS.md](../PROJECT_STATUS.md) · чек-лист импорта и API — ниже. |
||||
|
||||
**Предпосылка:** спринт 1 (версии) принят. |
||||
**Секреты:** для стенда допускается отдельный ключ DeepSeek; в логах/скриншотах **не** светить полный ключ. |
||||
|
||||
**MVP 2026-04 (импорт + LLM, до полного спринта 2):** в `backend` задать `DEEPSEEK_API_KEY` *или* `OPENAI_API_KEY` → `POST /api/tests/import/document` при загрузке файла возвращает `generation.draft` → в карточке теста, блок «Импорт из файла», кнопка **«Применить сгенерированный черновик»** → затем **«Сохранить черновик»**. Юнит-тесты: `documentGenService.test.js`. |
||||
|
||||
--- |
||||
|
||||
## 1. Автоматизировано и self-check (разработка) |
||||
|
||||
_Отмечайте [ ] → [x] по мере выполнения._ |
||||
|
||||
### 1.1 Безопасность и API |
||||
|
||||
- [ ] Эндпоинты настроек не возвращают сырой ключ на клиент |
||||
- [ ] Ошибка при отсутствии/невалидном ключе — структурированная, с кодом/текстом для UI |
||||
- [ ] «Проверить подключение» при валидном ключе — успех; при фейле — сообщение об ошибке сети/401 и т.д. |
||||
|
||||
### 1.2 Моки / контракты (по возможности) |
||||
|
||||
- [ ] Парсинг JSON-ответов LLM: при невалидном JSON — пользователю сообщение, не 500 без текста |
||||
- [ ] Unit-тесты маппинга «ответ LLM → черновик теста/вопроса» (на фикстурах) |
||||
|
||||
### 1.3 Смоук перед передачей |
||||
|
||||
- [ ] Сгенерировать тест: только с названием; превью; применить — вопросы в редакторе |
||||
- [ ] Проверить тест: модалка с текстом |
||||
- [ ] Улучшить вопрос: чекбоксы, применение частично |
||||
- [ ] Дистракторы: к существующим ответам добавилось 3 варианта |
||||
- [ ] После применения AI-изменений сохранение теста согласовано с правилами **версий** (если были попытки) |
||||
|
||||
--- |
||||
|
||||
## 2. Ручная приёмка (я / заказчик) |
||||
|
||||
### 2.1 Настройки |
||||
|
||||
- [ ] Сохранить ключ, обновить страницу — приложение не показывает ключ, но AI-функции работают |
||||
- [ ] Очистить/испортить ключ — AI показывает ошибку и **есть** переход/ссылка на настройки |
||||
- [ ] «Проверить подключение» отражает реальное состояние (успех/ошибка) |
||||
|
||||
### 2.2 Уровень теста |
||||
|
||||
- [ ] **Сгенерировать тест** недоступен при пустом названии; при заполненном — выдаёт осмысленный черновик, применяется **целиком** по кнопке |
||||
- [ ] **Проверить тест** — рекомендации читаемы, модалка закрывается, данные теста не портит без явного применения |
||||
- [ ] **Предложить улучшение** — сравнение было/стало, выбор чекбоксами, применяется только отмеченное |
||||
|
||||
### 2.3 Уровень вопроса |
||||
|
||||
- [ ] **Улучшить вопрос** — нет молчаливой перезаписи; подтверждение через чекбоксы/применить |
||||
- [ ] **Дистракторы** — три новых **не** заменяют старые ответы |
||||
- [ ] **Сгенерировать подсказку** — текст появляется в поле, можно отредактировать и сохранить |
||||
|
||||
### 2.4 Версионирование + AI (регресс) |
||||
|
||||
- [ ] На тесте **без** попыток: массовое применение AI не создаёт лишних версий бессмысленно (ожидание как в спринте 1) |
||||
- [ ] На тесте **с** попытками: осмысленные сохранения ведут себя по правилам 4.1 (новая версия при изменении) |
||||
|
||||
### 2.5 Дизайн |
||||
|
||||
- [ ] Кнопки, модалки, превью, состояния загрузки/ошибок **визуально** в одном ряду с остальным модулем (как спринт 1) |
||||
|
||||
### 2.6 Качество UX |
||||
|
||||
- [ ] Долгий ответ LLM: индикатор ожидания, нельзя «задвоить» запросы без контроля |
||||
- [ ] Понятные сообщения при сбое сети или API DeepSeek |
||||
|
||||
--- |
||||
|
||||
**Итог приёмки спринта 2:** дата __________, комментарий _________________________ |
||||
@ -0,0 +1,65 @@
|
||||
# Спринт 2 — Редактор тестов: AI-помощники (desktop web) |
||||
|
||||
**Формат:** отдельное веб desktop-приложение (этап 1, фича §4.2). |
||||
**Граница спринта:** начинается **после** приёмки спринта 1; заканчивается готовностью **всех** функций AI-помощника из ТЗ (настройки ключа, проверка подключения, сценарии уровня теста и уровня вопроса) на базе **DeepSeek** и сохранения **идентичности дизайна** с остальным приложением. |
||||
**Предпосылка:** версионирование (спринт 1) работает; сгенерированные/изменённые черновики сохраняются в модель **текущей редактируемой версии** согласно правилам 4.1. |
||||
|
||||
**Стек (целевой в ТЗ):** Python, FastAPI — **в репозитории TestingWebApp фактически Node.js + Express**, LLM через HTTP (OpenAI-совместимый API, в т.ч. DeepSeek); ключ в окружении или (в целевом виде спринта) в БД, не на клиенте. Сводка MVP: [../PROJECT_STATUS.md](../PROJECT_STATUS.md). |
||||
|
||||
--- |
||||
|
||||
## Цель спринта |
||||
|
||||
Реализовать **§4.2 ТЗ**: интеграция DeepSeek, страница настроек, все табличные функции уровня теста и вопроса, обработка отсутствия ключа, UI с превью и подтверждением (без «тихой» перезаписи там, где ТЗ требует сравнения с чекбоксами). |
||||
|
||||
--- |
||||
|
||||
## Функции (контрольный список из ТЗ) |
||||
|
||||
### Интеграция и настройки |
||||
|
||||
- Ключ DeepSeek на `/settings`, хранение в БД, не отдаётся на фронт |
||||
- «Проверить подключение» — тестовый запрос |
||||
- Все AI-действия при отсутствии ключа — понятная ошибка + ссылка на настройки |
||||
|
||||
### Уровень теста |
||||
|
||||
| Функция | Критерий | |
||||
| --- | --- | |
||||
| Сгенерировать тест | Только при заполненном названии; превью; применение целиком | |
||||
| Проверить тест | Модалка с рекомендациями | |
||||
| Предложить улучшение всего теста | Постатейно было → стало, чекбоксы, применение выбранного | |
||||
|
||||
### Уровень вопроса |
||||
|
||||
| Функция | Критерий | |
||||
| --- | --- | |
||||
| Улучшить вопрос | Модалка, было/стало по частям, чекбоксы, **без** прямой замены без подтверждения | |
||||
| Дистракторы | +3 неправдоподобных варианта **добавляются**, не заменяют | |
||||
| Сгенерировать подсказку | Текст в поле подсказки; автор правит/удаляет (связь с §4.4 в следующих спринтах) | |
||||
|
||||
--- |
||||
|
||||
## Технические подзадачи |
||||
|
||||
| # | Задача | |
||||
| --- | --- | |
||||
| 1 | Модель настроек (ключ), API save/test, маскирование в ответах | |
||||
| 2 | Промпты и контракты JSON для каждой функции; валидация ответа LLM | |
||||
| 3 | Эндпоинты/сервисы: 6 сценариев + единая обёртка ошибок/квот | |
||||
| 4 | UI: кнопки в редакторе, модалки, превью «сгенерировать тест», дифы с чекбоксами | |
||||
| 5 | Соблюдение правил 4.1 при сохранении применённых AI-изменений | |
||||
| 6 | Логи без утечки ключа; rate-limit/таймауты по best effort | |
||||
|
||||
--- |
||||
|
||||
## Вне спринта 2 |
||||
|
||||
- Медиа (§4.3), полноценное поведение подсказок в прохождении (§4.4 + §4.5) — отдельные спринты, если не входят в минимум для кнопки «подсказка» в редакторе |
||||
- Дашборды (этап 2 ТЗ), HR-интеграция, MAX |
||||
|
||||
--- |
||||
|
||||
## Документ тестирования |
||||
|
||||
Чек-лист: `sprint-02-testing.md`. |
||||
@ -0,0 +1,8 @@
|
||||
# Пошаговая спецификация (`docs/шаги/`) |
||||
|
||||
Файлы **01**–**11** — **проектные шаги** (целевое поведение и API), а не автоматическая копия кода. Фактическое состояние фич, сценарии «как у пользователя» и ветка **`dev`** описаны в: |
||||
|
||||
- [../PROJECT_STATUS.md](../PROJECT_STATUS.md) — что сделано и что в планах; |
||||
- [../DEV_CONTOUR_USER_GUIDE.md](../DEV_CONTOUR_USER_GUIDE.md) — инструкция для проверки на dev-стенде. |
||||
|
||||
Журнал приёмки: [../revision_task/TESTING_JOURNAL.md](../revision_task/TESTING_JOURNAL.md). |
||||
Loading…
Reference in new issue