Bastamat — TimasFriends

Каталог бизнес-задач для студенческих команд. Бизнес описывает проблему, уточняет сведения с помощником, редактирует карточку и подтверждает публикацию. Команда выбирает задачу и предлагает решение; бизнес вручную принимает или отклоняет предложение.

Стек: Unity 6000.3.7f1, uGUI / TextMeshPro, WebGL; Python 3.12 или 3.13, FastAPI, Pydantic, SQLite. Интерфейс рассчитан на настольный браузер в горизонтальном окне.

Быстрый старт — Windows

Нужны Git, Python 3.12 или 3.13, Unity Hub → Unity 6000.3.7f1 с модулем WebGL Build Support. Команды ниже — PowerShell; после клонирования оставайтесь в корне проекта.

git clone https://github.com/BAITC-Hacks/hack-415c3411-timasfriends.git QuestBridge
cd QuestBridge
py -3.12 -m venv backend/.venv
backend/.venv/Scripts/python.exe -m pip install -r backend/requirements.txt
if (!(Test-Path backend/.env)) { Copy-Item backend/.env.example backend/.env }
backend/.venv/Scripts/python.exe -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --env-file backend/.env

Для установленного Python 3.13 замените только py -3.12 на py -3.13. При повторном запуске клонирование, создание окружения и копирование настроек не нужны. Терминал backend оставьте открытым; localhost:8000/health должен показать status: "ok".

1. В Unity: добавьте корневую папку в Hub, дождитесь импорта, откройте Assets/QuestBridge/QuestBridge.unity. На объекте QuestBridge, компоненте QuestBridgeApp, установите Server Url = http://127.0.0.1:8000 и нажмите Play. Выберите бизнес или команду.
2. В браузере: выйдите из Play, в File → Build Profiles выберите WebGL/Web и нажмите Switch Platform. Дождитесь переключения, выполните QuestBridge → Build Web Preview и дождитесь успешного завершения. Во втором PowerShell из корня проекта выполните команду ниже и откройте http://localhost:8080/. Оба терминала должны работать.

backend/.venv/Scripts/python.exe scripts/serve_web.py --port 8080

Без ключей AI работает серверный fallback: можно пройти публикацию, отклик, выбор команды и подтверждение этапа. Для живого AI задайте OPENAI_API_KEY и AI_MODEL только в backend/.env и перезапустите backend. Не помещайте ключи в Unity или Git. Профили демонстрационные, входа по паролю нет. Готовый WebGL-билд не хранится в Git — после чистого клона его нужно собрать.

Подробности, Linux/macOS и решение ошибок — ниже; сборка и размещение WebGL, сценарий показа.

Запуск для жюри

Для демонстрации AI-ключ не обязателен: backend поддерживает пошаговый чат, публикацию задач, отклики и начисление опыта без внешнего AI. Для первого скачивания зависимостей нужен интернет. SQLite и демонстрационные данные создаются автоматически; отдельный сервер базы данных устанавливать не нужно.

Ниже — команды для Windows / PowerShell. Вариант для Linux/macOS приведён после шага 5.

1. Подготовьте Python и проект

Установите Python 3.12 или 3.13. В новом окне PowerShell проверьте установленную версию:

py -3.12 --version

Если установлен Python 3.13, здесь и при создании окружения используйте py -3.13.

Получите проект через Git:

git clone https://github.com/BAITC-Hacks/hack-415c3411-timasfriends.git QuestBridge
cd QuestBridge

Можно скачать ZIP репозитория и распаковать его. Если проект уже скачан, откройте PowerShell в его папке. Все дальнейшие команды выполняйте из корня проекта, где находятся README.md, backend/ и Assets/.

2. Создайте окружение и установите зависимости

При первом запуске создайте окружение:

py -3.12 -m venv backend/.venv

Если backend/.venv уже существует, повторное создание пропустите. Установите зависимости backend:

backend/.venv/Scripts/python.exe -m pip install -r backend/requirements.txt

Активировать окружение не требуется: команды обращаются к его Python напрямую. Зависимости для тестов устанавливать для демонстрации не нужно.

3. Создайте файл настроек

Команда создаст backend/.env, если этого файла ещё нет:

if (!(Test-Path backend/.env)) { Copy-Item backend/.env.example backend/.env }

Для запуска без AI оставьте OPENAI_API_KEY и AI_MODEL пустыми. Сохраните SEED_DEMO=true, чтобы появились готовые примеры. Остальные значения можно оставить из шаблона.

Чтобы подключить живой AI, заполните OPENAI_API_KEY и AI_MODEL в backend/.env и перезапустите backend той же командой ниже. Подробности настройки — в backend/README.md.

