Sana Quest

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

Проект команды LEXUS для кейса AI Sana Challenge Hub на хакатоне HackAlem AI.

Sana Quest помогает заказчику превратить краткое описание потребности в задачу с понятным результатом, исходными данными и критериями приёмки. ИИ задаёт уточняющие вопросы и помогает подготовить карточку, а заказчик проверяет и подтверждает её содержание. Студенческие команды находят задачи в открытом каталоге и предлагают решения. Заказчик выбирает исполнителей, принимает выполненную работу и оставляет отзыв.

Демо · Запуск · Тестовые аккаунты · Сценарий проверки · Критерии оценки · Ошибки

Доступ к приложению

Посмотреть пример видео по задаче

В демо можно пройти путь от создания потребности до приёмки результата: зарегистрироваться, подготовить и опубликовать задачу, отправить отклик, согласовать изменения и оставить отзыв команде. Для проверки ролей подготовлены девять тестовых аккаунтов, включая администратора. Пример видео создан по утверждённой задаче «Карта доступного города»; длительность — 30 секунд, без озвучивания.

Онлайн-демо использует отдельную базу, локального помощника и видеорендер без голоса. OpenAI и ElevenLabs подключаются в локальной версии через API-ключи; результаты их проверки приведены в отчёте.

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

Назначение и преимущества

Платформа решает две связанные проблемы: бизнесу сложно сформулировать задачу для команды, а студентам — оценить, достаточно ли информации для начала работы. Рейтинг готовности показывает полноту согласованного описания и помогает заказчику последовательно его улучшать.

Возможность	Польза для заказчика и команды
Уточнение по одному вопросу	Заказчик отвечает последовательно, видит прогресс и может вернуться к предыдущему ответу
Объяснимый рейтинг готовности	Видно, какие разделы подтверждены, сколько баллов они дают и чего не хватает
Публикация неполной задачи	Заказчик может начать с краткой потребности; низкая готовность не закрывает доступ к откликам
Версии и согласование изменений	Команда видит прежние и новые условия и подтверждает актуальность своего предложения
Текст, аудио и видео	Пользователь выбирает удобный способ описания и изучения задачи
Отзывы по выполненным работам	Репутация команды формируется после сдачи результата конкретному заказчику
Дополнительные возможности Pro	Генерация обложек и видео доступна по тарифу; покупка тарифа не повышает рейтинг задачи

Преимущество решения — объединение этих возможностей в одном процессе: от уточнения потребности до приёмки результата. Эффективность на реальных пользователях ещё предстоит оценить в пилоте. Предлагаемые метрики: время до согласованной публикации, доля задач с данными и критериями приёмки, доля актуальных откликов после изменения условий и доля принятых результатов.

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

Требования

• Docker Engine или Docker Desktop с запущенным Docker daemon.
• Docker Compose 2.24 или новее.
• Доступ к репозиторию организаторов и интернет для первой сборки.
• Свободные локальные порты 8080 и 5434.

Для сборки и видеорендера рекомендуются 4 CPU, 8 ГБ оперативной памяти, выделенной Docker, и около 10 ГБ свободного диска. Это рекомендуемая конфигурация; минимальные ресурсы отдельно не измерялись. Проверенная среда — macOS ARM64 с Docker Desktop.

Команды

git clone [email protected]:BAITC-Hacks/hack-654d40a5-lexus.git
cd hack-654d40a5-lexus
docker compose up --build -d

Если репозиторий уже открыт, выполните последнюю команду в его корне. Dockerfile устанавливает зависимости приложения, Chromium, FFmpeg, Poppler и шрифты. Go и Node.js на компьютере проверяющего для этого способа запуска не нужны.

Откройте http://localhost:8080 и проверьте состояние сервисов:

docker compose ps
curl http://localhost:8080/api/health

Ожидаемый результат: сервисы app и db имеют статус healthy, API возвращает {"status":"ok"}. Первая сборка занимает больше времени из-за загрузки образов и зависимостей. Порт 8080 используется приложением, 5434 — PostgreSQL; оба доступны только через 127.0.0.1.

Основной сценарий можно проверить без внешних API-ключей и личных аккаунтов участников. В этом режиме доступны локальный помощник, публикация задач, отклики, выбор команды, отзывы, файлы и видео без озвучивания. Реальные AI-запросы и распознавание аудио подключаются отдельно, как описано в разделе ИИ и внешние сервисы.

