SteppeMind

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

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

• напрямую через Node.js;
• в production-контейнере Docker.

Демонстрация проекта

Видеодемонстрация и связанные материалы доступны в папке Google Drive.

Назначение решения

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

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

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

1. Бизнес вводит исходное описание задачи.
2. AI извлекает только факты из описания и создаёт 3–5 релевантных вопросов по пропущенным сведениям.
3. Ответы попадают в редактируемую карточку.
4. Бизнес вручную проверяет и подтверждает текущую версию.
5. Система рассчитывает рейтинг готовности от 0 до 100 и показывает расшифровку.
6. Бизнес отдельно публикует подтверждённую версию.
7. Студент находит задачу в каталоге и отправляет предложение.
8. Владелец задачи вручную принимает или отклоняет предложение. Автоматического назначения команд нет.

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

Возможности

Для бизнеса

• регистрация и вход с ролью «Бизнес»;
• создание и сохранение черновиков;
• AI-анализ исходного описания;
• уточняющие вопросы на русском или казахском языке;
• редактирование всех полей карточки;
• отдельные действия подтверждения и публикации;
• AI-оценка качества подтверждённых сведений с пояснениями;
• повторная оценка после изменения карточки;
• сохранение последней опубликованной версии до повторной публикации;
• просмотр предложений только к собственным задачам;
• ручное принятие и отклонение нескольких предложений.

Для студентов

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

Надёжность и безопасность

• ключ OpenAI используется только на сервере;
• AI-ответы проверяются через Zod Structured Outputs;
• извлечённые факты принимаются только при наличии точной цитаты в исходном описании;
• при отсутствии или ошибке OpenAI используется локальный fallback;
• пароли хешируются с помощью scrypt и индивидуальной соли;
• сессии хранятся на сервере, cookie имеет HttpOnly и SameSite=Lax;
• сервер проверяет роль, владельца задачи, версию черновика и источник изменяющих запросов;
• приватные черновики и содержание чужих предложений не выдаются в общий каталог.

Архитектура

Браузер
   │
   ▼
Next.js App Router
   ├── React-интерфейс и маршруты страниц
   ├── Route Handlers: авторизация, задачи, каталог, предложения
   ├── бизнес-логика черновика → подтверждения → публикации
   └── серверная интеграция OpenAI Responses API
           │
           ▼
SQLite через Drizzle ORM и better-sqlite3

Основные каталоги:

Путь	Назначение
src/app	Страницы App Router и серверные API-маршруты
src/components	Интерфейс авторизации, каталога, дашбордов и конструктора
src/lib	Работа с БД, авторизация, AI, рейтинг, валидация и workflow
tests	Модульные и интеграционные проверки
docs	Дополнительная документация и сценарии демонстрации
Dockerfile	Многоэтапная production-сборка контейнера

Хранение данных

По умолчанию используется файл steppemind.db в корне проекта. При первом обращении приложение автоматически:

• создаёт таблицы и индексы;
• применяет аддитивные миграции;
• добавляет воспроизводимый демонстрационный набор данных;
• не создаёт повторные копии демо-записей при перезапуске.

Для Docker база хранится в /app/data/steppemind.db. Эту директорию необходимо подключать как persistent volume.

Используемые технологии

Технология	Назначение
Next.js 16 App Router	Полнофункциональное React-приложение и серверные маршруты
React 19	Пользовательский интерфейс
TypeScript	Типизация приложения
Tailwind CSS 4	Стилизация интерфейса
SQLite	Локальное постоянное хранилище
Drizzle ORM	Типизированный доступ к БД
better-sqlite3	SQLite-драйвер для Node.js
OpenAI JavaScript SDK	Анализ задачи, вопросы и оценка готовности
Zod	Валидация HTTP- и AI-ответов
Lucide React	Иконки интерфейса
Docker	Воспроизводимый production-запуск

Точные версии зависимостей зафиксированы в package-lock.json.

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

Создайте .env.local на основе примера:

cp .env.example .env.local

