AI Sana Challenge Hub · ShoqanAI

Рабочий интерактивный MVP для HackAlemAi: бизнес превращает короткую потребность в карточку, студенты отправляют предложения, бизнес самостоятельно выбирает команды.

Запуск

Запуск на Windows

Распакуйте проект в обычную папку, затем дважды нажмите start.bat. Скрипт запускает локальный сервер именно из папки проекта, выбирает свободный порт и открывает главную страницу в браузере по умолчанию. Оставьте появившееся окно консоли открытым; для остановки нажмите Ctrl+C.

Требуется Python 3. Сборка, npm-пакеты и API-ключ не нужны.

Запуск вручную

Из корневой папки проекта выполните:

python start.py

Если команда python недоступна в Windows, используйте py -3 start.py. Скрипт напечатает локальный адрес и откроет его в браузере. Если браузер не открылся автоматически, скопируйте напечатанный адрес в Chrome, Edge или Firefox.

Не открывайте index.html из окна ZIP-архива или временной папки. При белой странице закройте старую вкладку, запустите start.bat из распакованной папки и перейдите по новому адресу, напечатанному в окне.

tests.html запускает 23 проверки бизнес-логики. Интеграционные проверки обработчиков запускаются командой node tests/workflow.cjs при установленном Node.js. Интерфейс использует системные шрифты: внешние шрифты, библиотеки и CDN не загружаются. Основной функционал работает без интернета.

Удобство повседневной работы

• Мои черновики: ответы и шаг сохраняются автоматически. После перезагрузки откройте раздел и нажмите «Продолжить». Можно вести несколько черновиков; новая задача не стирает предыдущую.
• Редактирование: изменения опубликованной карточки сохраняются отдельно. Каталог обновится после повторного подтверждения. Галочка согласия не восстанавливается автоматически.
• Избранное: звёздочка сохраняет задачу в этом браузере. Фильтр показывает избранные задачи, а сброс возвращает общий каталог. Это список браузера, не отдельного профиля команды.
• Поиск: несколько слов в любом порядке, без учёта регистра и различия «е»/«ё», по названию, компании, теме, контексту, потребности, результату, пользователям и данным. Счётчик показывает число результатов; сортировка по рейтингу сохраняется.

Планы дальнейшего развития — в docs/ROADMAP.md.

Адаптивность и доступность

• Компьютеры: боковая навигация, многоколоночный каталог, ограниченная ширина контента на больших мониторах.
• Планшеты до 1000 px: раскрывающееся меню вместо постоянной боковой панели.
• Экраны до 760 px: формы и рейтинг в одну колонку; предварительный рейтинг виден над конструктором.
• Телефоны до 480 px: карточки и фильтры в одну колонку, основные действия на всю ширину.
• Поля ввода имеют размер текста 16 px; интерактивные кнопки — высоту не менее 44 px. Учтены safe-area на устройствах с вырезами, альбомная ориентация и длинные названия.
• Предусмотрены переход к содержимому с клавиатуры, видимый фокус, состояния меню и ролей для скринридера, закрытие меню клавишей Escape и настройка уменьшения движения.

Перед демонстрацией проверьте размеры 320, 375, 390, 768, 1024, 1440 и 1920 px, обе ориентации и масштаб браузера 200%. Отдельно откройте меню, конструктор, карточку с длинным текстом и форму отклика. Реальные устройства и браузерная отрисовка в среде разработки не проверены; адаптация не является гарантией поддержки всех моделей устройств.

Целевая аудитория и ценность

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

Реализованный сценарий

Черновик → 3 открытых уточняющих вопроса → редактируемая карточка → ручное подтверждение → каталог → отклик → ручной выбор или отклонение → подтверждённый этап (+50 баллов).

Переключатель «Для бизнеса / Для студентов» имитирует роли для защиты. Это не авторизация. Демо-кабинет бизнеса управляет всеми синтетическими задачами.

Архитектура

