SanaBrief · AI Sana

От идеи бизнеса до понятной задачи, выбранной команды и подтверждённого результата.

SanaBrief — веб-приложение для практического хакатона AI Sana. Оно помогает бизнесу описать задачу, уточнить недостающие сведения и опубликовать карточку с прозрачным рейтингом готовности. Студенческие команды самостоятельно выбирают задачи и предлагают решения, а бизнес решает, с кем продолжать работу.

Главная игровая механика направлена на бизнес: чем полнее подтверждённая карточка, тем выше её рейтинг и позиция в каталоге. Команды получают XP за результат, который проверил бизнес.

Команда DT20: Aldiyar, Abylaikhan, Zhadiger.

Репозиторий: BAITC-Hacks/hack-ddcc8765-dt20.

Возможности

Для бизнеса

• Конструктор из трёх шагов: свободное описание → уточняющие вопросы → редактируемая карточка.
• AI задаёт 3–5 вопросов и помогает собрать карточку; резервный режим предлагает 5 вопросов по шаблонам.
• Все поля ТЗ: название, контекст, потребность, пользователи, данные и доступ к ним, результат, критерии успеха, сроки, ограничения, контакт и взаимодействие.
• Автосохранение, восстановление черновиков, предпросмотр и ручное подтверждение перед публикацией.
• Рейтинг 0–100 с расшифровкой и подсказками, какие сведения добавить.
• Отдельная проверка качества 13 полей с AI: объяснения, какие ответы недостаточно конкретны и как их улучшить.
• Кабинет с задачами, откликами, профилями команд и ручным выбором исполнителей.
• Проверка результата этапа и подтверждение начисления XP.

Для команд

• Общий каталог с поиском, сортировкой по рейтингу и фильтрами по отрасли и готовности.
• Просмотр всех опубликованных задач, включая задачи с низким рейтингом.
• Отклик с идеей решения, планом, сроком и необязательной ссылкой на прототип.
• Кабинет команды с интересами, навыками, технологиями, откликами и XP.
• Отправка результата из кабинета или прямо из карточки задачи.

На страницах используются общие шапка, навигация и подвал. Логотип SanaBrief возвращает в каталог. Переходы из редактора через навигацию дожидаются сохранения.

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

Нужны Node.js 22.15+, npm и современный браузер. Для локального сохранения используется Web Locks: открывайте сайт через localhost, 127.0.0.1 или HTTPS.

git clone https://github.com/BAITC-Hacks/hack-ddcc8765-dt20.git
cd hack-ddcc8765-dt20
npm ci
npm run dev

Откройте http://127.0.0.1:3000. Нажмите «Добавить демопримеры», чтобы заполнить каталог, или «Создать задачу», чтобы пройти сценарий с начала.

Перед запуском проверьте .env.local: для самостоятельной демонстрации без внешних сервисов задайте NEXT_PUBLIC_DATA_MODE=local. Без переменной приложение также выбирает локальный режим, однако в текущем репозитории уже отслеживается конфигурация общего стенда с режимом api. После изменения режима перезапустите приложение. Существующие настройки сохраняйте.

В Windows PowerShell при блокировке npm.ps1 используйте npm.cmd вместо npm.

Режимы работы

Режим	Где хранятся данные	Как работает помощь	Назначение
NEXT_PUBLIC_DATA_MODE=local	localStorage текущего браузера	Прозрачный шаблонный режим, без вызова AI	Запуск без ключей и репетиция на одном устройстве
NEXT_PUBLIC_DATA_MODE=api, AI_MODE=mock	Supabase через сервер приложения	Шаблонный режим	Общий стенд без внешнего AI
NEXT_PUBLIC_DATA_MODE=api, AI_MODE=live	Supabase через сервер приложения	OpenAI; при сбое — явно обозначенный резервный результат	Общий стенд с AI

В локальном режиме данные между устройствами не синхронизируются. Используйте один адрес: localhost и 127.0.0.1 имеют разные браузерные хранилища. Изменение режима не переносит локальные записи в базу автоматически.

В API-режиме ошибка базы не превращается в локальное успешное сохранение: интерфейс сообщает об ошибке и сохраняет введённый текст в форме.

Подключение общего сервера и AI

Серверные обработчики входят в этот же Next.js-проект; отдельное серверное приложение не требуется.

1. Если .env.local ещё нет, создайте его по .env.example.
2. Подготовьте тестовый проект Supabase и выполните supabase/schema.sql в его SQL Editor. Скрипт создаёт таблицы и пять профилей команд.
3. Заполните переменные окружения из таблицы ниже.
4. Перезапустите npm run dev. При изменении публичных переменных перед производственным запуском повторите сборку.
5. В каталоге нажмите «Добавить демопримеры»: в базу добавятся задачи и отклики.

