Stuness

MVP для кейса AI Sana Challenge Hub  

Рейтинг качества бизнес-задач и открытый выбор команд

Репозиторий

GitHub: https://github.com/BAITC-Hacks/hack-8486c8c7-f1

---

1. О проекте

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

Бизнес вводит краткое описание задачи, после чего Sana Bot анализирует его, определяет недостающую информацию и задаёт уточняющие вопросы.

После уточнения формируется редактируемая карточка задачи, которую бизнес проверяет и подтверждает. Система рассчитывает Task Readiness — рейтинг готовности задачи от 0 до 100.

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

Основная геймификация направлена на качество бизнес-задачи: чем полнее она описана, тем выше её Task Readiness и позиция в каталоге.

---

2. Основной сценарий

Stuness реализует полный сквозной сценарий:

1. Бизнес вводит краткое описание потребности, проблемы или задачи.

2. Sana Bot анализирует описание и определяет недостающие сведения.

3. Система задаёт минимум 3 уточняющих вопроса.

4. Бизнес отвечает на вопросы.

5. Из полученной информации формируется редактируемая карточка.

6. Представитель бизнеса проверяет и вручную подтверждает сведения.

7. Система рассчитывает Task Readiness от 0 до 100.

8. Пользователь видит расшифровку баллов и список недостающих сведений.

9. Бизнес публикует задачу.

10. Задача появляется в общем каталоге.

11. Студенческая команда самостоятельно выбирает интересную задачу.

12. Команда отправляет предложение.

13. Бизнес сравнивает полученные предложения.

14. Представитель бизнеса вручную выбирает или отклоняет команду.

15. После подтверждения фактического этапа выбранная команда получает XP.

ИИ не назначает команды автоматически и не принимает решение вместо бизнеса.

---

3. Реализованный функционал

Конструктор задачи

Реализованы:

• свободный ввод первоначального описания;

• анализ полноты описания;

• минимум 3 уточняющих вопроса;

• редактируемая карточка;

• ручное подтверждение информации перед публикацией.

Карточка задачи

Карточка содержит:

• название;

• контекст;

• потребность;

• пользователей;

• данные и материалы;

• ограничения;

• ожидаемый результат;

• критерии успеха;

• контакт;

• формат консультаций;

• порядок обратной связи.

Task Readiness

Реализованы:

• рейтинг от 0 до 100;

• расшифровка начисленных баллов;

• отображение недостающих сведений;

• пересчёт после редактирования и подтверждения;

• уровни готовности Challenge Evolution.

Каталог

Реализованы:

• общий каталог опубликованных задач;

• сортировка по Task Readiness;

• поиск;

• фильтрация по направлению;

• фильтрация по уровню готовности;

• отображение количества откликов;

• отображение текущего уровня задачи.

Низкий Task Readiness не скрывает задачу и не запрещает студентам отправлять предложения.

Отклики команд

Студенческая команда может указать:

• идею решения;

• план работы;

• предполагаемый срок;

• ссылку на прототип при наличии.

Количество откликов на одну задачу не ограничивается логикой выбора команды.

Выбор бизнеса

Бизнес видит полученные предложения и вручную может:

• выбрать команду — Select;

• отклонить предложение — Reject.

Автоматическое назначение команды не используется.

Прогресс команды

После выбора команды бизнес может подтвердить фактически выполненный этап.

За подтверждённые этапы команда получает XP:

• Исследование — +50 XP

• Прототип — +100 XP

• Передача результата — +150 XP

---

4. Формула Task Readiness

Task Readiness показывает готовность конкретной бизнес-задачи к работе со студенческой командой.

Максимальный рейтинг — 100 баллов.

| Показатель | Вес | Условие |

|---|---:|---|

| Контекст и потребность | 20 | Понятно текущее состояние и что необходимо изменить |

| Данные и материалы | 20 | Указаны доступные данные, примеры или источники |

| Ожидаемый результат | 15 | Описан конкретный результат работы команды |

| Критерии успеха | 15 | Есть измеримые признаки принятия результата |