При первом запуске создаются 5 опубликованных задач, 5 черновиков, 5 команд и 5 откликов. Все начальные данные синтетические. Задачи, аккаунты и медиа сохраняются в Docker volumes между перезапусками.

docker compose down               # остановить с сохранением данных
docker compose up -d              # запустить снова
docker compose up --build -d      # обновить после изменения кода

Команда docker compose down -v удаляет volumes вместе с локальной базой и медиа. Для обычного обновления или перезапуска она не требуется.

Тестовые аккаунты для жюри

Это специально созданные тестовые учётные записи для проверки MVP, включая управление ролями и тарифами. Они не принадлежат реальным заказчикам или студентам. Адреса используются как логины; доступ к почтовым ящикам и подтверждение письмом не нужны.

Общий пароль всех аккаунтов в таблице: Pass1234!. Для входа нажмите «Войти» в правом верхнем углу приложения.

Логин	Роль и начальный тариф	Что можно проверить
[email protected]	Администратор	Список пользователей, назначение ролей, выдача и отзыв Pro, история изменений доступа
[email скрыт]	Заказчик · Free	Создание новой задачи, помощник, публикация, загрузка своего фото и файлов
[email скрыт]	Заказчик · Pro · Green Step	Генерация обложки при подключённом OpenAI и персонального видео
[email скрыт]	Заказчик · Free · Alem Coffee	Работа с подготовленными задачами и черновиками, приём откликов и оценка результатов
[email скрыт]	Студент · Free · Pixel Pioneers	Просмотр каталога, отклик на задачу, подтверждение новых условий и сдача результата
[email скрыт]	Студент · Free · Qadam Lab	Отклик второй команды и сравнение предложений у заказчика
[email скрыт]	Студент · Free · Nomad Code	Проверка независимого доступа другой команды
[email скрыт]	Студент · Free · Data Nomads	Работа с задачами от имени команды аналитиков
[email скрыт]	Студент · Free · Alem Makers	Дополнительный профиль для проверки каталога и откликов

В таблице указаны роли и тарифы на новой базе. Изменения, сделанные администратором во время проверки, сохраняются. Перезапуск приложения не возвращает тарифы и пароли к исходным значениям.

Проверка администратора

1. Войдите как [email protected]. Откроется раздел «Пользователи и доступ»; он также доступен по адресу http://localhost:8080/#admin.
2. Найдите [email скрыт], выберите тариф Pro и нажмите «Сохранить доступ».
3. В другом браузере или приватном окне войдите как [email скрыт] и проверьте доступ к функциям Pro. Для генерации обложки нужен настроенный OpenAI API; видео без голоса работает локально.
4. Верните пользователю тариф Free. В истории изменений доступа появятся обе операции. Рейтинг его задач от смены тарифа не меняется.
5. Для проверки смены роли зарегистрируйте отдельный тестовый аккаунт и завершите заполнение профиля. Пока у него нет задач и откликов, администратор может изменить его роль. Смена роли пользователя с уже созданными задачами или откликами ограничена, чтобы сохранить связи с работами. Администратор не может снять собственную роль.

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

Регистрация нового пользователя проходит в три этапа: почта и пароль с подтверждением → выбор «Ученик или студент» / «Заказчик или бизнес» → заполнение профиля. Студент создаёт профиль команды; заказчик указывает организацию или проект. Роль администратора при регистрации выбрать нельзя.

Параметр SEED_PASSWORD задаёт другой пароль тестовых аккаунтов до их первого создания. В compose.yaml параметр SEED_ACCOUNTS: "true" включает их создание. Значение "false" отключает создание отсутствующих тестовых аккаунтов, но не удаляет существующие записи или начальные задачи. Общий тестовый пароль предназначен для демонстрации; для работы с реальными данными нужны индивидуальные учётные записи.

Реализованные возможности

