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

MVP для кейса HackAlem AI. Представитель бизнеса описывает задачу своими словами. ИИ задаёт уточняющие вопросы и собирает карточку, система оценивает её готовность от 0 до 100 и публикует в открытом каталоге. Студенческие команды сами выбирают задачи и откликаются, а бизнес вручную выбирает, с кем работать.

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

Сквозной сценарий: черновик → уточняющие вопросы → карточка → рейтинг → каталог → отклик команды → выбор бизнеса → очки команде за подтверждённый этап.

Содержание

• Быстрый старт
• Демо за 5 минут
• Деплой на Vercel
• Архитектура
• Выбор команды и число этапов
• Формула рейтинга
• Правила каталога
• ИИ
• Данные
• Тестирование
• GitHub Actions
• Частые проблемы

Быстрый старт

Нужны Python 3.11+, Node.js 20+ и Git. CI собирает проект на Node 20 и Python 3.13; функция Vercel настроена на Python 3.12. На Windows команды *.ps1 запускаются из PowerShell, а сами скрипты используют Git Bash из Git for Windows. Docker Desktop нужен только для PostgreSQL или полного запуска в контейнерах.

cp .env.example .env     # ключ OpenAI и база — по желанию, см. ниже
./check.sh               # проверить всё и запустить (Windows: .\check.ps1)

Что сделать	PowerShell (Windows)	bash (macOS / Linux)
Проверить всё и запустить	.\check.ps1	./check.sh
Только запустить	.\run.ps1	./run.sh
Запустить со сбросом базы к тестовым данным (перед демо)	.\run.ps1 --reset	./run.sh --reset
Только проверить, без запуска	.\check.ps1 --no-serve	./check.sh --no-serve
Быстрые тесты и сборка, без серверов и smoke-сценария	.\check.ps1 --quick	./check.sh --quick

Скрипты сами создают Python virtualenv, устанавливают backend-пакеты и выполняют npm install, ждут готовности серверов, открывают браузер и печатают ссылки:

• сайт: http://127.0.0.1:5173 (#/ — мастер создания задачи, #/business — кабинет бизнеса, #/team — кабинет команды);
• API и Swagger: http://127.0.0.1:8000/docs.

Остановить — Ctrl+C в терминале, где запущен скрипт. Чтобы браузер не открывался, задайте NO_OPEN=1 ($env:NO_OPEN=1 в PowerShell). run использует порты 8000/5173; check для изолированной проверки — 8001/5174.

Ручная установка (если скрипт запуска не подходит)

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

npm install
cd backend
python -m venv .venv
# macOS/Linux/Git Bash:
source .venv/bin/activate
# PowerShell вместо предыдущей команды: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Во втором терминале из корня репозитория:

npm run dev

