SmartFlow

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

Проект команды Juniors для хакатона HackAlem AI.

О проекте

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

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

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

Какую проблему решает SmartFlow

Описания «нужно улучшить продажи» недостаточно для начала работы. Команде нужны сведения о текущем процессе, пользователях, данных, ограничениях и ожидаемом результате.

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

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

Работа с бизнес-задачами

• Ввод названия, отрасли и описания проблемы.
• Получение 3–5 уточняющих вопросов.
• Перенос ответов в редактируемую карточку.
• Подтверждение каждого поля человеком.
• Сохранение без публикации.
• Публикация после отдельного подтверждения.
• Редактирование существующих задач.

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

• Оценка от 0 до 100.
• Расшифровка начисленных баллов.
• Пересчёт при заполнении и подтверждении полей.
• Независимый серверный расчёт при сохранении.
• Отображение недостающих сведений.

Каталог и отклики

• Общий каталог опубликованных задач.
• Сортировка по рейтингу.
• Поиск по названию, компании и описанию.
• Фильтры по отрасли и уровню готовности.
• Предложения команд: идея, план, срок и ссылка на прототип.
• Просмотр предложений в кабинете бизнеса.
• Ручное принятие и отклонение.
• Возможность выбрать несколько команд.

Прогресс команд

После подтверждения бизнесом завершённого этапа выбранная команда получает 10 баллов. Повторное подтверждение того же этапа не увеличивает результат.

Переключение активной команды

• Выбор команды в профиле или кнопкой «Перейти в команду» в разделе «Команды».
• Активная команда выделяется среди остальных.
• Выбор сохраняется в браузере после обновления страницы.
• В форме нового предложения автоматически выбирается активная команда.
• Изменение команды в форме предложения также обновляет активную команду.
• При переключении команды введённый текст предложения сохраняется.
• Ранее отправленные предложения остаются привязаны к исходной команде.
• Переключатель поддерживает RU / KZ / EN и мобильный интерфейс.

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

AI-помощник SmartFlow

Встроенный чат открывается кнопкой в правом нижнем углу. Помощник:

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

Помощник работает через OpenAI API без Chatbase. Он не публикует задачи, не выбирает команды и не начисляет баллы.

Языки и темы

• Русский, казахский и английский интерфейс: RU / KZ / EN.
• Петрольная тема по умолчанию.
• Дополнительные темы: Слива и Терракота.
• Сохранение языка и темы в браузере.
• Сохранение введённых данных при переключении языка.

Тексты задач и ответов автоматически не переводятся.

Основной пользовательский сценарий

1. Бизнес вводит краткое описание проблемы.
2. SmartFlow предлагает уточняющие вопросы.
3. Пользователь отвечает и переносит сведения в карточку.
4. Бизнес проверяет и подтверждает заполненные поля.
5. Рейтинг показывает готовность задачи.
6. После подтверждения публикации карточка появляется в каталоге.
7. Команда самостоятельно выбирает задачу и отправляет предложение.
8. Бизнес вручную выбирает одну, несколько или ни одной команды.
9. После выполнения этапа бизнес подтверждает результат, и команда получает баллы.

В MVP используется общий демонстрационный интерфейс без регистрации и разграничения доступа.

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

Рейтинг = сумма весов заполненных и подтверждённых полей

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

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

Уровни готовности

Баллы	Уровень
0–39	Черновик
40–69	Рабочая
70–89	Готовая
90–100	Приоритетная

Изменение текста в интерфейсе снимает подтверждение соответствующего поля.

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

Правила каталога

• Все опубликованные задачи доступны всем командам.
• Низкий рейтинг не скрывает задачу и не запрещает отклики.
• Неопубликованные карточки доступны в кабинете бизнеса.
• Уровень «Черновик» и отсутствие публикации — разные состояния.
• Число откликов программно не ограничивается.
• Выбор одной команды не отклоняет остальные предложения.
• Автоматическое назначение исполнителей отсутствует.

Технологии

Компонент	Реализация
Интерфейс	HTML, CSS, JavaScript
Клиентские модули	Браузерные ES modules
Сервер	Node.js, встроенный node:http
Хранение данных	Локальный JSON-файл
AI	OpenAI Chat Completions API
Модель по умолчанию	gpt-4.1-mini
Запросы к AI	Серверный fetch
Тестирование	node:test, node:assert/strict
Шрифт	Manrope через Google Fonts, запасной Arial

Сторонние npm-зависимости и отдельная сборка не требуются.

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

Браузер
  ├── Каталог и конструктор задач
  ├── Кабинет бизнеса и команды
  ├── Языки и темы
  └── AI-помощник
          |
          | HTTP / JSON
          v
      Node.js сервер
          ├── Валидация запросов
          ├── Расчёт рейтинга
          ├── JSON-хранилище
          └── OpenAI API / локальные ответы

Данные сохраняются в data/db.json. Запись выполняется через временный файл и переименование. Настройки интерфейса сохраняются в localStorage.

Структура проекта:

public/
  index.html          Страница приложения
  app.js              Интерфейс и чат
  styles.css          Оформление и темы
  i18n.js             Переводы RU / KZ / EN

lib/
  domain.js           Рейтинг, валидация и промпт вопросов
  assistant.js        Промпт чата и обработка истории
  seed.js             Демонстрационные данные

tests/
  domain.test.js      Проверка бизнес-логики
  api.test.js         Сквозной HTTP-сценарий
  assistant.test.js   Проверка чата и переводов

