AI Sana Challenge Hub

Кроссплатформенный сервис для кейса МНВО — AI Sana. Он помогает бизнесу превратить короткое описание проблемы в ясный студенческий проект, а командам — понять задачу и предложить решение.

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

1. Название проекта

AI Sana Challenge Hub — Паспорт ясности образовательных задач.

2. Проблема и пользователи

Бизнес часто описывает потребность одной-двумя фразами. Студентам не хватает контекста, доступных данных, ожидаемого результата и критериев успеха, чтобы решить, за что браться. Hub помогает бизнесу уточнить эти пункты и опубликовать понятный бриф. Студенческие команды изучают каталог и отправляют предложения; бизнес вручную выбирает, с кем продолжить работу.

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

• Каталог задач с поиском по тексту и фильтрами по образовательной теме.
• Мастер создания задачи: черновик → уточняющие вопросы → редактируемая карточка → публикация.
• AI-вызов через FastAPI для генерации вопросов и структурирования карточки. Модель не должна придумывать отсутствующие факты; результат проверяет заказчик.
• Демо-режим без API-ключа, чтобы можно было открыть MVP и пройти сценарий.
• Если модель не отвечает или вернула некорректный результат, API переключается на локальный демо-режим и сообщает об этом клиенту.
• «Паспорт ясности»: рейтинг 0–100, вклад каждого поля и список недостающих данных.
• Рейтинг не скрывает задачу и не запрещает командам откликаться.
• Отклик команды: идея, план, срок и необязательная ссылка на прототип.
• Уведомление в приложении после отправки отклика; сообщение также появляется во входящих бизнеса.
• Регистрация и вход для бизнеса и студенческих команд; подтверждение почты временно отключено для MVP. В разделе «Мой профиль» можно менять имя, почту и пароль; для изменений нужен текущий пароль.
• Пароли хранятся в базе только в виде защищённых PBKDF2-хэшей. При смене пароля остальные активные входы завершаются.
• Согласие на обработку данных сохраняет дату и версию; уведомление объясняет необходимое браузерное хранилище, аналитические и рекламные cookie не используются.
• Карточки и отклики связаны с аккаунтом автора; бизнес управляет откликами только на собственные задачи, студент видит свои предложения.
• На главной показывается фактическое число зарегистрированных участников без публикации их профилей.
• Бизнес вручную принимает или отклоняет предложения. После решения команда получает уведомление внутри приложения.
• Адаптивный Flutter-клиент для Web, Android, iOS, Windows, macOS и Linux; тот же FastAPI API обслуживает браузерную версию.
• Новые записи создаются только через формы пользователей. Вымышленные задачи и отклики отключены по умолчанию; примеры можно включить только явной настройкой DEMO_SEED=true.

4. Как работает пользовательский сценарий

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

Отклики и решения показываются во входящих приложения. Email-уведомления о новых откликах, SMS и push не подключены.

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

• Клиент: Flutter и Dart; адаптивный Material 3 интерфейс.
• API: Python, FastAPI и Pydantic.
• AI: OpenAI Responses API или NVIDIA NIM с OpenAI-совместимым API. Ключ хранится только в серверном .env.
• Хранилище: Supabase Postgres при настройке проекта; SQLite для запуска без внешней базы.
• Статистика: считается по сохранённым задачам и откликам. При пустой базе показатели начинаются с нуля.
• Транспорт: HTTP/JSON между Flutter, браузерным клиентом и FastAPI.

Официальные руководства: OpenAI Responses API, NVIDIA NIM API, Flutter Web, FastAPI, Supabase Python.

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

Flutter: Web / Android / iOS / Windows / macOS / Linux
                         │ HTTP/JSON
                         ▼
                    FastAPI API
             ┌───────────┼───────────┐
             ▼           ▼           ▼
          OpenAI       NVIDIA     Supabase
        Responses      NIM API    Postgres
                                      │
                          если Supabase не настроен
                                      ▼
                                    SQLite

Браузерная версия в корневом index.html использует тот же API. FastAPI отдаёт её на http://127.0.0.1:8000/. Flutter-клиент лежит в app/, сервер — в backend/, SQL-схема — в backend/supabase/schema.sql.

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

Запустить Python API и браузерную версию

Нужен Python 3.10 или новее.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python3 -m uvicorn backend.main:app --reload

Откройте:

• Приложение в браузере: http://127.0.0.1:8000/
• Интерактивная документация API: http://127.0.0.1:8000/docs

Для личного кабинета владельца откройте .env и задайте ADMIN_EMAIL своей почтой. Затем войдите или зарегистрируйте аккаунт именно на этот адрес. В левом меню появится «Личный кабинет»: там видны агрегированные просмотры и участники, а доступ к аккаунту можно временно отключить или восстановить. Счётчик оценивает браузерные сессии, а не устанавливает личность посетителя.

Задайте длинный случайный секрет в AUTH_SECRET. Подтверждение почты сейчас отключено для MVP, поэтому SMTP не требуется для входа. Если позже включите подтверждение, настройте SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM и публичный HTTPS-адрес в APP_PUBLIC_URL.

Без AI-ключа модель не вызывается, но интерфейс работает в демо-режиме. Если настроенная модель недоступна, API явно включает локальный резервный режим. Чтобы включить OpenAI, откройте .env и укажите свой ключ в AI_API_KEY. По умолчанию настроен Responses API и модель gpt-6-astra:

AI_PROVIDER=openai
AI_API_KEY=вставьте_ключ_сюда
AI_MODEL=gpt-6-astra

Сохраните файл и перезапустите сервер. Если вашей организации недоступна модель по умолчанию, измените AI_MODEL на доступную в вашем API-аккаунте.

