HackAlem AI — LogicX

Описание проекта

SanaBusiness — это MVP-платформа для бизнес-задач, которая помогает структурировать идею, оценивать её готовность к реализации и находить подходящие студенческие команды для выполнения проекта. Решение создано как демонстрационный продукт для хакатона и предназначено для двух ролей: бизнеса и команды.

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

Проблема, которую решает проект

Часто бизнес описывает задачу слишком коротко, поэтому студентам сложно понять, за что браться. В таком виде задача не всегда достаточно ясна, плохо структурирована и не имеет понятных критериев качества. SanaBusiness помогает перевести неформальную идею в понятную карточку с ограничениями, критериями и ожидаемым результатом.

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

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

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

1. Бизнес открывает интерфейс в роли «Бизнес».
2. Он описывает задачу в краткой форме.
3. AI задаёт уточняющие вопросы и помогает заполнить поля карточки.
4. Система оценивает готовность задачи по рейтингу.
5. Бизнес подтверждает карточку и публикует её в каталоге.
6. Команда в роли «Команда» открывает задачу и отправляет отклик.
7. Бизнес просматривает отклики, выбирает подходящую команду или отклоняет часть заявок.
8. Данные сохраняются локально в браузере и доступны после перезагрузки страницы.

Технологии

Frontend

• React 18
• Vite
• JavaScript / JSX
• Tailwind CSS

Backend / server-side

• Node.js
• Vite dev/preview middleware
• собственный API endpoint /api/ai

AI и интеграции

• OpenAI Responses API
• модель по умолчанию: gpt-4o-mini
• переменные окружения: OPENAI_API_KEY, OPENAI_MODEL

Инструменты и проверки

• Node.js test runner (node --test)
• Vite build
• локальное хранение в localStorage

Архитектура проекта

Проект состоит из нескольких ключевых частей:

• src/App.jsx — координация состояния приложения, роли пользователя и бизнес-логики.
• src/components/TaskForm.jsx — форма создания задачи и AI-подсказок.
• src/components/Catalog.jsx — каталог задач и фильтрация/сортировка.
• src/components/TaskDetails.jsx — карточка задачи, отклики команды и управление решениями бизнеса.
• src/components/TaskEditor.jsx — редактор уже опубликованной задачи.
• src/utils/calculateScore.js — расчёт рейтинга готовности задачи.
• src/utils/submissions.js — валидация откликов, безопасные ссылки, статусы решений.
• src/utils/taskEditing.js — логика редактирования и подтверждения изменений.
• server/ai.js — серверный слой для вызова OpenAI и проверки входных данных.
• server/check-ai.js — проверка AI-сервиса через HTTP.
• data/initialData.json и src/data/initialData.json — стартовые данные для демонстрации и совместимости.

Основной поток взаимодействия:

• пользовательский интерфейс React отправляет запросы к серверному /api/ai;
• сервер вызывает OpenAI с JSON-схемой;
• ответ проходит валидацию и используется для заполнения карточки или подсказки;
• данные хранятся в localStorage браузера и используются далее в интерфейсе.

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

Требования

• Node.js 20+ (в проекте проверялся на Node.js 22)
• доступ к OpenAI API key для AI-функций

Шаги установки

1. Клонируйте репозиторий.
2. Установите зависимости:

npm install

3. Создайте файл .env рядом с package.json на основе .env.example:

cp .env.example .env

На Windows PowerShell:

Copy-Item .env.example .env

4. В .env добавьте ключ OpenAI:

OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4o-mini

Ключ не должен попадать в Git-репозиторий. В проекте используется .env.example как шаблон.

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

Локальная разработка

npm run dev

После этого откройте адрес, который покажет Vite в терминале.

Проверка сборки

npm run build
npm run preview

Не открывайте dist/index.html напрямую. Для корректной работы AI и приложения нужен HTTP-сервер.

Запуск тестов

npm test

Проверка AI напрямую

npm run ai:check

Эта команда выполняет реальные вызовы к OpenAI и может потребовать API-кредиты.

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

Для жюри можно повторить следующий сценарий:

1. Открыть проект в браузере.
2. В роли «Бизнес» ввести краткую идею задачи.
3. Использовать AI-уточнение, чтобы получить вопросы и заполнить карточку.
4. Подтвердить и опубликовать задачу в каталоге.
5. Переключиться в роль «Команда» и открыть карточку.
6. Заполнить отклик: идея решения, план, срок, ссылка на прототип.
7. Отправить отклик.
8. Вернуться в роль «Бизнес» и принять или отклонить отклик.
9. Перезагрузить страницу и убедиться, что данные сохраняются.
10. Проверить, что поля с пустыми значениями или некорректной ссылкой не проходят валидацию.

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

Источники данных

• стартовые демо-данные в data/initialData.json;
• локальные данные в localStorage;
• миграция старых данных через src/utils/demoState.js.

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

• OpenAI Responses API для генерации вопросов и подсказок;
• Vite dev server и preview server для доступа к /api/ai.

Ограничения по данным

• данные хранятся только в локальном браузерном хранилище;
• авторизация между пользователями не реализована;
• роли демонстрационные и используются только в UI.

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

• Проект является демонстрационной MVP-версией, а не полноценной production-системой.
• AI работает только через серверный endpoint и требует корректного .env с OPENAI_API_KEY.
• Статическая сборка без HTTP-сервера не поддерживает AI-функции.
• В текущей версии отсутствует реальная синхронизация между устройствами и пользователями.
• В проекте не реализованы баллы студентам за подтверждённый этап по шагу 8 ТЗ, что отмечено в документации команды.
• Для полного демонстрационного сценария нужно вручную проверить интерфейс в браузере.

Deployed-версия

Ссылка на deployed-версию в текущем репозитории не указана. Проект представляет собой локальную демонстрационную версию, рассчитанную на запуск в среде разработчика или на локальном сервере.

Дополнительные материалы

• TEAM_TASKS.md — распределение задач и финальная проверка команды.
• prompts.txt — исходные AI-промпты.
• server/ai.js — серверная логика AI.

Итог

SanaBusiness — это локальная демонстрационная платформа, которая объединяет AI, бизнес-задачи и командный поиск исполнителей. Она позволяет структурировать задачу, оценивать её готовность, публиковать проект в каталоге и управлять откликами команд, оставаясь в пределах MVP-подхода и реального репозитория проекта.