Omnipotent

От описания бизнес-проблемы — к понятной задаче и решениям команд.

Omnipotent — веб-прототип для кейса HackAlem AI. Малому бизнесу бывает трудно сформулировать задачу так, чтобы студенческая команда могла начать работу: в описании не хватает данных, результата или критериев приёмки. Приложение помогает разобрать исходную ситуацию, увидеть пробелы и опубликовать задачу. Команды предлагают решения, а бизнес самостоятельно выбирает подходящие предложения.

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

• Отдельные кабинеты бизнеса и команды: создание профиля и повторный вход по имени, без пароля. Кнопка «Мой кабинет» доступна в навигации.
• Ручное заполнение или разбор по кнопке «Распределить описание с AI»: факты распределяются по полям карточки, оцениваются смысл, соответствие задаче и полнота; вопросы появляются для недостающих или неполных сведений.
• Редактируемые критерии, объяснения баллов и рекомендации. AI не должен придумывать отсутствующие контакты, сроки или данные; карточку проверяет человек.
• Предварительная оценка до подтверждения, круговые индикаторы готовности и анимация с учётом настройки уменьшенного движения.
• Сохранение пустого черновика, публикация с любым рейтингом, отдельное снятие с публикации.
• Общий каталог всех опубликованных задач и публичные решения команд. Поиск, сортировка по убыванию рейтинга, фильтры по отрасли, готовности и статусу «Открыто» / «Решено».
• Избранные задачи, привязанные к текущему профилю.
• Отклик команды: идея, план, сроки и необязательная ссылка на прототип.
• Выбор или отклонение решения владельцем задачи, письменная обратная связь, возможность выбрать несколько команд.
• Подтверждение результата: +10 баллов команде один раз за отклик. Эти баллы не входят в рейтинг готовности задачи.
• Удаление бизнесом своих задач и командой своих решений с подтверждением в интерфейсе.
• Числовая позиция в общем рейтинге, независимая от выбранных фильтров. Переходы с адресами страниц и работающими кнопками браузера «Назад» / «Вперёд».
• Серверное JSON-хранилище: задачи, профили, сессии, избранное и решения сохраняются между перезапусками.

Как работает решение

1. Бизнес открывает «Мой кабинет», выбирает роль и вводит название. Новое название создаёт профиль, существующее открывает его кабинет.
2. Создаёт задачу и описывает ситуацию обычным текстом. Можно заполнить критерии вручную или нажать «Распределить описание с AI».
3. По кнопке AI за один запрос извлекает уже указанные факты, раскладывает их по критериям, оценивает достаточность и формулирует уточнения. Без этой кнопки поля не изменяются автоматически. Пользователь видит результат рядом с описанием и может исправить каждое поле.
4. Изменение ответа после паузы запускает повторную смысловую оценку без перезаписи полей. Устаревший ответ запроса не должен заменять более новые правки. До подтверждения рейтинг является предпросмотром.
5. Пользователь подтверждает сведения и публикует. Достаточно непустого названия и подтверждения: слабая готовность не запрещает публикацию.
6. Команда просматривает каталог, сохраняет задачи в избранное, изучает чужие решения и отправляет своё.
7. Владелец бизнеса видит входящие решения в кабинете, выбирает или отклоняет их и оставляет обратную связь. Команда видит результат в своём кабинете. Бизнес может отметить задачу решённой или снова открытой.

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

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

Модель возвращает качество каждого ответа от 0 до 1 и пояснение. Сервер применяет фиксированные веса: баллы поля = round(качество × максимум поля). Итог — сумма полей. В интерфейсе виден отдельный индикатор каждого оцениваемого поля.

Проверяются конкретность, смысловая связь с исходной задачей и достаточность ответа. Само наличие текста не означает полный балл. Полезный частичный ответ получает часть баллов; пустые поля, очевидная бессмыслица и повтор одного ответа во многих полях не должны повышать рейтинг. Точное число, например 56/100, не задаётся заранее: оно получается из оценок критериев.

