Тренажер знаний ГЦО — архитектура и запуск

AI-платформа обучения и тестирования сотрудников Группы цифрового обслуживания по внутренним документам (Red Policy, Tone of Voice).

Репозиторий: https://github.com/jokhacom/final_project Сайт: https://final-project-lac-tau.vercel.app Статус: развёрнут на Vercel, база данных на Supabase, регистрация и вход работают.

Отдельный демо-проект (trenaszer-test-1.vercel.app, репозиторий jokhacom/trenaszer-test) — это самостоятельная презентационная версия без базы данных. К основному проекту она не относится, из неё берётся только дизайн.

Стек

• Next.js 15 (App Router) — фронтенд и API routes в одном проекте
• PostgreSQL (Supabase) + Prisma 5 — единая схема данных
• NextAuth v4 — вход по логину и паролю (JWT-сессии, роль хранится в токене)
• AI-провайдер за интерфейсом — AIProvider: Gemini (есть бесплатный лимит), Claude (официальный SDK) и OpenAI. Промпты общие (src/lib/ai/prompts.ts). Основной провайдер — AI_PROVIDER, остальные с заданным ключом работают как запасные (src/lib/ai/index.ts)
• Хостинг: GitHub → Vercel; БД: Supabase

Роли

Роль	Как получить	Доступ
EMPLOYEE	Самостоятельная регистрация на главной странице	Тесты, личный кабинет, рейтинг
ADMIN	Выдаёт суперадмин: «Админ» → «Обзор» → «Сотрудники» → роль «Администратор»	/admin/*
SUPERADMIN	Логин javokhir, создаётся один раз через /api/setup/seed	Всё, включая управление материалами

src/middleware.ts пускает на страницы только вошедших, а в /admin/* — только ADMIN и SUPERADMIN. API проверяет сессию сам (src/lib/session.ts): кто отвечает на тест, берётся из сессии, а не из тела запроса. Загрузка и анализ документов, генерация вопросов и настройки доступны только SUPERADMIN; банк вопросов, аналитика, выгрузка, обратная связь и «Что нового» — ADMIN и SUPERADMIN.

Развёртывание (GitHub → Supabase → Vercel)

1. GitHub

Код лежит в репозитории GitHub. Любой пуш в main запускает новую сборку на Vercel.

2. Supabase

1. Создайте проект Supabase и запомните пароль базы данных.
2. В разделе подключения возьмите две строки (pooler):
   • Transaction pooler (порт 6543) → DATABASE_URL, в конце добавьте ?pgbouncer=true
   • Session pooler (порт 5432) → DIRECT_URL
3. Бесплатный проект Supabase засыпает при простое. Если сайт пишет tenant/user not found или Can't reach database server, откройте проект в Supabase и нажмите Restore.

3. Vercel

1. Импортируйте репозиторий в Vercel (Framework: Next.js).
2. В Settings → Build & Development включите Override для Build Command:

   prisma generate && prisma db push --accept-data-loss && next build
   

   Так таблицы в базе создаются автоматически при каждой сборке (миграции не используются). Та же команда записана в package.json как скрипт vercel-build, поэтому Override можно и не включать.
3. В Settings → Environment Variables добавьте переменные (для всех окружений):

Переменная	Назначение
DATABASE_URL	Строка Transaction pooler (6543, ?pgbouncer=true)
DIRECT_URL	Строка Session pooler (5432)
NEXTAUTH_URL	Основной адрес сайта, например https://final-project-lac-tau.vercel.app
NEXTAUTH_SECRET	Длинная случайная строка
SETUP_SECRET	Секрет для одноразового создания суперадмина
AI_PROVIDER	Основной ИИ: gemini, anthropic или openai
GEMINI_API_KEY	Ключ Google AI Studio (есть бесплатный лимит). Модель — GEMINI_MODEL, по умолчанию gemini-2.5-flash
ANTHROPIC_API_KEY	Ключ Claude API. Модель — ANTHROPIC_MODEL, по умолчанию claude-haiku-5-5
OPENAI_API_KEY	Ключ OpenAI. Модель — OPENAI_MODEL
GRADING_MODE	Можно не задавать: если ключ ИИ есть — проверка через ИИ, если нет — по ключевым словам. keyword оставляет проверку без ИИ даже при наличии ключа
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, FEEDBACK_EMAIL	Пересылка обратной связи на почту (опционально, без них обращения видны в админ-панели)

После изменения переменных нужен Redeploy (Deployments → ⋯ → Redeploy).

4. Первый запуск: суперадмин

Откройте в браузере один раз:

https://<ваш-сайт>/api/setup/seed?secret=<SETUP_SECRET>&password=<новый пароль>

Будет создан суперадмин javokhir с указанным паролем. Повторный вызов ничего не изменит. Пароль потом можно сменить в «Кабинет» → «Сменить пароль».

Управление сотрудниками

Суперадмин в «Админ» → «Обзор» → «Сотрудники» может сменить роль (сотрудник / администратор), сбросить забытый пароль (🔑) и удалить сотрудника вместе с его результатами. Удалённый сотрудник сразу теряет доступ, смена роли действует без повторного входа. Суперадмина изменить или удалить нельзя.

Если при регистрации приходит 409, такой логин уже существует. Логин: 3–32 символа, латинские буквы, цифры, ., -, _.

5. Наполнение вопросами (ИИ не нужен)

Для теста нужно минимум 10 вопросов на уровень (лучше 5 с вариантами + 5 со свободным ответом). Пока вопросов не хватает, карточка уровня у сотрудников отмечена «Скоро». Что уже готово, видно в «Админ» → «Обзор» → «Готовность к запуску».

• Импорт из Excel: «Админ» → «Вопросы» → «Скачать шаблон» → заполнить → «Загрузить». Если в файле есть ошибки, ничего не сохраняется, а ошибки показываются по номерам строк.
• Вручную: «Админ» → «Вопросы» → «Добавить вручную».
• Уровень открыт у сотрудников, как только в нём есть хотя бы 1 вопрос; в тест попадает min(сколько есть, настройка «вопросов в тесте»).
• Архив: «🗄 В архив» убирает вопрос из тестов, но хранит его; во вкладке «Архив» — «↩ Вернуть в тесты» или «Удалить навсегда».
• К любому вопросу можно прикрепить скриншот (сжимается в браузере), а к открытым — эталонный ответ: он показывается сотруднику в разборе, по нему проверяет ИИ, а без ИИ ответ засчитывается, если совпадает примерно треть его слов (или есть хотя бы одно ключевое слово, если они заданы).
• Документы можно загрузить в «Материалы» заранее — анализ станет доступен после подключения ИИ.

Проверка открытых ответов и лимит попыток

• Во время теста открытые ответы только сохраняются — сотрудник сразу переходит к следующему вопросу. При «Завершить тест» все открытые ответы проверяются одновременно (по 5 за раз), затем показывается итог и разбор.
• Суперадмин задаёт в «Обзор» → «Настройки», сколько раз сотрудник может пройти каждый уровень (0 — без ограничений; считаются все начатые попытки, администраторов лимит не касается). Карточка уровня показывает «Осталось попыток» или «🔒 Попытки закончились». Кнопка 🔄 у сотрудника в списке сбрасывает счётчик (история результатов сохраняется).

Ручная проверка ответов

«Админ» → «Проверка»: открытые ответы сотрудников с уже поставленной автоматической оценкой (по ключевым словам, эталонному ответу или ИИ). Администратор подтверждает или исправляет её: верно/неверно, число орфографических и грамматических ошибок, комментарий. «Конфеты» попытки, рейтинг и достижения пересчитываются сразу, а сотрудник видит в разборе пометку «проверено» и комментарий. Сколько ответов ждут проверки, видно на «Обзоре».

6. Подключение ИИ (когда будете готовы)

Код менять не нужно — только переменные в Vercel и Redeploy. Рекомендуемая схема — бесплатный Gemini основным и Claude Haiku 5.5 запасным:

• AI_PROVIDER=gemini
• GEMINI_API_KEY — ключ из Google AI Studio
• ANTHROPIC_API_KEY — ключ из console.anthropic.com (запасной)

Запрос сначала уходит в Gemini. Если он не ответил — закончился бесплатный лимит (429) или сбой — тот же запрос автоматически отправляется в Claude Haiku 5.5. После ответа «лимит исчерпан» Gemini 15 минут пропускается, потом сайт снова пробует его первым. Если не ответил никто, открытый ответ проверяется по ключевым словам, тест не ломается. Какая цепочка включена, видно в «Админ» → «Обзор». Можно указать только один ключ — тогда работает только этот провайдер.

После Redeploy сразу включатся: проверка открытых ответов по смыслу, орфографии и грамматике (−1 🍬 за ошибку), анализ документов в «Материалах», генерация и перегенерация вопросов. Без ИИ ответы проверяются по ключевым словам, орфография не учитывается.

Локальный запуск

npm install
cp .env.example .env   # заполнить DATABASE_URL, DIRECT_URL, NEXTAUTH_SECRET, SETUP_SECRET
npx prisma db push
npm run dev

База знаний ИИ

Цепочка источника: Document (Material) → Topic → Rule → Question.

• Topic, Rule — ИИ читает документ и выделяет темы и правила (REQUIRED, FORBIDDEN, RECOMMENDED, EXAMPLE_GOOD, EXAMPLE_BAD) с цитатой источника.
• Версии документов: Material.version, supersedesId, isActive. Старые вопросы остаются привязаны к старой версии.
• Типы вопросов: MULTIPLE_CHOICE, OPEN, FIND_ERROR, FIX_MESSAGE, BEST_RESPONSE. Уровни: Новичок, Middle, Professional, EXAM. Итоговый экзамен (EXAM) — отдельное задание со своими вопросами: они не берутся из других уровней и не создаются автоматически (добавьте вручную, через Excel с уровнем «Экзамен» или кнопкой «+ Экзамен» у темы).
• Проверка открытого ответа идёт строго по правилу, к которому привязан вопрос, с объяснением решения. Если ИИ недоступен, работает проверка по ключевым словам.

Большие документы и книги

Документ любого размера ИИ читает целиком: текст режется на части примерно по 8 000 символов (≈4 страницы, по границам абзацев, src/lib/parsing/chunks.ts), каждая часть разбирается отдельным запросом, темы с одинаковым названием из разных частей объединяются. Кнопка «🤖 Создать тесты» в «Материалах» делает всё сама: анализ всех частей → вопросы по каждой теме для трёх уровней (сколько на тему — задаётся, по умолчанию 4) с прогрессом на экране. Повторное нажатие создаёт только недостающие вопросы. Шаги идут из браузера по одному запросу к ИИ, поэтому не упираются в лимит времени функций Vercel; страницу нельзя закрывать, пока идёт обработка. Проверка открытого ответа опирается на правила темы вопроса, а не на начало документа.

Чтобы каждый запрос укладывался в 60 секунд функции Vercel, при разборе документа и создании вопросов/игр ИИ отвечает в быстром режиме (Gemini flash — без «размышлений», Claude — effort: low), а обрезанный ответ не теряется: сайт берёт все темы и вопросы, пришедшие целиком. Проверка ответов сотрудников идёт в обычном режиме.

Язык вопросов и игр выбирается в «Материалы» → «Настройки создания»: «Как в документе» (узбекский документ → узбекские вопросы, русский → русские), «Русский» или «Oʻzbekcha (lotin)». Узбекский текст ИИ пишет по правилам современной орфографии (как в словаре imlo.uz: oʻ, gʻ, ʼ). Темы и правила документа сохраняются на языке документа, комментарий к проверке открытого ответа — на языке ответа сотрудника. Интерфейс сайта пока только на русском.

Ограничения: файл до ~4 МБ (лимит запроса Vercel), PDF должен содержать текст, а не сканы.

Обучение: презентации и игры

Раздел «📖 Обучение» для сотрудников: готовые презентации и три игры для закрепления правил — «Можно или нельзя?» (реплика сотрудника клиенту: допустима ли она, с объяснением), «Найди и исправь ошибку» (скриншот чата или сообщение с ошибкой → сотрудник пишет исправленный вариант и сравнивает с правильным; конфеты не снимаются) и «Грамотность» (русский или узбекский язык — отдельными раундами: предлоги, окончания, суффиксы, слитно/раздельно, орфография, пунктуация, ударение; 10 вопросов, 10 секунд на каждый).

⌨️ Скорость печати (/typing, карточка в «Обучении») — тест в стиле monkeytype: русский, узбекский (oʻ, gʻ; апостроф ' засчитывается) и узбекский на новом алфавите (проект 2021 года: ó, ǵ, ş, ç — есть кнопки на экране). Режимы 15/30/60/120 с, скорость (слов в минуту), точность, личный рекорд и топ-10 (TypingResult).

«Грамотность» не зависит от документов: в «Админ» → «Обучение» → «Грамотность» есть кнопка «📚 Добавить готовые вопросы» (около 60 русских и 45 узбекских, src/lib/languageBank.ts; повторное нажатие не дублирует) и «🤖 Создать ИИ». Узбекские вопросы — по «Oʻzbek tilining asosiy imlo qoidalari» (oʻ, gʻ, tutuq belgisi ʼ). Любой вопрос можно добавить вручную, изменить или удалить. Старая игра «Карточки» убрана из интерфейса.

• Презентации загружает администратор в «Админ» → «Обучение»: PDF или PowerPoint (.pptx, .ppt) до 100 МБ. PDF открывается прямо на сайте, PowerPoint — через просмотрщик Microsoft Office (встроен в страницу). Можно переименовать и удалить.
  • Для PowerPoint и файлов больше 4 МБ нужно хранилище файлов Vercel Blob (бесплатно в тарифе Hobby): Vercel → проект → Storage → Create Database → Blob → Connect к проекту (все окружения) → Redeploy. Vercel сам добавит переменные: в новых проектах BLOB_STORE_ID и BLOB_WEBHOOK_PUBLIC_KEY (вход без ключа), в старых — BLOB_READ_WRITE_TOKEN; сайт работает с обоими вариантами. Тип хранилища — Public. Браузер отправляет файл на сайт частями по 3 МБ (лимит запроса Vercel ~4,5 МБ), сайт собирает их и сохраняет в хранилище.
  • Без хранилища работает старый способ: только PDF до ~4 МБ, файл хранится в базе.
  • Файлы в хранилище доступны по длинной случайной ссылке (её видят только вошедшие сотрудники; просмотрщику Microsoft нужна открытая ссылка). Не загружайте презентации с секретными данными.
• Игры ИИ создаёт только по команде: «Материалы» → «🎮 Создать игры» у документа (по N элементов на тему; темы, где игры уже есть, пропускаются). «Создать тесты» игры не создаёт. В «Админ» → «Обучение» любой элемент игры можно добавить вручную, изменить или удалить.

Основные эндпоинты

Эндпоинт	Что делает
POST /api/materials/upload	Загрузка PDF/DOCX/TXT, извлечение текста
POST /api/materials/[id]/analyze	ИИ строит темы и правила по одной части документа ({chunk}), {finalize:true} — завершить
GET /api/materials/[id]/knowledge	Темы и правила документа
POST /api/questions/generate	Генерация вопросов по теме или правилу
POST /api/questions/manual	Ручное создание вопроса
PATCH/DELETE /api/questions/[id]	Правка и удаление вопроса
GET /api/questions/[id]/source	Цепочка вопрос → правило → тема → документ
POST /api/attempts/start	Старт теста: случайные вопросы, 15 минут. Правильные ответы в браузер не отдаются
POST /api/attempts/submit-mc	Ответ на вопрос с вариантами (MULTIPLE_CHOICE, BEST_RESPONSE)
POST /api/grade	Проверка ответа своими словами (OPEN, FIND_ERROR, FIX_MESSAGE)
POST /api/attempts/finish	Завершение теста: неотвеченные считаются неверными, конфеты, рейтинг, достижения, разбор
GET /api/attempts/[id]	Результат и полный разбор завершённого теста
/certificate/[attemptId]	Сертификат (более 90 «конфет»), сохраняется в PDF через печать. Старый GET /api/certificates/[attemptId] перенаправляет сюда
GET /api/me	Личный кабинет текущего сотрудника
GET /api/admin/users	Список сотрудников
PATCH/DELETE /api/admin/users/[id]	Роль, сброс пароля, удаление (только суперадмин)
POST /api/auth/change-password	Смена своего пароля (нужен текущий)
GET /api/admin/review, PATCH /api/admin/review/[answerId]	Ручная проверка открытых ответов

Дизайн и интерфейс

Дизайн реализован по описанию ниже: общие стили — src/app/globals.css, шапка — src/components/Header.tsx.

Стиль: игровой, «конфетный». Тёмная тема с фиолетовым фоном (#1B0B2E → #2A0F45) и светлая с нежно-розовым (#F6F0FF → #FDEBF3), переключатель тем. Шрифт Nunito. Кнопки и акценты — градиент фиолетовый → розовый (#7C4DFF → #FF6FA5). Заголовок «🍬 Тренажер знаний ГЦО», декоративные конфеты на фоне.

Цвета уровней:

Уровень	Цвет
🟢 Новичок	#00E5A0
🟡 Middle	#FFC93C
🔴 Professional	#FF6FA5
🎓 Итоговый экзамен (KPI)	#7C4DFF

Экраны:

1. Вход / регистрация.
2. Выбор уровня — карточки с подписью «10 вопросов · 15 мин · до 100 🍬». Число вопросов в тесте (любое; половина с вариантами, половина открытых; по умолчанию 10) и время (любое число минут, по умолчанию 15) меняются в «Админ» → «Обзор» → «Настройки».
3. Прохождение теста — полоска прогресса из сегментов (пройдено зелёным, текущий розовым), таймер (последние 10 секунд красным), 5 вопросов с вариантами и 5 открытых.
4. Экран ожидания: «Мы проверяем ваш ответ...» (не «Вас проверяет ИИ»).
5. Результат — сумма «конфет», итоговый уровень и полный разбор: по каждому вопросу видно, правильно ли ответил сотрудник, что он написал и какой ответ был нужен, с пояснением. Верный ответ отмечен зелёной галочкой, неверный красным крестиком.
6. Личный кабинет — история, достижения, слабые темы.
7. Таблица лидеров с кубком 🏆.
8. Плавающая кнопка обратной связи, раздел «Что нового», панель администратора.

Итоговые уровни результата:

«Конфеты»	Результат
95 и больше	Эксперт
85–94	Отлично
70–84	Хорошо
50–69	Нужно повторить материал
меньше 50	Требуется обучение

Правила подсчёта: максимум 100 «конфет», за неверный ответ −50/N (N — число вопросов в тесте: при 10 вопросах −5, при 20 — −2,5), −1 за орфографическую ошибку, −1 за грамматическую. Сертификат выдаётся при результате выше 90.

Достижения: например, «Эксперт ГЦО» 👑 — за 95 и больше «конфет» на уровне Professional.

Тексты вопросов: реальные кейсы из документов «Редполитика AVO» и «Редполитика для базы знаний» (задолженность, тарифы, хейт и т.п.), а не абстрактные формулировки.

Что реализовано

• Вход и регистрация по логину и паролю (bcrypt), три роли, проверка прав во всех API
• Загрузка документов (PDF/DOCX/TXT), база знаний (темы и правила), версии документов
• Генерация вопросов ИИ по теме, правилу или всему документу; ручное создание, импорт из Excel, правка, удаление и перегенерация
• Полная работа без ИИ: ИИ включается одним ключом в Vercel, чек-лист готовности в админке
• Пять типов заданий в интерфейсе: выбор ответа, лучший ответ клиенту, открытый вопрос, найди ошибку, исправь сообщение
• Экраны теста: выбор уровня, вопросы с таймером и сегментной полосой прогресса, экран «Мы проверяем ваш ответ...», результат с полным разбором
• Проверка ответов ИИ строго по правилу и материалу (Claude, Gemini или OpenAI), запасная проверка по ключевым словам
• «Конфеты», итоговые уровни, достижения, рейтинг с кубком, личный кабинет со слабыми темами
• Сертификат (кириллица, печать в PDF), Excel-экспорт с фильтром по сотруднику и датам
• Запрет копирования и вставки в открытых ответах (ProtectedTextarea)
• Тёмная и светлая темы, адаптивная вёрстка для телефона
• Обратная связь, «Что нового», аналитика (сложные вопросы, слабые темы, результаты по уровням)

Что ещё не готово

• Программа обучения по дням
• AI-симулятор клиента, XP и уровни, адаптивное обучение поверх WeakTopic
• Интерфейс для ежедневного мини-теста (переключатель и API /api/daily-quiz есть, отдельного экрана нет)

Скорость

Серверные функции Vercel работают в регионе sin1 (Сингапур, vercel.json) — рядом с базой Supabase (ap-southeast-1). Если база будет перенесена в другой регион, поменяйте regions на ближайший к ней (например fra1 для Франкфурта), иначе каждый запрос к базе будет идти через полмира.

Частые проблемы

Симптом	Причина и решение
Can't reach database server / tenant/user not found	Проект Supabase на паузе или неверный DATABASE_URL. Восстановите проект, проверьте строку и сделайте Redeploy
Environment variable not found: DIRECT_URL	Переменная не добавлена или добавлена не в то окружение. Добавьте и сделайте Redeploy
Сборка идёт без создания таблиц	Не включён Override у Build Command
Invalid URL на /_not-found	Не задан NEXTAUTH_URL
404 на новой странице	Файл лежит не по пути src/app/..., либо открыт адрес старого деплоя. Используйте основной домен
Регистрация возвращает 409	Логин уже занят
Сайт медленно открывается	Регион функций Vercel далеко от базы — см. раздел «Скорость». Первый запрос после простоя всегда чуть дольше