AI Sana

Локальный MVP платформы, где бизнес формулирует реальные задачи, а студенческие команды самостоятельно выбирают проекты и предлагают решения. AI помогает извлечь факты и задать уточняющие вопросы. Подтверждение, публикация и выбор команд всегда остаются за человеком.

Быстрый старт

Требуется Node.js 22 или 24 LTS.

npm ci
npm run dev

Откройте http://127.0.0.1:3000.

OPENAI_API_KEY необязателен. Без него приложение автоматически работает в резервном режиме (fallback).

Возможности

• Демо-переключатель бизнеса и студенческих команд, по пять профилей каждой роли. Это не авторизация.
• Конструктор: описание → 3–7 вопросов → редактируемая карточка → подтверждение → публикация.
• Живой предварительный рейтинг и отдельный подтверждённый рейтинг с разбивкой, рекомендациями и реальным изменением.
• Каталог всех опубликованных задач: поиск, отрасли, уровни готовности, сброс фильтров.
• Неограниченное число откликов; сравнение идей, планов, навыков и сроков; независимое принятие или отклонение.
• Принятая команда отправляет результат этапа; после подтверждения бизнесом получает 25 баллов прогресса. Повторное подтверждение не начисляет баллы второй раз.
• Серверное JSON-хранилище задач, команд, откликов, решений и результатов; синтетические начальные данные; явный сброс с подтверждением.
• OpenAI Responses API и честно обозначенный резервный режим без внешней модели.
• Адаптивный интерфейс на русском языке.

Запуск

Требуется Node.js LTS 22 или 24 (Next.js требует минимум 20.9). При разработке использованы Node.js 24.21.0 и npm 11.19.0. Точные версии зависимостей зафиксированы в package-lock.json.

npm ci
npm run dev

Откройте http://127.0.0.1:3000. Сервер по умолчанию слушает только локальный интерфейс.

Для production-режима:

npm run build
npm start

Windows

Для проверки проекта на другом компьютере или чистой установки достаточно установить официальный Node.js 22 или 24 LTS, открыть новый терминал VS Code и выполнить стандартные команды npm ci и npm run dev. Папка .tools не требуется. Если PowerShell блокирует npm.ps1, используйте npm.cmd ci и npm.cmd run dev.

Папка .tools — только локальное удобство разработки на исходном компьютере. В этом окружении переносимый Node.js уже загружен в игнорируемую папку .tools. Из терминала cmd.exe можно запускать без изменения системного PATH:

.tools\node-v24.21.0-win-x64\node.exe scripts\npm-local.mjs run dev

Аналогично замените run dev на run typecheck, run lint, run test, run build, run test:e2e или run test:ai. Установка: install --cache .tools/npm-cache. Папка .tools не входит в Git, на другом компьютере используйте обычный Node.js. В текущей среде запуск через cmd.exe оказался надёжнее PowerShell.

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

Существующий .env сохранён без изменений. Если файла ещё нет, создайте его по .env.example. Не копируйте пример поверх рабочего файла.

Переменная	Назначение
OPENAI_API_KEY	Серверный ключ OpenAI; необязателен для резервного режима
OPENAI_MODEL	Модель, по умолчанию gpt-4.1-mini
AI_MODE	fallback принудительно отключает внешний AI; пустое значение разрешает OpenAI
AI_SANA_DATA_FILE	Путь JSON-базы; по умолчанию .data/db.json

Все значения в .env.example пустые. Ключ не передаётся браузеру, не хранится в localStorage, не попадает в ответы API и логи. Другие провайдеры и ключи не используются. Конфигурация OpenAI задаёт официальный endpoint явно.

Стек и структура

Next.js App Router, React, TypeScript, Tailwind CSS 4, Zod, официальный OpenAI SDK, Lucide. Тесты: Node.js test runner + tsx и Playwright. База данных и облачная инфраструктура не нужны.

src/app/                  Страница приложения, стили и серверные API
src/components/           Кабинет, каталог, конструктор, рейтинг и отклики
src/lib/domain.ts         Типы и схемы Zod
src/lib/scoring.ts        Чистый детерминированный рейтинг
src/lib/service.ts        Правила публикации, откликов и прогресса
src/lib/storage.ts        Файловые транзакции
src/lib/seed.ts           Синтетический начальный набор
src/lib/ai/               Промпт, OpenAI, проверка фактов и fallback
scripts/ai-smoke.ts       Один реальный запрос, без вывода секретов
tests/domain.test.ts      Бизнес-правила и хранилище
tests/storage-worker.ts   Проверка сохранения между процессами
tests/e2e/                Браузерный сценарий
docs/DEMO.md              Пятиминутная демонстрация
docs/STATUS.md            Результаты проверок и ограничения

