Alem — от бизнес-задачи к совместному результату

MVP для HackAlem AI: платформа сотрудничества бизнеса и студенческих команд с AI-помощником для подготовки задач.

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

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

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

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

• Главная страница с объяснением платформы и переходами для бизнеса и команд.
• Конструктор задачи: описание, уточняющие вопросы AI, редактирование десяти полей, подсказки, счётчик заполнения и предпросмотр.
• Публикация и редактирование карточки после явного подтверждения пользователем.
• Оценка полноты задачи от 0 до 100 с разбивкой по критериям.
• Каталог: поиск по полям карточки, фильтры по теме и готовности, сортировка по готовности, числу откликов или названию.
• Избранное в localStorage браузера. Навигация, фильтры и незавершённые формы сохраняются в sessionStorage текущей вкладки.
• Отклики команд: идея, план, срок и ссылка на прототип.
• Ручной выбор или отклонение команды. Можно выбрать несколько команд.
• Подтверждение одного этапа по отклику: +25 баллов однократно.
• Рейтинг команд с общими местами при равных баллах и выделением призовых позиций.
• AI-студия с описанием ролей и настроенного провайдера.
• Адаптивный интерфейс, обновление данных без ухода с текущей страницы.
• Локальный деморежим без API-ключа и сохранение серверных данных между перезапусками.

Как рассчитывается готовность

Это оценка заполненности полей, а не качества идеи или достоверности текста. Непустое поле приносит фиксированные баллы.

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

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

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

1. Бизнес вводит описание проблемы в разделе «Создать задачу».
2. Аналитик выделяет известные сведения, интервьюер задаёт 3–7 уточняющих вопросов.
3. Пользователь отвечает; редактор собирает карточку. Пользователь проверяет и дополняет поля вручную.
4. После подтверждения карточка публикуется в каталоге с рассчитанным рейтингом.
5. Команда находит задачу и отправляет идею, план, срок и ссылку на прототип.
6. Бизнес рассматривает предложения и выбирает исполнителя вручную.
7. После подтверждения этапа команда получает 25 баллов, а рейтинг команд обновляется.

AI не публикует задачи, не выбирает исполнителей и не подтверждает выполнение работ.

4. Технологии и AI

Компонент	Реализация
Интерфейс	HTML, CSS, JavaScript, ES-модули; без UI-фреймворка
Сервер	Node.js, встроенный node:http
Хранение	JSON-файл, встроенный node:fs
Вызовы AI	Встроенный fetch, серверные HTTP-запросы
Тесты	node:test, node:assert/strict
Внешние npm-зависимости	Отсутствуют

Основная конфигурация в .env.example: OpenAI, gpt-4.1-mini для всех трёх ролей. Используется Chat Completions API и строгая JSON Schema. Это три роли приложения с разными промптами, а не три автономных сервиса или Agents SDK.

Роль	Назначение
Аналитик	Извлекает известные поля из исходного описания
Интервьюер	Формирует 3–7 разных уточняющих вопросов
Редактор	Собирает карточку из описания, существующих полей и ответов

Адаптер также поддерживает Groq и NVIDIA. Идентификаторы ниже взяты из кода и конфигурации; наличие адаптера не гарантирует доступность модели у провайдера.

Провайдер	API	Модели в конфигурации
OpenAI	https://api.openai.com/v1/chat/completions	gpt-4.1-mini
Groq	https://api.groq.com/openai/v1/chat/completions	qwen/qwen3.8-27b
NVIDIA	https://integrate.api.nvidia.com/v1/chat/completions	Аналитик: nvidia/nemotron-3-nano-30b-a3b; интервьюер: nvidia/nvidia-nemotron-nano-9b-v2; редактор: nvidia/llama-3.3-nemotron-super-49b-v1.5 из .env.example

Если AI_PROVIDER не задан, адаптер выбирает Groq; штатный запуск через start.mjs использует .env.example, где выбран OpenAI. Автоматического переключения между провайдерами при ошибке нет.

5. Архитектура

