SanaChallenge AI

Помогаем бизнесу описать задачу, а студентам — найти проект и команду.

Репозиторий команды · HackAlem AI · Локальный MVP

---

1. Зачем мы это сделали

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

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

2. Что уже работает

Для бизнеса:

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

Для студента:

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

Ответы, профили и прочитанные уведомления сохраняются в базе. После обновления страницы они не пропадают. Навыки можно изменить через «Мои навыки».

3. Как это выглядит для пользователя

flowchart TD
    A[Бизнес описывает идею] --> B[AI задаёт вопросы]
    B --> C[Бизнес проверяет и публикует задачу]
    D[Студент указывает свои навыки] --> E[Находит задачу и команду]
    C --> E
    E --> F[Команда отправляет предложение]
    F --> G[Бизнес получает уведомление]
    G --> H[Бизнес выбирает команду]

Например, бизнес пишет: «Хочу интернет-магазин для продажи обуви». Вместо пустой длинной формы он получает вопросы о товарах, текущих продажах, нужных функциях и сроках. Пока AI готовит вопросы, видна загрузка. Дальше вопросы открываются на отдельных карточках.

AI может предложить ответ, но пользователь сам решает, применять его или нет. Перед публикацией можно просмотреть всё задание и увидеть, каких деталей не хватает. Результат — задача, на которую команда уже может предложить конкретный план.

4. На чём сделан проект

Часть	Что используем
Интерфейс	React 19, TypeScript, Vite 6, React Router, Lucide, CSS
Сервер	Python 3.12 в Docker, FastAPI, Pydantic, Uvicorn
База данных	PostgreSQL 16, SQLAlchemy Async, asyncpg
Изменения схемы базы	Alembic
AI	OpenAI Python SDK и Responses API, ответы по заданной структуре
Запуск	Docker Compose и Nginx
Тесты	pytest, HTTPX, Playwright; проверка кода — Ruff и TypeScript

Модель задаётся в OPENAI_MODEL. Локально использовали gpt-5.6-sol. Для другого аккаунта нужно выбрать доступную ему модель с поддержкой используемого API — это имя не гарантированно доступно каждому ключу.

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

5. Как всё устроено

flowchart LR
    U[Браузер: React] --> N[Nginx]
    N --> A[Сервер: FastAPI]
    A --> D[(PostgreSQL)]
    A --> O[OpenAI API]

Браузер показывает страницы и отправляет запросы серверу. Сервер проверяет, кто вошёл и какие действия ему доступны, сохраняет данные и обращается к AI. Ключ OpenAI остаётся на сервере и не передаётся браузеру.

В базе хранятся аккаунты, навыки, команды, задачи, ответы, оценки и отклики. Уведомление связано с откликом: когда бизнес открывает его, сервер сохраняет отметку о прочтении.

frontend/src/         страницы и компоненты интерфейса
backend/app/api/      запросы к серверу
backend/app/application/  создание задач, отклики и выбор команды
backend/app/domain/   правила оценки и основные сущности
backend/app/infrastructure/  работа с БД, аккаунтами и AI
backend/alembic/      изменения схемы базы
backend/scripts/     демонстрационные данные
backend/tests/       тесты сервера
frontend/tests/      проверки в браузере

6. Как запустить

Нужны Git, Docker с Docker Compose и браузер. При первой сборке понадобится интернет для загрузки образов и пакетов. Для AI нужен доступ к OpenAI API. Видеокарта не требуется.

Скачать проект

git clone https://github.com/BAITC-Hacks/hack-61bb6bed-sudo-ai.git
cd hack-61bb6bed-sudo-ai
cp .env.example .env

Если .env уже существует, не копируйте его заново: там могут быть ваши настройки.

Настроить .env

Для обычного локального входа установите:

APP_ENV=development
DEMO_AUTH_ENABLED=false
FRONTEND_URL=http://localhost:5173
OPENAI_API_KEY=
OPENAI_MODEL=
AI_TIMEOUT_SECONDS=25

В .env.example ключ и модель оставлены пустыми, технический демо-вход отключён. Для работы AI впишите свой ключ и доступную модель только в локальный .env. Без ключа можно заполнить задачу вручную.

DEMO_AUTH_ENABLED включает вход по техническому заголовку X-Demo-User. Для входа через форму, в том числе в демо-аккаунты ниже, он не нужен.

Запустить

Из корня проекта:

docker compose up -d --build

