AI Sana — практические задачи для бизнеса и студенческих команд

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

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

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

• Два демо-сценария: вход от имени представителя бизнеса или одной из подготовленных студенческих команд, с возможностью переключаться между ними.
• Конструктор задачи: описание своими словами, 3–5 уточняющих вопросов, редактируемая карточка, сохранение черновика, подтверждение и публикация. Если ключ OpenAI не задан или запрос не удался, вопросы формируются локально.
• Подсказки по карточке: помощник предлагает фрагменты из исходного описания с указанием текста-источника. Пользователь может изменить, принять или отклонить предложение; оно не записывается в карточку автоматически.
• Рейтинг готовности 0–100: сервер начисляет баллы за наличие содержательной информации о контексте, потребности, данных, результате, критериях успеха, ограничениях, пользователях и взаимодействии с бизнесом. Показаны разбивка и незаполненные пункты. Рейтинг обновляется после подтверждения карточки и не запрещает публикацию задачи с низким баллом.
• Каталог и отклики команд: опубликованные задачи доступны всем демо-командам; есть поиск, фильтры, сохранённые задачи и объяснимые рекомендации по профилю команды и её действиям. Команда отправляет идею, план, срок и HTTP(S)-ссылку на прототип. Черновик отклика сохраняется в этом браузере.
• Решение бизнеса и прогресс: бизнес вручную выбирает, отклоняет или оставляет отклики без решения; можно выбрать несколько команд. Подтверждение одного завершённого этапа выбранной команды начисляет ей 10 баллов прогресса один раз. Команда видит свои отклики, их статусы и ранг, вычисленный в интерфейсе из накопленных баллов.

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

1. Представитель бизнеса вводит описание задачи. API запрашивает уточняющие вопросы у OpenAI при наличии ключа или использует локальный алгоритм. Сведения, явно содержащиеся в описании, могут появиться как предложения с проверяемым фрагментом-источником.
2. Человек отвечает на вопросы и редактирует карточку. Черновик можно сохранить заранее; после подтверждения сервер фиксирует текущую версию и рассчитывает рейтинг по фиксированным правилам. Модель не выставляет баллы и не публикует задачу.
3. После публикации карточка появляется в открытом каталоге. Команда изучает условия и отправляет отклик. Рекомендации помогают упорядочить задачи, но не закрывают доступ к остальному каталогу.
4. Бизнес просматривает отклики и принимает решение сам. Если выбранная команда завершила этап, бизнес подтверждает результат, а баллы прогресса сохраняются в PostgreSQL. Интерфейс пересчитывает видимый ранг команды по этим баллам.

Технологии

Часть	Используется
Интерфейс	TypeScript, React 19, Vite 8, CSS
API	Python 3.11+, FastAPI, Pydantic, SQLAlchemy
База данных	PostgreSQL 17 через Docker Compose, драйвер psycopg
AI	OpenAI Chat Completions API; модель по умолчанию — gpt-4o-mini. При отсутствии ключа работает локальный сценарий уточнений
Проверки	Pytest, Ruff; сборка TypeScript/Vite и тесты логики интерфейса на Node.js

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

Архитектура

Браузер: React + Vite
  ├─ интерфейс бизнеса и команды
  ├─ localStorage: выбранный демо-участник и черновики откликов
  └─ запросы /api
        ↓
FastAPI
  ├─ карточки, отклики, решения и подтверждённый прогресс
  ├─ расчёт рейтинга и рекомендаций
  ├─ помощник задач → OpenAI API (необязательно; есть локальный fallback)
  └─ SQLAlchemy → PostgreSQL

Код интерфейса находится в web/, API и логика — в api/app/, запуск базы — в compose.yaml. Контракт API доступен в api/openapi.json; дополнительные решения и результаты проверок — в docs/.

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

Команды ниже рассчитаны на macOS/Linux. Нужны Docker с Compose, Python 3.11+ и Node.js 20.19+ или 22.12+ с npm.

1. Получите репозиторий и создайте локальную конфигурацию:

   git clone https://github.com/BAITC-Hacks/hack-4349459c-kemeldenai.git
   cd hack-4349459c-kemeldenai
   cp .env.example .env
   

   В .env замените учебный POSTGRES_PASSWORD и укажите такой же пароль в DATABASE_URL. Не добавляйте .env и API-ключи в Git. OPENAI_API_KEY можно оставить пустым: демонстрация продолжит работать с локальными вопросами. При необходимости измените OPENAI_MODEL.

2. Запустите PostgreSQL:

   docker compose up -d db
   docker compose ps
   

   Дождитесь состояния healthy у контейнера базы. Если порт 5432 занят, поменяйте POSTGRES_PORT в .env и порт в DATABASE_URL на одно и то же свободное значение.

