Практика

Платформа для задач бизнеса и студенческих команд. Проект команды Sloppy-team по кейсу AI Sana.

1. Какую проблему решаем

Бизнесу бывает сложно превратить идею в понятное техническое задание, а студентам — найти задачу для практики. «Практика» помогает уточнить потребность, оформить карточку и собрать предложения команд. Бизнес выбирает исполнителей самостоятельно.

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

• Регистрация и вход по email и паролю; личный кабинет с задачами владельца.
• Помощник: черновик → три уточняющих вопроса → редактируемая карточка.
• Рейтинг заполненности 0–100, расшифровка и подсказки по улучшению задания.
• Публикация и редактирование после явного подтверждения пользователем.
• Открытый каталог, поиск, фильтры по направлению, статусу и баллам, сортировка по готовности или дате.
• Отклики с названием команды, идеей, планом, сроком и необязательной ссылкой на прототип.
• Ручное принятие или отклонение откликов владельцем задачи. Можно выбрать несколько команд.
• Сохранение аккаунтов, задач, рейтингов и откликов в PostgreSQL.
• Настоящий AI через OpenAI и отдельный демонстрационный режим без ключа.

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

1. Бизнес регистрируется и вводит описание своей потребности.
2. Помощник задаёт три вопроса и на основе ответов составляет карточку задания.
3. Пользователь проверяет текст, дополняет поля, видит рейтинг и подтверждает публикацию.
4. Студент входит в свой аккаунт, находит задачу и отправляет предложение команды.
5. Владелец задачи рассматривает предложения и принимает или отклоняет их.

Результат — опубликованное задание и сохранённые решения по откликам. Само студенческое решение платформа не разрабатывает. Низкий рейтинг не закрывает задачу для откликов.

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

Часть	Технологии
Интерфейс	TypeScript, React 19, Next.js 16, CSS, Lucide React
Сервер приложения	Next.js Route Handlers, Node.js 22.12+
База данных	PostgreSQL, Prisma 7, драйвер pg
AI и рейтинг	Python 3.11+, FastAPI, Uvicorn, Pydantic 2
Внешний AI	OpenAI API, модель gpt-4o, OpenAI Python SDK 2, Structured Outputs через Chat Completions
Настройки и проверки	dotenv / python-dotenv, HTTPX, unittest, node:test, tsx, TypeScript

Зависимости зафиксированы в frontend/package.json, frontend/package-lock.json и backend/requirements.txt.

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

flowchart TD
    Browser[Браузер: бизнес или студент] --> Next[Next.js: интерфейс и API]
    Next --> Auth[Вход и проверка владельца]
    Next --> Store[Prisma / pg]
    Store --> DB[(PostgreSQL)]
    Next --> Python[FastAPI: AI и рейтинг]
    Python --> Score[Расчёт рейтинга без AI]
    Python --> Assistant[Помощник]
    Assistant --> OpenAI[OpenAI gpt-4o: режим openai]
    Assistant --> Demo[Фиксированные вопросы: режим demo]

• frontend/components/ — каталог, регистрация, создание и редактирование карточек, отклики.
• frontend/app/api/[...path]/route.ts — запросы браузера, проверка входных данных и прав.
• frontend/lib/auth.ts — хеширование паролей через scrypt и подписанная HttpOnly cookie на семь дней.
• frontend/lib/task-service.ts, store.ts — работа с задачами и откликами; prisma/ — схема, миграции и демонстрационные данные.
• frontend/lib/backend-client.ts — связь Next.js с Python, обработка ошибок и таймаутов.
• backend/main.py, schemas.py — Python API и схемы данных.
• backend/ai_service.py — вопросы и карточки; scoring.py — единая формула рейтинга.

Браузер обращается к Next.js. Только сервер Next.js обращается к Python, а Python — к OpenAI. Ключ не передаётся в браузер. Каталог читает сохранённые баллы из PostgreSQL; создание, редактирование и расшифровка рейтинга требуют Python.

Рейтинг — оценка заполненности, а не качества идеи. Контекст и данные дают до 20 баллов каждый, результат и критерии успеха — до 15, ограничения и аудитория — до 10, контакт и формат консультаций — до 5 каждый. Поле короче 10 символов даёт 0; 10–29 символов — половину с округлением вниз; от 30 — максимум. Пробелы по краям не учитываются.

Баллы	Статус
0–39	Требует уточнения
40–69	В проработке
70–89	Готова к работе
90–100	В приоритете

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

