Career Quest

Career Quest recommends not the weakest skill, but the next best career move.

AI-навигатор развития сотрудника: по профилю, истории участия и требованиям следующего грейда система подбирает 1–3 шага развития, объясняет каждый минимум по трём факторам и показывает, как сдвинется карьерная готовность — до того, как человек потратит на это время.

HackAlem AI · трек Halyk Bank · кейс Career Quest Команда: Алихан (Intelligence), Манахнбет (Experience), Даник (Trust)

Employee, HR, Trust и Skill Exchange используют общую демо-идентификацию. Адреса / и /demo перенаправляют в кабинет сотрудника /employee.

Почему наше решение другое

Decision Engine	Многофакторный детерминированный выбор: разрыв по навыкам с приоритетом критичных, история участия, выполнимость, цель, разнообразие. Не один prompt и не «самый низкий навык».
Digital Twin	Карьерный эффект виден до выполнения активности: what-if по уровням и readiness, план на несколько шагов, подтверждение с пересчётом.
Trust Center	У каждого решения есть Evidence Receipt. Баг-репорт на сам AI: нарушения eligibility, подтверждённость чисел, корректность пересчёта истории, latency, поведение без LLM.
Внешнее обучение	Отдельный offline-каталог для разрывов без доступной внутренней активности; без выдуманного прироста и без влияния на рекомендации или readiness.

Быстрый старт

pnpm install --frozen-lockfile
pnpm dev

Открыть http://localhost:3000, нажать «Посмотреть демо» и выбрать синтетический профиль. Сервер устанавливает подписанную cookie: сотруднику отдаётся только его профиль и история, HR-профилю — организационный набор для аналитики. Выбор демо-персоны не является корпоративным входом или SSO.

В навигации доступны «Моя траектория», «HR-аналитика», «Проверка решений» и «Обмен навыками» (/chat). Кнопки «Сотрудник» / «HR» открывают нужный кабинет; для HR требуется выбор HR-профиля. Собственные файлы можно импортировать локально через экран сотрудника — они остаются в браузере.

Общий переключатель «Язык» в верхней панели меняет интерфейс, форматы чисел и дат и язык AI-объяснений: Қазақша (kk) / Русский (ru) / English (en). Выбор сохраняется в браузере и восстанавливается после перезагрузки. Язык интерфейса не зависит от preferred_language выбранного сотрудника: смена профиля его не меняет.

Docker:

docker compose up --build

Для production без Docker: pnpm build, затем pnpm start. pnpm start и Docker при пустом SESSION_SECRET создают и сохраняют ключ демо-сессий в data/runtime/session-secret; можно задать свой секрет от 32 байт. В dev ключ живёт в процессе: после перезапуска нужно снова выбрать профиль. Runtime-каталог исключён из Git и Docker build context; Compose сохраняет его в volume.

Если опциональные LLM-переменные заданы в .env.local, передать их Compose явно:

docker compose --env-file .env.local up --build

LLM-ключ не обязателен. Без него приложение работает полностью: тот же ranking и детерминированные объяснения. Ключ включает bounded-критика и HR-агента поверх вычисленных фактов. Переменные — в .env.example.

Требуется Node 22 и pnpm (corepack enable).

Настройка AI для демо

Скопировать .env.example в .env.local рядом с package.json, если файла ещё нет (cp .env.example .env.local или PowerShell Copy-Item .env.example .env.local). Действующий ключ задаётся локально как LLM_API_KEY; альтернативно сервер читает OPENAI_API_KEY из окружения ОС. Непустой LLM_API_KEY имеет приоритет. Значения по умолчанию: https://api.openai.com/v1, gpt-4.1-mini. Для другого OpenAI-compatible провайдера задать его URL и модель явно. После изменения окружения перезапустить сервер; ключи не входят в Git или Docker image.

Compose передаёт переменные при запуске: docker compose --env-file .env.local up --build. Bounded-критик использует LLM_TIMEOUT_MS=2500 (100–3000 мс); HR Agent — отдельный LLM_AGENT_TIMEOUT_MS=10000 на обращение к модели.

Для проверки выбрать HR-персону и открыть /hr. Статус /api/ai/agent доступен только подписанному HR: available означает наличие конфигурации, не успешный вызов провайдера. Полный AI-сценарий подтверждается ответом на вопрос и пройденной проверкой фактов; ошибка доступа/сети/лимита остаётся видимой. Без обоих ключей работает fallback. Live-проверка ключа, описанная в PR #15, относится к машине автора и не заменяет проверку настроек текущего запуска; здесь аудит не отправляет платные запросы.