UI вызывает /api/state, /api/command и /api/ai. Команды проверяются Zod и доменными правилами на сервере. Демо-заголовки выбирают профиль, но не заменяют аутентификацию. Сервер проверяет принадлежность задачи/отклика выбранному профилю; студент не получает приватные черновики бизнеса и чужие отклики.

Подтверждение и публикация

У задачи раздельные draft, confirmed, published, score и revision. Сохранение черновика не меняет публичную карточку. «Сохранить и подтвердить изменения» создаёт подтверждённую копию и пересчитывает рейтинг на сервере. previousScore хранит рейтинг до последнего подтверждения: повторное подтверждение без изменений показывает прирост 0. Удаление полезных сведений уменьшает рейтинг. Конфликт версий из разных вкладок возвращает 409, чтобы не перезаписать чужие изменения.

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

Формула рейтинга

Рейтинг — сумма следующих независимых критериев. Максимум строго 100. Ни AI, ни клики, ни число сохранений, ни отклики не добавляют баллы.

Категория	Точные условия начисления
Контекст и потребность — 20	10 за содержательный context, 10 за содержательный problem
Данные и материалы — 20	10 за содержательный materials, 10 за содержательный access
Ожидаемый результат — 15	10 за содержательный result; ещё 5, если назван артефакт по словарю ниже
Критерии успеха — 15	5 за содержательный success; ещё 10 за число или маркер проверки
Ограничения — 10	5 за содержательный constraints; ещё 5 за конкретный маркер границ
Пользователи — 10	10 за содержательный users
Связь с бизнесом — 10	5 за контакт в формате email, HTTP(S)-ссылки или телефона; 5 за содержательный feedback

Содержательное поле: после удаления крайних пробелов есть минимум два различных слова/числа и суммарно минимум восемь букв/цифр. Под словами понимаются последовательности Unicode-букв и цифр. Повтор одного слова не проходит. Не учитываются точные заглушки без учёта регистра и завершающей пунктуации: потом, не знаю, уточнить, не указано, нет, неизвестно, тест, todo, tbd, na, n/a, нет данных, будет позже, не определено.

Дополнительные баллы требуют содержательного поля и совпадения с открытым словарём:

• Артефакт: прототип, систем, приложени, сайт, панел, отчёт/отчет, модел, макет, бот, дашборд, таблиц, интерфейс, исследован, карта, документ, сервис, алгоритм, анализ, дизайн, план.
• Проверка: любая цифра либо провер, тест, приём/прием, демонстрац, сценари, экспорт, импорт, без ошибок, подтвержд, чек-лист (также слитное написание или один иной разделитель).
• Границы: любая цифра либо нельзя, только, без , запрещ, не более, не менее, огранич, доступ, бюджет, срок, персональ, локаль, открыт, не требу.
• Контакт: email с @ и точкой домена, ссылка http:///https:// с непустым продолжением либо +, цифра и ещё минимум восемь символов из цифр, пробелов, скобок и дефиса. Это проверка формата, не реальности контакта.

Сопоставление словаря ищет подстроку без учёта регистра. Правила — прозрачная эвристика заполненности, а не доказательство правдивости или оценка качества текста. Длина сверх порога сама по себе не увеличивает баллы. «Данных пока нет; менеджер соберёт 20 примеров» может получить баллы за описанный план. Подсказки placeholder не являются значениями.

Уровни: 0–39 Черновик, 40–69 Рабочая, 70–89 Готовая, 90–100 Приоритетная. Уровень «Черновик» не означает запрета публикации.

Каталог, отклики и прогресс

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

Нет квоты откликов, в том числе для одной команды. Случайный повтор одной отправки подавляется UUID запроса и блокировкой кнопки. Идея, план и срок обязательны; ссылка на прототип необязательна, но при заполнении допускает только HTTP(S).

Бизнес принимает ноль, одну или несколько команд. Решение по одному отклику никогда не меняет остальные. Решение можно вернуть на рассмотрение. Принятие и отправка отклика не дают баллы. Баллы команды вычисляются по уникальным подтверждённым этапам: 25 × число подтверждённых этапов. Это отдельная шкала, не связанная с рейтингом задачи. Подтверждённый ранее результат остаётся фактом даже при последующем изменении статуса отклика.

