AI Sana Challenge Hub

Проект команды ProGulSHIK II для HackAlem AI. Веб-приложение помогает бизнесу превратить короткое описание проблемы в задачу для студентов: уточнить сведения, собрать карточку, повысить её готовность и опубликовать. Студенческие команды самостоятельно отправляют предложения, а бизнес вручную выбирает исполнителей.

Запуск для жюри

Нужен Node.js 22.18 или новее с npm. Скачать исходники можно из репозитория кнопкой Code → Download ZIP, затем распаковать. Либо:

git clone https://github.com/BAITC-Hacks/hack-67f2bb71-progulshik-ii.git
cd hack-67f2bb71-progulshik-ii
npm install
npm start

При скачивании ZIP выполните последние две команды в распакованной папке с package.json. На Windows также можно открыть START_WINDOWS.cmd после установки Node.js.

Откройте http://127.0.0.1:3001. Интерфейс и сервер запускаются вместе; отдельная сборка не нужна. Окно запуска должно оставаться открытым. Остановка — Ctrl+C.

API-ключ для запуска не нужен. По умолчанию вопросы создаются локальными правилами; интерфейс обозначает демонстрационный режим. Карточки, рейтинг, каталог и отклики при этом работают с настоящей локальной базой. Чтобы включить внешний ИИ, нажмите «Настройки ИИ», вставьте собственный ключ и выберите «Подключить и проверить». Изменять файлы или перезапускать приложение не нужно.

• Подробная инструкция и решение проблем
• Сценарий защиты на пять минут
• Контракт API
• Архитектура интерфейса
• Как продолжать разработку

Возможности MVP

• Короткое описание задачи → минимум три уточняющих вопроса → редактируемая карточка из десяти полей.
• Подтверждение человеком, проверка содержания полей, рейтинг 0–100 с расшифровкой и рекомендациями, публикация.
• Каталог всех опубликованных задач: поиск, фильтры темы и готовности, сортировка по рейтингу. Низкий рейтинг не запрещает отклики.
• Демонстрационное переключение «Бизнес / Команда», выбор и создание профиля команды.
• Отклик с идеей, планом, сроком и ссылкой на прототип; просмотр статуса отправленных предложений.
• Просмотр предложений бизнесом и ручное принятие или отклонение. Можно принять несколько команд; автоматического назначения нет.
• Сохранение задач, вопросов и ответов, команд и откликов в SQLite; проверка ввода и защита карточек от перезаписи устаревшей версией.
• Начальный набор: 5 черновиков, 5 опубликованных карточек, 5 команд и 5 откликов.
• Подключение собственного API-ключа через «Настройки ИИ» и возврат к демонстрационному режиму.

Как устроен рейтинг

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

Баллы начисляются только за поля, которые подтвердил человек и которые прошли проверку содержания. При нажатии «Подтвердить и оценить» сервер проверяет всю карточку: описаны ли пользователи, результат, измеримые критерии и другие требуемые сведения. Набор букв, заглушки и ответы без нужной конкретики не добавляют баллов за соответствующее поле; рядом появляется пояснение. Веса из таблицы задаёт программа, ИИ не назначает произвольный балл. Название обязательно для публикации, но не добавляет баллы.

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

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

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

Внешний ИИ — по желанию

Подключение в приложении

1. Откройте приложение на http://127.0.0.1:3001 и нажмите «Настройки ИИ».
2. Вставьте собственный ключ в поле «API-ключ OpenAI». Поле скрывает введённые символы.
3. Оставьте предложенную модель или укажите модель, доступную вашему API-аккаунту.
4. Нажмите «Подключить и проверить». Сервер отправит один короткий запрос с вымышленным описанием задачи; проверка расходует средства API. Нужны интернет, действующий ключ и доступный баланс.

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

Введённый здесь ключ хранится только в памяти запущенного сервера. Он не записывается в файлы, SQLite, Git, cookies или хранилище браузера и не возвращается при чтении настроек. После остановки и нового запуска сервера его нужно ввести снова. При обновлении страницы сервер продолжает использовать ключ. Настройки общие для вкладок, работающих с этой копией приложения.