4. Запустите backend

backend/.venv/Scripts/python.exe -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --env-file backend/.env

Дождитесь сообщений Application startup complete и Uvicorn running on http://127.0.0.1:8000. Оставьте этот терминал открытым на время демонстрации. --env-file backend/.env загружает созданные настройки.

Для остановки нажмите Ctrl+C. При следующем запуске достаточно открыть терминал в корне проекта и повторить команду этого шага. SQLite сохраняется в backend/data/questbridge.sqlite3; задачи и опыт остаются после перезапуска.

5. Убедитесь, что backend доступен

Откройте в браузере:

• Состояние сервера — /health. Без AI-ключа ожидается:

  {"status":"ok","service":"questbridge","aiMode":"fallback","demo":true}
  

• Каталог — /api/catalog: JSON с карточками задач и командами. В новой базе создаются пять демонстрационных задач и пять команд.

• Документация API — /docs: список методов и форм для отправки запросов.

fallback — ожидаемый режим без внешнего AI. Окно проекта открывается через Unity или браузер по шагам 6–7; страница /docs предназначена для просмотра API.

Запуск backend на Linux и macOS

Из корня скачанного проекта, с установленным Python 3.12:

python3.12 -m venv backend/.venv
backend/.venv/bin/python -m pip install -r backend/requirements.txt
if [ ! -f backend/.env ]; then cp backend/.env.example backend/.env; fi
backend/.venv/bin/python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --env-file backend/.env

Для Python 3.13 замените python3.12 на python3.13. Если окружение уже создано, первую команду пропустите. Настройки и адреса проверки совпадают с шагами 3–5.

6. Откройте проект в Unity

Установите Unity 6000.3.7f1 через Unity Hub. Добавьте в Hub корневую папку проекта, откройте её и дождитесь импорта. Откройте сцену Assets/QuestBridge/QuestBridge.unity. На объекте QuestBridge в компоненте QuestBridgeApp задайте Server Url = http://127.0.0.1:8000 без /api в конце и нажмите Play.

Выберите «Бизнес» или «Команда». Бизнес использует профиль business-demo; команда выбирается из пяти готовых профилей. Роль переключается в шапке. Это демонстрационные профили; полноценная авторизация в MVP не реализована. Сценарий показа приведён в следующем разделе.

7. Для показа в браузере соберите WebGL

Для этой версии Unity установите модуль WebGL Build Support. Выйдите из Play, откройте File → Build Profiles, выберите WebGL/Web → Switch Platform и дождитесь переключения. Затем выберите QuestBridge → Build Web Preview и дождитесь успешной сборки в Builds/WebGL. Готовые файлы сборки не входят в Git.

Оставьте backend работающим. Во втором терминале, также из корня проекта, запустите:

backend/.venv/Scripts/python.exe scripts/serve_web.py

На Linux/macOS: backend/.venv/bin/python scripts/serve_web.py.

Откройте http://localhost:8080/. Сервер предпросмотра отдаёт сборку и перенаправляет API-запросы в backend на порту 8000. Во время показа оба терминала должны оставаться открытыми. Подробная инструкция WebGL.

Если запуск не получается

Сообщение или симптом	Что сделать
py не найден или нет Python 3.12	Установите Python 3.12/3.13 и откройте новый терминал. Для установленного 3.13 используйте py -3.13.
No module named backend или не найден requirements.txt	Перейдите в корень проекта с папками backend/ и Assets/, затем повторите команду.
Не найден backend/.venv/Scripts/python.exe	Выполните создание окружения из шага 2. На Linux/macOS используйте путь backend/.venv/bin/python.
Permission denied при повторном создании .venv	Остановите работающий backend через Ctrl+C. Если окружение уже создано, переходите к установке зависимостей и запуску.
Порт 8000 занят (WinError 10048 / Address already in use)	Остановите ранее запущенный экземпляр backend через Ctrl+C в его терминале и повторите запуск.
Unity показывает отсутствие связи	Проверьте /health, работающий терминал backend и Server Url = http://127.0.0.1:8000.
На странице предпросмотра отсутствует сборка	Сначала выполните QuestBridge → Build Web Preview; затем открывайте http://localhost:8080/.

Основной сценарий — до пяти минут