| Ограничения | 10 | Указаны сроки, технологии, доступы или другие ограничения |

| Пользователи | 10 | Понятно, для кого создаётся решение |

| Связь с бизнесом | 10 | Есть контакт, формат консультаций и порядок обратной связи |

| Итого | 100 | |

Баллы начисляются только за заполненные и подтверждённые бизнесом сведения.

Для критерия успеха требуется измеримый показатель. Пустые или неопределённые сведения не увеличивают рейтинг.

Расчёт Task Readiness является детерминированным и выполняется отдельно от LLM.

---

5. Challenge Evolution

Для визуализации прогресса используются четыре уровня:

• 0–39 — Idea

• 40–69 — Builder

• 70–89 — Launch Ready

• 90–100 — Gold Challenge

Уровень меняется автоматически при изменении Task Readiness.

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

Задачи с более высоким рейтингом получают более высокую позицию при сортировке каталога по готовности.

---

6. Использование AI

В проекте реализован Sana Bot.

Sana Bot получает первоначальное описание задачи и уже заполненные поля, анализирует недостающую информацию и формирует минимум 3 уточняющих вопроса.

Ограничения Sana Bot

Sana Bot:

• не добавляет факты, которых не сообщил пользователь;

• не отвечает за пользователя;

• не рассчитывает Task Readiness;

• не выбирает студенческие команды;

• не назначает исполнителей;

• возвращает структурированный результат.

Все сведения перед публикацией редактируются и подтверждаются человеком.

OpenAI

Для AI используются:

• OpenAI Responses API

• Structured Outputs

• модель по умолчанию — gpt-4o-mini

Если OpenAI API недоступен или API-ключ не указан, приложение использует локальный fallback Sana Bot.

Таким образом, основной демонстрационный сценарий продолжает работать даже без внешнего API.

---

7. Дополнительная геймификация

Основной механикой геймификации является Task Readiness.

Дополнительно в MVP реализованы:

Sana Coins

Внутренняя демонстрационная валюта.

Бизнес может получать Sana Coins при достижении новых уровней Challenge Evolution.

XP

XP используется для отображения прогресса бизнеса и студенческих команд.

Achievements

Для задач отображаются достижения, связанные с развитием challenge и взаимодействием с командами.

Shop

Sana Coins можно использовать в Shop для косметических улучшений бизнес-задачи.

Доступны:

• Neon Frame — 50 Coins

• Spotlight — 100 Coins

• Aurora Skin — 150 Coins

Покупки являются дополнительной косметической механикой и не изменяют Task Readiness.

Spotlight временно выделяет задачу в каталоге.

---

8. Правила каталога

После подтверждения бизнес может опубликовать задачу.

Опубликованные задачи:

• доступны студенческим командам;

• могут быть найдены через поиск;

• фильтруются по направлению;

• фильтруются по уровню готовности;

• сортируются по Task Readiness;

• остаются доступными для отклика независимо от рейтинга.

Task Readiness используется как показатель готовности задачи, а не как ограничение доступа.

Студенты самостоятельно решают, на какие задачи отправлять предложения.

---

9. Роли

В MVP используются два демонстрационных режима.

Business

Business может:

• создавать задачи;

• работать с Sana Bot;

• редактировать карточку;

• подтверждать сведения;

• публиковать задачу;

• видеть Task Readiness;

• просматривать отклики;

• выбирать или отклонять команды;

• подтверждать этапы работы;

• использовать Shop.

Student

Student может:

• просматривать общий каталог;

• использовать поиск и фильтры;

• открывать карточки задач;

• выбирать демонстрационную команду;

• отправлять предложения;

• просматривать свои отклики;

• получать XP после подтверждения прогресса бизнесом.

Режимы Business и Student не являются полноценной системой авторизации и используются для демонстрации MVP.

---

10. Технологии

Frontend

• React

• Vite

• Tailwind CSS

• Lucide React

Backend

• Python

• FastAPI

• Pydantic

• HTTPX

База данных