Для NVIDIA NIM укажите AI_PROVIDER=nvidia, свой токен в AI_API_KEY и доступное в NVIDIA API Catalog имя модели в AI_MODEL. NVIDIA_BASE_URL уже содержит стандартный NIM endpoint. Приложение не отправляет секретный ключ из Flutter или браузера.

Использовать Supabase вместо локальной SQLite

1. Создайте проект Supabase.
2. Откройте SQL Editor и выполните скрипт из backend/supabase/schema.sql.
3. В корневом .env заполните SUPABASE_URL и SUPABASE_SERVICE_ROLE_KEY значениями проекта.
4. Установите AUTH_SECRET в .env как длинную случайную строку.
5. Перезапустите FastAPI.

Сгенерировать секрет можно командой openssl rand -hex 32. В Render сохраните его как переменную окружения AUTH_SECRET, чтобы входы не сбрасывались после перезапуска.

Если проект Supabase уже настроен, повторно выполните обновлённый backend/supabase/schema.sql, чтобы добавить новые поля аккаунта и таблицу просмотров. Для SQLite изменения применяются автоматически при запуске.

Если эти две переменные оставить пустыми, данные сохраняются в backend/data/hub.sqlite3. Не вставляйте ключ service_role в Flutter, браузер, README или GitHub: он предназначен только для API-сервера.

SQLite хранит данные только на этом компьютере. Чтобы разные участники видели одни и те же карточки и отклики, подключите Supabase и разместите FastAPI-сервер в доступном всем месте. Новые карточки создаются пользователями в разделе «Создать задачу», отклики — через «Предложить решение»; счётчики каталога читают данные из подключённой базы.

Запустить Flutter-приложение

Нужны Flutter SDK и Dart из комплекта Flutter. Для добавления стандартных папок платформ к исходникам проекта:

cd app
flutter create . --platforms web,android,ios,windows,macos,linux
flutter pub get
flutter run -d chrome --dart-define=API_BASE_URL=http://127.0.0.1:8000

Сначала запустите FastAPI из корня репозитория в отдельном терминале. Для запуска на подключённом телефоне используйте адрес компьютера в локальной сети, например:

flutter run --dart-define=API_BASE_URL=http://192.168.1.25:8000

Замените IP на адрес компьютера, где работает FastAPI; телефон и компьютер должны быть в одной сети. В эмуляторе Android приложение по умолчанию использует 10.0.2.2:8000. Для запуска на Windows/macOS/Linux выберите соответствующее устройство Flutter; desktop runner создаётся командой flutter create выше.

8. Как проверить MVP

1. Запустите FastAPI и зарегистрируйте аккаунт с ролью «Представитель бизнеса».
2. Создайте и опубликуйте карточку задачи.
3. В другом браузере или окне инкогнито зарегистрируйте аккаунт «Студент / команда».
4. Откройте опубликованную задачу, отправьте отклик и проверьте, что он появился у бизнеса во входящих.
5. Войдите бизнес-аккаунтом и примите или отклоните отклик; команда увидит обновлённый статус.

В OpenAPI-документации доступны /api/health, /api/tasks, /api/ai/refine, /api/ai/organize, /api/tasks/{id}/responses, /api/responses и /api/notifications.

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

• При обычном запуске база пустая; в каталог попадают карточки, созданные пользователями.
• Пользователи хранятся в таблице users; подтверждение почты временно отключено. Пароли хранятся как PBKDF2-хэши, браузерные сессии — 14 дней. Для смены имени, почты или пароля сервис просит текущий пароль.
• AI получает черновик и ответы только при наличии AI_API_KEY; FastAPI возвращает ошибки модели без добавления вымышленных данных в карточку.
• SQLite используется для локального старта; Supabase включается серверными переменными окружения и SQL-схемой из репозитория.
• Восстановление пароля и проверка бизнес-аккаунтов не реализованы; роль выбирается при регистрации.
• Локальная SQLite не синхронизируется между компьютерами; для общей работы требуется Supabase.
• Для локального показа примеров можно явно задать DEMO_SEED=true; по умолчанию примеры отключены.

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

• Flutter SDK не включён в репозиторий; команды запуска ниже создают нужные платформенные runner-файлы на компьютере разработчика.
• Персональный подбор бизнес-сфер и идей по интересам и реакциям пользователя пока описан как следующий этап и ещё не реализован в приложении.
• Для AI нужен действующий API-ключ и модель, доступные конкретному аккаунту. Без ключа интерфейс работает с локальным демо-режимом.
• Supabase и AUTH_SECRET нужно настроить для публичного запуска. По умолчанию доступна локальная SQLite.
• Восстановление пароля и модерация бизнес-аккаунтов не реализованы; роль выбирает сам пользователь при регистрации.
• Шаблон соглашения находится в privacy.html; перед публичным сбором данных нужно вписать оператора, контакт и сроки хранения.
• Flutter-клиент поддерживает вход и регистрацию в течение открытой сессии приложения; для длительного сохранения входа требуется добавить защищённое хранилище токенов на устройстве.
• Сообщения показываются во входящих приложения; email, SMS и push не настроены.
• Рейтинг прозрачно проверяет заполнение полей, но не доказывает качество или реализуемость проекта.
• Источника deployed-версии пока нет; приложение запускается локально по инструкциям выше.

11. Ссылка на deployed-версию

Публичная развёрнутая версия пока не настроена.

Короткий питч для защиты

«AI Sana Hub помогает бизнесу сформулировать задачу так, чтобы студентам было понятно, с чего начать. Он спрашивает о пробелах, показывает прозрачный паспорт ясности, собирает отклики и оставляет выбор команды за человеком».