Браузер: public/index.html + app.js + style.css
  │  fetch /api/*
  ▼
server.mjs — HTTP API, проверка запросов, сохранение
  ├── domain.mjs — рейтинг, правила выбора и подтверждения этапа
  ├── seed.mjs → data/db.json — начальные и текущие данные
  └── ai.mjs — последовательные вызовы AI-ролей
        └── provider.mjs → API выбранного провайдера

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

public/             Интерфейс приложения
server.mjs          HTTP-сервер и API
start.mjs           Проверка Node.js и загрузка .env
provider.mjs        Выбор провайдера, ключа и моделей
ai.mjs              Промпты, вызовы и обработка ответов AI
domain.mjs          Бизнес-правила и проверки карточек
seed.mjs            Синтетические начальные данные
test/               Автоматические проверки
.env.example        Пример конфигурации без ключей
.gitignore          Исключение секретов, данных и логов
START-WINDOWS.cmd   Запуск в Windows
render.yaml         Конфигурация размещения на Render
DEPLOY.md           Дополнительная инструкция по размещению

Основные маршруты:

Метод	Путь	Назначение
GET	/api/health	Проверка работы сервера
GET	/api/state	Задачи, команды, отклики и публичная конфигурация AI
POST	/api/ai/analyze	Анализ описания и вопросы
POST	/api/ai/compose	Сборка карточки
POST	/api/tasks	Публикация или изменение задачи
POST	/api/proposals	Отправка отклика
POST	/api/decision	Решение по отклику
POST	/api/complete	Подтверждение этапа

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

Требования

• Node.js 22.9 или новее; для приведённого ниже режима тестирования рекомендуется Node.js 24.
• Современный браузер.
• Для реального AI — интернет, ключ выбранного провайдера, доступ к модели и доступная квота API.

Локальный запуск

1. Склонируйте репозиторий команды или распакуйте исходный архив.
2. Откройте терминал в папке, где находится package.json.
3. Проверьте Node.js и запустите приложение:

node --version
node start.mjs

Установка пакетов и сборка не нужны. Альтернатива при наличии npm: npm start. В Windows можно открыть START-WINDOWS.cmd.

При первом запуске start.mjs создаёт .env из .env.example. Если базы ещё нет, сервер создаёт data/db.json с демонстрационными данными.

4. Откройте http://localhost:3210.
5. Оставьте процесс сервера работающим. Для остановки нажмите Ctrl+C в терминале.

Открытие public/index.html двойным щелчком не запускает сервер. Одной статической публикации на GitHub Pages для этого приложения недостаточно.

Подключение OpenAI

В созданном .env задайте:

AI_PROVIDER=openai
OPENAI_API_KEY=ваш_ключ
OPENAI_MODEL=gpt-4.1-mini
PORT=3210

Замените ваш_ключ действительным ключом только локально, затем перезапустите node start.mjs. .env не должен попадать в GitHub. Ключ хранится на сервере и не включается в /api/state.

Статус «Ключ настроен» означает наличие значения в конфигурации, а не успешную проверку ключа у провайдера. Проверка доступа происходит при AI-запросе.

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

Переменная	Назначение
AI_PROVIDER	openai, groq или nvidia
OPENAI_API_KEY, GROQ_API_KEY, NVIDIA_API_KEY	Ключ выбранного провайдера
OPENAI_MODEL	Общая модель OpenAI
OPENAI_MODEL_ANALYST, OPENAI_MODEL_INTERVIEWER, OPENAI_MODEL_EDITOR	Отдельные модели OpenAI; имеют приоритет над общей
AI_MODEL_ANALYST, AI_MODEL_INTERVIEWER, AI_MODEL_EDITOR	Переопределение моделей для Groq/NVIDIA; не для OpenAI
NVIDIA_MODEL_ANALYST, NVIDIA_MODEL_INTERVIEWER, NVIDIA_MODEL_EDITOR	Модели NVIDIA, если не заданы соответствующие AI_MODEL_*
PORT	Порт, по умолчанию 3210
HOST	Адрес прослушивания; обычно 127.0.0.1, при RENDER=true — 0.0.0.0
DATA_DIR	Каталог JSON-базы; по умолчанию папка data рядом с сервером
PUBLIC_ORIGIN	Разрешённый публичный origin для POST-запросов, например адрес HTTPS-туннеля
AI_HOURLY_LIMIT	Общий лимит AI-операций на процесс за час; по умолчанию 30

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

Работа без ключа

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

7. Как проверить решение жюри

Сценарий воспроизводится без платного API. На чистой базе есть 5 задач, 5 команд и 5 откликов; у команд по 0 баллов. В существующей базе числа могут отличаться.

1. Откройте «Создать задачу». Введите: Магазин ведёт остатки в Excel. Нужно сократить ошибки учёта товаров. Нажмите «Задать вопросы».

2. Проверьте появление вопросов. Без ключа это шаблоны; с ключом — ответ выбранного провайдера. Для проверки реального AI ответьте на вопросы и нажмите «Составить карточку из ответов».

3. Для предсказуемого рейтинга вручную оставьте только эти значения, очистив остальные поля карточки:

   Поле	Значение
   Название	Учёт остатков магазина
   Контекст	Магазин ведёт остатки в Excel.
   Потребность	Нужно сократить ошибки учёта товаров.
   Данные и материалы	Синтетическая CSV-таблица с примерами товаров.

4. Предварительная готовность должна быть 40/100. Подтвердите сведения и опубликуйте карточку. Найдите её в каталоге через поиск.

5. Выберите «Я — команда», откройте задачу, выберите команду и заполните отклик: идея — Веб-интерфейс учёта; план — Изучить CSV, собрать прототип, проверить сценарии; срок — 14 дней; ссылка — https://example.com (тестовый адрес, не настоящий прототип).

6. Отправьте предложение. Переключитесь на «Я — бизнес», выберите эту команду и подтвердите этап.

7. В разделе «Команды» проверьте увеличение баллов выбранной команды на 25. Повторное начисление за тот же отклик недоступно.

8. Перезапустите сервер: созданная задача, отклик и баллы должны сохраниться в JSON-базе.

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

node --test

В средах, где запрещён запуск дочерних процессов, на Node.js 24:

node --test --test-isolation=none

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

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

• Начальные задачи, команды, описания и отклики генерируются в seed.mjs. Это синтетические демонстрационные данные, а не реальные клиенты или участники.
• Упоминание CSV в примерах — текст карточки. Загрузка файлов, чтение CSV и интеграция с Excel не реализованы.
• Пользовательские задачи, отклики и баллы сохраняются локально в data/db.json.
• Описание, поля и ответы передаются выбранному AI-провайдеру только при нажатии соответствующих AI-кнопок.
• Ссылки на прототипы открываются как внешние ссылки. Сервер проверяет HTTP/HTTPS-схему, но не наличие или качество прототипа.
• Автоматическая синхронизация с GitHub, CRM, университетскими системами и внешними базами отсутствует.

9. Ограничения текущей версии

• Нет регистрации, авторизации и серверного разграничения прав. Переключатель «бизнес/команда» — демонстрационный режим, а не защита доступа. Пользователи общего демо могут менять общие данные.
• Команды предзаданы; создание и редактирование профилей команд не реализованы.
• JSON-хранилище рассчитано на один серверный процесс. Нет полноценной СУБД, межпроцессной синхронизации и встроенного резервного копирования.
• В отклике можно подтвердить только один демонстрационный этап. Нет полноценного трекера проекта, чата, уведомлений и проверки фактического выполнения работы.
• Рейтинг задачи оценивает наличие текста, а не его содержание.
• AI-поля проверяются на совпадение с точными фрагментами исходных данных. Это ограничивает выдуманные сведения, но может отклонить корректный пересказ. Проверка не гарантирует фактическую истинность текста.
• AI зависит от доступности провайдера, модели и квоты. Таймаут отдельного вызова — 60 секунд; анализ содержит два последовательных вызова. Ошибки выводятся пользователю.
• Лимит AI общий для процесса и сбрасывается при перезапуске; это не полноценная защита публичного сервиса от злоупотреблений.
• Избранное хранится только в конкретном браузере, черновики — в текущей вкладке; синхронизации между устройствами нет.
• В коде есть проверка origin, типов запросов и ограниченная раздача статических файлов, но они не заменяют авторизацию.
• На хостинге с непостоянной файловой системой JSON-данные могут теряться при перезапуске или повторном развёртывании.

10. Размещение и демонстрационная версия

В репозитории есть render.yaml и DEPLOY.md, но наличие этих файлов не подтверждает выполненное развёртывание. Постоянный публичный адрес в конфигурации исходного проекта не закреплён.

Для текущей демонстрации используется временная ссылка Alem. Это адрес туннеля к локальному серверу, а не постоянный хостинг. Доступность зависит от работающего компьютера, сервера, интернета и процесса туннеля; адрес может измениться. Для воспроизводимой проверки используйте локальный запуск выше.

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