Halyk Career Quest

HackAlem AI · Halyk Bank · Case 1 — Career Quest

AI-powered career navigation and employee development platform — платформа, которая связывает навыки сотрудника с карьерной целью и помогает выбрать следующий полезный шаг развития.

Сегодня работает: персональная карта, расчёт навыков и дефицитов, каталог событий, сохранение завершений, кабинет HR, импорт данных и демонстрационный Halyk Market.

OpenAI подключён. Модель выбирает 1–3 подходящих активности по полному контексту; сервер строит объяснения из проверенных фактов. Настройте AI_PROVIDER=openai и OPENAI_API_KEY в корневом .env. NVIDIA пока не используется.

Статус · Быстрый запуск · Демо-доступ · API · Проверки · Демо-сценарий

README обновлено после независимого аудита 23.09.2026. Исходные наблюдения сохранены в TEST_AUDIT.md; исправления описаны в QA_FIXES.md.

1. Problem

Сотрудник получает множество предложений обучения, но не всегда понимает, почему конкретная активность полезна, какой дефицит она закрывает, к чему ведёт и что изменится после завершения. Каталога курсов недостаточно для выбора следующего шага.

HR нужны три практических ответа: какие дефициты встречаются чаще всего, как сотрудники участвуют в активностях и кому сейчас нельзя предложить подходящее мероприятие. Career Quest связывает эти задачи в один цикл развития, выходящий за рамки каталога LMS.

2. Solution

Профиль → текущие навыки → требования цели → дефициты → карьерный маршрут
   → подходящие события → рекомендация → завершение → новый прогресс
   → вовлечение и награды → следующий шаг

Backend рассчитывает факты и допустимые события. Карта объясняет ближайшие шаги и обновляется после сохранённого завершения. AI-слой вызывает OpenAI для выбора 1–3 рекомендаций; числовые объяснения строятся сервером.

3. Product Vision

Направление	Польза и стадия
Career Intelligence	✅ Профиль, требования, дефициты и достижимый прирост навыков
Career Map / Events	✅ Маршрут и каталог с проверкой ограничений
AI Recommendations	✅ Live OpenAI, проверка выбора и объяснения из фактов
HR Analytics	✅ Дефициты, участие, сотрудники без подходящих событий
Gamification / Rewards	✅ Карта и монеты; 🧭 личные XP, уровни и серии
Social Discovery	🟡 Career Stories: подготовлены спецификация и план, рабочего модуля нет

Обозначения: ✅ IMPLEMENTED — есть реализация; 🟡 IN PROGRESS — подготовка ведётся, стадия указана явно; 🧭 PLANNED — запланировано, реализации нет; 💡 CONCEPT / FUTURE IDEA — идея для дальнейшей оценки.

4. Current Feature Status

Feature	Status
Career Map	✅ IMPLEMENTED — серверные данные, локальный маршрут и темп
Employee / HR roles	✅ IMPLEMENTED — разграничение API с приватными токенами
Skill projection	✅ IMPLEMENTED — переигрывание завершений после оценки
Next-grade gaps / career goal	✅ IMPLEMENTED — отдельные расчёты; редактирования цели нет
Event eligibility	✅ IMPLEMENTED — аудитория, prerequisites, расписание, история, прирост
Activity completion	✅ IMPLEMENTED — собственные завершения, сохранение и повторы команд
HR dashboard	✅ IMPLEMENTED — дефициты, участие, отсутствие кандидатов
Dataset import	✅ IMPLEMENTED — HR-импорт профилей и истории
Coins	✅ IMPLEMENTED — 80 за новое добровольное завершение через API
Halyk Market	✅ IMPLEMENTED — demo-каталог и сохраняемые обмены
Notifications / course offers	✅ IMPLEMENTED — SMTP, предложения, напоминания, паузы и журнал
AI context / validation	✅ IMPLEMENTED — AIRefinementInput, JSON, проверяемые факты
Live OpenAI/NVIDIA provider	✅ IMPLEMENTED — OpenAI; NVIDIA не подключён
HR AI-recommendation coverage	✅ IMPLEMENTED — ready/failed/stale/not_generated, критичные пробелы каталога
Career Stories	🟡 IN PROGRESS — спецификация и план; backend/frontend ещё не реализованы
Personal Progress / XP	🧭 PLANNED — нет XP, уровней или streak-механики
Calendar	🧭 PLANNED — даты сессий есть, календарного экрана/интеграции нет
Career Copilot	🧭 PLANNED — диалогового помощника нет
Team Quests / Duels	💡 CONCEPT / FUTURE IDEA
Career Simulator / AI Quest Master / AI video / Manager View	💡 CONCEPT / FUTURE IDEA

