FORGE — ясная бизнес-задача для команды

FORGE — веб-платформа для практического хакатона AI Sana. Она помогает бизнесу превратить свободное описание проблемы в проверяемое задание, а командам — понять исходные данные, ожидаемый результат и критерии приёмки до старта работы. Организаторы получают панель для управления ролями и наблюдения за активностью. Это рабочее приложение с аккаунтами и сохранением данных, а не набор демо-экранов.

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

• Публичный лендинг с адаптивной навигацией, орбитальной анимацией этапов вокруг знака FORGE, плавным появлением секций и поддержкой prefers-reduced-motion. Основная палитра — чёрный, серый и белый; тёплый акцент используется только в основных кнопках. Восемь разных монохромных иллюстраций распределены по отдельным разделам без повторов.
• Регистрация и вход для бизнеса и команд; возврат на лендинг с обоих экранов. Администратора нельзя выбрать при регистрации. Сессии, права доступа и проверка владельца выполняются сервером.
• Кабинет бизнеса: черновики, уточняющие вопросы, редактирование карточки, Task Pack, Handoff Test, публикация и ручное рассмотрение предложений.
• Разбор исходного текста и интервью с помощью OpenAI при наличии ключа. Предположения модели сопровождаются цитатой из исходного текста и не считаются подтверждёнными, пока их не проверит автор. Без ключа доступны честно обозначенные вопросы по правилам.
• Readiness Compiler: воспроизводимая оценка до 100 баллов только по подтверждённым сведениям, коды ошибок и предупреждений, конкретный следующий шаг. Низкий балл не скрывает задачу и не запрещает публикацию: замечания остаются видны командам.
• Task Pack из семи секций, источник и статус каждого пункта, история ответов, версия пакета. Handoff Test проверяет пять условий передачи по правилам; при наличии OpenAI-ключа дополнительная рецензия может выявить неоднозначность, но не улучшить правиловую оценку или выбрать команду.
• Отдельная Тест-лаборатория NVIDIA NIM предлагает три проверочных сценария: основной, пограничный и сбойный. Используются только подтверждённые пункты Task Pack; нужны подтверждённые проблема и ожидаемый результат. Это черновые гипотезы, а не факты: бизнес подтверждает каждый сценарий отдельно, и только после этого он виден командам. Изменение задания сбрасывает старые сценарии.
• Каталог опубликованных задач с поиском и фильтрами, карточка с открытыми замечаниями, профиль команды, предложение с идеей, планом, сроком, необязательной ссылкой на прототип и вопросами заказчику. Бизнес сам принимает, отклоняет или откладывает предложения; подтверждённый этап начисляет команде баллы.
• Администратор видит обычное рабочее пространство, каталог и все предложения (чужие решения — только для просмотра); отдельный пункт сайдбара открывает админ-панель. Можно создавать и редактировать свои задачи, назначать роли, смотреть сводку, журнал изменений ролей и журнал AI-вызовов с провайдером, моделью, токенами и локальной оценкой затрат.

Основной сценарий

1. Бизнес создаёт аккаунт и описывает проблему своими словами. Черновик сохраняется в SQLite при локальном запуске или в Turso на Vercel.
2. OpenAI, если ключ настроен, предлагает поля и уточняющие вопросы. Автор сверяет предложения с источником, отвечает и подтверждает факты. Без OpenAI этот шаг использует вопросы по правилам.
3. Компилятор показывает полноту и пробелы. Автор дополняет Task Pack: данные, результат, критерии приёмки, контакт, ограничения и порядок взаимодействия.
4. Handoff Test проверяет, сможет ли независимая команда начать работу. При настроенном OpenAI-ключе модель дополнительно проверяет ясность; при недоступности модели правила продолжают работать.
5. Если настроен NVIDIA-ключ, автор запускает Тест-лабораторию, проверяет три предложенных сценария и подтверждает подходящие. Они дополняют, но не заменяют Task Pack и Handoff Test.
6. После публикации команда находит задачу, читает подтверждённый пакет и сценарии, отправляет предложение. Владелец задачи сравнивает подходы и принимает решение вручную.

Оценка, AI и границы доверия