• Конструктор задачи: свободное описание, 3–7 уточняющих вопросов, один вопрос на экране, текстовый или голосовой ответ, прогресс, редактирование и согласование карточки. Локальный помощник задаёт семь заранее подготовленных вопросов.
• Каталог задач: поиск, фильтры по направлению и готовности, сортировка по рейтингу и новизне, сопоставление с навыками команды. Задача с нулевым баллом остаётся доступной для отклика.
• Работа с командами: идея решения, план, срок, ссылка на прототип, вложения; ручной выбор исполнителей; подтверждение этапа, сдача результата и отзыв заказчика.
• Каталог команд: описание, навыки, учебное заведение, уровень, очки опыта, завершённые работы и оценки заказчиков.
• История изменений: неизменяемые опубликованные версии, сравнение «было / стало», уведомления, рекомендации по обновлению плана и повторное согласование отклика.
• Аудио: запись с микрофона или загрузка файла, распознавание, редактирование транскрипта перед использованием, озвучивание текста по запросу пользователя.
• Обложки: загрузка JPEG/PNG до 8 МБ; генерация по содержанию задачи для Pro с предпросмотром и подтверждением.
• Вложения: до 5 файлов по 20 МБ в задачу, отклик и финальную сдачу. Поддерживаются PDF, DOCX, XLSX, CSV, TXT, PNG, JPG и ZIP. Файлы черновика приватны; материалы задачи становятся доступны после публикации; файлы отклика доступны его автору и заказчику.
• Видео: сценарий из утверждённой задачи, раскадровка, пробный ролик до 30 секунд, согласование, полный MP4 и субтитры VTT. Доступно на тарифе Pro.
• Доступность: управление клавиатурой, подписи полей, увеличенный текст, повышенный контраст, уменьшение анимации и адаптивная вёрстка.
• Администрирование: управление ролями и тарифами, история изменений доступа. Онлайн-оплата не подключена.

Текущий интерфейс и новая генерация работают на русском языке. В коде сохранены словари казахского и английского для дальнейшего развития; переключение языка в этой версии отключено. Ранее сохранённые материалы автоматически не переводятся.

Как проверить основной сценарий

Для демонстрации подготовьте два окна: заказчик [email скрыт] и студент [email скрыт]. Общий пароль — [скрыто]. Сценарий защиты с хронометражем рассчитан на 4 минуты 40 секунд после предварительной подготовки.

1. Создайте потребность. От имени заказчика введите: «Вечером в кофейне остаётся выпечка. Хотим понять, сколько готовить». Нажмите «Помочь сформулировать», пройдите вопросы и соберите карточку. Неизвестные сведения можно пропустить. В интерфейсе указан источник ответа: OpenAI или локальный помощник.
2. Опубликуйте неполную задачу. Укажите название и подтвердите потребность, оставив остальные разделы незаполненными. Просмотрите карточку и подтвердите публикацию. Она появится в каталоге с готовностью 0/100.
3. Отправьте отклик. Войдите как студент, откройте эту задачу и заполните идею, план, срок и ссылку https://example.org/prototype.
4. Уточните условия. Вернитесь к заказчику, заполните все разделы по примеру ниже и подтвердите каждый из них. Опубликуйте новую версию. Готовность станет 100/100; на странице доступна расшифровка баллов.
5. Согласуйте изменения. Студент получает уведомление, просматривает сравнение версий и подтверждает актуальность отклика. Заказчик вручную принимает предложение. Принятие отклика по устаревшим неподтверждённым условиям блокируется.
6. Завершите работу. Заказчик подтверждает этап, студент отправляет результат, заказчик принимает его и оставляет оценку. Команда получает 50 + 150 XP, а отзыв появляется в её профиле. Повторное начисление за тот же этап и повторный отзыв не допускаются.

Синтетические сведения для шага 4:

Поле	Пример
Контекст	Бариста вручную записывают остатки после каждой смены
Потребность	Уменьшить списания выпечки за счёт точного планирования производства
Пользователи	Бариста и управляющий кофейней
Данные	Обезличенная таблица продаж и остатков за три месяца в CSV
Ожидаемый результат	Локальный прототип прогноза на следующий день и инструкция запуска
Критерии успеха	Снизить списания на 20% в пилоте; пять сотрудников проходят сценарий без помощи
Ограничения	Три недели, локальный запуск, только обезличенные данные
Контакт	[email protected]
Формат взаимодействия	Созвон во вторник, ответ на вопросы в течение двух рабочих дней