1. Бизнес: введите «В учебном центре преподаватели долго проверяют пробные SAT». Помощник задаёт три вопроса по очереди: ответьте на первый отдельным сообщением, дождитесь второго, затем третьего. Каждый ответ сохраняется в черновике; после третьего ответа можно перейти к карточке. Этот порядок работает и без AI-ключа; можно написать «не знаю».
2. Нажмите «Карточка →». Дополните название, тему и известные сведения. Дождитесь проверки содержания и исправьте отмеченные поля по подсказкам. После успешной проверки справа видны подтверждённый балл, возможная прибавка и вклад каждого поля. Неизвестные поля остаются пустыми.
3. «Подтвердить сведения» → «Опубликовать». Счётчик и всплывающие прибавки показывают вклад заполненных полей. Задача появляется в каталоге. Её можно открыть и отредактировать с повторным подтверждением. Низкая оценка не запрещает публикацию.
4. Во втором окне выберите «Команда», профиль и опубликованную задачу. Откройте отклики, нажмите «Предложить решение», заполните идею, план, срок и HTTP(S)-ссылку на прототип или проект.
5. Бизнес открывает «Предложения команд» → «Подробнее», выбирает или отклоняет команду. Можно выбрать несколько. Решения обновляются примерно каждые пять секунд.
6. Выбранная команда открывает «Этапы работы» и описывает результат. Бизнес открывает этапы того же предложения и подтверждает выполненное. Сервер однократно начисляет 10 опыта и один завершённый этап.

Материалы: бизнес-кейсы, чек-лист ожидаемого поведения. Наличие пункта в чек-листе не означает, что он уже проверен.

Интерфейс

На старте экран разделён на две кликабельные половины: «Бизнес» слева и «Команда» справа. У каждой свой значок и короткое описание; наведение плавно подсвечивает выбранную сторону. Выбор команды открывает список готовых профилей.

После выбора роли интерфейс разделён на три области:

Область	«Бизнес»	«Команда»
Слева	Чат с помощником, кнопка «Карточка →»	Профиль, опыт, «Каталог задач» и «Мои отклики»; чата нет
По центру	Общий каталог и «Мои задачи», фильтры	Расширенный каталог с теми же фильтрами
Справа	Профиль выбранной команды	Профили участников и конкурирующих команд

Редактор, полная карточка, объяснение рейтинга, предложения и этапы открываются поверх каталога. Роль меняется кнопкой в шапке; выбранная команда — через её левую панель.

• Фильтры темы и готовности; сортировка по рейтингу. Полные карточки, отклики и этапы загружаются с сервера.
• Каталог общий для всех тематик: «Бизнес» и «Образование» — фильтры, а не отдельные разделы. Фильтры по теме и готовности обязательны по ТЗ. Все десять строк расшифровки рейтинга видны одновременно без внутренней прокрутки — в редакторе задачи и опубликованной карточке.
• Черновик и ручные исправления сохраняются локально в PlayerPrefs. Ответы помощника не стирают вручную изменённые поля. История чата показывается в текущей сессии; её восстановление после перезапуска пока отсутствует.
• Демо доступно в Editor и в отдельном режиме показа http://localhost:8080/?showcase=1. Кнопка запускает помеченную локальную анимацию рейтинга; Выйти возвращает серверный каталог. В обычном браузерном запуске кнопка скрыта. Для демонстрации работоспособности используйте основной сценарий выше.
• Готовые профили команд позволяют сразу пройти сценарий в двух окнах. Это синтетические данные, без регистрации и авторизации. Карточки-примеры помечены в каталоге.
• В WebGL при клике на поле используется браузерное текстовое поле: курсор, выделение и Ctrl/Cmd+C/V/X/A. Тексты переписки, полной задачи и отклика доступны для выделения по клику. Прокрутка или клик снаружи закрывают поле с сохранением текста. Остальная оболочка остаётся Unity Canvas; это не DOM-сайт и не обеспечивает поиск по всей странице через Ctrl+F.
• В Editor/Game view тексты сообщений и полных описаний тоже выделяются по клику: мышь, Shift + стрелки, Ctrl+A/C. Поле только для чтения; закрытие выделения восстанавливает исходный текст и расположение.
• Фокус скрывает каталог светлой подложкой и приглушает события. Большая кнопка возвращает каталог. Клик по фону / Escape закрывает окно.
• Game view для чёткого текста: 1x, Low Resolution Aspect Ratios выключен. Звук тихий, настройка запоминается.

Архитектура и AI

Unity WebGL → HTTP JSON API → FastAPI → SQLite / AI provider.

Клиент: QuestBridgeApp.cs — каталог и чат, QuestBridgeWorkflow.cs — роли и карточка, QuestBridgeProposals.cs — отклики и этапы, QuestBridgeContracts.cs — DTO. Сервер: backend/app, схемы models.py, рейтинг scoring.py, AI ai.py. Контракт API.