Нужны Git, Node.js 22.12+, npm, Python 3.11+ и работающий PostgreSQL. Ниже команды для Windows PowerShell. Для первого знакомства используйте деморежим: ключ OpenAI не нужен.

Шаг 1. Скачайте проект и создайте базу

git clone https://github.com/BAITC-Hacks/hack-30765277-sloppy-team.git
cd hack-30765277-sloppy-team
psql -U postgres -h localhost -c "CREATE DATABASE praktika;"

PostgreSQL запросит пароль пользователя postgres. Если psql не добавлен в PATH, создайте пустую базу praktika через pgAdmin. Если база уже существует, повторно создавать её не нужно.

Шаг 2. Настройте окружение

Из корня проекта скопируйте примеры, сохранив существующие настройки:

if (!(Test-Path backend/.env)) { Copy-Item backend/.env.example backend/.env }
if (!(Test-Path frontend/.env)) { Copy-Item frontend/.env.example frontend/.env }
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Последняя команда создаёт случайную строку для SESSION_SECRET. Откройте .env в текстовом редакторе и заполните:

Файл	Переменная	Что указать
backend/.env	AI_MODE	demo для проверки без внешнего AI
backend/.env	OPENAI_API_KEY	В demo можно оставить пустой
frontend/.env	DATABASE_URL	postgresql://postgres:YOUR_PASSWORD@localhost:5432/praktika?schema=public, заменив пароль своим
frontend/.env	SESSION_SECRET	Сгенерированную строку, не менее 32 символов
frontend/.env	AI_BACKEND_URL	http://127.0.0.1:8000

Спецсимволы пароля в URL нужно URL-кодировать. .env загружается автоматически; уже заданные переменные окружения имеют приоритет. Секреты исключены из Git. Не добавляйте ключ в исходники или NEXT_PUBLIC_*.

Шаг 3. Запустите Python

Первый терминал из корня проекта:

cd backend
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 8000

Оставьте его открытым.

Шаг 4. Запустите интерфейс

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

cd frontend
npm ci
npm run db:migrate
npm run db:seed
npm run dev

Seed добавляет шесть учебных задач, не перезаписывая существующие. Python должен работать: он рассчитывает их рейтинг. Для обновления базы используйте миграции; не запускайте migrate reset на базе с нужными данными.

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

Как включить настоящий AI

В backend/.env задайте AI_MODE=openai и свой OPENAI_API_KEY, затем перезапустите Python. Используется gpt-4o. Для проверки из папки backend:

.\.venv\Scripts\python.exe smoke_openai.py

Скрипт делает два оплачиваемых запроса на учебном примере: вопросы и карточку. В demo запросов к OpenAI нет; вопросы фиксированы, ответы переносятся в поля. При ошибке настоящего AI автоматической подмены на demo нет.

После изменения настроек перезапускайте соответствующий сервер. Если меняете порт Python, измените и AI_BACKEND_URL. Для production предусмотрены npm run build и npm start; для входа в этом режиме нужен HTTPS из-за Secure cookie. Для локальной демонстрации используйте npm run dev.

7. Как проверить решение жюри

Запустите приложение в demo. Нужны два разных аккаунта: бизнес и студент. Их можно открыть в обычном и приватном окнах браузера. Переключатель роли меняет интерфейс, но не заменяет вход и не даёт права владельца.

1. Нажмите «Войти» → «Регистрация». Создайте аккаунт бизнеса с паролем 12–128 символов.

2. Выберите «Бизнес» → «Создать задачу». Введите «Нужно разобраться в продажах» и нажмите «Уточнить задачу».

3. Ответьте на вопросы:

   Поле	Учебный ответ
   Результат	Дашборд продаж с фильтрами по дням и товарам
   Данные	Обезличенные таблицы продаж за последние шесть месяцев
   Приёмка	Суммы в отчёте совпадают с исходными таблицами

4. Нажмите «Сформировать карточку». Ожидается 60/100; контакт, ограничения и аудитория остаются пустыми. Посмотрите расшифровку и рекомендации.

5. Назовите задачу «Пилот: дашборд продаж кофейни», подтвердите проверку и опубликуйте. Найдите её через поиск.

6. В другом аккаунте выберите «Студент», откройте эту задачу и отправьте отклик: команда Альфа, идея «Дашборд динамики продаж», план «Проверка данных → расчёты → интерфейс → проверка с бизнесом», срок «Четыре недели». Ссылку можно оставить пустой.

7. В аккаунте бизнеса откройте «Кабинет бизнеса» и отклики своей задачи. Примите Альфу. После перезагрузки решение сохраняется; другие команды всё ещё могут откликаться.