OpenAI и резервный режим

Используется client.responses.parse() и zodTextFormat() по официальной документации Structured Outputs. По умолчанию выбрана GPT-4.1 mini, поддерживающая структурированные ответы.

Вызовы — только после нажатия пользователем: один для анализа и один для формирования карточки. Таймаут 20 секунд, автоматических повторов нет, максимум 3500 выходных токенов, описание до 10 000 символов, совокупный AI-вход до 22 000 символов, HTTP-body до 80 КБ. store: false. Системный промпт хранится отдельно, пользовательское описание передаётся как данные.

Ответ проверяется Zod и консервативной проверкой происхождения фактов. Описательные поля допускают ограниченный набор безопасных переформулировок, включая «звонят» → «связываются по телефону» и «записывает вручную» → «вручную фиксируются». Контакты, URL, числа, даты, суммы, проценты и сроки должны сохраняться точно; новые технологии и другие неподтверждённые сведения не принимаются. Это не универсальная проверка смысла: незнакомая или неоднозначная описательная формулировка оставляет поле пустым для ручного заполнения, а неподтверждённые точные факты включают fallback. Источники — исходное описание и ответы, связанные с конкретным полем; старый AI-черновик не служит доказательством. Вопросы очищаются от дублей и приоритетно относятся к незаполненным полям.

Отсутствие ключа, 401/403, 429, сетевой сбой, таймаут, отказ или невалидный ответ включают резервный анализ. В логах только безопасная категория ошибки. На экране явно показано «AI-анализ: OpenAI» либо «Резервный анализ: без внешней модели».

Fallback переносит исходное описание в проблему, распознаёт строки Название поля: значение и предложения с явными признаками полей (например, «Сейчас…», «Пользователи…», «Критерии…»), использует ответы, адресованные полям, и задаёт вопросы по незаполненным полям. Неподписанные факты из свободного текста не всегда распределяются автоматически; интерфейс об этом сообщает. Неизвестные значения остаются пустыми. Весь сценарий работает без API.

Отдельная проверка выполняет один небольшой реальный запрос с синтетическим описанием:

npm run test:ai

Этот smoke-test может расходовать API-кредиты. Обычные тесты их не расходуют. Реальный запрос успешно проверен при разработке; текущая доступность зависит от вашего ключа, лимитов и сети.

Хранение и сброс

По умолчанию данные находятся в .data/db.json, который игнорируется Git. Первый доступ создаёт seed только при отсутствии файла. Новые процессы читают существующую базу. Транзакция получает межпроцессную блокировку .lock, читает JSON, применяет команду, записывает временный файл, вызывает fsync и атомарно переименовывает его. Параллельные записи сериализованы; ожидание блокировки ограничено тремя секундами. Повреждённый существующий JSON не заменяется seed автоматически.

Сброс: в роли бизнеса нажмите «Сбросить демо-данные» внизу навигации, прочитайте последствия и нажмите «Подтвердить сброс». Восстановятся 5 задач разных отраслей и уровней (10, 65, 80, 100, 55 баллов), 5 команд и 5 откликов. Баллы seed рассчитываются производственной функцией. Все организации, контакты и ссылки синтетические (example.com, example.org).

При аварийном принудительном завершении во время записи может остаться .lock. Сначала остановите все экземпляры приложения, сохраните копию JSON, затем удалите только соответствующий .lock и перезапустите. Не удаляйте lock работающего сервера. Для нескольких инстансов и production нужна настоящая БД.

Проверки

npm run typecheck
npm run lint
npm test
npm run build
npx playwright install chromium
npm run test:e2e

Браузерный тест использует отдельный .data/e2e.json, порт 3100 и AI_MODE=fallback; пользовательская база не сбрасывается. Обычные тесты используют временные каталоги. В ограниченной Windows-песочнице tsx может требовать разрешённого запуска из-за uv_os_get_passwd; это ограничение окружения, не ошибка бизнес-логики.

Ограничения MVP

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

Пятиминутный сценарий: docs/DEMO.md. Точный статус проверок: docs/STATUS.md.

Сторонние компоненты

В проекте используются сторонние компоненты с открытым исходным кодом: Next.js, React, Tailwind CSS, Zod, OpenAI SDK, Lucide, Playwright и tsx. OpenAI используется как внешний AI API.

Основная бизнес-логика, расчёт рейтинга готовности, сценарии каталога и откликов, а также интерфейс этого MVP реализованы командой во время хакатона.