Уровни готовности: 0–39 — Черновик, 40–69 — Рабочая, 70–89 — Готовая, 90–100 — Приоритетная. Уровень «Черновик» описывает готовность и отличается от неопубликованного черновика. «Открыто» / «Решено» — отдельный статус, которым управляет владелец бизнеса.

При недоступности AI приложение показывает причину и резервные подсказки. Смысловая оценка не подменяется баллами за длину или наличие текста: резервная оценка равна 0 и явно обозначена как недоступная. Сохранять и публиковать задачу по-прежнему можно.

Технологии

Компонент	Использование
TypeScript	Общие типы, интерфейс и сервер
React 19, React DOM	Формы, каталог, кабинеты, навигация
Vite 7	Сервер разработки и сборка интерфейса
Node.js 22.12+ / 24, Express 5	HTTP API и раздача собранного приложения
OpenAI Responses API	Извлечение фактов, смысловая оценка, уточняющие вопросы
gpt-4.1-mini	Модель по умолчанию; настраивается через OPENAI_MODEL
Structured Outputs	Строгая JSON-схема ответа модели и дополнительная серверная валидация
JSON-файл	Локальное хранение данных без отдельной СУБД
Node Test Runner, Supertest, Testing Library, JSDOM	Проверки логики, API и пользовательских сценариев
CSS, SVG	Адаптивный интерфейс и круговые индикаторы

Для вызова OpenAI используется серверный fetch, отдельный OpenAI SDK не установлен. Шрифт Manrope загружается из Google Fonts, при недоступности используется системный шрифт.

Архитектура

Браузер: React + формы + навигация
                  │ /api
                  ▼
Express: сессия → валидация → проверка владельца
          │                         │
          ▼                         ▼
server/analysis.ts             data/store.json
OpenAI Responses API           профили, задачи,
извлечение + оценка + вопросы   решения, избранное, сессии
          │
          ▼
shared/scoring.ts → фиксированные веса → интерфейс

• src/App.tsx, src/styles.css — пользовательские экраны, автоматический анализ и отображение результатов.
• shared/types.ts, shared/scoring.ts — контракты, веса критериев и проверка актуальности оценки.
• server/app.ts — API, сессии, права текущего профиля, сохранение и миграция данных.
• server/analysis.ts — разбор описания по кнопке, проверка цитат-источников и оценка полей.
• server/evaluation.ts — серверная оценка при сохранении подтверждённой карточки, если нет подходящего результата в кеше.
• server/openai.ts, server/ai.ts — настройки провайдера, совместимый маршрут уточнения и резервные вопросы.
• server/seed.ts — синтетические примеры при первом запуске.
• tests/ — автоматические проверки; docs/ — сценарии и дополнительные демонстрационные данные.

POST /api/analyze принимает {description, industry, fields} и возвращает {mode, notice, fields, questions, assessment}. Баллы от браузера не принимаются как достоверные: сервер сам получает оценку. Успешные оценки кешируются в памяти процесса для сохранения той же карточки; ошибки не кешируются.

Другие маршруты: /api/session, /api/state, /api/tasks, /api/tasks/:id/status, /api/proposals, /api/favorites/:id, /api/ai/status. Чужие неопубликованные задачи скрыты; публичные решения видны вместе с опубликованной задачей. Менять статус и решения бизнеса может только владелец соответствующей задачи, удалять своё предложение — его команда.

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

Нужны Node.js 22.12+ или 24 и npm. Приватный репозиторий требует доступа к GitHub.

git clone https://github.com/BAITC-Hacks/hack-f3361f1e-omnipotent.git
cd hack-f3361f1e-omnipotent
npm ci

Настройка AI

Если .env ещё нет:

cp .env.example .env

В PowerShell: Copy-Item .env.example .env. Если файл уже существует, отредактируйте его, сохранив свои настройки.

OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4.1-mini
PORT=3001

Ключ вписывается только в локальный .env; файл исключён из Git. Не добавляйте префикс VITE_: секрет должен оставаться на сервере. Сервер читает .env при запуске; переменные окружения процесса имеют приоритет. После изменения ключа или модели перезапустите сервер.

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