Демо-сценарий

Выбрать демо-профиль E0028: System Design после replay равен 3, EV_006 повторно не предлагается. Примерить и подтвердить Leadership Foundations: readiness 74% → 78%. Открыть HR: число добровольных завершений увеличится с 1044 до 1045. Открыть Trust и запустить проверки; затем вернуться к сотруднику — профиль и журнал сохранятся.

Полный скрипт: docs/DEMO.md.

Skill Exchange

Поиск наставников помогает закрывать разрывы через опыт коллег. Доступны фильтры по навыку, отделу, роли и готовности помогать; карточка показывает только имя, роль, грейд, уровень запрошенного навыка и доступность. Можно отправить запрос, принять или отклонить его, переписываться и закрыть диалог.

На snapshot 2026-10-01 у 125 из 200 сотрудников есть хотя бы один критичный разрыв без доступной сейчас активности с положительным effective gain: 188 пар «сотрудник — навык». Методика и границы этой метрики — в docs/EVALUATION.md.

Переписка сохраняется на сервере в JSON-файле, включая непрочитанные и доступность. Сообщения — обычный текст до 2000 символов; лимит — 20 сообщений в минуту на identity. Обновления опрашиваются каждые 3 секунды в видимой вкладке. Для двух участников используйте разные профили браузера или приватное окно: обычные вкладки делят cookie.

Поиск по локальному импорту работает в браузере; серверный чат использует только встроенный набор и выбранную демо-идентификацию. Подробности и приёмка: docs/SKILL_EXCHANGE.md.

Дополнительные профили жюри

Загрузчик принимает 1–4 файла с режимами «Дополнить» / «Заменить». Профили и историю с нестандартными именами распознаёт по содержимому; неоднозначный тип выбирается вручную. Недостающие части берутся из текущего набора. Слияние проходит общую валидацию, показывает сводку добавлений/обновлений, отклонённых строк и переход к новым профилям. Лимит — 10 МБ на файл; BOM и CRLF поддерживаются. Без загруженной базы нужны все четыре части. Дополнение использует свежий normalized snapshot: подтверждённые навыки и история входят в новый набор без повторного gain. Журнал, preview и план импорта сбрасываются — UI сообщает об этом заранее.

База дополнения ограничена текущим доступом: employee demo содержит собственный профиль, HR demo — организационный набор. Фикстура fixtures/judge/judge_profiles.json добавляет три профиля; результат 200 → 203 относится к полному исходному набору, а не к private employee view. Импорт не превращает judge-профили в серверные chat identities. При переходе в чат импорт сохраняется; автор переписки явно указан как подписанная demo-персона. После reload локальный импорт сбрасывается и возвращается доступный demo-набор.

Внешнее обучение

Если для разрыва нет доступного внутреннего шага, раскрываемый блок «Внешние курсы» предлагает варианты из локального курируемого data/external_courses.json (35 записей). Подбор учитывает уровень, предпочитаемый язык профиля, бесплатность и длительность. UI показывает источник, языки, длительность и пометку «бесплатно/платно»; HR — потенциальную аудиторию по языку и подходящему уровню без персонального рейтинга. Employee показывает первые три направления и до трёх курсов на навык; HR-блок относится ко всей организации и скрывается при фильтрации аналитики по роли.

Внешние курсы не участвуют в top-3, score или readiness, не начисляют подтверждённый прирост и не записываются в ledger. Каталог работает без provider API и scraping; ссылки проверяются по HTTPS и allowlist доменов. Доступность и стоимость на стороне провайдера не проверяются в реальном времени. Эффект курса не подтверждён данными компании.

Архитектура

Экономика развития

В кабинете сотрудника доступен личный баланс по добровольным завершениям, каталог демо-наград, добровольные вызовы и отказ от участия. Обязательные события не дают баллов; публичного рейтинга нет. Баланс выводится из истории и текущего ledger, подтверждённое событие не учитывается дважды.

Это демо-механика без оплаты или выдачи наград: обмен, принятые вызовы и opt-out сохраняются только до ухода со страницы или нового импорта и не передаются HR. Чат пока не начисляет баллы за наставничество или благодарности. Данные правил и каталога версионированы в data/gamification_rules.json и data/rewards.json.

