Sauron — от идеи бизнеса к понятной задаче для команды

MVP команды Sauron для кейса AI Sana Challenge Hub на хакатоне HackAlem AI.

Бизнес описывает проблему, AI-навигатор помогает уточнить детали, а рейтинг показывает полноту карточки. Студенческие команды находят задачи в каталоге и предлагают решения. Бизнес сам выбирает одну, несколько или ни одной команды — автоматического назначения нет.

Зачем нужен Sauron

«Хотим автоматизировать процесс» ещё не объясняет команде, что именно делать. Без контекста, данных и критериев успеха участникам приходится сначала восстанавливать постановку задачи в переписке.

Sauron помогает бизнесу сформулировать потребность, а студентам — оценить, что известно о задаче и какие вопросы остаются открытыми. Геймификация строится вокруг улучшения карточки: бизнес дополняет описание, видит рост баллов и поднимает задачу в каталоге.

Что работает

1. Черновик. Бизнес указывает название, направление и описание своими словами.
2. Уточнение. Навигатор предлагает не меньше трёх вопросов с учётом описания и заполненных полей.
3. Карточка. Человек отвечает на вопросы и редактирует контекст, результат, ограничения и контакты.
4. Рейтинг. Интерфейс показывает оценку 0–100, вклад каждого блока и недостающие сведения. При сохранении рейтинг пересчитывает сервер.
5. Публикация. После ручного подтверждения задача появляется в каталоге. Есть поиск, фильтры по направлению и готовности, сортировка и закладки.
6. Отклик. Команда создаёт профиль, описывает идею, план и сроки. Ссылка на прототип необязательна.
7. Решение бизнеса. В рабочем пространстве можно принять несколько откликов или отклонить все. Принятие одного не отклоняет остальные.

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

Есть адаптивный интерфейс, редактирование профилей команд, локальное сохранение черновика формы и обработка ошибок сети. Изменение уже опубликованной карточки требует нового подтверждения перед сохранением.

Технологии

Зависимости: requirements.txt, package.json, package-lock.json.

Быстрый запуск

Нужны Git, Python 3.12+, Node.js 22.12+ и доступ к репозиторию команды. Для локального демо не нужны Docker и ключ внешнего AI.

Windows / PowerShell

git clone https://github.com/BAITC-Hacks/hack-a83e1c43-sauron.git
cd hack-a83e1c43-sauron

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

npm ci
npm run build

$env:AI_PROVIDER = "mock"
.\.venv\Scripts\python.exe manage.py migrate
.\.venv\Scripts\python.exe manage.py seed_demo
.\.venv\Scripts\python.exe manage.py runserver 127.0.0.1:8000

Если репозиторий уже скачан, начните с перехода в его папку. Активация виртуального окружения не требуется: команды явно используют Python из .venv.

Откройте:

• Главную страницу.
• Каталог задач.
• Проверку API — ожидается {"status":"ok","service":"hackalem-ai-backend"}.

Django отдаёт готовую сборку из dist/ и API на одном адресе. После изменения файлов в src/ повторите npm run build. Сборка, база и зависимости не хранятся в Git.

git clone https://github.com/BAITC-Hacks/hack-a83e1c43-sauron.git
cd hack-a83e1c43-sauron

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
npm ci
npm run build

export AI_PROVIDER=mock
.venv/bin/python manage.py migrate
.venv/bin/python manage.py seed_demo
.venv/bin/python manage.py runserver 127.0.0.1:8000

Разработка с автоперезагрузкой фронта

После установки зависимостей и миграций:

npm start

Скрипт запускает Django и Vite или использует уже запущенные серверы. Фронтенд разработки доступен на http://127.0.0.1:5173/, запросы /api проксируются на порт 8000. На Windows также можно запустить start-sauron.cmd.

Как проверить решение жюри

После seed_demo в общем пространстве есть пять синтетических задач с разной полнотой описания.

1. Откройте создание задачи. Укажите название, направление «Образование» и черновик: «Нужно помочь кураторам вовремя замечать студентов, которым сложно продолжать обучение».
2. Нажмите «Уточнить с навигатором». Появятся вопросы; в стандартном запуске это явно обозначенный базовый навигатор.
3. Заполните часть ответов, затем дополните контекст, результат, критерии успеха и контакты. Проверьте, как меняется предварительный рейтинг и баллы по блокам.
4. На шаге обзора нажмите «К публикации». Карточка сохранится, но публикация потребует отдельного подтверждения. Отметьте его и нажмите «Опубликовать задачу».
5. Найдите задачу в каталоге. Проверьте поиск, сортировку и фильтры. Задачи с низким баллом тоже доступны.
6. В карточке нажмите «Предложить подход». Выберите или создайте команду, заполните идею, план и сроки, отправьте отклик.
7. Откройте отклики, найдите предложение и нажмите «Принять» или «Отклонить», затем подтвердите решение.
8. Обновите страницу: задача, профиль, отклик и решение сохранятся в базе. Для проверки выбора нескольких команд отправьте ещё один отклик от другого профиля.

В MVP используется общее пространство без регистрации: можно пройти обе стороны сценария в одном браузере. Это не разграничение прав доступа.

Рейтинг готовности

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

В блоках из двух полей одно заполненное поле даёт половину баллов. Пустой текст, ответы короче трёх букв/цифр, повторы одного символа и известные заглушки вроде test, TODO и «не знаю» баллов не дают.