5. Employee Experience

В кабинете доступны «Карта развития», «Мой обзор», «События» и Halyk Market. Навыки, история и требования показаны в карте и обзоре; отдельного экрана XP или Stories нет.

Сотрудник видит свои данные, открывает карточку события, проверяет ограничения и подтверждает уже выполненную активность. После ответа сервера обновляются навыки, маршрут, история и баланс. Это самоотчёт о завершении, без подтверждения LMS или руководителем.

AI Navigator — отдельная панель запроса рекомендаций: интерфейс умеет показать объяснения, доказательства, гипотезы, уточняющие вопросы и ошибку отсутствующего провайдера. Сохранение ответов на вопросы пока не реализовано.

6. Career Map

Карта показывает 1–3 сохранённые AI-рекомендации без заполнения случайными курсами. Сначала предлагается один самый подходящий шаг; дополнительные требуют высокой уверенности и отдельной пользы. Неактуальные и отклонённые предложения скрываются. Полный каталог доступен в «Событиях».

Темп 1, 3 или 5 часов в неделю меняет локальную оценку длительности; он пока не передаётся LLM. Переключатель цели меняет показ дефицитов, но не редактирует профиль и не меняет серверную цель. У Lead нет следующего грейда. Завершение обновляет навыки и маршрут; покрытие требований не гарантирует повышение.

7. Recommendation Engine

AIRefinementInput содержит полный профиль, рассчитанные текущие навыки, связанную историю с карточками мероприятий, каталог, требования ролей, карьерную цель, кандидатов, исключения и неизвестные предпочтения.

OpenAI выбирает 1–3 активности и ссылки на факты. Backend проверяет доступность, ID, ревизию, минимум три категории evidence и повторные неуспешные попытки. Ошибочные ссылки evidence у реального допустимого курса заменяются проверенными фактами кандидата; неизвестный курс отклоняется. Выбор курса при этом не заменяется локальным рейтингом.

Текст объяснения строится из current skills, реального gain и max_level, требований грейда и истории. Неподтверждённый свободный текст модели и гипотезы не показываются. При отсутствии карьерной цели явно обозначается ориентир по умолчанию. Сохраняются видимые оставшиеся критичные пробелы, даже если рекомендован другой полезный курс.

AI_PROVIDER=openai и OPENAI_API_KEY включают live-провайдер; none отключает его. Есть одна повторная попытка при таймауте в пределах общего сетевого бюджета AI_TIMEOUT_SECONDS (10 секунд по умолчанию). Внешняя задержка не гарантируется. Ошибки авторизации/квоты не повторяются; фиктивная рекомендация при сбое не создаётся. no_candidates не вызывает модель. Ключи остаются на backend.

См. provider setup, исходный аудит, исправления.

8. Events

Каталог содержит курсы, практические занятия, менторство, сертификации, встречи, onboarding и compliance. Карточки задают целевые роли/грейды, prerequisites, формат, длительность, обязательность, приросты и пределы навыков, даты сессий.

Каталог → проверка условий → просмотр → фактическое прохождение вне приложения
   → подтверждение завершения → атомарная запись → пересчёт навыков и наград

Самостоятельные события не требуют сессии; для планируемого живого события нужна текущая/будущая дата. При завершении нельзя указать будущую сессию. Существующие назначения in_progress/overdue завершаются по source_record_id и заменяют эффективный статус исходной записи, без двойного начисления.

Обязательные активности исключены из рекомендаций и не дают монет. Интерфейс предлагает их завершение через назначения; backend пока не требует назначение во всех mandatory-сценариях — это известное ограничение, а не строгая серверная гарантия.

Добровольные события обычно неповторяемы; исключение — клуб EV_036. Исходная история также содержит ежегодные повторения обязательного compliance: они сохраняются, а отдельные существующие назначения могут завершаться повторно. Запись на мероприятие, резервирование места и внешняя LMS-интеграция отсутствуют.

