Career Quest

AI-навигатор развития сотрудника: показывает разрывы в навыках, рекомендует следующий шаг и пересчитывает прогресс после завершения активности. HR видит аналитику команды и может загружать проверочные данные.

Для жюри: начните с запуска через Docker, создайте два аккаунта и пройдите сценарий проверки. Внешний AI-ключ для демонстрации не требуется.

Дата демонстрации — 1 октября 2026 года (2026-10-01). Для рекомендаций и пересчёта прогресса используется дата среза данных, а не текущая дата компьютера. Менять системную дату не нужно.

Быстрый запуск для жюри — Docker

Нужны Docker с командой docker compose и свободный порт 8000. Выполняйте команды в корне скачанного репозитория, где находится docker-compose.yml. PHP, Node.js и базу данных отдельно устанавливать не нужно.

1. Запустите приложение

cp .env.example .env
docker compose up --build -d
docker compose logs -f app

Копируйте .env.example только при первом запуске; если .env уже настроен, сохраните его. Дождитесь сообщения о запуске сервера, затем нажмите Ctrl+C, чтобы выйти из просмотра логов. Приложение продолжит работать в фоне.

При первом запуске автоматически создаётся SQLite-база, применяются миграции и загружается стартовый набор: 200 сотрудников, 40 активностей и 2743 записи истории. Вручную импортировать стартовые данные не нужно.

2. Создайте аккаунты сотрудника и HR

В том же терминале выполните по очереди:

docker compose exec app php artisan users:create [email protected] --employee=E0001
docker compose exec app php artisan users:create [email protected] --name="HR Administrator" --hr

Каждая команда запросит Password. Придумайте и сохраните пароль для соответствующего аккаунта: не менее 12 символов, не более 72 байт. При вводе символы не отображаются — это нормально. Не добавляйте к этим командам --no-interaction.

Готовых аккаунтов и общих паролей нет. Эти команды создают доступ только в вашей установке. Роль HR назначается из серверной консоли; посетитель сайта не может выдать её себе.

3. Откройте форму входа

Откройте http://localhost:8000/login и используйте созданные данные:

Что проверить	Email	Пароль
Личный кабинет сотрудника E0001	[email protected]	Заданный первой командой
HR: все профили, аналитика и импорт	[email protected]	Заданный второй командой

Без API-ключа рекомендации работают через детерминированный движок: учитывают навыки, карьерную цель и историю, содержат обоснование и пометку fallback. Чтобы проверить внешний LLM, задайте ключ и провайдера в .env по разделу AI-слой, затем выполните docker compose up -d.

Сценарий проверки для жюри

Как читать даты: будущие сессии активностей определяются относительно 1 октября 2026 года, включая сам этот день. Например, сессия 2026-10-07 считается предстоящей независимо от дня запуска приложения. При нажатии «Отметить выполненной» в историю записывается дата завершения 2026-10-01. Это позволяет проверять исходный набор данных в одинаковых условиях в любой день.

1. Развитие сотрудника

Войдите как [email protected] и откройте свой профиль E0001 (/employees/E0001). На странице видны карьерная лестница Junior → Lead, текущие навыки, разрывы до Middle и история активностей.

1. Нажмите «Получить рекомендацию». Появятся до трёх активностей с объяснением выбора и факторами, связанными с профилем. Перезагрузите страницу — рекомендации сохранятся.
2. На одной карточке нажмите «Отметить выполненной». Проверьте изменение навыков, готовности к следующему грейду и запись в истории.
3. Получите рекомендации ещё раз: подбор учитывает обновлённый прогресс. Завершённая активность не предлагается повторно, кроме повторяемого клуба EV_036.

2. HR-аналитика

Нажмите «Выйти» и войдите как [email protected]. Откроется режим HR со всеми сотрудниками.