Сначала запускается база и обновляется её схема. Затем автоматически создаётся небольшой набор для проверки, после чего запускаются сервер и интерфейс:

• два аккаунта для входа: бизнес и студент;
• три команды с демо-участниками: фронтенд, бэкенд и аналитика;
• четыре готовые задачи;
• один отклик с непрочитанным уведомлением для бизнеса.

Это только синтетические примеры из кода. Локальная база разработчика, ключи, пользовательские черновики и история тестов не входят в этот набор. AI при подготовке примеров не вызывается. Анкета студента остаётся пустой, чтобы проверяющий мог пройти её самостоятельно.

За набор отвечает scripts.seed_review_demo. Повторный запуск не создаёт дубликаты, не сбрасывает ответы и не делает прочитанный отклик новым. Чтобы отключить автозаполнение, задайте REVIEW_DEMO_ENABLED=false в .env. В production оно отключено независимо от этого флага.

Откройте http://localhost:5173. После выбора роли данные демо-входа заполнятся автоматически:

Роль	Email	Тестовый пароль
Бизнес	[email protected]	Sana-Demo-Business-2026
Студент	[email protected]	Sana-Demo-Student-2026

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

Ещё полезные адреса:

• Документация API.
• Проверка работы сервера.
• Проверка готовности базы.

Данные сохраняются в Docker volume postgres_data. В основном Compose база не доступна снаружи Docker, а сайт и API доступны только на локальной машине.

docker compose ps                       # состояние контейнеров
docker compose logs --tail=100 backend  # последние сообщения сервера
docker compose stop                    # остановить приложение

После смены ключа или модели:

docker compose up -d --force-recreate backend

7. Как проверить

Быстро посмотреть готовый пример

1. Запустите проект командой из предыдущего раздела — примеры добавятся автоматически.
2. Войдите как бизнес и нажмите колокольчик.
3. Откройте отклик API Crew · демо на задачу «Интернет-магазин: каталог и заказы · демо». В нём есть описание команды, план из четырёх шагов и срок — 3 недели. После открытия уведомление станет прочитанным.
4. Нажмите «Выйти». Вы вернётесь на главную с выбором роли.
5. Войдите как студент. В анкете выберите Фронтенд → React и TypeScript → Есть учебные или личные проекты. Если анкета уже заполнена, откройте «Мои навыки».
6. В кабинете найдите «Витрина интернет-магазина · демо». Она появится, если ещё открыта.
7. В «Моих командах» посмотрите рекомендации. Например, API Crew добавит навыки работы с сервером и базой, а вы — React и TypeScript. Можно вступить в команду с открытым набором.

Этот пример не требует вызова AI. Если вы уже прочитали уведомление или вступили в команду, приложение сохранит эти действия — при повторном просмотре состояние будет другим.

Пройти весь путь с новой задачей

1. Подключите OpenAI и войдите как бизнес.
2. Напишите: «Хочу интернет-магазин обуви. Сейчас заказы принимаем в Instagram» и создайте черновик.
3. Дождитесь вопросов и заполните карточки. Для теста можно указать каталог и корзину, 20 тестовых заказов как критерий успеха и 3 недели на прототип без онлайн-оплаты.
4. Попробуйте помощь AI в одной карточке. Проверьте предложенный текст перед применением.
5. На странице проверки оцените задачу. Заполните обязательные поля, если что-то пропущено, и опубликуйте её. Точный балл AI может отличаться от запуска к запуску.
6. В другом профиле браузера войдите студентом, создайте команду или вступите в открытую. Найдите задачу и отправьте предложение с подходом и сроком.
7. Вернитесь к бизнесу. Откройте новое уведомление, посмотрите предложение и подтвердите выбор команды.

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

Автоматические проверки

Для браузерных проверок нужны Node.js 22, работающая платформа и демо-данные:

cd frontend
npm ci
npm run build
npx playwright install chromium
npx playwright test tests/student.spec.ts tests/notifications.spec.ts

Тест уведомлений подставляет ответы для проверки интерфейса. Реальное создание уведомления и права доступа проверяются тестами сервера. Браузерные тесты создают тестовые аккаунты и могут менять демо-данные.

Для сервера нужны Python 3.12–3.14 и uv. Из корня проекта:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres
# Создать один раз, если тестовой базы ещё нет:
docker compose exec -T postgres createdb -U sana sana_test
cd backend
uv sync --frozen
export TEST_DATABASE_URL='postgresql+asyncpg://sana:[email protected]:55439/sana_test'
DATABASE_URL="$TEST_DATABASE_URL" uv run alembic upgrade head
uv run pytest -q
DATABASE_URL="$TEST_DATABASE_URL" uv run alembic check