9. Career Stories

🟡 IN PROGRESS — стадия спецификации и плана, не рабочая функция. См. дизайн и план.

Идея — внутренний слой знакомства с возможностями развития:

Завершение → добровольное Share Achievement → история
   → коллега узнаёт о событии → приватно проверяет пользу для своего маршрута

Предусмотрены Employee Achievement и Halyk Official: HR рассказывает о существующем событии, курсе, сроке, напоминании или возможности. Career Quest System Story — будущая идея. Реакции MVP: 🔥 ❤️ 🚀 💪; комментарии, личные сообщения и подписчики не требуются.

Публикация достижения только по явному согласию. План не допускает автоматического раскрытия дефицитов, готовности к повышению, пропусков, отказов, частных карьерных целей или performance-данных. Ни лента, ни публикации, ни реакции сейчас не реализованы.

10. Personal Progress

🧭 PLANNED — Personal Progress Rating («Личный прогресс»). Сотрудник сравнивает развитие со своим предыдущим состоянием; это не публичный рейтинг эффективности сотрудников.

Пример будущих уровней: Explorer → Bronze → Silver → Gold → Sapphire → Diamond. Иллюстрация будущего интерфейса, не реальные данные приложения:

Diamond · 5700 / 10000 XP
Активная серия: 2 недели · Личный рекорд: 36 недель

Формула XP, пороги и серии пока не реализованы. Публичные места среди коллег и сравнительные performance-процентили не предусмотрены: такая механика противоречит ограничению кейса на публичные рейтинги эффективности.

11. XP vs Coins

	XP — 🧭 PLANNED	Coins — ✅ IMPLEMENTED
Назначение	Личные уровни, развитие и серии	Валюта демонстрационных наград
Можно потратить	Нет	Да, в Halyk Market
Начисление	Правила предстоит определить	80 за новое добровольное runtime-завершение
Связь с навыками	Не заменяет расчёт навыков	Не повышает навыки, грейд или доступ к обучению

12. Halyk Market

✅ IMPLEMENTED — внутренний demo-каталог, без коммерческих транзакций Halyk Market. Начальный баланс — 0. Исходная и импортированная история монет не приносит; новое завершение добровольного назначения через API приносит 80. Обязательные активности — 0.

Награда	Монеты
Книга для следующего шага	80
Термокружка Halyk	160
Шоппер Halyk	240
Билет на конференцию	400

Баланс равен заработанным монетам минус сохранённые обмены. Каждую награду сотрудник может получить один раз; сервер проверяет остаток и повтор команды. Квитанции сохраняются после перезапуска. HR видит каталог без персонального кошелька и не выполняет обмены. Реальных платежей, доставки и выдачи товаров нет. Источник правил: market.py.

13. Calendar

🧭 PLANNED. Будущий календарь объединит сессии, сроки, принятые задания, рекомендации, напоминания и завершённые события. Сейчас есть только даты сессий и локальное распределение нагрузки по неделям; календарного экрана, синхронизации и бронирования нет.

14. Employee Engagement Loop

AI находит событие [planned] → объясняет пользу [правила уже работают]
 → сотрудник смотрит [работает] / принимает [planned] → напоминание [planned]
 → завершение → прогресс навыков → монеты [работает] / XP [planned]
 → добровольная Story [in progress: дизайн] → коллеги узнают о событии [planned]
 → следующий шаг

Геймификация делает пользу небольших действий заметной и поддерживает регулярность. Награды дополняют развитие; они не оценивают производительность и не определяют повышение.

15. HR Cabinet

HR видит агрегаты дефицитов и участия, импортирует профили и историю, открывает сотрудников. employees_without_candidate — отсутствие доступных событий. employees_without_recommendation — отсутствие актуального готового ответа AI; recommendation_states различает ещё не созданные, ошибочные, устаревшие ответы и необходимость уточнения.

critical_catalog_gaps показывает сотрудника, роль/грейд, критичный навык, текущий/требуемый уровень и достижимый уровень после доступных сейчас событий. Альтернативный необязательный курс не скрывает незакрываемый критичный пробел. Аналитика и детали доступны только HR.

16. Notifications