Переменная	Значение и назначение
NEXT_PUBLIC_DATA_MODE	local или api
NEXT_PUBLIC_API_BASE_URL	Оставьте пустым для встроенного API на том же адресе
NEXT_PUBLIC_COLLAB_FIXTURES	По умолчанию 0; 1 включает автоматическое добавление исторических локальных примеров участника №3
SUPABASE_URL	URL проекта Supabase
SUPABASE_SECRET_KEY	Серверный секретный ключ Supabase
AI_MODE	mock для резервного режима, live для внешней модели
OPENAI_API_KEY	Серверный ключ OpenAI, нужен для реального AI
OPENAI_MODEL	Доступная вашему проекту модель с поддержкой Structured Outputs
DEMO_OWNER_ID	Идентификатор общего бизнеса; по умолчанию demo-business
APP_ORIGIN	Публичный HTTPS-адрес стенда или туннеля без пути страницы; для локального запуска можно оставить пустым

Ключи используются только сервером; им нельзя добавлять префикс NEXT_PUBLIC_. В текущей истории репозитория .env.local уже отслеживается, поэтому правило .gitignore не защищает его от дальнейших коммитов. Не переносите этот файл в публичные копии проекта. Перед публичным распространением удалите секреты из распространяемой истории и замените соответствующие ключи.

Страницы и API открываются без логина и пароля, включая производственный режим. Старая переменная DEMO_ACCESS_PASSWORD не используется. http://127.0.0.1:3000/api/health проверяет доступность приложения, но не соединение с базой.

Для HTTPS-туннеля задайте его адрес в APP_ORIGIN, оставьте NEXT_PUBLIC_API_BASE_URL пустым и перезапустите сервер. При смене адреса туннеля обновите APP_ORIGIN.

Подробности настройки и серверных контрактов: docs/BACKEND.md.

Сквозной сценарий

1. Черновик. Бизнес описывает потребность своими словами.
2. Уточнение. Система предлагает вопросы по недостающим сведениям.
3. Карточка. Ответы превращаются в редактируемую структуру; бизнес проверяет и подтверждает её.
4. Рейтинг. Система показывает баллы и конкретные рекомендации по заполнению.
5. Публикация. Подтверждённая задача появляется в каталоге.
6. Предложение. Команда выбирает задачу и отправляет идею, план и срок.
7. Решение бизнеса. Бизнес принимает или отклоняет отклики.
8. Результат. Выбранная команда передаёт результат; после проверки бизнесом получает +10 XP.

Число откликов не ограничивается. Бизнес может выбрать одну, несколько или ни одной команды. Автоматического назначения исполнителей нет.

Рейтинг готовности

Рейтинг относится к конкретной задаче. Официальные баллы начисляются за поля, которые заполнил и подтвердил бизнес.

Группа	Максимум	Начисление
Контекст и потребность	20	Контекст — 10, потребность — 10
Данные и материалы	20	Описание данных — 10, источник или доступ — 10
Ожидаемый результат	15	Результат работы команды — 15
Критерии успеха	15	Показатель или проверка — 10, условие приёмки — 5
Ограничения	10	Срок — 5, границы работы — 5
Пользователи	10	Описание пользователей — 10
Связь с бизнесом	10	Контакт — 5, консультации — 3, обратная связь — 2
Итого	100

Баллы	Уровень	Поведение в каталоге
0–39	Черновик / требует уточнения	Опубликованная задача видна; отклики разрешены
40–69	Рабочая задача	Доступна всем командам
70–89	Готова к работе	Выше менее заполненных задач
90–100	Приоритетная задача	Верхние позиции благодаря высокому рейтингу; заметная отметка уровня

Каталог сортируется по убыванию подтверждённого рейтинга, затем по дате публикации. При равенстве используется ID задачи для устойчивого порядка. Публикация возможна при любом рейтинге, включая 0: нужны название и подтверждение актуальной карточки.

Черновик и публикация разделены. Во время редактирования меняется предварительная оценка. Опубликованный текст, официальный рейтинг и позиция обновляются после ручного подтверждения. Неопубликованный черновик в каталог не попадает; уровень готовности «черновик» сам по себе публикацию не запрещает.

Пустые поля, распространённые заглушки, бессмысленные повторы и неподходящие числовые ответы не приносят баллов; у контакта проверяется формат. Числовое условие приёмки допустимо вместе с описанной метрикой. Базовая формула находится в src/lib/scoring.ts.