Переменная	Обязательна	Значение и назначение
OPENAI_API_KEY	Нет	API-ключ OpenAI. Без него работает локальный fallback
OPENAI_MODEL	Нет	Модель OpenAI; значение по умолчанию — gpt-5.4-nano
OPENAI_BASE_URL	Нет	Альтернативный OpenAI-совместимый endpoint
DATABASE_PATH	Нет	Путь к SQLite; по умолчанию steppemind.db
SEED_DEMO_DATA	Нет	Установите 0, чтобы отключить создание демо-аккаунтов в новой БД
PORT	Нет	Порт production-сервера; по умолчанию 3000
HOSTNAME	Нет	Адрес прослушивания; для контейнера используется 0.0.0.0

Минимальный .env.local для AI-режима:

OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-5.4-nano
DATABASE_PATH=steppemind.db

Для запуска без внешнего API оставьте OPENAI_API_KEY пустым. Секреты нельзя коммитить в Git или встраивать в Docker-образ; .env.local исключён из Docker build context.

Способ 1: запуск через Node.js

Системные требования

• Node.js 24 LTS;
• npm;
• Git;
• инструменты сборки C/C++ и Python 3, если для better-sqlite3 нет готового бинарного пакета.

Для Debian/Ubuntu инструменты сборки устанавливаются так:

sudo apt-get update
sudo apt-get install -y python3 make g++

На macOS при необходимости установите Command Line Tools:

xcode-select --install

Установка

git clone <URL_РЕПОЗИТОРИЯ>
cd hack-827386af-steppemind
npm ci
cp .env.example .env.local

После копирования укажите OPENAI_API_KEY в .env.local, если требуется настоящий AI-режим.

Режим разработки

npm run dev

Откройте:

http://localhost:3000

Изменения кода применяются автоматически. Этот режим предназначен для разработки, а не для публичного размещения.

Production-режим через Node.js

npm run build
npm start

Сервер будет доступен по адресу http://localhost:3000.

Чтобы открыть приложение для других устройств в локальной сети:

HOSTNAME=0.0.0.0 PORT=3000 npm start

После этого используйте http://IP_КОМПЬЮТЕРА:3000. Системный firewall должен разрешать входящие подключения к выбранному порту.

Способ 2: запуск через Docker

Системные требования

• Docker Engine либо Docker Desktop;
• свободный порт 3000.

Локальная установка Node.js при запуске через Docker не требуется.

Сборка образа

В корне репозитория выполните:

docker build -t steppemind .

Dockerfile использует multi-stage build, компилирует better-sqlite3, создаёт standalone-сборку Next.js и запускает приложение от непривилегированного пользователя.

Запуск контейнера

docker run -d \
  --name steppemind \
  --restart unless-stopped \
  --env-file .env.local \
  -e DATABASE_PATH=/app/data/steppemind.db \
  -p 3000:3000 \
  -v steppemind-data:/app/data \
  steppemind

Откройте http://localhost:3000.

Если Docker сообщает bind: address already in use, порт 3000 уже занят другим процессом (часто ранее запущенным npm run dev). В этом случае опубликуйте контейнер на другом порту хоста:

docker run -d \
  --name steppemind \
  --restart unless-stopped \
  --env-file .env.local \
  -e DATABASE_PATH=/app/data/steppemind.db \
  -p 3001:3000 \
  -v steppemind-data:/app/data \
  steppemind

После этого откройте http://localhost:3001. Проверить, какой процесс занимает порт 3000 на macOS или Linux, можно командой:

lsof -nP -iTCP:3000 -sTCP:LISTEN

Назначение параметров:

• --env-file .env.local передаёт настройки во время запуска, не добавляя секреты в образ;
• -e DATABASE_PATH=/app/data/steppemind.db направляет SQLite в постоянное хранилище;
• -v steppemind-data:/app/data сохраняет БД при пересоздании контейнера;
• -p 3000:3000 публикует приложение на всех сетевых интерфейсах хоста;
• --restart unless-stopped автоматически перезапускает контейнер после перезагрузки сервера.

Проверка состояния и просмотр логов:

docker ps
docker logs -f steppemind

Остановка и повторный запуск:

docker stop steppemind
docker start steppemind

Обновление после изменения кода:

docker build -t steppemind .
docker stop steppemind
docker rm steppemind
docker run -d \
  --name steppemind \
  --restart unless-stopped \
  --env-file .env.local \
  -e DATABASE_PATH=/app/data/steppemind.db \
  -p 3000:3000 \
  -v steppemind-data:/app/data \
  steppemind