Реализованы предложения курсов, SMTP-аккаунт HR с шифрованием пароля, время и частота уведомлений, паузы, действия enroll/later/decline и журнал доставки. Повторные запросы и действия защищены от дублирования. После неизвестного результата SMTP автоматическая повторная отправка не выполняется. Внешнего зачисления в LMS нет.

Настройки: MAIL_ENCRYPTION_KEY, PUBLIC_APP_URL, NOTIFICATION_WORKER_ENABLED, NOTIFICATION_POLL_SECONDS. AI_AUTO_PREPARE=false готовит рекомендации при открытии профиля; true также включает фоновую подготовку. См. уведомления.

17. Future AI Features

Идея	Сценарий	Статус
AI Career Copilot	«Что нужно для Senior?», «Почему это событие?», «Есть только час в неделю», «Есть другой формат?»	🧭 PLANNED
Career Simulator	«Что изменится, если выбрать другую карьерную траекторию?»	💡 CONCEPT
AI Adaptive Recommendations	Адаптация к ответам и поведению; история уже входит в контекст, адаптивного диалога нет	💡 CONCEPT
AI Quest Master	Единый образ карьерного навигатора	💡 CONCEPT
AI Future Me / Video	Короткая мотивационная визуализация будущего пути	💡 CONCEPT

18. Team Quests / Duels

💡 CONCEPT / FUTURE IDEA. Solo Challenge, Skill Duel и Team Quest могут поддерживать личную регулярность, взаимопомощь и общую учебную цель. Предпочтение — сотрудничеству и добровольным заданиям, без публичного ранжирования эффективности или соревнования за карьерные решения. Рабочих механик пока нет.

19. Privacy

Backend ограничивает сотрудника собственными данными, HR получает разрешённый доступ к просмотру и импорту. Токен хранится в памяти страницы; выход или перезагрузка очищает сессию. Приватные API-ответы используют Cache-Control: no-store.

Публичного performance-leaderboard и автоматической публикации дефицитов нет. Для будущих Stories предусмотрен opt-in и отдельный безопасный состав публичных полей. Приватные bearer-токены выдаёт администратор; production IAM/SSO пока не реализован.

20. Dataset

Числа проверены по исходным файлам, без добавлений runtime-состояния:

Файл	Содержание
employees.json	200 профилей с assessment-навыками и датой оценки
events.json	40 событий
skills.json	60 навыков и 32 профиля требований роль/грейд
activity_history.csv	2 743 записи участия

Снимок — 2026-10-01, история — 2024-10-01—2026-09-30. Исходные файлы data/raw неизменяемы; их хеши хранятся в manifest. Синтетический starter kit предназначен для хакатона; условия использования — в README данных.

HR-импорт принимает employees.json в исходной оболочке meta/employees и/или CSV со всеми исходными столбцами. Multipart-поля — employees и history; лимит всего запроса — 10 MiB. ZIP и замена каталога не поддерживаются. Идентичные записи — no-op, конфликтующие ID/участия отклоняют весь импорт. Сначала проверяется полный будущий набор, затем выполняется запись.

Изменяемое состояние хранит импорт, завершения, квитанции команд и Market отдельно от raw. Native-путь — data/state/state.json, Compose — named volume career_quest_state. Обычный docker compose down сохраняет данные. Несовместимый fingerprint или повреждённое состояние вызывают ошибку запуска, а не тихий сброс.

Для намеренного сброса одноразового демо сначала остановите backend и сохраните копию состояния; удаляйте только выбранный demo-state или volume этого проекта. Это уничтожает runtime-прогресс, импорт и обмены, сохраняя raw.

21. Skill Projection

Навыки профиля — снимок оценки, а не актуальный баланс. progress_engine.py повторно применяет завершения строго после last_review_date и не позднее даты приложения, в порядке даты и стабильного ID. Отсутствующий навык имеет уровень 0.

last_review_date < completed_on <= as_of_date
new_level = max(current, min(current + gain, max_level))
gap = max(required - current, 0)

gain увеличивает уровень, max_level ограничивает эффект события; событие с низким пределом не уменьшает уже развитый навык. Шкала — 0–5. Незавершение, пропуск, отказ и прерывание не дают прироста.

