AI Sana Challenge Hub

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

Приложение состоит из веб-интерфейса, Node.js-сервера, локального JSON-хранилища и необязательной интеграции с OpenAI. Без ключа OpenAI основные сценарии доступны в демонстрационном режиме.

Что умеет программа

Для бизнеса

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

Для команды

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

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

• Задачи, уточняющие вопросы, команды, предложения и рейтинги хранятся в отдельных JSON-файлах в data/.
• Интерфейс также сохраняет рабочие данные в localStorage браузера и синхронизирует серверные записи при доступности API.
• Предварительная оценка в редакторе показывает полноту карточки по правилам интерфейса. Кнопка сохранения рейтинга запрашивает серверную оценку: с настроенным ключом баллы по критериям выставляет AI, итоговую сумму и уровень готовности вычисляет сервер.
• Если OpenAI не настроен или недоступен, генерация вопросов и карточки переключается на локальные шаблоны, а рейтинг — на оценку заполненности. Ответ содержит режим demo или fallback.

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

Веса серверной формулы дают максимум 100 баллов:

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

Уровни рейтинга: draft (0–39), in_progress (40–69), ready (70–89), priority (90–100). В интерфейсе они показываются как «Черновик», «Рабочая», «Готовая» и «Приоритетная».

Как запустить

Требуется Node.js версии 20 или новее. Дополнительные npm-пакеты проекту не нужны.

1. Откройте терминал в папке проекта.

2. Запустите сервер:

   npm start
   

3. Откройте в браузере http://localhost:3000.

Не открывайте index.html напрямую: интерфейс обращается к API сервера.

Для автоматического перезапуска сервера при изменении файлов используйте:

npm run dev

Подключить OpenAI

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

PowerShell:

$env:OPENAI_API_KEY="ваш-ключ"
$env:OPENAI_MODEL="gpt-5-mini"
npm start

macOS или Linux:

OPENAI_API_KEY="ваш-ключ" OPENAI_MODEL="gpt-5-mini" npm start

Можно также задать PORT, чтобы изменить порт сервера. Значение по умолчанию — 3000. Файл .env.example показывает имена переменных, но сервер автоматически не загружает .env.

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

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

В кабинете бизнеса доступна кнопка добавления демо-задач. Это тестовые примеры; они не являются реальными предложениями бизнеса.

API сервера

Все запросы и ответы API используют JSON. Ошибки возвращаются объектом с полем error.

Метод и путь	Назначение
POST /api/questions	Получить 3–5 вопросов по описанию и известным полям
GET /api/questions/demo	Посмотреть пример входа и локальных вопросов
POST /api/cards	Собрать одну карточку из описания, вопросов и ответов
GET /api/cards/demo	Посмотреть пример локальной карточки
GET /api/tasks	Получить список задач
POST /api/tasks	Создать задачу
PATCH /api/tasks/:id	Изменить разрешённые поля задачи
GET /api/clarifying-questions	Получить сохранённые вопросы и ответы
POST /api/clarifying-questions	Сохранить вопрос, ответ и связь с задачей
GET /api/teams	Получить команды
POST /api/teams	Создать команду
GET /api/proposals	Получить предложения команд
POST /api/proposals	Отправить предложение по задаче от команды
PATCH /api/proposals/:id	Изменить статус предложения и комментарий бизнеса
GET /api/ratings	Получить сохранённые рейтинги
POST /api/ratings/evaluate	Рассчитать и сохранить рейтинг задачи по taskId

Пример запроса на уточняющие вопросы

{
  "description": "В магазинах покупатели долго ждут помощи консультанта.",
  "industry": "Розничная торговля",
  "knownFields": {
    "context": "В часы пик свободного консультанта сложно найти."
  },
  "fieldsToCheck": ["context", "need", "users", "data", "constraints"]
}

Пример запроса на серверный рейтинг

{
  "taskId": "идентификатор-задачи"
}