• В разделе «Сотрудники» проверьте поиск и фильтры по роли и грейду, откройте любой профиль.
• В «HR-аналитика» (/hr) посмотрите проседающие навыки, сотрудников без рекомендованного шага и участие в активностях.
• В «Активности» (/hr/events) доступны поиск, фильтры, создание и редактирование активностей.

Режим определяется назначенной ролью аккаунта при входе. Для просмотра команды используйте HR-аккаунт, для личного профиля — аккаунт сотрудника.

3. Проверочные данные жюри

Войдя как HR, откройте «Импорт данных» (/admin/upload) и загрузите employees.json и/или activity_history.csv. Образцы формата находятся в docs/case_1/career_quest_dataset/:

• JSON содержит объект {"employees": [...]}.
• CSV содержит заголовок и столбцы как в стартовом файле истории.

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

Для просмотра загруженного профиля из HR новый аккаунт не нужен. Если хотите проверить вход от имени этого сотрудника, создайте отдельный аккаунт командой users:create с его --employee=ID.

4. Разграничение доступа

Действие	Ожидаемый результат
Выйти и открыть /employees	Перенаправление на форму входа
Войти сотрудником E0001 и открыть /employees/E0002	404 — чужой профиль скрыт
Тем же сотрудником открыть /hr или /admin/upload	403 — доступ запрещён
Проверить шапку личного кабинета сотрудника	Переключателя в HR нет
Войти HR и открыть список сотрудников и импорт	Доступ разрешён

Права и привязка к профилю хранятся в аккаунте на сервере. Режим интерфейса и старые демонстрационные сессии не выдают HR-права.

Повторный запуск и частые вопросы

docker compose stop     # остановить приложение, сохранив данные
docker compose up -d    # снова запустить

Аккаунты, импортированные данные и прогресс сохраняются в томе sqlite_data. Повторно создавать аккаунты не нужно.

Ситуация	Что сделать
Страница пока не открывается	Посмотреть docker compose logs --tail=100 app и дождаться запуска сервера
Порт 8000 занят	Освободить порт либо изменить левую часть 8000:8000 в docker-compose.yml и открыть новый порт
При вводе пароля ничего не видно	Продолжить ввод и нажать Enter: пароль скрыт
Команда сообщает, что email или профиль уже занят	Использовать ранее созданный аккаунт; для нового нужен свободный email и ещё не привязанный профиль
HR видит личный кабинет вместо списка сотрудников	Выйти и снова войти под HR-аккаунтом, чтобы обновить режим сессии
После частых попыток входа появился ответ 429	Подождать минуту и повторить вход с верным паролем
У рекомендации стоит fallback	Это рабочий подбор без внешнего LLM; ключ для проверки основного сценария не нужен

Запуск без Docker

Нужны PHP 8.4+ с SQLite, Composer, Node.js 22.12+ и npm. В корне проекта выполните:

./setup.sh
php artisan users:create [email protected] --employee=E0001
php artisan users:create [email protected] --name="HR Administrator" --hr
php artisan serve

Команды создания аккаунтов запрашивают пароли так же, как в Docker. Откройте /login на адресе, который выведет php artisan serve, и пройдите тот же сценарий для жюри.

setup.sh устанавливает зависимости, создаёт конфигурацию, применяет миграции, импортирует данные и собирает интерфейс. Используйте его для первоначальной установки: повторный импорт обновляет оценки навыков из исходного набора. Для последующих запусков достаточно php artisan serve. После изменений интерфейса выполните npm run build.

При обновлении установки без Docker после добавления авторизации выполните php artisan migrate --force. Старые пользователи не получают HR-права и профиль автоматически. Один профиль можно привязать только к одному аккаунту; HR также можно создать с личным профилем через --employee=ID.

Для ручного импорта каталога или отдельных файлов:

php artisan data:import --path=/path/to/jury-data
php artisan data:import --path=/path/to/employees.json
php artisan data:import --path=/path/to/activity_history.csv

В Docker добавляйте перед php artisan префикс docker compose exec app.

Технические детали и API