Общий поток

Next.js + TypeScript. Согласованный интерфейс на RU/KK/EN использует AppProviders, IdentityProvider и один sharedEmployeeStore. Сервер ограничивает demo dataset выбранной identity: свой профиль для сотрудника, полный набор для HR. Журнал развития хранится в памяти; demo snapshots восстанавливаются при повторном выборе персоны в текущей вкладке. Прогресс локального импорта отделён от demo.

Import (Zod) -> NormalizedDataset -> history replay -> target gaps
   -> hard filters -> multi-factor ranking -> Evidence Receipt
        ├─> Employee Digital Twin (what-if, planner, ledger)
        ├─> HR Command Center (агрегаты, no-step alerts)
        └─> AI Trust Center (baseline, evals, fallback)

Для объяснений текущий UI обращается к /api/ai/explain: передаёт язык интерфейса и ограниченные числовые evidence-факты по кандидатам, включая импортированные наборы. Сохранённый /api/ai/review принимает только ID и восстанавливает evidence на сервере из встроенного набора; доступ разрешён к собственному профилю либо HR. Контракты этих endpoints различаются.

Модули из принятого main 0d068536 объединены с Skill Exchange и согласованным UI. Альтернативные CareerQuestStore, IndexedDB и старый XP-модуль не подключены к активным страницам; новый DevelopmentEconomy использует текущий normalized store. Private Employee projection теперь применяется сервером при выдаче demo dataset. Переписка хранится отдельно от карьерного ledger в data/runtime/messages.json.

HR Agent и участие

HR видит фактическое участие за 6 и 12 месяцев: добровольные активности, инициатора участия, пропуски/отказы/выходы и отдельно обязательные процессы. Это операционный срез, не прогноз увольнения или публичный рейтинг.

HR Agent использует шесть инструментов только для чтения текущего snapshot, максимум пять вызовов на запуск. /api/ai/agent требует подписанную HR identity и ограничивает размер тела, частоту и одновременные обращения. Клиент проверяет числовые ответы относительно фактических результатов инструментов. Без ключа панель явно сообщает об отсутствии AI; обычные HR-таблицы продолжают работать.

Вопрос и разрешённые числовые факты/ID передаются модели; их происхождение из локального импорта сервер не восстанавливает. Свободный текст агента требует оценки HR.

Подробно: docs/ARCHITECTURE.md · контракты: docs/CONTRACTS.md · данные: docs/DATASET.md.

Как считается рекомендация

Перед любым расчётом движок доигрывает историю: уровни в профиле актуальны на last_review_date, а всё завершённое позже ещё не учтено. В стартовом наборе 318 таких completed-записей; 202 записи у 114 сотрудников содержат заявленные эффекты навыков. После применения cap фактический положительный replay дают 186 записей у 111 сотрудников.

Hard-фильтры (до скоринга): mandatory, несоответствие роли/грейду, невыполненные prerequisites, уже пройденное (кроме recurring EV_036), нулевой effective gain, отсутствие будущей сессии.

Ранжирование:

Фактор	Вес
Target gap impact (critical skills ×2)	45%
Engagement fit (история, self vs assigned)	20%
Feasibility (prerequisites, формат, сессия)	15%
Goal alignment (в т.ч. cross-role цели)	10%
Path / diversity	10%

effective_gain = max(0, min(current + gain, max_level, 5) - current) — правило роста задано самим датасетом, не придумано нами.

Результаты проверки

