Tubi — задачи бизнеса и студенческие команды

Рабочий каркас для 5-часового AI-хакатона. Бизнес уточняет задачу, подтверждает карточку и публикует её. Студенты сами отправляют предложения; бизнес вручную выбирает команду.

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

• Конструктор: описание → минимум 3 вопроса → ответы → редактируемая карточка.
• Рейтинг 0–100 с разбивкой, подсказками и пересчётом после редактирования.
• Подтверждение человеком, сохранение черновика, публикация и повторное редактирование.
• Каталог, поиск, фильтры, сортировка; низкий рейтинг не скрывает задачу.
• Пять демонстрационных команд, отправка откликов и ручной выбор бизнеса.
• Подтверждение выполненного этапа: 50 баллов выбранной команде, без повторного начисления.
• SQLite сохраняет данные после перезапуска. При первом запуске создаются 5 карточек и 5 откликов; в seed-файле также есть 5 слабых описаний.

Быстрый запуск

Нужны Node.js 22.12+ и Python 3.11+. Репозиторий содержит package-lock.json; для frontend используйте npm ci.

Windows PowerShell

Из папки проекта запустите ./start.ps1. Скрипт устанавливает зависимости, собирает frontend и запускает приложение на http://127.0.0.1:8000. Остановить сервер: Ctrl+C.

Если политика PowerShell запрещает скрипт, используйте команды вручную (менять системную политику не требуется):

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r server/requirements.txt
cd web
npm ci
npm run build
cd ..
.\.venv\Scripts\python.exe -m uvicorn app.main:app --app-dir server --host 127.0.0.1 --port 8000

macOS / Linux

python3 -m venv .venv
.venv/bin/python -m pip install -r server/requirements.txt
cd web
npm ci
npm run build
cd ..
.venv/bin/python -m uvicorn app.main:app --app-dir server --host 127.0.0.1 --port 8000

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

Backend: команда uvicorn выше, при разработке добавьте --reload. Frontend: cd web → npm run dev → http://127.0.0.1:5173. Vite перенаправляет /api на порт 8000. После изменения production frontend нужен новый npm run build и перезагрузка страницы. API-документация: http://127.0.0.1:8000/docs. Проверка состояния: /api/health.

OpenAI и деморежим

Скопируйте server/.env.example в server/.env, задайте OPENAI_API_KEY и при необходимости OPENAI_MODEL, затем перезапустите backend. По умолчанию указана gpt-4o-mini; модель должна быть доступна вашему API-проекту и поддерживать Structured Outputs. API использует отдельный ключ и биллинг.

Без ключа приложение полностью проходит демонстрационный сценарий на локальных шаблонах: вопросы выбираются по незаполненным полям, ответы переносятся в карточку. Интерфейс явно показывает деморежим. Это заглушка, а не работающая генерация OpenAI.

С ключом сервер использует Responses API и Pydantic для структурированного результата. Инструкция запрещает выдумывать факты; неизвестные сведения остаются null. Формат проверяется, но смысл всё равно подтверждает человек. При отказе, ошибке, таймауте или неправильном формате включается обозначенный fallback. Таймаут — 20 секунд; автоматические повторы API отключены. Ключ и сырые ответы провайдера не выводятся в логи. Живой API без ключа не проверяется.

Архитектура и разделение команды

Владелец	Папки	Ответственность
Участник 1	web/src/features/business/, web/src/shared/, web/src/App.tsx, настройки frontend	Конструктор, общий интерфейс и подключение экранов
Участник 2	web/src/features/marketplace/	Каталог, карточка, отклики и решение бизнеса
Участник 3 — backend	server/, contracts/, README	API, SQLite, AI, рейтинг и контракт

contracts/api.md — договор, contracts/types.ts — типы frontend, contracts/fixtures.json — примеры для независимой работы. Все экранные запросы находятся в api.ts своего модуля. Главный интерфейс использует настоящий локальный backend. Для работы на заглушках импортируйте примеры из fixtures в адаптер своего модуля. Общие зависимости и контракт изменяйте согласованно.

Backend: schemas.py — входные модели, rating.py — формула, ai.py — AI и fallback, db.py — SQLite, main.py — маршруты и раздача собранного сайта. База по умолчанию: server/data/tubi.sqlite3; путь можно изменить через TUBI_DB_PATH.

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

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

Засчитывается текст длиной от 3 символов, содержащий буквы/цифры. Пустые значения и явно заданные заглушки («не знаю», «не указано», «тест» и др.) дают 0. Это прозрачная проверка полноты MVP, а не семантическая экспертиза качества. Перечень правил находится в rating.py. AI баллы не начисляет.

0–39 — нужно уточнение; 40–69 — рабочая; 70–89 — готова; 90–100 — приоритетная. Черновик публикации скрыт до подтверждения, но опубликованная задача с любым рейтингом видна и принимает отклики. При сохранении изменённых сведений сервер заново считает рейтинг. Выбор команды не зависит от рейтинга и не автоматизируется.

Проверки

.\.venv\Scripts\python.exe -m pip install -r server/requirements-dev.txt
$env:PYTHONPATH='server'
.\.venv\Scripts\python.exe -m unittest discover -s server/tests -v
cd web
npm run build

На macOS/Linux: PYTHONPATH=server .venv/bin/python -m unittest discover -s server/tests -v. API-проверки используют временную БД, не меняют демонстрационные данные и не вызывают OpenAI. Они проверяют полный сценарий, видимость задач с низким рейтингом, пересчёт, валидацию URL, независимость решений по откликам и защиту от повторного начисления баллов.

Перегенерация примеров и OpenAPI: python scripts/export_contracts.py из корня с активным окружением проекта.

Демонстрация за 5 минут

1. Каталог: покажите разные уровни готовности и фильтры.
2. В роли «Бизнес» нажмите «Создать задачу», затем «Попробовать пример».
3. Ответьте на три вопроса, соберите карточку; покажите текущие баллы.
4. Добавьте пользователей, измеримый критерий успеха и контакт; покажите рост рейтинга.
5. Подтвердите сведения и опубликуйте задачу.
6. Переключитесь в «Команда», найдите задачу и отправьте предложение.
7. Вернитесь в «Бизнес», откройте отклики и вручную выберите команду.
8. При наличии времени покажите подтверждение выполненного этапа.

Ограничения каркаса

Это локальная демонстрация: переключатель ролей не является авторизацией, данные бизнеса общие. Нужны настоящая аутентификация и проверки владельца перед использованием реальных данных или публичным размещением. Сервер по умолчанию слушает только 127.0.0.1. Чат, регистрация и проектный трекер не входят в MVP. Шрифт Manrope загружается из Google Fonts; без сети используется системный шрифт.