Без ключа работает «Без ИИ · пошаговый режим»: фиксированные вопросы и извлечение явно отмеченных ответов. Для полного сценария нужен локальный backend; внешний AI и личная подписка не требуются. Пустой Server Url / ?offline=1 дают просмотр локальных примеров и черновик без серверных публикаций.

Живой AI включается на сервере через OPENAI_API_KEY и AI_MODEL из backend/.env.example. Ключи не входят в Unity, WebGL или Git. Промпты и обработка невалидного ответа находятся в backend/prompts/ и backend/app/ai.py. При ошибке используется fallback. Извлечение ограничено подтверждаемыми фрагментами пользовательских сообщений; неизвестные данные не додумываются.

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

Контекст 10 + потребность 10 + данные 20 + результат 15 + критерии успеха 15 + ограничения 10 + пользователи 10 + контакт 4 + формат взаимодействия 3 + обратная связь 3 = 100.

Учитываются заполненные и подтверждённые поля, прошедшие проверку содержания. Бессвязный текст, повторы и заглушки вроде «не знаю» не дают баллы. AI проверяет смысл и соответствие полям; без ключа доступен более ограниченный локальный фильтр явного мусора. Ошибки показываются в чате и у полей карточки; отклонённый ответ не продвигает уточнения, а публикация требует исправлений. При недоступности настроенного AI проверку нужно повторить. Оценка показывает полноту; проверка смысла не доказывает достоверность фактов или ценность задачи. Предпросмотр показывает потенциальную прибавку после подтверждения. Анимация подтверждения — визуальная обратная связь; опыт команды начисляет только сервер за выполненный этап.

Подтверждение показывает изменение каждого поля: голубую прибавку или коралловое уменьшение после удаления сведений. Подтверждённый результат личного черновика сохраняется локально: повторное открытие не запускает прежние прибавки заново. «Сначала» сбрасывает этот результат вместе с черновиком.

Уровни: 0–39 — черновик, 40–69 — рабочая, 70–89 — готовая, 90–100 — приоритетная. Все опубликованные задачи доступны для отклика. Отдельная AI-ясность 0–10 разрешает равенство основной оценки; далее используется стабильный ID. Она вычисляется при публикации/изменении текста и показана в полной карточке вместе с объяснением. В fallback интерфейс сообщает, что AI-оценка недоступна; значение 0 не выдаётся за ответ модели. AI не назначает команды.

Состояние проверки и ограничения

В Game view проверены новый экран выбора роли из двух половин, логотип, подсветка «Мои отклики», выделение и копирование фрагмента сообщения, анимации +4/−4 при заполнении и удалении контакта, вход в демокаталог с активным фильтром. Все десять строк рейтинга помещаются без прокрутки. Эти действия не публиковали изменений задачи на сервере.

23 сентября в 17:37 по Астане WebGL собран успешно из исходников 697f4c4: 0 ошибок, около 65 МБ. В сборку вошли экран выбора роли, текстовый мост, исправления рейтинга и клиент проверки содержания от backend. Единственное предупреждение относится к отключённому служебному мосту Pipeline в Player. Локальная страница возвращает HTTP 200, API через порт 8080 отвечает status: ok; backend перезапущен с последними изменениями. Полный новый сценарий публикации, отклика и подтверждения этапа пока не проверен вручную в браузере. Автоматические тесты в этом проходе не запускались. Живой AI и публичное HTTPS-развёртывание требуют настройки; подробности — в docs/WEBGL.md.

Scope API предназначены для демонстрации на синтетических данных. Для настоящих закрытых задач потребуется серверная авторизация. SQLite при размещении должен находиться на постоянном диске. Детали откликов доступны автору, владельцу задачи либо всем при согласии автора.

Third-party

• Unity packages: Packages/manifest.json, Packages/packages-lock.json.
• Noto Sans Regular — источник, SIL Open Font License; Assets/QuestBridge/Resources/OFL.txt.
• Kenney Interface Sounds, CC0: происхождение файлов. Четыре коротких звука интерфейса.
• Логотип Bastamat предоставлен командой: исходный вариант. В приложении и WebGL использованы неизменённые копии; белые поля скрываются настройкой области отображения. Браузерный текстовый мост написан в этом репозитории, без дополнительных пакетов.
• FastAPI 0.115.12, AnyIO 4.14.2, Pydantic 2.11.7, Uvicorn 0.34.3, HTTPX 0.28.1, python-dotenv 1.1.1; существующие тесты используют pytest 8.4.1. Лицензии backend. SQLite и сервер предпросмотра используют стандартную библиотеку Python.

Материалы команды

Бизнес-задачи AI Sana от Claude (DOCX) — документ участника команды; источник указан с его слов. Исходный файл сохранён без изменений.