Стек: Laravel 13 / PHP 8.4+, SQLite, Blade + Tailwind. Дата среза данных: 2026-10-01; подбор будущих активностей считается относительно неё.

• Именованные роуты: employees.index, employees.show, employees.recommendations, employees.complete, hr.index, admin.upload, admin.upload.store, session.role.
• POST complete принимает event_id, возвращает ровно контракт из PLAN.md. Повторное завершение запрещено с 422, кроме EV_036. Прирост ограничен gain, max_level и 5; уже достигнутый уровень не снижается. Для Lead следующего грейда нет: grade: null, covered: 0, total: 0.
• POST recommendations возвращает 200 с 1–3 рекомендациями и source=llm|fallback; без доступного полезного шага — {"recommendations": []}. Последний ответ сохраняется в БД и заменяется при новом запросе; complete очищает устаревшие рекомендации.
• HrAnalyticsService::employeesWithoutNextStep() использует тот же движок, что и рекомендации, включая расписание, историю и положительный вклад в навыки. Внешний LLM для HR не вызывается.
• GET списка, профиля и HR поддерживают Accept: application/json. Список принимает search, role, grade, сохраняет фильтры при пагинации. Ключи профиля: employee, gaps, grade_readiness, history, skills, events, recommendations; HR: skill_gaps, employees_without_next_step, participation. В events профиля остаются события, которые можно отметить завершёнными; сохранённые recommendations содержат связанное event.
• Поля multipart-загрузки: employees, activity_history. Ответ JSON: {"imported": {"employees": 2, "activity_records": 3}} с ключами фактически загруженных файлов.
• Все POST используют стандартную CSRF-защиту Laravel: cookie сессии + X-CSRF-TOKEN из meta-тега страницы либо поле _token. POST /login принимает email и password и ограничен по частоте; POST /logout закрывает сессию. Маршруты с данными требуют входа (перенаправление для HTML, 401 для JSON). POST /session/role принимает role=employee|hr, но переход в HR требует назначенной сервером роли, иначе возвращается 403.
• JSON-поля skills/required_skills — карты skill_id → level. Eloquent-связи: activityRecords, recommendations, manager, reports, employee, event. Для составного ключа роли используются методы Employee::roleProfile() и nextGradeProfile(), возвращающие модель или null.
• Клиентский сценарий использует fetch с CSRF-токеном и Accept: application/json. Повторная отправка блокируется на время запроса; ошибки и пустой результат показаны на странице. После завершения обновляется серверный HTML профиля, поэтому шкалы и история используют тот же расчёт, что и API.

Проверка

php artisan test --compact
npm run build

Стартовые количества: 60 skills, 32 role_profiles, 200 employees, 40 events, 2743 activity_records. Тесты используют отдельную SQLite in-memory базу; проверяют повторный импорт, частичный merge, откат ошибочной загрузки, прогресс, повторные завершения, роли, HTTP-контракты и HR-агрегации.

AI-слой

Проверка на стартовом датасете без Docker и базы (нужны PHP 8.4+ и composer install):

php artisan ai:recommend E0028 --offline

Команда возвращает JSON по контракту PLAN.md. Другая папка с данными: php artisan ai:recommend E0028 --dataset=path/to/dataset --offline. Без --offline команда обращается к выбранному LLM-провайдеру.

В локальном .env задаются LLM_DRIVER=openai, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL=gpt-4o-mini, LLM_TIMEOUT=8. Для Anthropic: LLM_DRIVER=anthropic и соответствующие ANTHROPIC_*. LLM_DRIVER=disabled полностью отключает сеть. Ключи не должны попадать в Git. Для OpenAI-compatible сервера без JSON Schema: OPENAI_STRUCTURED_OUTPUTS=false; локальная проверка ответа сохраняется. Повторных запросов нет, таймаут ограничен 8 секундами даже при большем значении в .env.

Контракт сервисов

