Тренажер знаний ГЦО — архитектура и запуск
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
- Создайте проект Supabase и запомните пароль базы данных.
- В разделе подключения возьмите две строки (pooler):
- Transaction pooler (порт
6543) → DATABASE_URL, в конце добавьте ?pgbouncer=true
- Session pooler (порт
5432) → DIRECT_URL
- Бесплатный проект Supabase засыпает при простое. Если сайт пишет
tenant/user not found или Can't reach database server, откройте проект в Supabase и нажмите Restore.
3. Vercel
- Импортируйте репозиторий в Vercel (Framework: Next.js).
- В Settings → Build & Development включите Override для Build Command:
prisma generate && prisma db push --accept-data-loss && next build
Так таблицы в базе создаются автоматически при каждой сборке (миграции не используются). Та же команда записана в package.json как скрипт vercel-build, поэтому Override можно и не включать.
- В 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=geminiGEMINI_API_KEY — ключ из Google AI StudioANTHROPIC_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 |
Экраны:
- Вход / регистрация.
- Выбор уровня — карточки с подписью «10 вопросов · 15 мин · до 100 🍬». Число вопросов в тесте (любое; половина с вариантами, половина открытых; по умолчанию 10) и время (любое число минут, по умолчанию 15) меняются в «Админ» → «Обзор» → «Настройки».
- Прохождение теста — полоска прогресса из сегментов (пройдено зелёным, текущий розовым), таймер (последние 10 секунд красным), 5 вопросов с вариантами и 5 открытых.
- Экран ожидания: «Мы проверяем ваш ответ...» (не «Вас проверяет ИИ»).
- Результат — сумма «конфет», итоговый уровень и полный разбор: по каждому вопросу видно, правильно ли ответил сотрудник, что он написал и какой ответ был нужен, с пояснением. Верный ответ отмечен зелёной галочкой, неверный красным крестиком.
- Личный кабинет — история, достижения, слабые темы.
- Таблица лидеров с кубком 🏆.
- Плавающая кнопка обратной связи, раздел «Что нового», панель администратора.
Итоговые уровни результата:
| «Конфеты» | Результат |
|---|
| 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 далеко от базы — см. раздел «Скорость». Первый запрос после простоя всегда чуть дольше |