CSV не содержит точного времени завершения: его date используется как приближение. Runtime-завершение имеет явную completed_on; переход существующего назначения учитывается один раз. LLM в этом расчёте не участвует.

22. Architecture

Browser → Next.js / React → same-origin proxy /backend → FastAPI
                                                         ├─ Session / Auth
                                                         ├─ Employee / Trajectory
                                                         ├─ Eligibility / Completion
                                                         ├─ Recommendations / Context
                                                         ├─ HR / Dataset import
                                                         └─ Market
                                                               ↓
                                                            Services
                                                               ↓
                                                          Repositories
                                                        ↙              ↘
                                               Raw JSON/CSV       Mutable state.json

Отдельная AI-граница:
Recommendation context → AIClient → JSON adapter → output validation
                            └─ по умолчанию DisabledRecommender
                               OpenAI подключён; NVIDIA не используется

Один backend-процесс, один lock изменений. Запись выполняется через временный файл, flush/fsync и атомарную замену; snapshot публикуется после сохранения. Работает файловая очередь уведомлений и фоновый worker; несколько процессов с общим state-файлом не поддерживаются. Stories и Personal Progress пока не входят в runtime-архитектуру.

Подробности: architecture, data model, frontend integration. Старые проверки в handoff и аудите относятся к указанным там ревизиям; текущий код имеет приоритет.

23. Tech Stack

Слой	Зависимости из package/requirements-файлов
Frontend	Next.js 16.3.6, React / React DOM 19.3.0, TypeScript 5, Tailwind CSS / PostCSS 4.3.3, Lucide React, Golos Text; собственные CSS/SVG
Backend	Python 3.12 в Docker, FastAPI 0.141.1, Pydantic 2.13.5, Uvicorn 0.53.0, python-multipart 0.0.32
Tests	pytest 9.1.1, httpx 0.28.1
Runtime	Node.js 22 в Docker, Docker Compose, файловый JSON overlay

Используется официальный OpenAI SDK; отдельного LLM-фреймворка нет. Версии: frontend/package.json, requirements, dev requirements.

24. Repository Structure

backend/
  app/
    api/            session, employees, activities, recommendations, hr, dataset, market
    ai/             client.py, prompts.py, recommender.py
    core/           config, auth, errors
    schemas/        исходные, API- и state-модели
    services/       projection, gaps, eligibility, completion, HR, Market, AI context
    repositories/   чтение файлов, snapshot, валидация, сохранение
  tests/            pytest-набор
  Dockerfile
  requirements.txt
  requirements-dev.txt
frontend/
  src/app/          /, /employee/[id], /hr, стили
  src/components/   connected shell, journey, HR, иллюстрации
  src/lib/          api.ts, types.ts, career-data.ts
  public/           изображения и логотип
  next.config.ts    same-origin rewrite
  package.json
  Dockerfile
data/
  raw/              неизменяемый starter kit
  fixtures/         manifest исходных хешей
  state/            игнорируемое Git runtime-состояние
docs/               архитектура, данные, AI-контракт, аудит, handoff
  superpowers/      спецификации и планы, включая будущие Stories
.env.example
docker-compose.yml

25. Running with Docker

Требуется Docker Desktop с Linux containers. Из корня репозитория:

docker compose up --build

Адрес	Назначение
localhost:3000	Frontend
localhost:8000	Базовый адрес backend; отдельной главной страницы нет
localhost:8000/docs	Swagger / OpenAPI
localhost:8000/health	Публичная проверка здоровья

Для AI-рекомендаций нужен OpenAI API key; перед запуском выдайте приватные токены по разделу 27. Raw монтируется read-only, состояние — в named volume. Frontend ждёт backend healthcheck. Порты привязаны к loopback. Браузер обращается к /backend/api/..., Next.js направляет запросы на http://backend:8000; браузеру не нужно разрешать Docker hostname.

26. Local Development

Python 3.12+, Node.js 22+. Создайте окружение в корне.

Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS/Linux:

python3.12 -m venv .venv
source .venv/bin/activate

Далее в активированном окружении:

python -m pip install -r backend/requirements-dev.txt
python -m uvicorn app.main:app --app-dir backend --reload --host 127.0.0.1 --port 8000

Во втором терминале из корня:

cd frontend
npm ci
npm run dev