$result = app(\App\Services\LlmService::class)->recommend(
    employee: $employeeData,
    events: $eventRows,
    roleProfiles: $roleProfileRows,
    history: $activityRows,
    skillCatalog: $skillRows,
    asOf: '2026-10-01',
    skillsAlreadyCurrent: false,
);
// $result === ['recommendations' => [...]]

Все аргументы — массивы, поля совпадают с JSON/CSV датасета; для моделей используйте toArray() с приведёнными к массивам JSON-полями. Сервисы ничего не записывают в БД. Контроллер сохраняет ответ и обеспечивает доступ сотрудника только к своему профилю.

skillsAlreadyCurrent=false означает исходные навыки на last_review_date: SkillProjector добавляет завершения после этой даты в хронологическом порядке, не меняя исходный профиль. Завершения, уже включённые ProgressService в сохранённые навыки, помечаются внутренним skills_applied=true и пропускаются при начислении. Поле не входит в CSV. Повторный импорт оценки сотрудника сбрасывает эти отметки, чтобы проекция строилась от новой оценки. Для внешнего вызова с полностью актуальными навыками можно передать skillsAlreadyCurrent=true. История всё равно используется для фильтров и скоринга. При наличии completed_at используется эта дата; иначе — date из датасета.

Для HR можно вызвать RecommendationEngine::analyze() с теми же аргументами: он вернёт актуальные навыки, разрывы, сводку истории и полный список кандидатов. Пустой список означает отсутствие доступного полезного шага; искусственные рекомендации для заполнения трёх карточек не создаются.

Правила выбора и объяснения

• Исключаются обязательные, неподходящие по роли/грейду, недоступные по prerequisites, завершённые (кроме EV_036) и уже начатые активности.
• У событий по расписанию должна быть сессия не раньше даты среза; self_paced доступен всегда. Исключаются события без полезного прироста к требованиям следующего грейда или карьерной цели.
• Реальный прирост: max(0, min(gain, max_level - current, 5 - current)). Для Lead используются требования Lead, без вымышленного следующего грейда.
• Вес закрытия разрыва — 4 за уровень, критичного навыка — дополнительно 3, карьерной цели — дополнительно 2. Штрафы за no_show/declined/dropped: 4 за то же событие, 2 за другое с общими навыками, 0.5 только за общий тип. Одна запись получает только один штраф; обязательные события не штрафуют.
• Завершённые добровольные события с общими навыками дают до 1 балла, подтверждённые завершения в срок — до 0.5. Последнее требует completed_at и due_date: CSV не даёт оснований считать дату зачисления датой завершения.
• Доступность даёт 1 балл для self_paced, иначе 1 / (1 + days / 30). При равенстве баллов порядок определяется event_id.
• LLM получает обезличенный профиль, разрывы, сводку истории и топ-8. Первый кандидат движка обязателен; LLM выбирает до двух дополнительных. Для каждого шага выбираются минимум три проверяемых фактора: грейд, разрыв и история; критичный навык также обязателен, если он есть.
• Обоснование собирается из точных русских фраз выбранных факторов. Локальная проверка отклоняет выдуманные числа, неизвестные события, дубликаты, пропущенные факторы, отказ модели и обрезанный JSON. При любой ошибке провайдера возвращается топ-3 движка с source=fallback.

OpenAI использует Structured Outputs, Anthropic — Messages API с инструментом. В журнал пишутся только категория сбоя и HTTP-статус, без ключей и ответов провайдера.

Проверка AI-слоя

php artisan test --compact tests/Unit/RecommendationEngineTest.php tests/Feature/LlmServiceTest.php tests/Feature/RecommendEmployeeCommandTest.php tests/Feature/RecommendationIntegrationTest.php

Тесты отключают реальную сеть. Покрыты антипример из ТЗ, граничные условия, оба провайдера, невалидные ответы, ошибки связи и все 200 профилей стартового кита. Реальный OpenAI-запрос отдельно проверен на искусственном примере без данных из стартового кита; Anthropic проверен через имитацию HTTP-ответов.