Файл	Назначение
index.html	Точка входа
start.bat	Запуск проекта в Windows двойным щелчком
start.py	Локальный сервер с автоматическим выбором свободного порта
styles.css	Базовые стили интерфейса
responsive.css	Адаптивные раскладки, сенсорный ввод и доступность
theme.css	Тема AI Sana: зелёная палитра, лаймовые акценты, оформление карточек и форм
favicon.svg	Значок проекта для вкладки браузера
app.js	Экраны, формы, валидация, localStorage
ai_server.py	Локальный API-прокси OpenAI с проверкой запросов и ответов
ai-client.js	Вызовы AI API и обработка ошибок
domain.js	Рейтинг, уровни, контракт помощника, проверка этапов
data.js	10 подробных черновиков и карточек, 5 команд, 5 демонстрационных откликов
tests.html	Проверки доменной логики
tests/workflow.cjs	Проверки восстановления и полного сценария с имитацией DOM
DEMO.md	Сценарий защиты до 5 минут

Данные хранятся в localStorage с ключом aisana-hub-v1. В разделе «Как это работает» доступен экспорт JSON с актуальным рейтингом карточек. При недоступности хранилища приложение работает в памяти и предупреждает об этом. Черновики сохраняются в workbench, избранное — в favorites. Эти поля добавляются к ранее сохранённым данным без сброса задач и откликов и входят в экспорт JSON. После публикации соответствующий черновик убирается из списка. Очистка браузерного хранилища удаляет локальные данные.

Оформление

theme.css подключается после базового styles.css. Основные цвета задаются CSS-переменными: тёмно-зелёный для навигации и действий, лаймовый для акцентов и светлый нейтральный фон для рабочего пространства. Цвет направления привязан к теме задачи и сохраняется при сортировке. Уровни готовности и статусы предложений имеют отдельные классы; текстовые подписи остаются доступными независимо от восприятия цвета. Добавлены SVG-иконки навигации, клавиатурная ссылка перехода к содержимому, состояния фокуса и поддержка уменьшенного движения. Компоновка адаптируется к ноутбукам, планшетам и телефонам. Доменная логика и сохранённые данные не изменены.

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

score = Σ weight[i] × completeAndConfirmed[i].

Критерий	Вес	Поля
Контекст и потребность	20	context + need
Данные и материалы	20	data
Ожидаемый результат	15	result
Критерии успеха	15	success
Ограничения	10	constraints
Пользователи	10	users
Связь с бизнесом	10	contact + interaction

Критерий засчитывается целиком, если все его поля содержат непустой текст и подтверждены человеком. Название и компания обязательны для публикации, но не дают баллов. Это проверка полноты, а не автоматическая оценка достоверности текста. За содержательность и измеримость критериев отвечает подтверждающий представитель бизнеса.

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

Уровни: 0–39 — черновик; 40–69 — рабочая; 70–89 — готовая; 90–100 — приоритетная.

Правила каталога и команд

Все опубликованные задачи доступны всем командам, включая рейтинг 0. В кабинете бизнеса задачи сортируются по рейтингу готовности; в кабинете студента — по совпадению с профилем выбранной команды. Есть поиск, фильтр по теме и уровню. Для студента показаны балл совпадения и причины рекомендации. Это простая объяснимая эвристика по теме, навыкам и технологиям команды, не машинная оценка качества. Количество откликов не ограничено. Автоматического назначения нет. Бизнес может выбрать несколько команд, отклонить все или оставить предложения на рассмотрении.

За выбор команды баллы не начисляются. После выбора команда и бизнес проходят 4 этапа проекта: обсуждение, прототип, проверка и завершение. На каждом этапе бизнес фиксирует срок и результат; после принятия последнего этапа команда получает +50 баллов один раз. Чтобы увидеть сценарий, откройте одну из демонстрационных заявок, выберите команду и пройдите этапы в разделе «Мои проекты».

AI-функция: OpenAI и локальный резервный режим

Добавлены чат Sana AI и анализ задачи через OpenAI Responses API. Для включения сохраните ключ в .env и запускайте сайт через start.bat или python start.py. Подробная инструкция: docs/AI_SETUP.md. Без ключа или сервера конструктор использует явно обозначенные локальные вопросы. Чат не имитирует ответы модели при отсутствии подключения.

Промпт доступен в Hub.prompt (domain.js) и в интерфейсе. Контракт:

{
  "input": {"draft": "Хотим сократить списания в кафе", "topic": "Ритейл", "fields": {"context": "Хотим сократить списания в кафе"}},
  "output": {"questions": [
    {"field": "need", "question": "Что необходимо изменить и почему это важно?"},
    {"field": "data", "question": "Какие данные о продажах доступны команде?"},
    {"field": "success", "question": "Каким показателем измерите снижение списаний?"}
  ]}
}