Кнопка «Проверить качество с ИИ» дополнительно оценивает смысл и конкретность 13 полей. Модель возвращает решение по каждому полю, причину и совет; фиксированные веса и арифметику применяет код в src/lib/quality.ts. AI не может начислить баллы поверх базовых правил. Редактирование делает прежнюю проверку недействительной; подтверждение использует проверку точной текущей версии. Оценка готовности не является гарантией достоверности сведений или успешности будущего решения.

AI и резервный режим

AI используется для уточняющих вопросов, структурирования карточки и проверки качества заполнения. Модель не назначает числовой рейтинг, не публикует задачу и не выбирает команду.

Операция	Вход	Выход API
POST /api/ai/questions	rawText, industry, content	questions с полями id, field, text, необязательным hint; source
POST /api/ai/card	rawText, industry, content, questions, answers	content, source; для успешного AI-ответа также evidence
POST /api/ai/quality	content, industry	QualityReview: 13 решений accepted, reason, suggestion, источник и сведения о проверяемой версии

content содержит 14 полей карточки. source принимает ai или fallback, чтобы интерфейс отличал ответ модели от резервного результата. Полные схемы входа и выхода определены в src/lib/contracts.ts и src/lib/server/ai.ts.

Промпты находятся в src/lib/server/prompts.ts, формат обращения — в src/lib/server/model.ts. Используются Responses API, Structured Outputs и store: false. Инструкции запрещают придумывать факты и требуют цитаты-основания: значение поля должно быть фрагментом цитаты, а цитата — фрагментом исходного ввода. Сервер проверяет структуру и происхождение текста; правильность его отнесения к полю проверяет человек.

Таймаут попытки — 18 секунд, максимум две попытки; клиент ожидает AI-операцию до 45 секунд. Если ключ или модель не настроены, включён mock, внешний сервис недоступен либо ответ не прошёл проверку, возвращается fallback. Резервный алгоритм выбирает вопросы по незаполненным полям, переносит ответы без новых фактов и проверяет заполненность, формат и повторы. Он не обещает смысловую точность AI. Такая замена допускается ТЗ хакатона.

Демоданные и XP

Кнопка «Добавить демопримеры» загружает синтетический набор:

• 5 отдельных черновиков разной полноты;
• 5 опубликованных карточек четырёх уровней готовности;
• 5 профилей команд с интересами, навыками и технологиями;
• 5 откликов, включая два предложения на одну задачу и один принятый отклик с результатом для проверки.

Основной набор находится в src/lib/demo-data.ts. Повторное добавление не перезаписывает правки и решения. Ссылки example.com служат примерами, а не настоящими прототипами.

В локальном кабинете бизнеса есть «Сбросить демопримеры» с подтверждением и «Отменить последний сброс». Перед сбросом создаётся резервная копия. Собственные задачи и отклики сохраняются. Старый формат браузерных откликов поддерживается с сохранением результатов и XP.

Команда получает 10 XP за каждый подтверждённый этап. Отправка отклика или выбор команды сами по себе баллов не дают. Результат можно передать только по принятому отклику; повторное подтверждение не увеличивает XP. После подтверждения изменение результата и смена решения заблокированы.

Страницы

Адрес	Назначение
/	Переход в каталог
/catalog	Поиск, фильтры и опубликованные задачи
/tasks/new	Создание задачи
/tasks/[id]/edit	Редактирование и подтверждение карточки
/tasks/[id]	Публичная карточка, отправка отклика и собственные предложения
/business	Задачи бизнеса, выбор команд и подтверждение результатов
/student	Профиль команды, отклики, результаты и XP

[id] в адресе заменяется идентификатором задачи.

Стек и архитектура

Часть	Технологии
Интерфейс	Next.js 16 App Router, React 19, TypeScript
Оформление и компоненты	CSS, Tailwind CSS 4, Radix Dialog, Lucide
Валидация	Zod
Сервер	Обработчики Next.js, Node.js
Хранилище	localStorage для локального режима; Supabase PostgreSQL для общего стенда
AI	OpenAI SDK, Responses API, Structured Outputs
Проверки	Vitest, TypeScript, производственная сборка Next.js

Точные версии зафиксированы в package-lock.json. Интерфейс обращается к адаптерам gateway и collaborationGateway; те выбирают браузерное хранилище или HTTP. Правила каталога, решений и XP объединены в TaskService. Сервер повторно валидирует запросы и вычисляет официальный рейтинг.

В базе три сущности: tasks — задачи с черновиком и подтверждённой версией; teams — профили команд; proposals — предложения, решения и результаты. Версии записей защищают от незаметной перезаписи конкурентных изменений. При конфликте редактор предлагает сохранить правки отдельной копией.