Дополнительно можно проверить загрузку файлов, языковое предупреждение и выдачу Pro через администратора. Для видео используйте опубликованную задачу Pro-заказчика и вариант без голоса: он позволяет пройти весь путь от предпросмотра до MP4 без API-ключей. Готовые видео не входят в начальный набор чистой базы; их необходимо сгенерировать перед демонстрацией.

Рейтинг и правила каталога

Готовность задачи

Баллы начисляет сервер за заполненные и подтверждённые разделы. Подтверждение связано с хешем текста: изменение содержимого снимает подтверждение соответствующего поля. Пустые поля баллов не дают.

Раздел	Максимум
Контекст и потребность	20
Данные и материалы	20
Ожидаемый результат	15
Критерии успеха	15
Ограничения	10
Пользователи	10
Контакт и формат взаимодействия	10
Всего	100

Уровни готовности: 0–39 — требует уточнений; 40–69 — рабочая; 70–89 — готовая; 90–100 — приоритетная. Балл характеризует полноту согласованного описания. Достоверность сведений подтверждает заказчик; приложение не проводит независимую проверку бизнеса.

Языковая проверка

Система проверяет текст, транскрипт аудио и доступный текст документов. Короткие фразы и распространённые технические термины допускаются. Если значительная часть материала отличается от языка задачи, пользователь получает предупреждение и может исправить текст или подтвердить продолжение.

При явном согласии на публикацию такого материала применяется отдельная поправка:

Итоговая готовность = max(0, сумма баллов подтверждённых разделов − 5)

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

Аудит языка использует эвристику и может ошибаться. Для TXT/CSV проверяются первые 60 КБ, для DOCX/XLSX — извлечённый XML-текст, для PDF — первые 20 страниц с ограничением времени обработки 8 секунд. Для сканов, изображений и ZIP предусмотрена ручная проверка; OCR не подключён. Сам факт загрузки файла не подтверждает раздел «Данные и материалы» и не начисляет ему баллы.

Доступ и выбор исполнителей

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

По умолчанию каталог сортируется по готовности. Также доступны новизна, фильтры и сопоставление по совпадениям навыков с текстом задачи. Сопоставление меняет порядок, сохраняя доступ к общему каталогу. Количество откликов не ограничивается тарифом или баллом задачи. Заказчик может принять предложения нескольких команд, одной команды или отклонить все. Автоматического назначения исполнителя нет.

Репутация команды

За подтверждённый этап начисляется 50 XP, за принятый финальный результат — 150 XP. Уровень рассчитывается как floor(XP / 200) + 1. Рейтинг команды — среднее оценок заказчиков по сданным работам; при отсутствии отзывов отображается «—». Рейтинг команды, очки опыта и готовность задачи — отдельные показатели.

ИИ и внешние сервисы

Подключение

Скопируйте .env.example в .env, если этого файла ещё нет, и заполните нужные ключи. После изменения настроек пересоздайте контейнер приложения:

docker compose up -d --force-recreate app

Ключи читаются сервером. Файл .env исключён из Git и Docker build context; значения ключей не передаются в браузер. Образец настроек: .env.example.

Функция	Подключённый сервис	Работа без ключа
Уточняющие вопросы и карточка	OpenAI Responses, gpt-4o-mini, строгая JSON Schema	Локальные вопросы и ручное заполнение
Анализ изменений задачи	OpenAI Responses; результат кэшируется для версии	Сравнение версий и локальный список рекомендаций
Генерация обложки Pro	OpenAI Images, gpt-image-1-mini	Загрузка своего изображения
Распознавание аудио	ElevenLabs Scribe v2; при отсутствии его ключа — OpenAI Whisper	Текстовый ввод
Озвучивание	ElevenLabs Eleven v3; при отсутствии его ключа — OpenAI gpt-4o-mini-tts	Системные голоса браузера, если доступны на устройстве
Видеорендер	Remotion, Chromium и FFmpeg локально	Видео без голоса
Рейтинг и аудит языка	Локальный Go-код	Работают полностью

Промпт запрещает модели добавлять неизвестные факты, контакты, сроки и данные. Пользователь проверяет и редактирует результат перед публикацией. Сервер проверяет структуру ответа; некорректный ответ не применяется к карточке. При недоступности API можно продолжить с локальным помощником. Промпт, схема и обработка ответа.