8. Отредактируйте карточку: удалите «Данные и материалы» и подтвердите изменение. Рейтинг снизится с 60 до 40. Верните прежний текст — снова 60. После каждой правки подтверждение требуется повторно.

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

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

После установки зависимостей, из корня проекта:

cd backend
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
cd ../frontend
npm run typecheck
npm test
npm run build

Python-тесты проверяют схемы, ошибки AI и рейтинг, включая 6561 сочетание полей; внешние AI-ответы подставные. Без TEST_DATABASE_URL сквозной тест PostgreSQL пропускается. Для его запуска нужна отдельная тестовая схема с префиксом pilot_test_, применённые миграции и Python в режиме demo:

# В отдельном терминале frontend. Замените USER, PASSWORD и TEST_DB своими значениями.
$env:TEST_DATABASE_URL = "postgresql://USER:PASSWORD@localhost:5432/TEST_DB?schema=pilot_test_integration"
$env:DATABASE_URL = $env:TEST_DATABASE_URL
$env:AI_BACKEND_URL = "http://127.0.0.1:8000"
npm run db:migrate
npm test

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

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

• Источники — описания и ответы бизнеса, ручные правки и предложения команд.
• Шесть начальных карточек из frontend/lib/domain.ts — синтетические примеры. Seed не создаёт готовые аккаунты и отклики.
• PostgreSQL хранит аккаунты с хешами паролей, задачи и предложения. Старый .data/store.json автоматически не импортируется.
• OpenAI получает черновик, а при сборке карточки также вопросы и ответы. В demo эти данные не отправляются во внешний AI.
• Ссылки на материалы и прототипы вводятся пользователем; загрузки файлов и автоматического импорта по ссылкам нет.
• Интеграций с CRM, вузовскими системами и внешними датасетами нет.

9. Ограничения

• Рейтинг основан на длине текста и не гарантирует качества или выполнимости задания. AI-карточку нужно проверять вручную.
• Нет подтверждения этапов выполнения, баллов студентов, полноценных профилей и состава команд, автоматического подбора, чата и уведомлений.
• Отклик хранит название команды, но не отдельный профиль команды, связанный с аккаунтом.
• Нет автосохранения незавершённой формы и защиты от дублирования публикации/отклика после обрыва связи.
• Принятый отклик нельзя отклонить, отклонённый — принять; повтор того же решения допустим.
• Нет сброса паролей, индивидуального серверного отзыва сессий и ограничения частоты запросов.
• Python не проверяет пользовательские сессии; права проверяет Next.js. Для публичного запуска Python должен быть закрыт от прямого внешнего доступа; также нужны HTTPS, настройка CORS, лимиты расходов AI и резервное копирование БД.

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

Подтверждённая ссылка на публичную deployed-версию в репозитории не указана. Для проверки используйте локальный запуск выше.

11. Проверка интеграции — 23 сентября 2026

• Разрешены конфликты объединения AI/scoring и PostgreSQL. Сохранены регистрация, проверка владельца, ручное подтверждение, редактирование и выбор нескольких команд.
• Все 6 миграций применены к отдельному PostgreSQL 18, схема pilot_test_integration. Рабочая база пользователя не изменялась; подключение к ней нужно указать в frontend/.env.
• Прошли 12 Python-тестов, включая 6561 комбинацию полей и ошибки OpenAI, и 5 TypeScript-тестов без пропусков, включая полный сценарий с реальной тестовой БД, проверку прав и конкурентное принятие двух команд. TypeScript и production-сборка прошли.
• В браузере проверены регистрация, карточка 60 → 100, подтверждение и публикация, отклик другого аккаунта, ручное принятие и сохранение решения после перезагрузки. Исправлен ложный запрет локальной регистрации из-за нормализации Host в Next.js.
• Настоящий gpt-4o проверен с предоставленным локальным ключом: отдельно через smoke_openai.py и через мастер в браузере. Получены три вопроса и редактируемая карточка. После уточнения промпта повторный smoke-тест подтвердил перенос явно заданного условия приёмки в критерии успеха; отсутствующие контакты и ограничения остались null. Один пример не гарантирует качество модели на любых данных: требуется проверка человеком.
• .env, ключи, pgpass, тестовый кластер и выгрузки исключены из Git. Проверка текущих файлов на распространённые форматы секретов не нашла ключей. История Git не аудировалась.

Формат ответов модели: официальная документация OpenAI Structured Outputs.