Создание задачи через API требует businessId и title. Уточняющий вопрос должен ссылаться на существующую задачу. Предложение должно ссылаться на существующие задачу и команду.

Примеры создания записей

Создать черновик можно так:

{
  "businessId": "hackathon-demo-business",
  "status": "draft",
  "title": "Сократить время ожидания консультации",
  "topic": "Розничная торговля",
  "originalDescription": "Покупатели долго ждут помощи консультанта.",
  "context": "В часы пик свободного консультанта сложно найти.",
  "need": "Сделать получение консультации быстрее.",
  "users": "Покупатели магазина",
  "data": "Примеры обращений покупателей",
  "constraints": "Демонстрация через веб-браузер",
  "expectedResult": "Рабочий прототип записи на консультацию",
  "successCriteria": "Проверить прототип на пяти покупателях",
  "contact": "[email protected]",
  "interactionFormat": "Еженедельная встреча и ответы в чате"
}

Запрос POST /api/cards принимает description, industry, knownFields, массив questions и минимум три ответа answers. Каждый ответ содержит questionId и answer; questionId должен совпадать с ID одного из переданных вопросов.

Команда создаётся с полями name, interests, skills, technologies, description. Для POST /api/proposals укажите taskId, teamId, idea, plan; срок estimatedTerm, ссылка prototypeUrl и businessComment могут быть пустыми. Статусы предложений: pending, accepted, rejected.

При расчёте рейтинга API возвращает total, level, оценки по критериям в scores, список missingFields, рекомендации recommendations и источник оценки source (ai или local_stub). Сервер сохраняет рейтинг в истории и обновляет score, readinessLevel, missingFields задачи.

Где лежат данные

При первой записи сервер создаёт папку data/ и соответствующий файл:

• data/tasks.json — карточки задач;
• data/clarifying-questions.json — уточняющие вопросы и ответы;
• data/teams.json — команды;
• data/proposals.json — предложения команд и их статусы;
• data/ratings.json — история оценок карточек.

Эти JSON-файлы исключены из Git через .gitignore, поэтому локальные данные не попадают в коммиты автоматически. JSON-хранилище предназначено для прототипа и локальной демонстрации, а не для параллельной работы большого числа пользователей.

Основные поля моделей:

• Задача: id, businessId, status, title, topic, originalDescription, context, need, users, data, constraints, expectedResult, successCriteria, contact, interactionFormat, score, readinessLevel, missingFields, createdAt, updatedAt.
• Уточняющий вопрос: id, taskId, targetField, question, answer, source, createdAt.
• Команда: id, name, interests, skills, technologies, description.
• Предложение: id, taskId, teamId, idea, plan, estimatedTerm, prototypeUrl, status, businessComment, createdAt, updatedAt.
• Рейтинг: id, taskId, total, level, scores, missingFields, recommendations, source, createdAt.

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

• index.html, styles.css, app.js — основной интерфейс: кабинет бизнеса, мастер задачи, каталог, карточка задачи, кабинет команды и отклики.
• server.mjs — HTTP-сервер, API и раздача разрешённых файлов интерфейса.
• src/models.mjs — создание и нормализация моделей задачи, вопроса, команды, предложения и рейтинга.
• src/database.mjs — чтение и запись JSON-коллекций.
• src/question-generator.mjs — подготовка входа, шаблонные вопросы и проверка ответа AI.
• src/card-generator.mjs — подготовка входа, локальная карточка и проверка источников сведений.
• src/scoring.mjs — веса серверного рейтинга, ограничение баллов, расчёт суммы и уровня готовности.
• src/openai.mjs — запросы к OpenAI Responses API и строгие JSON-схемы.
• src/demo-data.mjs — примеры для демонстрационных API-маршрутов.
• previous-prototype/ — предыдущая версия интерфейса; текущий сервер её не запускает.
• business_questions.py — отдельный небольшой консольный пример на Python, не используемый веб-приложением.

Проверка проекта

Проверить синтаксис интерфейса и сервера:

npm run check

Запустить автоматические проверки:

npm test