Уровни: 0–39 — черновая; 40–69 — рабочая; 70–89 — готовая; 90–100 — приоритетная.

Уровень готовности и статус публикации независимы: опубликованная задача с 0 баллов остаётся в каталоге. Формула находится в challenges/scoring.py, предварительный расчёт интерфейса — в src/domain.ts.

AI-навигатор

Навигатор задаёт вопросы, а не пишет факты за бизнес. Ответы вводит человек; они сохраняются в соответствующие поля карточки.

• По умолчанию — AI_PROVIDER=mock. Это детерминированные локальные правила, не обращение к LLM. Вопросы учитывают тему черновика и уже заполненные поля. Такой режим позволяет показать сценарий без ключа и внешнего API.
• Опционально — AI_PROVIDER=openai. Серверный адаптер запрашивает структурированный ответ внешней модели. Модель задаётся через OPENAI_MODEL; значение по умолчанию в коде — gpt-4o-mini.
• Проверяются количество вопросов, типы данных, допустимые поля и отсутствие повторов. При ошибке провайдера или некорректном ответе используются локальные вопросы, а интерфейс сообщает о переходе.
• AI не публикует задачи, не принимает отклики и не назначает команды.

Вход API:

{
  "draft_text": "Нужно помочь кураторам вовремя поддерживать студентов.",
  "card": {
    "users": "Студенты первого курса и кураторы"
  }
}

Ответ содержит provider, draft_text, от 3 до 9 объектов {field, question} в questions и список missing_fields. При резервном режиме добавляются fallback_reason и notice.

Промпт, схема ответа и обработка ошибок: challenges/services/ai.py. Проверки повреждённых ответов и недоступности провайдера: challenges/test_regressions.py. Тесты не отправляют платные запросы внешнему AI.

Настройки окружения

Список переменных находится в .env.example. Django не загружает этот файл автоматически: задавайте переменные в терминале, из которого запускаете сервер, или средствами окружения.

Для внешнего режима нужны AI_PROVIDER=openai и OPENAI_API_KEY; OPENAI_MODEL необязателен. После изменения настроек перезапустите Django. Ключ хранится только на сервере: не добавляйте его в Git или переменные VITE_*, доступные браузеру.

Для PostgreSQL можно использовать сервис из docker-compose.yml и задать DATABASE_URL перед миграциями и запуском. Основной сценарий демо использует SQLite.

Данные и режимы приложения

python manage.py seed_demo создаёт в базе 5 задач с исходными описаниями и карточками, 5 профилей команд и 5 откликов. Данные синтетические. Повторный запуск не затирает ручные правки, решения или названия и не создаёт повторно те же записи.

Источник набора: challenges/management/commands/seed_demo.py.

Не путайте два режима интерфейса:

• Общее пространство — настоящий Django API и база данных. Это основной режим проверки решения.
• «Попробовать на примере» — отдельное демо в localStorage. Оно включается явно; его данные не отправляются на сервер. Ошибка API сама по себе не переключает приложение в этот режим.

Основные API

Базовый путь: /api/v1/. Все URL заканчиваются /.

Каталог поддерживает industry, readiness_level, min_score и max_score; по умолчанию задачи отсортированы по убыванию рейтинга. Неверные значения фильтров возвращают HTTP 400.

status, score и временные метки не задаются клиентом. При изменении опубликованной карточки в PATCH нужен confirmed: true после проверки человеком; без него прежняя версия остаётся в каталоге.

Проверки

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

npm run build
npm test
.\.venv\Scripts\python.exe manage.py check
.\.venv\Scripts\python.exe manage.py test

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

Полный браузерный прогон на Windows с установленным Microsoft Edge:

$env:RUN_BROWSER_TESTS = "1"
$env:AI_PROVIDER = "mock"
.\.venv\Scripts\python.exe manage.py test challenges.test_frontend

Он сам поднимает тестовый сервер и временную БД: рабочие задачи не изменяются. Четыре сценария охватывают каталог и закладки, путь от черновика до решения бизнеса, мобильные экраны и явное переключение на демо при ошибке сети. Результаты сохраняются локально в artifacts/.

Ограничения MVP и следующие шаги

• Нет авторизации и владельцев записей. API использует AllowAny; задачи, черновики, команды и решения доступны в общем пространстве. Текущая версия предназначена для локального демо, не для открытого сервиса с реальными данными.
• Нет загрузки файлов, чатов и уведомлений. Прототип можно приложить ссылкой.
• Баллы команд за выполненную работу и учёт дальнейшего прогресса пока не реализованы. Это следующий этап, а не часть показанного сценария.
• Нет собственной обученной модели и смысловой проверки качества каждой формулировки.
• Перед публичным запуском нужны серверные права доступа, безопасные настройки развёртывания и работа с персональными данными.

Автоматическое назначение исполнителя не является пропущенной функцией: по правилам продукта команды сами откликаются, а бизнес принимает решение вручную.

Где смотреть код

• src/ — интерфейс и клиент API.
• challenges/ — модели, API, рейтинг, AI-адаптер, демо-данные и тесты.
• config/ — настройки и маршруты Django.
• e2e/ — браузерные сценарии.
• docs/FRONTEND.md — подробности фронтенда и режимов запуска.

Рабочая версия находится в ветке main. Фронтенд команды интегрирован из ветки nurda; запускать отдельный старый лендинг не нужно.