Разработка

npm run dev

Откройте http://localhost:5173. Vite перенаправляет /api на Express по 127.0.0.1:3001. Эти порты должны быть свободны. Остановка — Ctrl+C.

Собранное приложение

npm test
npm run build
npm start

Откройте http://localhost:3001. Команда build сама сервер не запускает. npm start использует tsx, поэтому нужны установленные devDependencies.

Другой порт для собранного приложения: PORT=3002 npm start (macOS/Linux) или $env:PORT=3002; npm start (PowerShell). Для разработки оставьте API-порт 3001, как в конфигурации Vite.

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

1. Откройте приложение, нажмите «Мой кабинет», выберите бизнес и войдите как Демо-магазин. Создайте задачу.

2. Вставьте в описание одним текстом:

   В нашем магазине популярные товары заканчиваются до следующей поставки. Закупки планируют два менеджера вручную. Хотим прогнозировать спрос и получать рекомендации по заказу. Можем передать обезличенный CSV продаж и остатков за 6 месяцев, около 20 000 строк. Нужен веб-прототип с прогнозом на 14 дней и выгрузкой заказа. Прототип нужен за две недели, без платных интеграций. Контакт: [email protected].

3. Нажмите «Распределить описание с AI» и дождитесь ответа. Проверьте распределение фактов по полям, круговую оценку и уточнения, например о проверке результата или регулярности обратной связи. Не сравнивайте ответ с заранее заданным числом: AI-оценка может различаться.

4. Дополните критерии успеха: На отложенном месяце ошибка прогноза ниже простого среднего, пять сценариев заказа проходят без потери данных. Дождитесь обновления и изучите объяснение.

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

6. Добавьте задачу в избранное, откройте её из соответствующего раздела. Проверьте «Назад» и «Вперёд» браузера, фильтры готовности и статуса.

7. Выйдите и войдите как команда Демо-команда. Откройте задачу, просмотрите существующие решения и отправьте своё: идея — Прогноз по истории продаж, план — Проверим CSV, сравним модель со средним, соберём интерфейс, срок — 10 рабочих дней.

8. Снова войдите как Демо-магазин. В кабинете выберите или отклоните решение с комментарием. В кабинете команды проверьте ответ бизнеса. Отметьте задачу «Решено» и проверьте фильтр.

9. Для проверки удаления используйте отдельную тестовую задачу и решение. Удалите решение от имени его команды, затем задачу от имени её бизнеса. Чужих кнопок удаления быть не должно.

Дополнительные наборы: docs/additional-test-data.md. Проверочный сценарий: docs/user-scenario-and-test-data.md.

npm test
npm run build
# Обе проверки последовательно:
npm run check

Автоматические тесты подменяют AI-провайдер и не расходуют API-кредиты. Они проверяют извлечение и оценку, ошибки провайдера, формулу, доступ по ролям, публичность решений, избранное, статусы, удаление, сохранение и пользовательский сценарий.

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

При первом запуске создаются пять демонстрационных бизнесов, пять задач, пять команд, пять предложений и пять исходных описаний. Это синтетические данные; контакты и ссылки example.org — примеры, а не работающие интеграции.

Данные хранятся в data/store.json и исключены из Git. Сохранение выполняется через временный файл с переименованием. При миграции старого формата создаётся резервная копия рядом с хранилищем. Задачи старой версии без владельца доступны бизнесу «Мой бизнес». Не удаляйте файл для обычного обновления приложения.

Вызовы OpenAI идут только с сервера, с store: false, строгой схемой и тайм-аутом. При нажатии «Распределить описание с AI» описание, отрасль и ручные правки отправляются в OpenAI для извлечения. После изменения полей смысловая оценка запускается автоматически после паузы. Проверка при подтверждённом сохранении также может вызывать API. Ключ и сырые ответы об ошибках провайдера в браузер не передаются. GET /api/ai/status показывает наличие настройки, а не гарантирует успешный доступ к API.