server.js             HTTP-сервер и API
.env.example          Шаблон настроек
DEMO.md               Сценарий защиты
TEAM.md               План распределения работы

API

Метод и путь	Назначение
GET /api/state	Получение задач, рейтингов, команд и откликов
POST /api/analyze	Уточняющие вопросы
POST /api/assistant	Ответ AI-помощника
POST /api/tasks	Создание, редактирование и публикация задачи
POST /api/proposals	Отправка предложения
POST /api/proposals/:id	Решение бизнеса или подтверждение этапа

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

Требуется Node.js 22.9 или новее.

1. Клонировать репозиторий:

git clone https://github.com/BAITC-Hacks/hack-e38c07f2-juniors.git
cd hack-e38c07f2-juniors

Название репозитория отличается от названия продукта SmartFlow.

2. Запустить приложение:

node server.js

Открыть:

http://localhost:3000

При первом запуске создаётся хранилище с демонстрационными данными. Задачи, отклики и решения сохраняются после перезапуска.

Без ключа доступны локальные вопросы и резервные ответы помощника.

3. Подключить OpenAI

Создать .env на основе .env.example:

PORT=3000
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4.1-mini

Остановить ранее запущенный сервер через Ctrl+C и выполнить:

node --env-file=.env server.js

При наличии npm можно использовать:

npm start

Ключ используется только сервером. .env исключён из Git и не должен публиковаться.

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

Переменная	Назначение
PORT	Порт сервера, по умолчанию 3000
OPENAI_API_KEY	Ключ OpenAI API
OPENAI_MODEL	Модель, по умолчанию gpt-4.1-mini
DATA_DIR	Каталог хранения, по умолчанию data/

Индикатор «AI настроен» означает наличие ключа. Успешность подключения проверяется реальным запросом.

Работа AI

Генерация вопросов

Сервер передаёт описание и заполненные поля модели. Промпт требует 3–5 вопросов на выбранном языке, запрещает добавлять неизвестные факты и выбирать исполнителей.

Пример ответа:

{
  "questions": [
    {
      "field": "data",
      "question": "Какие данные о продажах доступны команде?"
    },
    {
      "field": "success",
      "question": "Как вы будете оценивать точность прогноза?"
    },
    {
      "field": "constraints",
      "question": "К какому сроку нужен первый прототип?"
    }
  ]
}

Сервер проверяет структуру, число вопросов, допустимые уникальные ключи и длину текста.

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

Диалоговый помощник

Для ответа используются последние 12 сообщений длиной до 2000 символов каждое.

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

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

При отсутствии ключа, ошибке API, таймауте или некорректном ответе SmartFlow использует локальные вопросы либо резервный ответ чата. Интерфейс сообщает об этом.

Локальный режим не является вызовом AI-модели.

Как проверить решение

Автоматические тесты

node --test

Проверяются:

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

Тесты используют отдельное временное хранилище и не требуют API-ключа.

Ручной сценарий

1. Открыть «Создать задачу» и подставить пример.
2. Получить вопросы, ответить минимум на три и перенести ответы в карточку.
3. Подтвердить контекст, потребность и данные — получить 40/100.
4. Дополнить и подтвердить остальные поля — получить 100/100.
5. Подтвердить публикацию и найти задачу в каталоге.
6. Отправить предложение от команды.
7. В кабинете бизнеса выбрать команду.
8. Подтвердить завершённый этап и проверить прибавку 10 баллов.
9. Обновить страницу и проверить сохранность данных.

Дополнительно:

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

Подробный сценарий защиты находится в DEMO.md.

Данные и интеграции

Начальный набор в lib/seed.js содержит:

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

Данные синтетические. Контакты используют домен .example, ссылки на прототипы — демонстрационные адреса example.com.

Внешние сервисы:

• OpenAI API — вопросы и диалоговый помощник.
• Google Fonts — шрифт Manrope.

При подключённом ключе сведения для анализа и сообщения помощнику отправляются OpenAI. NVIDIA API и Chatbase не используются.

Команда и вклад

SmartFlow разработан командой Juniors.

Фактические изменения участников доступны в:

• Истории коммитов
• Pull Requests

План распределения работы описан в TEAM.md.

Ограничения

• Нет регистрации, авторизации и разграничения доступа.
• Достоверность и смысловое качество сведений подтверждает человек.
• Один подтверждаемый этап на отклик.
• При последующем отклонении выбранного отклика его подтверждение этапа и соответствующие баллы сбрасываются.
• Нет чата между бизнесом и командами, уведомлений и файлового хранилища.
• Нет персональных рекомендаций и автоматического назначения.
• Тексты задач автоматически не переводятся.
• История AI-чата не сохраняется после обновления страницы.
• JSON-хранилище рассчитано на один серверный процесс.
• Сервер слушает 127.0.0.1 и предназначен для локальной демонстрации.
• Внешний AI зависит от доступности API, ключа и выбранной модели.

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

Публичная deployed-версия пока не указана.

Для проверки используется:

http://localhost:3000

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

FAQ и анимации

В разделе «Вопросы и ответы» доступны 8 раскрывающихся ответов о рейтинге, редактировании, откликах, выборе команд, баллах за этапы, AI и сохранении данных. FAQ переведён на RU / KZ / EN; кнопка из раздела открывает AI-помощника. Вопросы доступны с клавиатуры через Tab и Enter или пробел.

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