Именованный volume steppemind-data при этом не удаляется, поэтому данные сохраняются. Команда docker volume rm steppemind-data удалит базу без возможности восстановления и для обычного обновления не нужна.

Доступ из локальной сети или интернета

При публикации -p 3000:3000 приложение доступно по адресу:

http://IP_СЕРВЕРА:3000

Для публичного размещения рекомендуется поставить перед контейнером Nginx или Caddy, открыть только порты 80/443 и настроить HTTPS. Не публикуйте файл SQLite и не открывайте к нему сетевой доступ.

Демонстрационные данные

При запуске с новой базой автоматически создаются:

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

Роль	Логин	Пароль
Бизнес	demo_business	Demo2026!
Студенты	demo_student_1 … demo_student_5	Demo2026!

Демо-данные создаются идемпотентно. Чтобы отключить их для новой базы, задайте SEED_DEMO_DATA=0 до первого запуска.

Порядок проверки основного сценария

Для полного сценария удобно использовать два отдельных окна браузера или обычное и приватное окно.

1. Проверка роли бизнеса и конструктора

1. Откройте /login.

2. Войдите как demo_business с паролем Demo2026! либо зарегистрируйте новый бизнес-аккаунт.

3. Откройте «Создать задачу».

4. Введите слабое описание, например:

   Хотим сократить списания продуктов в небольшой сети кофеен.
   

5. Нажмите «Проанализировать описание».

6. Убедитесь, что система показывает минимум три вопроса по отсутствующим сведениям. При настроенном ключе вопросы генерирует AI; без ключа интерфейс явно показывает локальный fallback.

7. Ответьте на вопросы о пользователях, данных, результате и критериях успеха.

8. Нажмите «Собрать карточку» и проверьте, что все поля можно редактировать вручную.

9. Укажите название задачи, если оно отсутствует.

10. Сохраните черновик и убедитесь, что он не появился в общем каталоге.

11. Нажмите «Подтвердить сведения задачи».

12. Проверьте рейтинг 0–100, сумму категорий, объяснения и список недостающих сведений.

13. Дополните карточку, подтвердите ещё раз и убедитесь, что рейтинг пересчитался.

14. Перейдите к публикации и нажмите «Опубликовать задачу».

15. Откройте каталог и найдите опубликованную задачу.

2. Проверка каталога и роли студента

1. Выйдите из бизнес-аккаунта.
2. Войдите как demo_student_1 с паролем Demo2026! либо зарегистрируйте студента.
3. Откройте каталог.
4. Проверьте сортировку по рейтингу и фильтры по отрасли и уровню готовности.
5. Откройте созданную задачу.
6. Заполните название команды, идею решения, план, срок и при необходимости ссылку на прототип.
7. Отправьте предложение.
8. Откройте «Мои предложения» и убедитесь, что предложение имеет статус «На рассмотрении».

3. Проверка ручного решения бизнеса

1. В другом окне снова войдите как demo_business или как владелец созданной задачи.
2. Откройте раздел «Предложения».
3. Найдите предложение студента.
4. Нажмите «Выбрать» или «Отклонить».
5. Вернитесь в студенческий аккаунт и проверьте изменение статуса.
6. При необходимости отправьте предложения от нескольких студентов и убедитесь, что бизнес может выбрать более одной команды.

Ожидаемый результат: сценарий «черновик → уточнение → карточка → рейтинг → публикация → предложение → ручное решение» выполняется полностью через интерфейс без ручного изменения БД.

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

Перед демонстрацией выполните:

npm run lint
npm run test:logic
npm run build
npm run test:auth

Проверки охватывают:

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

Интеграционный тест запускает собранное приложение на отдельном порту и использует временную SQLite-базу, поэтому рабочая база не изменяется.

Ограничения развёртывания

SQLite рассчитан на один экземпляр приложения с постоянным локальным диском. Текущую сборку следует размещать на VM/VPS или Docker-хосте с persistent volume. Serverless-платформы с эфемерной файловой системой требуют миграции на внешнюю БД.

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

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

• Архитектура
• Бизнес-конструктор и рейтинг
• Сценарий демонстрации
• Требования MVP

Лицензия

Проект создан в рамках практического хакатона AI Sana. Отдельный файл лицензии в репозитории не предоставлен.