• SQLite

AI

• OpenAI Responses API

• Structured Outputs

• локальный fallback Sana Bot

---

11. Архитектура

Проект разделён на frontend и backend.

Frontend

Frontend отвечает за:

• пользовательский интерфейс;

• навигацию;

• каталог;

• поиск и фильтры;

• создание и редактирование задач;

• отображение Task Readiness;

• Challenge Evolution;

• отклики;

• кабинеты Business и Student;

• команды;

• Shop;

• отображение XP, Sana Coins и Achievements.

Backend

FastAPI отвечает за:

• REST API;

• бизнес-логику;

• работу с Sana Bot;

• интеграцию с OpenAI;

• расчёт Task Readiness;

• публикацию задач;

• обработку откликов;

• ручное решение бизнеса;

• подтверждение прогресса;

• начисление XP и Sana Coins;

• Shop;

• валидацию;

• работу с SQLite.

Структура проекта

backend/

  app/

    main.py       REST API и основные сценарии

    models.py     модели и валидация

    scoring.py    расчёт Task Readiness

    game.py       XP, Sana Coins и Challenge Evolution

    ai.py         OpenAI и локальный Sana Bot

    db.py         работа с SQLite

    seed.py       синтетические демо-данные

  tests/          тесты

frontend/

  src/

    main.jsx      основное приложение и навигация

    Catalog.jsx   каталог, поиск и фильтры

    forms.jsx     формы

    Detail.jsx    карточка задачи и отклики

    Workspace.jsx кабинеты, команды и Shop

    ui.jsx        общие UI-компоненты

    styles.css    стили

docs/

  SPEC.md         техническое задание

  DEMO.md         демонстрационный сценарий

  AI.md           описание AI

start.ps1         запуск проекта на Windows

---

12. Демо-данные

Для MVP используются синтетические данные.

При первом запуске создаются:

• 5 бизнес-задач разной степени полноты;

• 5 карточек задач;

• 5 студенческих команд;

• 5 предложений;

• стартовый демонстрационный баланс Sana Coins и XP.

Профили команд содержат название, интересы, навыки и технологии.

---

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

Требования

• Python 3.11+

• Node.js 20.19+ или 22.12+

• npm

Windows

Откройте PowerShell в корневой папке проекта:

powershell -ExecutionPolicy Bypass -File .\start.ps1

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

1. создаёт виртуальное окружение Python;

2. устанавливает backend-зависимости;

3. устанавливает frontend-зависимости;

4. собирает frontend;

5. запускает FastAPI.

После успешного запуска откройте:

http://127.0.0.1:8000

Для остановки:

Ctrl+C

macOS / Linux

python3 -m venv .venv

.venv/bin/python -m pip install -r backend/requirements.txt

npm ci --prefix frontend

npm run build --prefix frontend

.venv/bin/python -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000

После запуска:

http://127.0.0.1:8000

---

14. Настройка OpenAI

Для подключения OpenAI создайте .env в корне проекта:

OPENAI_API_KEY=ваш_ключ

OPENAI_MODEL=gpt-4o-mini

API-ключ используется только backend и не должен добавляться в GitHub.

Если OPENAI_API_KEY отсутствует, автоматически используется локальный Sana Bot.

---

---

15. Деплой

Проект можно задеплоить как один веб-сервис: сначала собирается frontend, после чего FastAPI запускает backend и отдаёт приложение.

Вариант: Render

Загрузите проект в GitHub.

В Render создайте New → Web Service и подключите репозиторий проекта.

Укажите следующие настройки:

Build Command

pip install -r backend/requirements.txt && npm ci --prefix frontend && npm run build --prefix frontend

Start Command

uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port $PORT

В разделе Environment Variables при необходимости добавьте:

OPENAI_API_KEY=ваш_ключ OPENAI_MODEL=gpt-4o-mini

OPENAI_API_KEY нельзя добавлять напрямую в репозиторий или публиковать в README.

Если ключ OpenAI не указан, приложение использует локальный fallback Sana Bot.