Официальный балл рассчитывается на сервере без модели. Контекст и потребность дают до 20 баллов, данные — 20, результат — 15, критерии успеха — 15, ограничения — 10, пользователи — 10, связь с бизнесом — 10. Ошибки E01–E07, предупреждения W02–W07 и статус сборки отражают полноту постановки, а не вероятность успеха проекта.

Handoff Test задаёт пять вопросов: ясна ли проблема, указаны ли пользователи, доступны ли данные, определён ли результат и понятна ли приёмка. Сначала вычисляются правила. OpenAI, если настроен, анализирует подтверждённую карточку; критическое замечание может понизить отдельную проверку. Тест-лаборатория NVIDIA решает другую задачу — предлагает возможные проверки приёмки. Оба AI-потока не читают историю интервью, неподтверждённые подсказки и чужие черновики. Результаты AI — рекомендации, не автоматическое решение о победителе.

Технологии и архитектура

Слой	Стек	Ответственность
Клиент	Nuxt 4, Vue 3, JavaScript, CSS	Лендинг, кабинеты, редактор, каталог, админ-панель
Сервер	Python, FastAPI, Pydantic	Авторизация, API, права, оркестрация AI
Хранение	SQLite локально; Turso/libSQL на Vercel	Пользователи, сессии, задачи, ответы, команды, предложения, журнал ролей и AI-токенов
AI	OpenAI Responses API, NVIDIA NIM Chat Completions	OpenAI: разбор, интервью, Handoff-рецензия; NVIDIA: сценарии Тест-лаборатории

Маршруты FastAPI — backend/main.py; точка входа Vercel Python Function — api/index.py. Правила и оценка — backend/domain.py и backend/compiler.py; AI-вызовы, проверка формы ответов и журнал токенов — backend/ai.py; схема, небольшие миграции и выбор локальной/удалённой базы — backend/storage.py. Главный пользовательский поток — app/pages/index.vue, панели — app/components/. Тёмная тема и движение — app/assets/rebrand.css, landing.css, motion.css. Символ на основе предоставленного референса — public/forge-mark.svg; он же используется в навигации, анимации, входе и favicon. Декоративные фотографии — отдельные WebP в public/.

Браузер обращается к FastAPI, но не получает API-ключи. Они читаются только сервером из .env. NVIDIA NIM используется через OpenAI-совместимый endpoint, но с собственным ключом и отдельной моделью. Сервер проверяет, что ответ содержит ровно три различных типа сценариев и заполненные поля. Неподтверждённые сценарии скрыты от команд на уровне API. Все выводы могут ошибаться — подтверждение сведений и выбор команды остаются за людьми.

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

Нужны Node.js 22+, npm и Python 3.10+. Из корня проекта:

npm install
python3 -m venv .venv
.venv/bin/pip install -r backend/requirements.txt
cp -n .env.example .env

Откройте .env и задайте нужные значения:

OPENAI_API_KEY=ваш_ключ_openai
OPENAI_MODEL=gpt-4.1-mini
NVIDIA_API_KEY=ваш_ключ_nvidia
NVIDIA_MODEL=meta/llama-3.3-70b-instruct

Можно настроить один ключ, оба или ни одного: основной поток задач работает без внешнего AI. Если меняете .env, перезапустите FastAPI. Не размещайте ключи в NUXT_PUBLIC_*, Git или браузере. Доступ к NVIDIA NIM и конкретной модели должен быть разрешён вашему NVIDIA-аккаунту; если модель не доступна, замените NVIDIA_MODEL на разрешённую в вашей консоли.

Для назначения первого администратора создайте случайный ADMIN_BOOTSTRAP_TOKEN длиной не менее 24 символов, например:

python3 -c 'import secrets; print(secrets.token_urlsafe(32))'

Вставьте значение в .env, перезапустите API, зарегистрируйте отдельный аккаунт бизнеса или команды и в появившемся баннере введите секрет. После назначения первого админа повторно использовать bootstrap нельзя; дальше роли выдаются в админ-панели. Последнего администратора понизить нельзя. Админ сохраняет доступ к рабочему пространству и может управлять только собственными задачами; решения по чужим предложениям остаются за их владельцами.