Hub.validateAssistant проверяет JSON, число вопросов (3–5), допустимые поля, непустой текст, длину и отсутствие дублей. Hub.assistant(task, rawResponse) при неверном ответе возвращает локальные вопросы с fallback: true. Кнопка «Тест ошибки AI» показывает этот путь в интерфейсе.

Серверный адаптер реализован в ai_server.py, клиент — в ai-client.js. Он использует отдельный промпт и строгий JSON-ответ с message и questions. Ключ хранится только на сервере. ИИ не определяет победителей, не изменяет карточку и не публикует её самостоятельно. Примеры и советы модели требуют проверки человеком.

Проверки

Проекты и этапы

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

Завершение последнего этапа начисляет 50 баллов один раз. Баллы за результаты, подтверждённые в прежней версии, сохраняются и повторно не начисляются. Старые подтверждения не превращаются автоматически в четыре пройденных этапа. Данные проектов сохраняются в браузере; переключение ролей остаётся демонстрационным, без настоящей авторизации. Стили страницы: projects.css.

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

В разделе откликов появились фильтры по задаче и статусу, а также сравнение 2–3 предложений на одну задачу: идея, план, срок, навыки и прототип. Решение о выборе команды остаётся ручным. В каталоге активные фильтры видны отдельными кнопками и снимаются по одному. Студент переключает команду в верхней панели; бизнес-формы скрыты из его навигации. Дополнительные стили находятся в experience.css; таблица сравнения прокручивается на узких экранах.

Запуск проверок сценариев: node tests/workflow.cjs. Они также проверяют ограничения сравнения, ручной выбор, фильтры статусов, переключение команды и безопасное отображение поискового запроса.

23 доменные проверки выполнены: веса и границы рейтинга, подтверждение и пересчёт, состав наборов, число вопросов, ошибочный JSON и схема, дубли, безопасные ссылки, принятый этап и защита от повторных баллов. Дополнительно проверены поиск по словам, нормализация е/ё, избранное, фильтрация публикаций и сохранение сортировки. Синтаксис трёх JS-файлов проверен. Дополнительно через обработчики приложения с имитацией DOM выполнен сценарий: черновик → вопросы → карточка → публикация (100 баллов) → отклик → ручной выбор → принятый этап (+50 баллов); проверена генерация всех основных экранов. В tests/workflow.cjs также проверены восстановление после перезагрузки, несколько черновиков, изоляция неподтверждённых изменений, избранное и отказ хранилища. Это не браузерный E2E-тест. Визуальная проверка в браузере в среде разработки не выполнена: подключённый браузер недоступен.

Ручные проверки перед защитой:

1. Пройдите DEMO.md от черновика до принятого этапа.
2. Опубликуйте только название и контекст: карточка с 0 баллов должна быть видна и принимать отклики.
3. Измените опубликованную карточку: до подтверждения каталог сохраняет предыдущую версию, после — пересчитывается.
4. Выберите две команды на одну задачу, отклоните третью.
5. Проверьте пустое предложение, неверную ссылку, пустое подтверждение этапа.
6. Перезагрузите страницу: карточки, отклики и принятые этапы должны сохраниться.
7. Проверьте поиск, оба фильтра и пустую выдачу.

Подготовка к GitHub

Проект уже расположен в репозитории BAITC-Hacks/hack-749c6a34-shoqanai. После проверки:

git add index.html styles.css responsive.css app.js domain.js data.js tests.html README.md DEMO.md .gitignore
git commit -m "Build AI Sana Challenge Hub MVP"
git push origin HEAD

Для статической публикации выберите корень нужной ветки в GitHub Pages. Сборка не требуется.

Границы MVP

Нет общего сервера данных, синхронизации между браузерами и реальной авторизации. Это однопользовательский демонстрационный прототип с переключением ролей. Контакты и компании синтетические, ссылки example.com служат примерами. Для реального запуска понадобятся сервер, база данных, разграничение прав и развёртывание AI-сервера.

Стартовая версия сайта

В папке starter находится отдельная начальная версия: главная страница, форма идеи и сохранение черновика в браузере. Откройте starter/index.html локально или через статический сервер. Эта версия не заменяет основной MVP.