После завершения сборки Render выдаст публичный URL приложения.

Важно для SQLite

В MVP используется SQLite. На облачном хостинге локальный файл базы данных может сбрасываться после перезапуска или нового деплоя сервиса, если не подключено постоянное хранилище.

Для демонстрации хакатонного MVP этого достаточно благодаря синтетическим данным. Для постоянного хранения данных рекомендуется подключить persistent disk или заменить SQLite на PostgreSQL.

16. Тестовый сценарий

Основной сценарий проверки MVP:

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

2. Выбрать режим Business.

3. Создать новую задачу со слабым и неполным описанием.

4. Проверить, что Sana Bot задаёт минимум 3 уточняющих вопроса.

5. Ответить на вопросы.

6. Проверить сформированную карточку.

7. При необходимости отредактировать сведения.

8. Подтвердить карточку.

9. Проверить Task Readiness и расшифровку баллов.

10. Проверить список недостающих сведений.

11. Дополнить карточку и показать рост Task Readiness.

12. Опубликовать задачу.

13. Убедиться, что она появилась в общем каталоге.

14. Переключиться в режим Student.

15. Найти опубликованную задачу.

16. Выбрать демонстрационную команду.

17. Отправить предложение.

18. Вернуться в режим Business.

19. Открыть полученный отклик.

20. Нажать Select или Reject.

21. Для выбранной команды при необходимости подтвердить этап и проверить начисление XP.

Дополнительно можно показать Shop и косметические улучшения, но они не являются частью расчёта Task Readiness.

---

17. Демонстрация

Рекомендуемый сценарий защиты рассчитан максимум на 5 минут:

1. Черновик  

Создать задачу со слабым описанием.

2. AI-уточнение  

Показать минимум 3 вопроса Sana Bot.

3. Карточка и рейтинг  

Дополнить информацию, подтвердить карточку и показать рост Task Readiness.

4. Публикация  

Опубликовать challenge и показать его в каталоге.

5. Student  

Переключиться в режим Student и отправить предложение.

6. Business  

Вернуться в Business, открыть предложение и вручную выбрать или отклонить команду.

Все эти действия выполняются непосредственно в работающем MVP.

---

18. Ограничения MVP

В рамках хакатонной версии не реализованы:

• полноценная регистрация;

• восстановление пароля;

• сложная ролевая модель;

• чат в реальном времени;

• уведомления;

• календарь;

• файловое хранилище;

• обучение собственной ML-модели;

• векторная база данных;

• автоматическое назначение команд;

• полноценный project tracker.

Это соответствует формату MVP: основной акцент сделан на полном сквозном сценарии от первоначального описания бизнес-задачи до отклика студенческой команды и ручного решения бизнеса.

---

19. Соответствие требованиям кейса

| Требование | Реализация |

|---|---|

| Свободный ввод бизнес-задачи | Реализовано |

| Проверка полноты | Реализовано |

| Минимум 3 уточняющих вопроса | Реализовано через Sana Bot |

| Редактируемая карточка | Реализовано |

| Ручное подтверждение | Реализовано |

| Task Readiness 0–100 | Реализовано |

| Расшифровка рейтинга | Реализовано |

| Недостающие сведения | Отображаются |

| Пересчёт рейтинга | Реализован |

| Общий каталог | Реализован |

| Сортировка по рейтингу | Реализована |

| Фильтры | Реализованы |

| Отклики команд | Реализованы |

| Ручной Select / Reject | Реализован |

| AI-функция | Sana Bot |

| Fallback без внешнего API | Реализован |

| Синтетические данные | Реализованы |

| Полный сквозной сценарий | Реализован |

---

20. Итог

Stuness реализует полный сценарий:

черновик → AI-уточнение → редактируемая карточка → подтверждение → Task Readiness → публикация → каталог → предложение команды → ручное решение бизнеса.

Основная геймификация построена вокруг качества самой бизнес-задачи: чем полнее и полезнее её описание, тем выше Task Readiness и позиция задачи в каталоге.