Документация интеграции: OpenAI Structured Outputs.

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

• Вход по имени не подтверждает личность. Любой, кто вводит то же название, открывает тот же профиль. Это осознанное упрощение хакатонного прототипа; паролей и восстановления доступа нет.
• AI может ошибиться при извлечении или оценке. Человек проверяет факты и подтверждает публикацию; баллы — ориентир готовности, а не гарантия успешного проекта.
• JSON-хранилище рассчитано на один процесс сервера. Нет промышленной БД, распределённых сессий и защиты от параллельной записи нескольких процессов.
• Нет загрузки файлов, чата, почтовых уведомлений, оплаты или подключений к CRM. Данные и ссылки на материалы пока описываются текстом.
• Новые отклики на решённую задачу закрыты; владелец может снова открыть её.
• Удаление задачи удаляет связанные отклики и записи избранного. Удаление подтверждённого решения отменяет его +10 баллов команде. Корзины и восстановления через интерфейс нет.
• Автоматические запросы расходуют квоту OpenAI; пауза при вводе сокращает их число, но не делает API бесплатным. При сбое нет бесконечных автоматических повторов.
• После ухода из редактора несохранённые изменения не записываются на сервер автоматически: используйте «Сохранить черновик».

Развёрнутая версия

Публичная deployed-версия в репозитории не указана. Подтверждённый способ запуска — локально по командам выше. Сервер по умолчанию слушает 127.0.0.1; внешнее размещение, домен и HTTPS требуют отдельной настройки.

Готовые оценки демонстрационных карточек

Пять исходных карточек включают сохранённые результаты настоящей AI-проверки: 8, 15, 41, 57 и 77 из 100. Поэтому после чистого запуска рейтинг виден сразу, даже без API-ключа. Результаты и объяснения находятся в server/seed-assessments.json; это оценки синтетических примеров, а не выдуманные данные пользователя. При обновлении прежние неизменённые примеры получают эти оценки автоматически. Совпадение проверяется по всем полям и исходному описанию: отредактированной задаче чужая оценка не присваивается. Для новых или изменённых карточек необходима новая AI-проверка.

Проверка требований кейса

• Рекомендации по улучшению доступны при создании и редактировании, в карточке задачи и на её карточке в кабинете владельца. Рядом указано, сколько баллов можно дополнительно получить.
• Чем выше содержательная готовность, тем выше задача в каталоге. Показывается позиция #N из M; фильтры не изменяют глобальную позицию. Равные рейтинги упорядочиваются по времени создания, затем идентификатору.
• AI-извлечение возвращает цитаты-источники. Сервер проверяет, что текст каждого автоматически заполненного поля состоит из точных фрагментов описания. Неподтверждённые текстом контакты, суммы, сроки и другие значения отбрасываются. Ручные правки, включая намеренно очищенное поле, сохраняются. Проверка источника не заменяет проверку смыслового соответствия человеком.
• Результат редактируется и подтверждается человеком; бизнес сам выбирает одну, несколько или ни одной команды. Автоматического назначения нет.
• Общий каталог не ограничивается интересами команды. Персонализированные AI-рекомендации студентам по навыкам в этой версии не реализованы: это допустимая возможность кейса, а не автоматический подбор исполнителей. Есть общий рейтинг, поиск, фильтры и избранное.
• Профили команд содержат название, интересы, навыки и технологии. Пол, возраст, национальность, здоровье и другие чувствительные признаки участников не собираются для оценки или ранжирования.

Минимальные наборы представлены в docs/demo-data.json: 5 черновиков, 5 карточек со всеми критериями и readinessScore, 5 профилей команд и 5 предложений с идеей, планом, сроком и ссылкой. Дополнительные описания для копирования на сайт — в docs/additional-test-data.md.

Обязательный сценарий «слабое описание → дополнение → рост рейтинга → публикация → отклик → ручное решение» и готовые тексты — в docs/user-scenario-and-test-data.md.