src/app/                       страницы, общие стили и API
src/app/api/[...path]/route.ts  HTTP-обработчики
src/components/app-chrome.tsx  общие шапка, навигация и подвал
src/components/builder/        конструктор бизнес-задачи
src/components/platform/       каталог, кабинеты, отклики и результаты
src/lib/contracts.ts           схемы карточки, вопросов и рейтинга
src/lib/collaboration-contracts.ts  схемы команд и предложений
src/lib/gateway.ts             сохранение и помощь в редакторе
src/lib/collaboration-gateway.ts    каталог, отклики, решения и демоданные
src/lib/task-service.ts        общие бизнес-правила
src/lib/task-state.ts          подтверждение и публикация
src/lib/scoring.ts             расчёт рейтинга
src/lib/quality.ts             проверка допустимости баллов за поля
src/lib/quality-contracts.ts   контракт проверки качества
src/lib/assistance.ts          резервные вопросы и карточка
src/lib/demo-data.ts           основной синтетический набор
src/lib/server/                база, AI и проверка HTTP-запросов
supabase/schema.sql            таблицы и профили команд
scripts/smoke-backend.mjs       проверка настроенного серверного стенда
scripts/check-ai.mjs            проверка вопросов, карточки и качества через API
scripts/seed-demo.mjs           загрузка примеров через API
tests/                         автоматические проверки
docs/                          настройка, контракты и демонстрация

Проверки и сборка

npm run typecheck
npm test
npm run build

Тесты покрывают рейтинг и его границы, AI-проверку качества и сброс устаревшей проверки, публикацию при 0 баллов, независимость черновика от публичной версии, несколько выбранных команд, начисление XP, неверные AI-ответы, конфликты сохранения, ошибки хранилища, совместимость старых откликов и восстановление демопримеров. Текущее количество и результаты показывает npm test.

Автоматические тесты используют тестовые хранилища и подмены внешних сервисов. Они не подтверждают доступность конкретной базы или оплату и доступность внешней модели.

На запущенном приложении с настроенными .env.local и тестовой базой можно отдельно проверить серверный сценарий:

npm run seed:demo
npm run smoke:backend
npm run check:ai -- --expect=ai

seed:demo добавляет примеры без перезаписи существующих записей. smoke:backend создаёт временную задачу и три отклика, проверяет HTTP-сценарий и пытается удалить только свои записи. В режиме live подтверждение и проверка задачи могут вызывать модель. check:ai проверяет вопросы, карточку и качество, включая отсутствие выдуманных сведений; для сервера с AI_MODE=mock используйте --expect=fallback. Живые проверки используют синтетические данные и могут расходовать средства API.

После успешной сборки приложение запускается командой:

npm start

Пароль для запуска и доступа к API не требуется. В режиме разработки круглый значок N — штатная панель Next.js с английским меню; это не элемент пользовательского сценария SanaBrief.

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

Время	Что показать
0:00–0:40	Слабое описание задачи пекарни и уточняющие вопросы
0:40–2:00	Редактирование карточки, рост рейтинга, подтверждение и публикацию
2:00–2:40	Позицию в каталоге, фильтры и доступность задачи с низкой оценкой
2:40–3:20	Выбор задачи командой и отправку предложения
3:20–4:00	Сравнение предложений и ручное решение бизнеса
4:00–5:00	Отправку результата, подтверждение бизнесом, +10 XP и сохранность после обновления

Для наглядного роста 35 → 80 → 100 начните с названия, контекста, потребности и результата — 35. Добавьте данные и доступ (+20), показатель и условие приёмки (+15), срок и ограничения (+10) — 80. Добавьте пользователей (+10), контакт (+5), консультации (+3), обратную связь (+2) — 100. Подтверждайте изменения, чтобы обновлялась позиция в каталоге.

Подготовленный пример и подробный порядок показа: docs/DEMO.md.

Границы MVP

Это хакатонный MVP с общим демонстрационным бизнесом и выбором подготовленных команд. Переключение кабинетов не является индивидуальной авторизацией: на общем стенде участники могут разыгрывать обе роли. Перед публичным использованием с реальными данными потребуются отдельные учётные записи и права доступа.

Регистрация, восстановление паролей, чат, уведомления, календарь, загрузка файлов и полноценный проектный трекер не входят в обязательный объём ТЗ. Персональные рекомендации задач также не обязательны и не реализованы.

Рейтинг проверяет готовность описания, а не качество будущего решения; AI-результат требует проверки человеком. Работа общего стенда зависит от настроенной базы и окружения. Локальный режим позволяет показать весь сценарий без этих зависимостей.

Дополнительная документация

• Настройка сервера, AI и список API-маршрутов.
• Контракты редактора и правила сохранения.
• Контракты каталога, команд и откликов.
• Сценарий защиты.
• Исторический отчёт участника №3 с примечанием о слиянии.