Запуск одним терминалом:

npm run dev:all

Или в двух терминалах:

.venv/bin/uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

npm run dev -- --host 127.0.0.1 --port 3000

Сайт: http://127.0.0.1:3000/. Документация API: http://127.0.0.1:8000/docs. Путь к локальному файлу базы задаётся DATABASE_PATH (по умолчанию .data/forge-live.db). Запуск создаёт отсутствующие таблицы и добавляет новые колонки без очистки существующих данных. Если заданы TURSO_DATABASE_URL и TURSO_AUTH_TOKEN, сервер использует Turso вместо локального файла; на Vercel постоянная база обязательна.

Развёртывание на Vercel

Код рассчитан на один проект Vercel: Nuxt обслуживает сайт, а api/index.py экспортирует FastAPI как Python Function на /api/*. Правило в vercel.json направляет запросы /api/* в эту функцию до fallback-маршрута Nuxt. Фронтенд обращается к API по тому же домену. Корень проекта — .; фреймворк — Nuxt; команды сборки и установки определяются Vercel автоматически. В корне есть requirements.txt для Python Function. .vercelignore исключает локальные .env, базы, виртуальное окружение, тесты, служебные файлы CLI и артефакты сборки из загрузки.

1. Войдите в Vercel CLI (npx --yes vercel@latest login) и из корня проекта выполните npx --yes vercel@latest link. Укажите существующий проект либо создайте новый.
2. В Vercel Marketplace подключите Turso к этому проекту на тарифе Starter или другом выбранном вами тарифе. Интеграция добавляет серверные TURSO_DATABASE_URL и TURSO_AUTH_TOKEN для Production, Preview и Development. Не переносите эти секреты в NUXT_PUBLIC_* и не коммитьте их.
3. В Project Settings → Environment Variables при необходимости добавьте OPENAI_API_KEY, OPENAI_MODEL, NVIDIA_API_KEY, NVIDIA_MODEL, ADMIN_BOOTSTRAP_TOKEN. AI-ключи необязательны для аккаунтов, задач и правиловой проверки; после добавления переменных нужно создать новый деплой. Для первого администратора задайте случайный ADMIN_BOOTSTRAP_TOKEN длиной от 24 символов и сохраните его в безопасном месте.
4. Выполните npx --yes vercel@latest deploy для проверки, затем npx --yes vercel@latest deploy --prod для production. Проверьте /api/health, регистрацию двух ролей и сохранение задач между перезагрузками. Если вы подключите Git-репозиторий в настройках проекта, дальнейшие деплои можно запускать автоматически при push; текущая CLI-привязка сама по себе Git-интеграцию не создаёт.

Локальный .env в Vercel не переносится. Секреты вводятся только в настройках Vercel; Turso-секреты создаются интеграцией. После изменения значений в Vercel нужно повторить деплой.

Как проверить: сценарий для жюри

1. Откройте лендинг, проверьте движение карточек 01/02/03 вокруг FORGE, прокрутите секции и убедитесь, что «На главную» работает со входа и регистрации. В системном режиме уменьшения анимации постоянное движение отключается.
2. Зарегистрируйте бизнес и создайте задачу из текста: «Мы получаем обращения клиентов из нескольких каналов. Операторы распределяют их вручную и теряют время. Нужен прототип, который поможет сортировать обращения». Проверьте сохранённый черновик, пробелы в оценке и вопросы. При OpenAI-ключе проверьте предложения с цитатами и подтвердите только верные сведения.
3. Заполните Task Pack, подтвердите проблему и ожидаемый результат, запустите Handoff Test. Без OpenAI-ключа он выполнит правиловую проверку. При NVIDIA-ключе нажмите «Создать сценарии» в Тест-лаборатории: проверьте основной, пограничный и сбойный сценарии, подтвердите один из них. Неподтверждённые остаются личным черновиком. Опубликуйте задачу.
4. Зарегистрируйте команду, найдите задачу в каталоге: виден только подтверждённый сценарий. Изучите замечания и отправьте предложение с планом и сроком. Вернитесь в бизнес-аккаунт и примите/отклоните его вручную. Измените подтверждённое поле задания — старые сценарии исчезнут до новой генерации.
5. Назначьте администратора, откройте обычный каталог, затем «Админ-панель» в сайдбаре. Проверьте пользователей, роли, журнал ролей и AI-токены. В журнале NVIDIA отмечена как операция «Тест-лаборатория». Админ может просматривать чужие предложения, но не подтверждать за чужой бизнес этапы.

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

.venv/bin/python -m unittest discover -s backend/tests -v
npm run build

Основные тесты используют отдельную временную SQLite-базу и моки AI, поэтому не расходуют API-квоту и не трогают рабочие записи. Дополнительный тест совместимости libSQL использует временную локальную базу и запускается только если пакет libsql установлен (.venv/bin/pip install -r requirements.txt).

Данные, интеграции и расходы

Пользователи, задания и предложения создаются самими людьми; стартовых демо-записей нет. Внешние сервисы используются только при заданных ключах: OpenAI для структурирования текста/интервью/Handoff, NVIDIA NIM для Тест-лаборатории. NVIDIA получает только подтверждённые поля текущего Task Pack, не персональные данные аккаунтов. AI-журнал хранит фактические токены, возвращённые провайдерами, и статус вызова. Для gpt-4.1-mini стоимость считается локально по тарифу $0.40 / $0.10 кэш / $1.60 за 1 млн токенов (официальная страница модели); для другой OpenAI-модели тариф можно задать через OPENAI_INPUT_USD_PER_MILLION, OPENAI_CACHED_INPUT_USD_PER_MILLION, OPENAI_OUTPUT_USD_PER_MILLION. Стоимость NVIDIA сейчас не оценивается, потому что тариф зависит от вашего доступа; её токены считаются, но не прибавляются к денежной сумме. Это не официальный биллинг аккаунта.

Восемь новых изображений forge-admin-operations.webp, forge-brief-detail.webp, forge-auth-studio.webp, forge-business-dialogue.webp, forge-team-prototype.webp, forge-admin-board.webp, forge-workspace-brief.webp, forge-catalog-team.webp созданы встроенным генератором изображений и оптимизированы в WebP. Каждое используется в отдельном контексте; карточки динамических задач не получают повторяющийся фон. Изображения декоративные и не содержат пользовательских данных.

Известные ограничения

• Для публичного продакшена нужны подтверждение почты, восстановление пароля, ограничение частоты запросов и мониторинг. Текущая версия рассчитана на пилотный запуск; не загружайте чувствительные данные без дополнительного аудита безопасности. HTTPS на Vercel предоставляет платформа.
• Turso обеспечивает постоянное хранение на Vercel, но текущие миграции выполняются при старте приложения; перед крупными изменениями схемы и высокой нагрузкой потребуются управляемые миграции и нагрузочное тестирование. Локальная SQLite-база не переносится в Turso автоматически.
• Handoff Test проверяет полноту и ясность входных сведений, но не качество будущего решения. AI-ответы могут быть неверными или недоступными из-за лимитов/сети; в этом случае остаются детерминированные правила.
• Тест-лаборатория требует NVIDIA-ключ и доступ к выбранной модели. Её сценарии не являются автоматическими тестами или договорными критериями приёмки; заказчик должен проверить их и уточнить открытые вопросы. В текущей версии сценарии можно подтвердить/скрыть, но не редактировать по отдельности — для изменений нужно обновить Task Pack и создать их заново.
• AI-журнал содержит только новые вызовы после включения учёта. Если провайдер не вернул usage или тариф неизвестен, денежная стоимость вызова остаётся неизвестной.
• Автоматический деплой из Git пока не настроен; текущая версия загружена через Vercel CLI.

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

https://forge-ai-sana.vercel.app — production на Vercel с постоянной базой Turso Starter. Проверены ответы главной страницы и /api/health (200), а также запрос входа к Turso (ожидаемый 401 для несуществующего пользователя). OpenAI/NVIDIA-ключи и ADMIN_BOOTSTRAP_TOKEN в Vercel пока не заданы: AI-операции и назначение первого администратора станут доступны после добавления соответствующих секретов и нового деплоя.