Если меняли настройки PostgreSQL, замените их и в URL. Тесты очищают таблицы тестовой базы, поэтому её имя обязательно должно заканчиваться на _test. Без TEST_DATABASE_URL проверки с БД пропускаются.

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

8. Какие данные и сервисы используем

Пользователь сам вводит описание бизнеса, ответы, навыки и предложения команды. Они сохраняются в PostgreSQL. Для демонстрации используются вымышленные пользователи и учебные задачи из скриптов. Внешние датасеты не импортировались.

OpenAI получает описание задачи и ответы для подготовки вопросов и анализа. Поэтому не нужно вводить конфиденциальные или реальные персональные данные без разрешения. Запросы используют store=False, но данные всё равно передаются во внешний сервис. Проверять ответы AI должен пользователь.

GitHub используется для исходного кода, Codex — при разработке. NVIDIA и курс Arizona State University не подключены к приложению.

Пароли хранятся в виде Argon2id-хешей. Вход работает через серверные сессии и HttpOnly-cookie; изменяющие запросы защищены CSRF-токеном. Сервер проверяет права на задачи и команды. Есть ограничения частоты входа и AI-интервью.

Настоящие ключи, токены и персональные промокоды нельзя добавлять в код, README или чат. .env исключён из Git; перед push нужно проверять и остальные файлы, включая .env.example.

9. Что пока ограничено

• AI может ошибаться или быть недоступен. Без него базовая оценка проверяет заполнение и не превышает 40/100. С AI оценка учитывает девять критериев: 20% за заполнение и 80% за смысл. Это оценка карточки, не оценка жюри.
• Вопросы готовятся одним запросом. Затем сохраняются. Они не приходят потоком после каждого ответа; для текущей карточки есть отдельный помощник.
• Подбор работает по навыкам. Опыт и интересы сохраняются, но пока не влияют на порядок рекомендаций. Процент совпадения не означает вероятность успеха команды.
• Уведомления не мгновенные. Список обновляется при открытии, возвращении в окно и каждые 30 секунд. Email и push-уведомлений нет.
• Нет подтверждения email, восстановления пароля и MFA.
• Опубликованную задачу пока нельзя редактировать. После выбора команды нет отдельного процесса управления выполнением проекта и оплатой.
• Демо-задачи могут иметь нулевую или базовую оценку. Они добавлены для демонстрации, а не прошли полноценную AI-проверку.
• XP-блок скрыт. Код расчёта прогресса остался, но активной геймификации в кабинете нет.
• NVIDIA не интегрирована. Для публичного запуска также нужны HTTPS и настройка эксплуатации.

10. Где посмотреть развёрнутую версию

Публичной версии пока нет. Сейчас проект проверяется локально по адресу http://localhost:5173 после запуска Docker Compose. Этот адрес не откроет приложение на чужом компьютере без установки проекта.

11. Что учли из инструкций хакатона

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

Также прочитали остальные пять документов:

• Активация OpenAI и NVIDIA: ключи и персональные промокоды не должны попадать в репозиторий. OpenAI используется, NVIDIA пока не подключена.
• Кибербезопасность: для демонстрации используем вымышленные данные. Перед отправкой кода проверяем, что в нём нет секретов. На площадке нельзя сканировать чужие системы или создавать свою точку доступа.
• Подготовка оборудования: заранее нужны рабочий ноутбук, зарядка, установленное ПО и проверенное сетевое подключение; при необходимости — Ethernet-переходник. IP и DNS должны получаться автоматически.
• Курс Arizona State University: прохождение курса, финальное задание и получение бейджа — отдельные действия участника. Приложение этого не проверяет.
• Правила зачёта участия: личный вклад, отметки по бейджу и присутствие на площадке подтверждаются отдельно. По коду нельзя подтвердить выполнение этих условий.

Перед сдачей команде остаётся сверить решение с требованиями выбранного кейса, отправить последнюю версию в выданный GitHub-репозиторий и нажать «Сдать решение» на платформе HackAlem. Один push в GitHub не заменяет сдачу на платформе. В этих шести PDF нет подробной шкалы оценивания конкретного кейса.

Дополнительно: описание backend и план проекта. План содержит и идеи на будущее; текущие возможности перечислены в этом README.