Кнопка «Деморежим» отключает внешний ИИ и удаляет активный ключ из памяти приложения. Файл .env не изменяется: при следующем запуске снова применяются настройки запуска. Управление ИИ доступно только при обращении к серверу с этого же компьютера через локальный адрес 127.0.0.1, localhost или ::1.

Постоянная настройка через файл — по желанию

Если нужно подключать ИИ автоматически после перезапуска, скопируйте .env.example в .env. Для Windows PowerShell:

Copy-Item .env.example .env

В локальном .env укажите:

AI_MODE=openai
OPENAI_API_KEY=ваш_собственный_ключ
OPENAI_MODEL=gpt-4o-mini

Модель должна быть доступна вашему API-аккаунту. Перезапустите приложение после изменения файла. Ключ используется только сервером; .env исключён из Git и не передаётся в браузер. Этот способ не обязателен для подключения через «Настройки ИИ».

Промпт, формат JSON и обработка ответа находятся в backend/ai.js. Используется OpenAI Responses API. Сервер проверяет структуру ответа, сохраняет приоритет введённых человеком сведений и отбрасывает предложения без дословного подтверждения во входных данных. Пользователь проверяет смысл и подтверждает карточку перед публикацией.

Режимы подготовки карточки: mock — локальные правила без внешних запросов; openai — ответ внешнего ИИ; fallback — локальные правила при отсутствии ключа, таймауте или некорректном ответе. Источник проверки качества обозначается отдельно: local, openai или fallback. ИИ помогает оценить содержание полей; фиксированную формулу баллов применяет сервер. ИИ не публикует задачи и не выбирает команды.

Архитектура

frontend/                  HTML, CSS и JavaScript без сборщика
  js/app.js                редактор, навигация и переключение роли
  js/http-service.js       связь редактора с API
  js/collaboration.js      каталог, команды и отклики
  js/ai-settings.js        окно подключения ИИ
backend/
  app.js                   HTTP API и выдача интерфейса
  schema.js                поля и валидация Zod
  scoring.js               рейтинг готовности
  quality.js               проверка содержания и актуальности отчёта
  ai.js                    промпт, внешний ИИ и резервный режим
  ai-runtime.js            настройки ИИ и временный ключ в памяти сервера
  store.js                 SQLite
  seed.js                  синтетические примеры
  server.js                запуск сервера
  tests/                   автоматические проверки
shared/                    типы данных и API-клиент
scripts/demo.mjs            сценарий API с базой в памяти
docs/                      запуск, защита, API и разработка

Node.js, Express 5, Zod 4, встроенный node:sqlite. При первом запуске создаётся data/hub.sqlite; данные сохраняются между перезапусками. У каждого скачавшего проект своя база. Кнопка сохранения отправляет на сервер также текущие вопросы и ответы; ещё не сохранённый ввод дополнительно хранится в браузере. Для установки через pnpm доступен pnpm-lock.yaml.

Команды для разработчиков

npm run dev:server
npm test
npm run demo

Первая команда перезапускает сервер при изменении кода. Тесты используют встроенный node:test и имитацию внешнего ИИ. Скрипт demo проходит сценарий API с временной базой в памяти, не меняя сохранённые задачи и не расходуя API-кредиты. Полный пользовательский сценарий описан в DEMO.md.

Границы версии

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

Данные примеров вымышлены; адреса example.test и ссылки на демонстрационные прототипы — заглушки. Рейтинг отражает подтверждение и проверку содержания полей, но не устанавливает достоверность фактов или реализуемость задачи. Локальные правила распознают типовые ошибки и недостаток сведений; они не гарантируют обнаружение любого бессмысленного текста. Оценка ИИ тоже может ошибаться, поэтому человек проверяет карточку перед публикацией. Регистрация, чат, загрузка файлов, уведомления и полноценный трекер выполнения проектов не входят в эту версию.