Откройте 127.0.0.1:3000. Прокси по умолчанию использует http://127.0.0.1:8000. Backend читает окружение процесса и не загружает .env автоматически. Next.js читает frontend/.env.local, если нужны переопределения.

27. Demo Credentials

Публичные demo-hr, demo-active, demo-employee больше не принимаются при запуске из окружения. Выбор роли на странице не выдаёт доступ.

python backend/provision_access.py --hr --employee E0004

Команда сохраняет API-ключи и существующие приватные аккаунты, удаляет старые публичные credentials и создаёт случайные токены в игнорируемом .env, поле DEV_IDENTITIES_JSON. Скопируйте свой токен в форму входа; HR-токен сотрудникам не передавайте. После выдачи доступа перезапустите backend. Токены хранятся в браузере только в памяти страницы.

To add imported employee identities, set DEV_IDENTITIES_JSON with a private token or run python backend/provision_access.py --employee NEW_ID before starting Python. Для завершения курса нужен собственный аккаунт нового сотрудника; HR не может завершить курс за него.

Это приватные bearer credentials для MVP, без SSO, автоматического истечения и восстановления аккаунта.

28. Environment Variables

Источник: .env.example. Для изменения Compose defaults можно скопировать его в .env.

Группа	Переменная	Поведение
App	DEV_IDENTITIES_JSON	Серверное соответствие токен → employee/HR
App	NEXT_PUBLIC_API_URL	Browser API prefix, default /backend, встраивается при сборке
App	BACKEND_INTERNAL_URL	Прокси Next.js: native http://127.0.0.1:8000; Compose build задаёт http://backend:8000
App	FRONTEND_ORIGIN	Разрешённый CORS origin, default http://localhost:3000
Data	DATA_RAW_DIR	Native override каталога raw; Compose задаёт контейнерный путь
Data	STATE_PATH	Native override state-файла; Compose задаёт контейнерный путь
Data	APPLICATION_DATE	Пусто → дата снимка 2026-10-01; override не раньше неё
AI	AI_PROVIDER	Зарезервирована, пример openai; сейчас не используется
AI	OPENAI_API_KEY, NVIDIA_API_KEY	Пустые server-only placeholders; текущий backend их не использует, Compose не передаёт
AI	AI_PROVIDER, OPENAI_API_KEY, OPENAI_MODEL, AI_TIMEOUT_SECONDS, AI_AUTO_PREPARE	Live provider и фоновая подготовка
Notifications	MAIL_ENCRYPTION_KEY, PUBLIC_APP_URL, NOTIFICATION_WORKER_ENABLED, NOTIFICATION_POLL_SECONDS	SMTP и worker

Часы демо привязаны к снимку, а не системной дате. Для поздних сессий сдвигайте APPLICATION_DATE вперёд и перезапускайте backend; не возвращайте дату назад поверх сохранённых завершений. После изменения production URL-настроек пересоберите frontend. Реальные ключи нельзя помещать в NEXT_PUBLIC_*, frontend или коммитить в .env.

29. API

Все /api требуют Authorization: Bearer TOKEN; /health публичный. В таблице только существующие маршруты:

Method	Path	Назначение
GET	/health	Состояние приложения
GET	/api/session	Роль и employee ID текущего токена
GET	/api/employees	Собственный профиль в списке / все сотрудники для HR
GET	/api/employees/{id}	Профиль, текущие навыки, эффективная история
GET	/api/employees/{id}/trajectory	Требования, дефициты, цель и кандидаты
GET	/api/employees/{id}/recommendations/context	Полный авторизованный AIRefinementInput
POST	/api/employees/{id}/recommendations	Live AI-выбор с проверенным объяснением / no_candidates
POST	/api/employees/{id}/activities/{event_id}/complete	Завершение своей активности; HR запрещено
GET	/api/hr/dashboard	HR-агрегаты и отсутствие кандидатов
POST	/api/dataset/import	HR-only multipart employees / history
GET	/api/market	Каталог и собственный ledger; HR получает только каталог
POST	/api/market/redeem	Сохраняемый обмен награды, employee-only

Тело завершения:

{"command_id":"00000000-0000-4000-8000-000000000001","source_record_id":null,"session_date":null}

Для существующего назначения передайте source_record_id, для известной сессии — session_date. Тело обмена:

