Career Quest — HackAlem, трек 03 «Управление»

Локальный MVP команды LUMIVERA QuantumSeal. Python 3.10+, только стандартная библиотека, без pip, API-ключей и сетевых AI-сервисов.

Запуск одной командой

python app.py

Откройте http://127.0.0.1:8000. Employee: E001 / employee-demo (также E002–E200); HR: HR / hr-demo. Остановка: Ctrl+C.

Архитектура и структура

app.py                    HTTP API, сессии, employee/HR UI
recommendation_engine.py  gap, готовность и рекомендации
data_loader.py            проверка входных данных и SQLite-транзакции
generate_demo.py          воспроизводимая генерация synthetic demo
data/
  employees.json          200 синтетических профилей
  events.json             40 активностей
  skills.json             60 навыков, требования Junior/Middle/Senior
  activity_history.csv    4800 строк, сентябрь 2024 — август 2026
tests/test_mvp.py          HTTP-интеграционные и алгоритмические проверки
verify_demo.py            воспроизведение evidence
evidence/                 результаты тестов и реальные ответы API
runtime/                  локальный прогресс (игнорируется Git)

Поток: браузер → серверная сессия → профиль и история → требования следующего грейда → gap → 1–3 шага → демо-выполнение → транзакция SQLite → пересчёт. HR видит сводную таблицу готовности. Employee получает только собственный профиль; идентификатор сотрудника берётся из сессии, не из тела запроса. HR не может выполнять активности за сотрудника.

Объяснимая AI-рекомендация

Реализован детерминированный content-based рекомендательный baseline, без LLM и без обучения модели. Рейтинг = 0.55 × доля закрываемого gap + 0.20 × совпадение формата + 0.15 × min(1, часы в неделю / длительность) + 0.10 × 1/(1 + завершения данного формата). Все четыре фактора возвращаются как текст и численные вклады. Это эвристические веса, ещё не откалиброванные на официальном наборе.

Отбрасываются завершённые, неактивные события, события без пользы для gap и с невыполненными prerequisites. При равенстве используется ID. Если подходящих событий нет, интерфейс объясняет отсутствие рекомендации. Каждый шаг ранжируется отдельно; общий недельный план из трёх шагов не оптимизируется. Длительная активность допускается на несколько недель.

Готовность = покрытие суммарных требований целевого грейда. На верхнем грейде показывается развитие до требований Senior. Грейд автоматически не повышается. Выполнение начисляет демонстрационные баллы, ограниченные уровнем 5; повторное выполнение не начисляет их снова. Это не оценка реальной квалификации и не автоматическое кадровое решение.

Данные и замена starter kit

Официальные файлы не обнаружены при разработке, включая оглавления двух имеющихся архивов. Все данные в data/ синтетические: Demo 001–200, без реальных ФИО, контактов и иных персональных данных. Архивы исходного репозитория не изменялись. Три траектории используются для разнообразия тестовых профилей; номер трека хакатона — 03 «Управление».

Контракт JSON — массивы объектов:

• employees: id, name, track, grade, preferred_format, weekly_hours, skills (словарь skill ID → уровень 0–5).
• events: id, title, format, hours, active, prerequisites, gains (последние два — skill ID → уровень/прирост).
• skills: id, name, track, requirements (словарь Junior/Middle/Senior → уровень 1–5).
• CSV: employee_id,event_id,date,status,format, ISO-дата, статус completed/skipped.

employees.skills — текущий снимок, уже включающий исходную историю: исторические баллы повторно не начисляются. Новые выполнения хранятся отдельно.

Поместите четыре официальных файла в отдельную папку и запустите:

python app.py --data-dir starter-kit --db runtime/official.sqlite3

При совпадении контракта замена не требует изменения кода. Фактическая официальная схема пока неизвестна: если поля отличаются, добавляется только преобразование в data_loader.load_data, рекомендательная логика и UI остаются прежними. Совместимость с ещё не полученным starter kit не заявляется как проверенная. Валидатор проверяет ID, ссылки, уровни и даты. Смена данных с прежней БД блокируется fingerprint: используйте новый путь БД.

python generate_demo.py заново создаёт demo и перезаписывает четыре файла — не запускайте после замены их официальными.

Проверка и воспроизведение

python -m unittest discover -s tests -v
python verify_demo.py

Тесты поднимают настоящий HTTP-сервер на свободном localhost-порту, используют отдельную временную БД и проверяют три профиля, четыре фактора, сохранение/повтор выполнения, изоляцию ролей, CSRF, неверный ID, пустой каталог и закрытый gap. verify_demo.py сохраняет фактические ответы API в evidence/demo_results.json, отчёт тестов — в evidence/tests.txt; пользовательский прогресс не меняется.

Ручная проверка: войдите как E001, изучите навыки/историю/объяснения, нажмите «Выполнить активность», проверьте прогресс и историю; перезагрузите страницу; выйдите и войдите как HR для сводки.

Подтверждённый Human Review: PASS

Проверенный пользователем сценарий: Profile → Skill Gap → Recommendation → Human Action → Progress Update → Saved State. До действия покрытие требований составляло 65%. Пользователь выполнил рекомендованную активность «Практика 37: Management»; система подтвердила «Прогресс обновлён и сохранён». После действия отображалось 83.3%, новый прогресс сохранился после обновления состояния. Источник — подтверждение пользователя от 2026-09-23; подробности: evidence/HUMAN_REVIEW_CONFIRMED.md.

Это отдельное ручное наблюдение. Предыдущий автоматический прогон на чистой тестовой БД дал 65.0% → 71.7%; его evidence сохранено без подмены. Причина различия состояний не установлена, бизнес-логика под результат ручной проверки не менялась.

Границы MVP / Human Review

Сервер слушает только 127.0.0.1. Пароли публичные демонстрационные; это серверное разграничение ролей для локального прототипа, не production-аутентификация. Для эксплуатации нужны SSO, индивидуальная идентификация, срок жизни сессий, проверка факта завершения, оценка качества рекомендаций и адаптер реального starter kit. Не загружайте реальные персональные данные в эту демоверсию.

Функциональный Human Review подтверждён. Следующий шаг требует нового Human Review; commit и push пока не разрешены.