Распознавание автоматически определяет язык записи и возвращает транскрипт для проверки пользователем. Оно не выполняет скрытый перевод. Генерация новых карточек и настройки озвучивания видео в текущем интерфейсе ориентированы на русский язык.

Ограничение расходов

Генерация карточки ограничена 2200 выходными токенами, анализ изменений — 700. Лимит обращений к платным API — 40 на пользователя в сутки в пределах процесса приложения; после перезапуска этот счётчик обнуляется. Генерация обложек ограничена четырьмя успешными изображениями в сутки на аккаунт, с сохранением счётчика в базе. Используются n=1, quality=low, размер 1536x1024; повтор с тем же содержанием возвращает кэшированную обложку.

Видеорендер не вызывает LLM: он использует подтверждённый сценарий и подготовленные компоненты. Озвучка кэшируется между пробным и полным рендером. Поддерживаются длительности 30, 45, 60 и 90 секунд; сценарий — 20–1800 символов, до 6 абзацев по 400 символов. Если голос не помещается в выбранную длительность, пользователь получает предложение сократить текст или увеличить длительность.

Проверка реальной интеграции

Успешный ответ /api/ai содержит provider: "openai", модель, providerRequestId и счётчики usage.input_tokens / usage.output_tokens. У локального помощника указан provider: "local". Значение capabilities.ai в /api/bootstrap показывает наличие настройки, но само по себе не подтверждает успешный запрос.

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

Переменные окружения

Переменная	Назначение и значение по умолчанию
OPENAI_API_KEY	Необязательный ключ OpenAI; также поддерживается OPEN_API_KEY
ELEVENLABS_API_KEY	Необязательный ключ ElevenLabs; также поддерживаются 11LABS_API_KEY, 11LABS_KEY
OPENAI_MODEL	gpt-4o-mini
OPENAI_IMAGE_MODEL	gpt-image-1-mini
ELEVENLABS_VOICE_ID	JBFqnCBsd6RMkjVDRZzb
DATABASE_URL	В Compose — PostgreSQL на db:5432; для запуска Go на хосте — postgres://sana:sana_local_only@localhost:5434/sana?sslmode=disable
PORT	8080
STATIC_DIR / MEDIA_DIR	В Docker — /app/web/dist / /app/data/media; на хосте — web/dist / data/media
SEED_PASSWORD	Pass1234!; используется при создании отсутствующих тестовых аккаунтов
SEED_ACCOUNTS	В compose.yaml явно задано "true"; для отключения измените значение в environment этого файла
CHROME_EXECUTABLE	В Docker — /usr/bin/chromium; для локального рендера/тестов можно указать путь к Chromium
NODE_PATH_BIN / FFPROBE_PATH	Пути к исполняемым файлам; по умолчанию node / ffprobe

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

flowchart LR
  Browser[React + TypeScript] -->|REST API и cookie сессии| Go[Go API и фоновый обработчик]
  Go --> DB[(PostgreSQL 17)]
  Go --> AI[OpenAI / ElevenLabs]
  Go --> Renderer[Node.js + Remotion + Chromium + FFmpeg]
  Renderer --> Files[(Docker volume: медиа и вложения)]
  Go --> Files

Компонент	Технологии и назначение
server/	Go, pgx, bcrypt; авторизация, роли, задачи, рейтинг, версии, отклики, файлы и интеграции
web/	React 19, TypeScript, Vite, Lucide; пользовательский интерфейс
PostgreSQL 17	Бизнес-данные и сессии
renderer/	Node.js 22, Remotion 4, Chromium, FFmpeg; локальная сборка видео
Poppler	Извлечение текста из PDF для языковой проверки
Docker Compose	Сборка, запуск, health checks и сохранение данных

Бизнес-данные MVP хранятся в одном JSONB-агрегате PostgreSQL. Изменения выполняются транзакционно с блокировкой записи, а revision защищает от сохранения устаревшего черновика. Пароли хешируются bcrypt. Сессии находятся в отдельной таблице auth_sessions: хранится хеш токена, пользователь и срок действия. Cookie имеет атрибуты HttpOnly и SameSite; сессия действует 24 часа и отзывается при выходе.