3. Установите зависимости API, создайте демонстрационные записи и запустите сервер из корня репозитория:

   python3 -m venv api/.venv
   api/.venv/bin/python -m pip install -r api/requirements.txt
   api/.venv/bin/python -m api.app.seed
   api/.venv/bin/python -m uvicorn api.app.main:app --host 127.0.0.1 --port 8000
   

   API будет доступен на http://127.0.0.1:8000, интерактивная схема — на http://127.0.0.1:8000/docs. Перезапустите API после изменения .env.

4. В другом терминале запустите интерфейс:

   cd web
   npm ci
   npm run dev
   

   Откройте адрес, напечатанный Vite (обычно http://127.0.0.1:5173/). В режиме разработки запросы /api направляются на локальный сервер FastAPI.

Для проверки кода из корня репозитория можно выполнить api/.venv/bin/python -m pytest api/tests, api/.venv/bin/ruff check api, а из web/ — npm run build. Тесты логики интерфейса запускаются командой npm test на версии Node.js с поддержкой встроенной обработки TypeScript; в проекте они проверялись на Node.js 25.6.

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

1. На экране «Демо-вход» выберите «Войти как бизнес». Введите, например: «Менеджеры вручную обрабатывают 100 заявок в день; нужен общий список заказов».
2. Нажмите «Получить вопросы». Убедитесь, что показаны 3–5 вопросов. Без OPENAI_API_KEY интерфейс прямо обозначит локальный вариант. Ответьте на вопросы и при желании обновите их: введённые ответы должны сохраниться.
3. Перенесите ответы в карточку. Проверьте предложенные фрагменты исходного описания: до нажатия «Добавить в карточку» соответствующее поле остаётся пустым. Укажите название задачи, подтвердите карточку и посмотрите рейтинг и разбивку.
4. Заполните ещё несколько недостающих полей, например данные и измеримый критерий успеха, затем подтвердите изменения. Рейтинг подтверждённой версии должен измениться. Опубликуйте задачу.
5. Нажмите «Сменить участника», войдите как демо-команда Data Nomads и найдите опубликованную задачу в каталоге. Отправьте отклик с идеей, планом, сроком и HTTP(S)-ссылкой на прототип. Для проверки только формы можно использовать тестовый адрес https://example.com/prototype; это не действующий прототип.
6. Вернитесь в бизнес-сценарий, откройте «Отклики команд» и вручную выберите полученный отклик. Подтвердите описанный завершённый этап. После переключения обратно на команду в «Мои отклики» будут видны решение и 10 начисленных баллов прогресса. Повторное подтверждение того же этапа баллы не удваивает.

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

• При первом запуске создаются синтетические данные: пять опубликованных задач с разной готовностью, пять черновиков, пять команд и пять откликов. Повторный запуск заполнения не должен дублировать записи или перезаписывать изменения пользователя.
• Карточки, команды, отклики, решения, подтверждённый прогресс, сохранённые задачи и сигналы рекомендаций хранятся в локальном PostgreSQL. Выбранный демо-участник и черновики откликов сохраняются в браузере; черновики не синхронизируются между устройствами.
• Единственный внешний AI-сервис во время работы — OpenAI API, если серверу передан ключ. Ключ остаётся на сервере. При недоступности API используются локальные вопросы и ограниченный набор предложений из текста пользователя. Реальные бизнес-датасеты для запуска не требуются.

Ограничения

• Демо-вход не является авторизацией. Нет регистрации, паролей, разграничения прав на сервере и личных аккаунтов команд; выбранные демо-профили общие.
• Рейтинг задачи показывает полноту заполнения карточки, а не истинность фактов, качество идеи или вероятность успеха. Ранг команды отражает записанные баллы за подтверждённые этапы, а не независимую оценку её квалификации. Рекомендации основаны на совпадении слов, профиле команды и её действиях; они не понимают все синонимы и не являются обученной моделью.
• Предложения помощника ограничены проверяемыми фрагментами текста. Удаление типичных email-адресов и телефонов перед вызовом OpenAI не является полной анонимизацией. Человек должен проверить AI-ответы перед подтверждением.
• Черновики откликов хранятся только в текущем браузере. Нет синхронизации между устройствами, уведомлений о новых решениях и полноценного трекера выполнения проекта.
• Docker Compose запускает только базу данных; API и интерфейс стартуют отдельно. Текущая инициализация создаёт недостающие таблицы, но не выполняет миграции существующих столбцов для промышленного обновления схемы.

Развёрнутая версия

Открыть развёрнутую версию AI Sana.