AI Sana Challenge Hub

Публичная версия: challenge-hub-production.up.railway.app · Исходное ТЗ

Демо-видео (4 мин 47 с): от черновика до принятого отклика · русские субтитры · описание записи

Проблема

Короткое описание бизнес-задачи часто не даёт студенческой команде понять, какие данные доступны, что нужно сделать и по каким критериям принимать результат. AI Sana Challenge Hub помогает бизнесу уточнить такую задачу, показывает готовность карточки к работе и открывает её командам. Команда сама предлагает решение, а бизнес выбирает, с кем продолжить работу. Проект создан для кейса AI Sana на HackAlem AI.

Что реализовано

• Конструктор задачи: свободный черновик, не менее трёх уточняющих вопросов, редактируемая карточка из десяти полей, ручное подтверждение и публикация.
• Рейтинг 0–100: расшифровка начислений, подсказки по недостающим сведениям, история изменения балла и прогноз места в каталоге. Официальный балл обновляется при подтверждении карточки.
• Открытый каталог: сортировка по подтверждённому рейтингу, фильтры по отрасли и уровню готовности. Низкий рейтинг не скрывает опубликованную задачу и не запрещает отклик.
• Отклики и выбор: команда отправляет идею, план, срок и ссылку; бизнес сравнивает предложения и вручную принимает или отклоняет их. Число откликов не ограничено.
• Дополнительные инструменты: рекомендации задач командам по совпадению интересов и навыков; помощник формулировок карточки; проверка карточки «ИИ-студентом»; подтверждение выполненного этапа с начислением команде 10 баллов; панель общих показателей программы.
• Проверка данных: ИИ подбирает полные исходные фразы бизнеса с сохранением отрицаний и условий; свободный пересказ отбрасывается. Контакты можно извлечь дословно. Структура JSON проверяется локально: неверный ответ вызывает повтор, затем заглушку. ИИН и номера банковских карт с корректными контрольными цифрами маскируются до сохранения и отправки в модель; для других упоминаний персональных данных выводится предупреждение.

Как работает решение

Черновик бизнеса → вопросы → ответы → редактируемая карточка
→ рейтинг и подсказки → подтверждение → общий каталог
→ отклик команды → ручное решение бизнеса → подтверждённый этап → баллы команде

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

Рейтинг считает код, а не модель. Максимум — 100 баллов; сумма частей уменьшается при отписках, бессмысленном тексте, повторах и наборах ключевых слов:

Показатель	Правило начисления	Макс.
Контекст и потребность	Контекст 6 + потребность 6 + числовая конкретика в каждом поле по 4	20
Данные и материалы	Описание 8 + источник 6 + формат 3 + объём или период 3	20
Ожидаемый результат	Описание 8 + подробность 4 + число 3	15
Критерии успеха	Описание 5 + числовая цель 7 + метрика 3	15
Ограничения	Описание 5 + числовая граница 3 + вид ограничения 2	10
Пользователи	Названы 6 + роль уточнена 4	10
Связь с бизнесом	Контакт 6 + формат взаимодействия 4	10

Уровни: 0–39 — черновик, 40–69 — рабочая, 70–89 — готовая, 90–100 — приоритетная. Каталог сортируется по официальному баллу по убыванию, при равенстве — по времени публикации (новые выше). Фильтр темы реализован через отрасль. Рекомендации доступны для опубликованных задач от уровня «рабочая» и основаны на совпадении слов в задаче с интересами, навыками и технологиями команды. Подробная формула — в docs/03-rating.md.

Технологии и архитектура

Слой	Используется
Веб	JavaScript/JSX, React 18, Vite 5, собственный CSS; запросы через fetch к /api
API	Python 3.11–3.14, FastAPI, Pydantic, Uvicorn, python-dotenv
Хранение	SQLite через стандартный модуль Python sqlite3; синтетические JSON-файлы в seed/
ИИ	OpenAI API через официальный SDK; модель по умолчанию — gpt-5-mini (настраивается OPENAI_MODEL); Structured Outputs со строгой JSON-схемой
Проверка API	pytest и httpx
Публичный хостинг	Railway, один Docker-сервис для API и собранного веб-интерфейса

Браузер (web/: React + Vite)
             │ fetch /api
             ▼
FastAPI (backend/app/main.py) ── backend/app/db.py ── SQLite
       ├── tasks.py: жизненный цикл карточки
       ├── rating.py + catalog.py: баллы, место, рекомендации
       ├── proposals.py + stats.py: отклики, этапы, показатели
       ├── privacy.py: маскирование и предупреждения
       └── ai.py → llm.py → OpenAI API (если задан ключ)