Видео обрабатываются последовательно фоновым обработчиком. Внешние вызовы выполняются вне транзакции БД. Опубликованные версии фиксируют текст, подтверждения, вложения, обложку и оценку; медиа сохраняют привязку к версии. Подробности: архитектура.

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

Для запуска проверок на хосте нужны Go 1.24+, Node.js 22+ и Python 3. Приложение должно быть запущено. Интеграционные и браузерные проверки создают тестовые задачи, пользователей и отклики, а также меняют тарифы тестовых аккаунтов; запускайте их на демонстрационной базе. По умолчанию тесты используют пароль [скрыто].

go test -race ./server
npm --prefix web ci
npm --prefix web run build
npm --prefix renderer ci
npm --prefix renderer run typecheck
SANA_URL=http://localhost:8080 python3 scripts/smoke.py

Браузерные проверки:

cd web
npx playwright install chromium
SANA_URL=http://localhost:8080 npm run test:e2e
cd ..
SANA_URL=http://localhost:8080 node scripts/browser-flow.cjs

При уже установленном Chromium можно задать CHROME_EXECUTABLE=/absolute/path/to/chromium. Лимит входа — 20 попыток в минуту с одного IP; между несколькими последовательными прогонами с большим числом входов может потребоваться пауза.

Проверены 11 Go-тестов, 13 браузерных тестов и 22 API-проверки основного сценария. Дополнительно проверены чистый Docker-запуск без API-ключей, сохранение сессии после перезапуска, отзыв сессии при выходе, восстановление после отключения БД и видеорендер. Автоматические проверки доступности охватывают подписи, контраст, клавиатуру и ширины 320–1440 px; проверка со скринридером остаётся отдельной задачей. Подробные результаты.

Соответствие критериям хакатона

README подготовлен с учётом Положения, п. 5.4.15 и 5.6, инструкции участникам и ТЗ AI Sana, §9–11. Ниже указаны максимальные баллы критериев и способы проверки реализации. Оценку выставляют эксперты хакатона.

Критерий кейса	Максимум	Что демонстрируется	Где проверить
Сквозной сценарий	20	Черновик → публикация → отклик → решение заказчика	Сценарий выше, браузерная проверка
Качество карточки	15	Уточняющие вопросы, редактируемые поля, подтверждение заказчиком	Studio.tsx, проверки конструктора
Геймификация бизнеса	25	Формула готовности, пересчёт после изменений, сортировка каталога	domain.go, доменные тесты
Каталог и отклики	15	Доступ к задачам с 0 баллов, свободный отклик, ручной выбор команды	App.tsx, QuestDetail.tsx, API-проверки
AI-функция	10	Структурированный ответ, исходный промпт, проверка и резервный режим	ai.go, результаты реальных вызовов
Техническое качество	10	Воспроизводимый запуск, валидация, права доступа, обработка ошибок	Dockerfile, compose.yaml, отчёт проверки
Демонстрация	5	Целостный работающий сценарий до 5 минут	Сценарий защиты
Всего	100

Языковая поправка −5 относится к готовности задачи внутри продукта. Она является дополнительной функцией и не меняет шкалу оценки проекта на хакатоне.

Для Demo Day применяется отдельная шкала из п. 5.7.2 Положения: ценность решения — 25, результат и качество — 20, инновационность — 15, развитие и масштабирование — 20, презентация и ответы — 20. Для защиты подготовлены описание проблемы, преимущества, работающий сценарий и ограничения реализации. План развития: пилот с бизнесом и университетом, измерение качества постановки задач, расширение локализации и переход к инфраструктуре для нескольких организаций.

Основной репозиторий проекта — BAITC-Hacks/hack-654d40a5-lexus, выданный организатором. Отправка кода в GitHub и действие «Сдать решение» на платформе хакатона выполняются отдельно. Для проверки доступны онлайн-демо и локальный запуск.

Ошибки и восстановление