{"command_id":"00000000-0000-4000-8000-000000000002","reward_id":"book"}

На каждое новое намеренное действие генерируйте новый UUID. После неопределённого результата повторяйте тот же UUID и тело: сервер вернёт исходную квитанцию даже после рестарта. Изменение тела при том же ID, повтор неповторяемого завершения, недостаток монет или повтор награды дают конфликт.

Ошибки имеют вид {"error":{"code":"...","message":"...","details":[]}}; details может содержать безопасные сведения о поле/строке. Используются 401/403/404/409/413/422/501/503. Stories API пока существует только в плане; Personal Progress, Calendar, внешнее LMS enrollment и редактирование цели не имеют рабочих endpoints. Notification/SMTP API реализован. Отдельного общего GET /api/events сейчас нет: каталог приходит в авторизованном контексте.

30. Testing

Из корня, с активированным Python-окружением и установленными dev-зависимостями:

python -m pytest backend/tests -q
cd frontend
npm run typecheck
npm run build
cd ..
docker compose config --quiet

Проверки при подготовке README, 23.09.2026, без установки зависимостей:

Проверка	Результат
Backend pytest	158 passed, 1 Starlette/httpx deprecation warning, 16.22 с; с --basetemp=.pytest-readme-check-20260923 --tb=short
Frontend typecheck	Пройден
Frontend production build	Пройден: webpack, TypeScript и генерация страниц
Compose config	Пройден; Docker сообщил предупреждение о недоступном пользовательском config.json
Browser / полный Docker startup	В этой задаче не запускались

Первый pytest-запуск: 83 passed, 75 setup errors из-за доступа к временному каталогу. Повтор использует отдельный доступный каталог через --basetemp; результат указан выше. Это не исправление product-кода.

Тесты покрывают raw-хеши/схемы, проекцию, eligibility, авторизацию, импорт, завершения, атомарность, повторы после рестарта, AI-контекст/валидацию и HR. Есть двухсекундный бюджет расчёта HR на реальном наборе. Отдельных Market-тестов и автоматизированного frontend/browser harness нет. Старые счётчики из аудита и handoff не являются результатом этого checkout.

31. Demo Day Flow

Сценарий на 60–90 секунд, с заранее запущенным приложением:

Время	Действие
0–15 с	Войти как сотрудник E0004; показать роль, следующий грейд и явную цель
15–30 с	Открыть дефицит/критический навык и ближайший шаг; объяснить правило подбора и недельный темп
30–40 с	Показать AI Navigator, выбранный моделью курс и проверенные факты его пользы
40–60 с	Открыть доступную самостоятельную активность или назначение и подтвердить уже выполненную работу; показать обновление навыков и +80 монет для добровольного события
60–70 с	Открыть Market: книга за 80 монет, если баланс достаточен и она ещё не обменена; показать demo-квитанцию
70–90 с	Сменить профиль на HR: частые дефициты, участие по событиям, сотрудники без кандидатов; кратко показать импорт

Перед показом проверьте доступность выбранной активности и награды в текущем сохранённом состоянии. Stories, XP и календарь можно назвать следующими этапами, но демонстрировать их как работающие экраны нельзя.

32. Roadmap

Приоритет	Следующий результат
P0 — до Demo Day	Live-провайдер; реальные 1–3 рекомендации; проверка качества объяснений и фактов; сетевой timeout / бюджет ≤10 с; интеграционные проверки и актуальное покрытие рекомендациями для HR
P0 — надёжность	Сохранять прохождение текущих тестов и HR performance budget; добавить Market-проверки; проверить браузерный сценарий и согласовать серверные ограничения mandatory completion
P1 — вовлечение	Реализация Career Stories по подготовленному плану; Personal Progress / XP; Calendar; AI Copilot; opt-in уведомления и course offers
P1 — управление развитием	Сохранение цели, запись на события и ответы на уточняющие вопросы
P2 — продвинутые идеи	Career Simulator, Team Quests, Skill Duels, Manager View, AI Quest Master / Future Me / видео

Roadmap не означает наличие функций в текущей версии. Production-аутентификация необходима перед выходом за границы локального демо.

33. Authors

Команда IFlow:

• Zhassyn Zhalynuly
• Danial Amangeldi
• Nurislam Aldabergenuly