Если фронт и API работают на других адресах, задайте Vite переменную API_URL (например, http://127.0.0.1:8000). По умолчанию /api проксируется на http://127.0.0.1:8000.

Настройки (.env)

Переменная	Зачем	По умолчанию
OPENAI_API_KEY	Ключ OpenAI для анализа черновика и сборки карточки	пусто — работает заглушка на правилах
OPENAI_MODEL	Модель	gpt-4o-mini
DATABASE_URL	База данных	SQLite в backend/data/app.db
ADMIN_TOKEN	Защита POST /api/admin/reset (заголовок X-Admin-Token)	пусто — сброс открыт (только для локальной разработки)
CORS_ORIGINS	Разрешённые адреса фронтенда через запятую	http://localhost:5173,http://127.0.0.1:5173

Если строка DATABASE_URL включена в .env.example, run попробует запустить локальный PostgreSQL через Docker Desktop; чтобы работать без Docker, закомментируйте DATABASE_URL в .env — приложение использует SQLite. URL PostgreSQL с postgres://, postgresql:// и postgresql+asyncpg:// принимаются, затем приводятся к синхронному драйверу psycopg.

Полностью в Docker (API, фронт и PostgreSQL): docker compose up --build. Compose публикует фронт на 5173 и API на 8000, Postgres доступен только на localhost:5432 и хранит данные в volume pg-data. Контейнер фронта запускает Vite dev-сервер, это локальный сценарий разработки.

Перед демо --reset пересоздаёт данные из backend/app/seed_data.json; текущие локальные записи при этом теряются. Используйте эту команду только чтобы вернуть демонстрационную базу.

Демо за 5 минут

Перед показом запустите .\run.ps1 --reset (или ./run.sh --reset). Весь сценарий идёт в интерфейсе.

1. Слабый черновик. Лендинг → «Create challenge» → «Подставить пример». Черновик: «Абитуриенты задают одни и те же вопросы…», рейтинг 10.
2. Уточнение. «Проанализировать» → вопросы с ценой в баллах («до +20 баллов») → ответы → «Собрать карточку». Рейтинг вырастает до 90–100, тест-драйв показывает замечания. Если очистить критерии успеха, баллы тут же упадут.
3. Публикация. Компания, тема «Образование», навыки «Чат-бот» и «Telegram» → галочка подтверждения → «Подтвердить и опубликовать» → «Открыть в кабинете».
4. Команда откликается сама. «Команда» → BotFactory → «Рекомендации»: задача первая («Совпало: Образование, Чат-бот, Telegram») → отклик с идеей, планом, сроком и ссылкой.
5. Бизнес решает вручную. Откройте #/business → выберите задачу → «Отклики команд». Укажите плановое число этапов от 1 до 10 в поле рядом с командой и нажмите «Выбрать»; для других откликов можно нажать «Отклонить». Подтверждайте этапы по мере выполнения. За каждый этап начисляется +20 очков; после выбранного количества кнопка подтверждения отключается. Прогресс показывается как подтверждено/запланировано.

Деплой на Vercel

Фронт Vercel собирает как Vite-проект и раздаёт статикой. Бэкенд FastAPI работает как Python-функция api/index.py, все запросы /api/* перенаправляются в неё (vercel.json). Сайт и API живут на одном домене, поэтому CORS не нужен.

Файловая система Vercel временная, поэтому нужен внешний PostgreSQL. Проще всего подключить Neon из Marketplace самого Vercel. Без базы приложение запустится на SQLite в /tmp, но данные будут пропадать.

Шаги

1. Создайте проект и задеплойте из папки репозитория (нужен аккаунт Vercel):

   npx vercel          # первый раз: войти, создать проект, превью-деплой
   

   Настройки сборки подхватятся из vercel.json. Репозиторий приватный и принадлежит организации GitHub, поэтому CLI надёжнее импорта из GitHub: на бесплатном тарифе Vercel импорт приватных репозиториев организаций может быть недоступен. Если у вас Pro или репозиторий личный, можно импортировать через Add New → Project.

2. Подключите базу. В проекте на vercel.com: Storage → Create Database → Neon (Postgres) → Connect. Vercel сам добавит DATABASE_URL и POSTGRES_URL в переменные окружения.

3. Добавьте переменные. Settings → Environment Variables:

   • OPENAI_API_KEY — ключ OpenAI (без него работает заглушка);
   • ADMIN_TOKEN — любая длинная случайная строка. Без неё любой посетитель сможет стереть базу через /api/admin/reset.

4. Выкатите в прод:

   npx vercel --prod
   

5. Проверьте. https://<проект>.vercel.app/api/health должен вернуть {"status":"ok"}. Таблицы и тестовые данные создаются сами при первом запросе.

Сбросить базу к тестовым данным перед демо:

curl -X POST -H "X-Admin-Token: <ADMIN_TOKEN>" https://<проект>.vercel.app/api/admin/reset

Что учесть: первый запрос после простоя идёт 2–5 секунд (холодный старт функции). Ответ OpenAI занимает 3–6 секунд, лимит функции — 60 секунд. Файл .env на Vercel не попадает (.gitignore, .vercelignore): переменные задаются только в настройках проекта.

Файл	Роль в деплое
vercel.json	Сборка Vite, перенаправление /api/* в функцию, лимит 60 с
api/index.py	Точка входа функции: подключает backend/app, создаёт таблицы и тестовые данные на пустой базе
requirements.txt	Зависимости функции (без инструментов разработки)
.vercelignore	Не загружать node_modules, .env, venv, тесты

Архитектура

Браузер ──► React + Vite (src/)
               │  /api/*  (локально — прокси Vite, на Vercel — rewrite)
               ▼
            FastAPI (backend/app)  ──►  PostgreSQL / SQLite
               ├─ ai.py            черновик → вопросы, ответы → карточка (OpenAI + заглушка)
               ├─ scoring.py       рейтинг 0–100, уровни, подсказки «+N баллов»
               ├─ drive_checks.py  тест-драйв: проверки реализуемости карточки
               ├─ crud.py          пересчёт рейтинга, правила каталога и рекомендаций
               └─ routers/         ai, tasks, proposals, teams

Страницы (hash-маршруты):

Маршрут	Что там
#/	Лендинг
#/new	Мастер создания задачи: черновик → вопросы → тест-драйв карточки → тема, навыки, публикация
#/business, #/business/<id>	Кабинет бизнеса: задачи и отклики, выбор команды с планом 1–10 этапов, подтверждение этапов, закрытие задачи, правка карточки с живым пересчётом рейтинга
#/team	Команды: каталог с фильтрами, рекомендации, форма отклика, мои отклики, лидерборд

Фон всех страниц — анимированные синие волны (src/Waves.tsx). Если в системе включено уменьшение анимации (prefers-reduced-motion), они неподвижны.

Структура репозитория:

api/index.py              точка входа на Vercel
backend/app/              FastAPI: схемы, модели, ИИ, рейтинг, роутеры, тестовые данные
backend/app/constants.py  общие лимиты этапов и очки за подтверждение
backend/tests/            pytest и smoke.py — сквозная проверка API через Vite proxy
src/api.ts                типизированный клиент ко всему API
src/App.tsx               лендинг и мастер создания задачи
src/business/             кабинет бизнеса
src/team/                 рабочее место команды и общие UI-элементы
scripts/, *.sh, *.ps1     запуск и проверка

API

Полная интерактивная документация — /docs (Swagger).

Метод	Путь	Шаг сценария
POST	/api/analyze	1–2. Черновик → недостающие поля и ≥3 вопросов с ценой в баллах
POST	/api/build-card	3. Ответы → карточка и источник каждого поля
POST	/api/score	4. Живой пересчёт рейтинга без сохранения
POST	/api/test-drive	4. Проверки реализуемости карточки
POST	/api/tasks	5. Публикация подтверждённой карточки
PATCH	/api/tasks/{id}	Правка → пересчёт рейтинга и позиции
GET	/api/catalog?topic&level&status&q&owner	5. Общий каталог
GET	/api/recommendations?team_id	6. Рекомендации команде
POST	/api/tasks/{id}/proposals	6. Отклик команды
GET	/api/tasks/{id}/proposals	7. Отклики на задачу
POST	/api/proposals/{id}/decision	7. Ручное решение: выбор с milestone_count от 1 до 10 или отказ
POST	/api/tasks/{id}/close	7. Закрыть задачу, в том числе без выбора
POST	/api/proposals/{id}/milestone	8. Этап подтверждён → команде +20 очков
GET	/api/leaderboard	8. Рейтинг команд
GET	/api/teams, /api/meta, /api/demo/drafts	Справочники и демо-черновики
POST	/api/admin/reset	Сброс к тестовым данным (заголовок X-Admin-Token, если задан ADMIN_TOKEN)

Выбор команды и число этапов

При принятии отклика бизнес обязан передать число этапов. Это число относится к конкретному отклику: у двух выбранных команд могут быть разные планы. Значение должно быть целым от 1 до 10 включительно; запрос без него или вне диапазона вернёт 422.

# Принять отклик 42 и запланировать 3 этапа
  curl -X POST http://127.0.0.1:8000/api/proposals/42/decision -H "Content-Type: application/json" -d '{"decision":"accept","milestone_count":3}'

# Отклонить отклик
  curl -X POST http://127.0.0.1:8000/api/proposals/42/decision -H "Content-Type: application/json" -d '{"decision":"reject"}'

# Подтвердить очередной этап
  curl -X POST http://127.0.0.1:8000/api/proposals/42/milestone -H "Content-Type: application/json" -d '{"note":"Рабочий прототип передан бизнесу"}'

Подтверждение сверх установленного лимита вернёт 409 и не начислит очки. Каждый подтверждённый этап приносит команде 20 очков; повторное подтверждение того же названия этапа также отклоняется. Ответ proposal содержит milestone_limit и массив milestones. Для ранее принятых записей без сохранённого плана миграция БД назначает безопасный максимум — 10 этапов.

Формула рейтинга

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

Показатель	Вес	Поля карточки
Контекст и потребность	20	context (10) + need (10)
Данные и материалы	20	data
Ожидаемый результат	15	expected_result
Критерии успеха	15	success_criteria
Ограничения	10	constraints
Пользователи	10	users
Связь с бизнесом	10	contact (5) + interaction_format (5)

Название (title) обязательно для публикации, но баллов не даёт.

Учитывается качество поля, а не только заполненность:

• пустое поле — 0%;
• короче 15 символов — 50% («слишком кратко»);
• критерии успеха без числа или процента — 60%;
• ограничения без срока или объёма — 70%;
• контакт без email, телефона или Telegram — 50%.

Каждый показатель возвращается с пояснением. Подсказки отсортированы по тому, сколько баллов они добавят. Эти же числа показаны у вопросов ИИ и у полей в кабинете.

Баллы	Уровень	Что значит
0–39	Черновик	Видна в каталоге с пометкой «требует уточнения»
40–69	Рабочая	Можно откликаться, система может рекомендовать
70–89	Готовая	Повышенная позиция в каталоге
90–100	Приоритетная	Полностью готова, выделяется в каталоге

После каждой правки рейтинг пересчитывается, история сохраняется в score_history и показывается в кабинете («Рост рейтинга: 59 → 89»).

Тест-драйв (drive_checks.py) дополняет рейтинг прозрачными проверками реализуемости: потребность без контекста, результат без критериев приёмки, неизмеримый критерий, технический результат без данных, контакт без формата обратной связи. Это проверка полноты и тестируемости, а не семантический анализ.

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

1. Все опубликованные задачи видны всем командам. Низкий рейтинг не скрывает задачу и не запрещает отклик.
2. Сортировка: закрытые задачи внизу → по рейтингу по убыванию → при равном рейтинге сначала свежие → затем с меньшим числом откликов.
3. Фильтры: тема, уровень готовности, статус, поиск по тексту.
4. Рекомендации получают только открытые задачи с рейтингом 40+. Подбор идёт по совпадению навыков, интересов и технологий команды с темой и тегами задачи, причина показывается («Совпало: NLP, Python»). Персональные признаки не используются, каталог рекомендациями не ограничивается.
5. Число откликов не ограничено. Отклики не принимаются только у закрытой задачи.
6. Команду выбирает только бизнес, вручную: одну, несколько или ни одной. Автоматического назначения нет.
7. Статусы задачи: open → in_progress (выбрана хотя бы одна команда) → closed.
8. При выборе каждой команды бизнес задаёт ей план от 1 до 10 этапов. Число этапов независимо для каждого отклика; подтвердить больше этапов, чем запланировано, нельзя.
9. За каждый подтверждённый этап команда получает 20 очков в общий рейтинг. Повторное подтверждение этапа с тем же названием запрещено.

ИИ

Файл backend/app/ai.py, клиент OpenAI, модель из OPENAI_MODEL, temperature=0, Structured Outputs по Pydantic-схеме.

• Промпт: извлечь 10 полей карточки только из текста пользователя. Для каждого непустого поля нужна точная цитата-источник, додумывать запрещено.
• Вход: черновик и ответы на уточняющие вопросы ({field, answer}).
• Выход: card (10 полей) и sources (цитата на каждое заполненное поле). Отсюда считаются questions с ценой в баллах и score, плюс mode: llm или mock.
• ИИ не добавляет фактов: поле, цитата которого не найдена в тексте или ответе пользователя, обнуляется. Если модель не заполнила название или контекст, они берутся из самого черновика.
• Ошибки: ответ повторно проверяется Pydantic-схемой. При невалидном ответе или сбое API делается до трёх попыток, затем включается заглушка на правилах. Интерфейс показывает режим: «ИИ-анализ» или «Режим заглушки».
• Карточку редактирует и подтверждает человек до публикации. ИИ не выбирает команду и не ограничивает каталог.

Данные

Синтетический набор в backend/app/seed_data.json загружается автоматически на пустой базе:

Набор	Объём	Поля
Черновики задач	5	текст, отрасль, степень полноты
Карточки задач	8	все 10 полей; рейтинг от 10 до 100, все четыре уровня
Профили команд	6	название, интересы, навыки, технологии
Отклики	6	команда, идея, план, срок, ссылка, статус

Тестирование

check (.\check.ps1 / ./check.sh) без аргументов за один прогон:

1. ставит зависимости;
2. запускает 12 автотестов бэкенда (backend/tests/test_api.py), всегда на заглушке ИИ, без обращений к OpenAI;
3. проверяет типы и собирает фронт;
4. поднимает изолированную копию API и Vite proxy на временной базе (порты 8001/5174) и прогоняет 17 smoke-проверок API-сценария (backend/tests/smoke.py). Если в .env задан OPENAI_API_KEY, анализ может обращаться к OpenAI; без ключа используется заглушка.

Рабочая база при проверке не затрагивается.

Что покрывают автотесты:

1. Сквозной сценарий: слабый черновик → ≥3 вопроса → карточка с источниками → рост рейтинга → публикация → отклик → ручной выбор → этап → очки команде.
2. Правка карточки повышает рейтинг и позицию в каталоге, история рейтинга растёт.
3. Неподтверждённые поля не дают баллов.
4. Каталог показывает черновики и отсортирован по рейтингу.
5. Задача с низким рейтингом принимает отклики, но не попадает в рекомендации.
6. Рекомендации объясняют совпадение.
7. Валидация: короткий черновик, неверная ссылка, неизвестное поле → 422.
8. Решение по отклику окончательное, закрытая задача не принимает отклики.
9. Заземление ИИ: поле без цитаты обнуляется, название и контекст берутся из черновика.
10. План этапов: выбор команды сохраняет заданное число, диапазон 1–10 соблюдается, подтверждение сверх лимита не проходит и не начисляет очки.

Параметры проверки:

• --no-serve — выполнить все проверки, включая smoke, и завершить работу без запуска основного приложения;
• --quick — выполнить pytest и проверку типов/сборку фронта, не поднимать тестовые серверы и пропустить smoke;
• KEEP_LOGS=1 — сохранить временные логи check при диагностике сбоя.

Рабочая БД не используется: backend-тесты работают на тестовой БД, smoke-сценарий — на отдельном временном SQLite-файле.

GitHub Actions

При push в main и для каждого pull request GitHub Actions запускает две проверки:

• Build check: Node.js 20, npm install, npm run build (TypeScript и production-сборка Vite);
• Backend tests: Python 3.13, установка backend/requirements.txt, pytest.

Статус проверок доступен во вкладке Actions репозитория и в checks коммита или pull request.

Частые проблемы

• Порт 8000/5173 занят. Остановите старый run через Ctrl+C в его терминале; check также требует свободные порты 8001/5174.
• Не подключается PostgreSQL. Убедитесь, что Docker Desktop запущен и контейнер db здоров. Для локальной работы без Docker закомментируйте DATABASE_URL в .env, чтобы использовать SQLite.
• API отвечает, но ИИ работает в режиме заглушки. Проверьте OPENAI_API_KEY в .env, затем перезапустите backend. Без ключа mock-режим ожидаем.
• Сброс на публичном сервере возвращает 403. Передайте действительный X-Admin-Token, совпадающий с ADMIN_TOKEN в переменных окружения.
• Нужна диагностика запуска check. Запустите ./check.sh --no-serve (PowerShell: .\check.ps1 --no-serve) и задайте KEEP_LOGS=1, чтобы оставить журналы временных серверов.