Код / ситуация	Причина	Действие
400	Некорректные поля, файл или отсутствие обязательного подтверждения	Исправить указанное поле либо проверить и подтвердить материал
401	Сессия отсутствует или истекла	Войти в аккаунт
403	Недостаточно прав, чужой объект или функция Pro без нужного тарифа	Проверить аккаунт, роль и тариф
404	Материал отсутствует или недоступен текущему пользователю	Проверить ссылку и аккаунт
409	Изменились версия задачи, черновик или статус отклика	Сохранить копию своих правок, обновить данные и согласовать актуальную версию
429	Достигнут лимит запросов или уже выполняется генерация видео	Дождаться завершения операции или обновления лимита
500	Внутренняя ошибка приложения или базы данных	Сохранить код запроса и проверить состояние сервисов и логи
502	Сбой внешнего API, тайм-аут или некорректный ответ ИИ	Повторить позже либо продолжить с локальным помощником, ручным вводом или своим фото
Нет ответа	Приложение недоступно по сети	Проверить Docker и соединение, оставить форму открытой
Видео в статусе failed	Фоновая генерация завершилась ошибкой	Прочитать причину, исправить параметры и повторить генерацию

Ошибка API содержит JSON {"error":"…","requestId":"…"} и заголовок X-Request-ID. Подробности внутренней ошибки 500 записываются в серверный лог. Интерфейс обрабатывает также не-JSON ответы и обрывы соединения; неудачный запрос не сбрасывает введённый текст. При сбое провайдера его код, например 401 или 429, может быть указан в сообщении ответа приложения с кодом 502.

docker compose ps
curl -i http://localhost:8080/api/health
docker compose logs --since=15m --tail=120 app
docker compose logs --since=15m --tail=80 db
docker compose exec -T db pg_isready -U sana -d sana

Если порт занят, остановите другой локальный экземпляр либо измените порт на стороне хоста в compose.yaml. После изменения .env выполните docker compose up -d --force-recreate app, после изменения кода — docker compose up --build -d. Для диагностики не требуется удалять базу или медиа. Полный вывод docker compose config может содержать значения секретов; не включайте его в публичные отчёты.

Разработка вне контейнера приложения

Для этого способа нужны Go 1.24+, Node.js 22+ и работающий PostgreSQL:

docker compose up -d db
docker compose stop app
npm --prefix web ci
npm --prefix web run build
go run ./server

Приложение доступно на http://localhost:8080. После изменения интерфейса повторите npm --prefix web run build. Для видеорендера на хосте дополнительно нужны Chromium, FFmpeg, ffprobe и собранный renderer (npm --prefix renderer ci, затем npm --prefix renderer run bundle). Для извлечения текста PDF нужен pdftotext из Poppler. Все эти зависимости уже включены в Docker-образ.

Ограничения MVP

• Подтверждение электронной почты, восстановление пароля, SMTP и онлайн-оплата не подключены. Pro назначается администратором для проверки тарифной модели.
• Используются один JSONB-агрегат и один обработчик видео. Для масштабирования потребуется нормализация таблиц, отдельная очередь и постоянный учёт квот API.
• Максимум — 50 загруженных файлов на аккаунт. Автоматическая очистка неиспользованных файлов и антивирусная проверка не реализованы.
• Языковой аудит эвристический; OCR сканов отсутствует. Качество распознавания зависит от записи и провайдера. Субтитры имеют приблизительный тайминг.
• Текущая версия интерфейса русская. Автоматические проверки доступности не являются сертификацией WCAG.
• Показатели пользы, рыночный спрос и готовность пользователей платить ещё не подтверждены пилотом.

Данные, сторонние компоненты и лицензии

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

В видеоадаптере использованы компоненты anything2explainer с сохранением лицензии и уведомлений автора. Исходный репозиторий закреплён как подмодуль skills/anything2explainer; для его просмотра можно выполнить git submodule update --init skills/anything2explainer. Docker-запуск не требует загрузки подмодуля: используемые компоненты находятся в renderer/src/vendor/.

Лицензия toolkit — PolyForm Noncommercial; для коммерческого использования требуется разрешение автора. У Remotion действуют отдельные условия лицензирования. Тариф Pro в этом MVP демонстрирует разграничение возможностей и не осуществляет реальные платежи.

При разработке использовался AI-агент OpenAI Codex. Баннер создан встроенным imagegen, обложки категорий — оригинальные SVG-иллюстрации проекта. Источники, лицензии библиотек и происхождение ассетов приведены в docs/assets.md.

Дополнительная документация: архитектура, отчёт проверки, сценарий защиты, решения по интерфейсу, исходное ТЗ и материалы хакатона.