Объединённая версия с актуальным main 4da973a (включая PR #13/#15) и Skill Exchange прошла 366/366 тестов в 43 файлах — PASS (2026-09-23). Production-сборка с полной проверкой TypeScript — PASS, Next.js 16.3.6, без предупреждений. Bootstrap прошёл 7 локальных процессных сценариев: генерация/повторное использование ключа, явная конфигурация, неверный ключ и отказ runtime-хранилища.

В браузере подтверждены двусторонняя переписка E0028 ↔ E0050, принятие, непрочитанные/прочтение, plain text и сохранение после reload; HR видит агрегаты без чужих диалогов. RU/KK/EN и экран 375 px без overflow проверены. Completion E0028 дал readiness 74% → 78%, HR — 1045 добровольных завершений; возврат к E0028 сохранил 78% и одну запись ledger. Ошибок/warnings console нет. Polling проверен unit-тестами; delivery без ручного refresh отдельно не измерялась. Импорт жюри в браузере: HR-набор 200 → 203 профиля, +4 записи истории, 2 отклонённые строки с причинами; J0001 открывается с readiness 58% и межролевой целью Product Manager Middle. Переход chat → employee сохраняет импортированные 203 профиля и выбранный J0001. Docker текущей версии не запускался, CI не использовался.

Результаты прежних этапов — 117/14, 152/19 (PR #6), 168/21 и 223/28 — исторические. Подробности: docs/INTEGRATION.md.

Стандартные команды проверки из корня проекта:

pnpm test
pnpm typecheck
pnpm build

GitHub Actions ранее был заблокирован из-за billing аккаунта до запуска команд проекта. Workflow синхронизирован с принятой командой версией: запуск только вручную через workflow_dispatch. CI в этой проверке не запускался. Windows spawn EPERM из исторического отчёта PR #7 относится к запуску инструментов на том хосте; локальные адаптации здесь сохраняют полный набор тестов и проверку TypeScript. Детали команд и ограничений: docs/INTEGRATION.md.

Метрики и adversarial-кейсы: docs/EVALUATION.md.

Приватность и отказоустойчивость

• Исходные импортированные файлы и полная история остаются в браузере; серверной БД нет.
• Demo Employee получает только собственный профиль и историю; HR получает полный организационный набор для аналитики. Сервер проверяет подписанную identity.
• Диалог доступен только его участникам. HR получает общие счётчики чата; тексты, участники и темы чужих диалогов не выдаются.
• В LLM уходят только evidence-факты по top-кандидатам — никогда raw-профиль и история.
• Ответ модели проходит Zod-схему и fact verifier: неизвестный ID, изменённое число или неподтверждённое утверждение блокируются.
• Текст из датасета трактуется как данные, а не как инструкции (защита от prompt injection).
• Без ключа или при ошибке модели — полноценный детерминированный режим.
• /api/ai/explain проверяет ответ относительно присланного evidence; происхождение импортированных фактов сервером не подтверждается. /api/ai/review использует серверный встроенный набор. Оба route ограничивают origin, JSON, размер тела и частоту запросов.
• /api/ai/agent разрешён только HR; инструменты не изменяют данные и не отправляют raw-профили/историю. Числовой grounding не доказывает причинность выводов агента.
• Демо-персоны свободно выбираются из синтетического набора; для production нужен SSO. Публичных рейтингов сотрудников нет.

Ограничения

• Перезагрузка сбрасывает импорт и карьерный ledger. Переписка сохраняется в JSON-файле и переживает перезапуск с тем же runtime-каталогом.
• Демо-идентификация не доказывает личность пользователя; приложение предназначено для синтетических данных.
• JSON-хранилище чата рассчитано на один процесс и демо-объёмы. Нет push, вложений, редактирования/удаления сообщений и шифрования переписки. Вместо WebSockets используется опрос.
• Beam search ограничен шириной 10 и глубиной 4; календарная совместимость активностей не рассчитывается.
• Живой платный LLM-провайдер не вызывался при проверке; протестированы проверенные ответы, отказ, таймаут и режим без ключа. AI не меняет порядок рекомендаций.
• Docker-конфигурация с runtime volume подготовлена; контейнер текущей версии здесь не запускался.

Документация

Файл	О чём
docs/ARCHITECTURE.md	Техническая модель, формула, release gates
docs/DATASET.md	Проверенные факты о данных и доменные правила
docs/CONTRACTS.md	Общие типы и публичный API ядра
docs/PLAYBOOK.md	План на 5 часов, feature gates, checklist
docs/WORKSTREAMS.md	Готовые Codex-задания по потокам
docs/EVALUATION.md	Метрики и adversarial-кейсы
docs/SKILL_EXCHANGE.md	Наставники, переписка, приватность и приёмка
docs/REQUIREMENTS_AUDIT.md	Матрица исходных ТЗ, фактические проверки и ограничения
docs/DEMO.md	Демо-скрипт на 90 секунд
AGENTS.md	Правила для AI-агентов
CONTRIBUTING.md	Ветки, коммиты, merge, handshake

---

Данные синтетические, предоставлены организаторами. Реальные персональные данные не используются.

Для стороннего LLM_BASE_URL требуется явный LLM_API_KEY: ключ OPENAI_API_KEY автоматически используется только для https://api.openai.com.