FastAPI раздаёт /api/* и собранные файлы web/dist с одного адреса. В разработке Vite проксирует /api на локальный FastAPI. Все вызовы модели проходят через backend/app/llm.py. Промпты, форматы входа и выхода и обработка неверного ответа показаны на странице «Как работает ИИ» (#/ai) и в GET /api/ai/spec. Контракт API — docs/02-api.md.

Установка и запуск

Нужны Python 3.11–3.14, Node.js 18+ и npm, а также доступ к реестрам пакетов при первой установке. Если репозиторий ещё не склонирован, скопируйте его адрес со страницы проекта и замените URL_РЕПОЗИТОРИЯ в команде:

git clone "URL_РЕПОЗИТОРИЯ" ai-sana-challenge-hub
cd ai-sana-challenge-hub

Если клон уже есть, откройте терминал в его корневой папке.

Быстрый запуск на macOS, Linux или в WSL:

./run.sh

Откройте http://localhost:8000. Состояние API доступно по http://localhost:8000/api/health.

Ручной запуск на macOS/Linux из корня репозитория:

python3 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt
[ -f .env ] || cp .env.example .env
(cd web && npm ci && npm run build)
cd backend
../.venv/bin/python -m app.db
../.venv/bin/python -m uvicorn app.main:app --port 8000

Ручной запуск на Windows (PowerShell) из корня репозитория:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
Set-Location web
npm ci
npm run build
Set-Location ..\backend
..\.venv\Scripts\python.exe -m app.db
..\.venv\Scripts\python.exe -m uvicorn app.main:app --port 8000

run.sh выполняет те же шаги автоматически и создаёт .env только при отсутствии файла. Команда python -m app.db и скрипт run.sh пересоздают локальную базу backend/hub.db. Ключ OpenAI не требуется для основного сценария: без OPENAI_API_KEY используется локальная заглушка. Для вызовов модели заполните OPENAI_API_KEY в .env; OPENAI_MODEL позволяет сменить модель, DEMO_MODE=1 принудительно включает заглушку.

На публичном Railway-сайте при проверке 23.09.2026 ответ /api/health показывал "llm":"llm": сервер настроен на вызовы OpenAI API. Чтобы проверить работу без ключа, запустите чистый клон локально с пустым OPENAI_API_KEY или задайте DEMO_MODE=1 в .env; тогда /api/health покажет "llm":"stub".

Для отдельной разработки интерфейса после запуска API можно открыть второй терминал:

cd web
npm install
npm run dev

Vite откроет адрес, указанный в терминале, и направит запросы /api на порт 8000.

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

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

1. Бизнес: выберите ТОО «Агро Север» → «Новая задача», отрасль «Агро». Введите: «Хотим понимать, какие поля скоро потребуют полива». Проверьте, что появились минимум три вопроса.
2. Ответы: сообщите о цели сократить расход воды на 20% за сезон, выгрузке датчиков влажности за 2 года в CSV, дашборде с прогнозом на 7 дней и критерии точности не ниже 80%. В собранной карточке дополните название, пользователей, ограничения, контакт и формат общения. Сохраните правки; проверьте рост и расшифровку рейтинга.
3. Публикация: нажмите «Подтвердить карточку», затем «Опубликовать». Переключитесь на команду «DataCats» и найдите задачу в каталоге; её место определяется подтверждённым рейтингом.
4. Отклик: откройте задачу от имени команды и заполните идею, план, срок и URL прототипа. Отправьте отклик.
5. Решение: вернитесь к бизнесу → «Мои задачи» → «Отклики». Примите предложение DataCats; в роли команды проверьте статус «Принят» в «Мои отклики». Бизнес также может отклонить предложение.
6. Результат: переключитесь обратно на бизнес ТОО «Агро Север» → «Мои задачи» → «Отклики» у созданной задачи. У принятого отклика в блоке «Подтвердить этап работы» введите название выполненного этапа и нажмите «Подтвердить этап · +10 баллов». Откройте «Панель программы» по ссылке из сообщения об успехе и проверьте, что у DataCats стало на 10 баллов больше.

Дополнительно можно изменить уже опубликованную карточку: предварительный балл изменится сразу, а официальный балл и место в каталоге — после повторного подтверждения. Команда до этого видит прежний подтверждённый текст и рейтинг (GET /api/catalog/{id}). Полный сценарий демонстрации с текстами — в docs/04-demo.md.

Для проверки API после установки зависимостей запустите из каталога backend:

../.venv/bin/python -m pytest

На Windows используйте ..\.venv\Scripts\python.exe -m pytest. Набор в backend/tests/ покрывает рейтинг, ИИ и его заглушку, маскирование данных, жизненный цикл задачи, каталог, отклики, статистику и сквозной сценарий; отдельно запустить последний можно командой ../.venv/bin/python -m pytest tests/test_scenario.py.

Данные и интеграции

В seed/ находятся 5 синтетических профилей бизнеса, 5 примеров черновиков, 5 опубликованных карточек, 5 профилей команд и 5 откликов. Примеры черновиков показываются через GET /api/meta; карточки, команды и отклики загружаются в SQLite при инициализации. Рейтинг начальных карточек пересчитывается тем же модулем, что и рейтинг новых задач. Внешний набор данных проект не загружает.

Единственный внешний AI-сервис — OpenAI API при наличии ключа. Без ключа локальная заглушка сохраняет путь от черновика до решения бизнеса; помощник формулировок без живой модели не предлагает текст. Railway используется для публикации веба и API по одной ссылке.

Ограничения текущей версии

• Роли выбираются в интерфейсе без регистрации и проверки личности; это демонстрационный режим.
• На Railway SQLite лежит в контейнере (/tmp/hub.db): при новом деплое данные и действия посетителей сбрасываются к синтетическому сиду.
• Рекомендации основаны на совпадении слов, без обученной модели или векторного поиска.
• Подтверждение этапа — ручное действие бизнеса по названию выполненной работы. Загрузка доказательств и защита от повторного начисления баллов за один этап не реализованы.
• Помощник карточки требует доступа к OpenAI API. Локальная заглушка обеспечивает основной сценарий, но не создаёт предложения помощника.

Раскрытие подготовленного кода

До начала соревновательной части были подготовлены структура репозитория, общий каркас FastAPI и тестовая фикстура. Схема БД, синтетические данные, рейтинг, ИИ-сценарий, каталог, отклики и интерфейс созданы после публикации кейса. Сторонние библиотеки и сервисы перечислены в разделе «Технологии и архитектура».