AI Sana: Платформа геймификации практических бизнес-задач

Полный работающий MVP платформы для трансформации первичных потребностей бизнеса в качественные карточки задач, их объективного рейтингования (0–100) и открытого выбора студенческих команд.

Разработано в рамках хакатона AI Sana (трек: Education & Gamification).
Репозиторий проекта: https://github.com/BAITC-Hacks/hack-0c02bd80-mussels

---

1. Архитектура системы и дизайн

Платформа построена по принципу модульного монолита на Python со строгой технологичной дизайн-системой (Linear / Vercel style) на базе нейтральной палитры Zinc:

• Автономное веб-приложение (server.py, templates/, run_web.sh): Основной веб-интерфейс на базе FastAPI, Jinja2, Tailwind CSS и Alpine.js на порту 8000. Отличается нулевым оверхедом сборки (No-Node build), быстрой реактивностью и чистой типографикой (Plus Jakarta Sans).
• Ролевая навигация (ADR-0008):
  • Левый продуктово-ролевой контур: ссылка на «Каталог» + сегментированный переключатель рабочих пространств участников [Команда | Бизнес];
  • Правый блок действий: первичная графитовая CTA-кнопка [+ Конструктор], презентационный бейдж-чип [Демо жюри], бейдж статуса AI ядра и кнопка сброса базы к эталону.
• Двухрежимный AI-движок (services/ai_generator.py, ADR-0002):
  • Основной режим: OpenAI (gpt-4o-mini) для контекстного анализа пробелов в описании и адаптивного пошагового уточнения ТЗ.
  • Резервный режим: Локальный детерминированный генератор (Local Fallback), обеспечивающий 100% стабильность демонстрации даже без сети или API-ключа.
• Движок скоринга (services/scoring.py, ADR-0004): Прозрачная аддитивная формула расчета рейтинга (0–100 баллов) с генерацией подсказок и векторным SVG-спидометром.
• Многомерный алгоритм рекомендаций (services/recommendation.py): Персонализированный подбор задач для команд по доменным интересам (40%), профилю инженерных компетенций (40%) и уровню готовности ТЗ (20%).
• Файловое хранилище (services/storage.py): JSON-хранилище в директории data/ с атомарной записью, поддержкой сидинга и кнопкой мгновенного сброса.

---

2. Формула рейтинга готовности задачи

Рейтинг отражает готовность конкретной бизнес-задачи к студенческой разработке и рассчитывается строго аддитивно по подтвержденным полям:

Показатель	Макс. балл	Как начисляются баллы
Контекст и потребность	20	Понятно текущее положение дел и требуемые изменения
Данные и материалы	20	Указаны доступные датасеты, примеры диалогов, ссылки
Ожидаемый результат	15	Описан конкретный артефакт (бот, сервис, модель, дашборд)
Критерии успеха	15	Сформулированы измеримые метрики приемки решения
Ограничения	10	Зафиксированы сроки, стек технологий, безопасность
Пользователи	10	Определена целевая аудитория будущего решения
Связь с бизнесом	10	Указаны прямые контакты, формат синков и консультаций
ИТОГО	100	Полная шкала готовности

Категории уровня готовности:

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

---

3. Ключевые разделы платформы

1. Конструктор задачи (/ или /constructor)

• Ввод первичной потребности бизнеса в свободной форме.
• Адаптивный пошаговый диалог с AI (выявление недостающих сведений, подсказки «Быстрый ответ для жюри»).
• Динамический спидометр готовности (0–100 баллов) и автоматическая сборка паспорта задачи с 3 контрольными этапами (milestones).

2. Общий каталог задач (/catalog)

• Единый открытый пул подтвержденных задач с ранжированием по рейтингу готовности.
• Живая фильтрация по отраслям бизнеса и уровням готовности («Приоритетная», «Готовая», «Рабочая», «Черновик»).
• Модальный паспорт задачи с детальной структурой ТЗ, критериями приемки и формой отклика команды.

3. Кабинет студенческой команды (/student, ADR-0009)

• Единый лаконичный селектор команды с отображением баланса XP.
• Сводный профиль команды со стеком технологий и счетчиками баллов: Подтверждено XP, Закрыто этапов, В разработке XP.
• Проектно-центричная структура прогресса: Проект → Завершенные контрольные этапы (+XP) → Этапы в разработке (+XP).
• Персональные AI-рекомендации задач с многомерным расчетом совместимости (домен 40%, стек 40%, готовность 20%) и текстовым объяснением.

4. Кабинет бизнеса и управление проектами (/business, ADR-0003, ADR-0007)

• Реестр задач компании и мониторинг проектного цикла.
• Принцип исключительно ручного выбора (ADR-0003): категорический запрет автоназначения платформой — представитель бизнеса лично принимает решение по откликам команд.
• Интерактивная шкала контрольных этапов и подтверждение с начислением баллов прогресса (+XP) команде.

5. Экспресс-демонстрация для жюри (/jury-demo или /demo)

• Интерактивный путеводитель по сквозному сценарию за 3 минуты: от ввода слабого черновика до начисления баллов XP.
• Памятка ключевых архитектурных решений хакатона.

---

4. Быстрый запуск

Требования:

• Python 3.9+
• Установленные зависимости

Установка:

# Клонирование репозитория
git clone https://github.com/BAITC-Hacks/hack-0c02bd80-mussels.git
cd hack-0c02bd80-mussels

# Создание и активация виртуального окружения
python3 -m venv venv
source venv/bin/activate

# Установка зависимостей
pip install -r requirements.txt

Запуск основного веб-приложения (FastAPI + Tailwind CSS, порт 8000):

./run_web.sh
# или напрямую:
uvicorn server:app --host 0.0.0.0 --port 8000 --reload

Приложение доступно по адресу: http://localhost:8000.

Запуск можно осуществлять как через ./run_web.sh, так и через ./run.sh (автоматически запускает веб-сервер FastAPI).

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

./venv/bin/pytest tests/
# 34 passed

---

5. Архитектурные решения (Architecture Decision Records)

Все проектные развилки зафиксированы в директории docs/adr/:

1. ADR-0001: Единая архитектура на базе Streamlit (устарело, заменено на ADR-0005)
2. ADR-0002: Двухрежимный AI-движок (OpenAI + Local Fallback)
3. ADR-0003: Категорический запрет автоназначения и ручной выбор бизнеса
4. ADR-0004: Прозрачная аддитивная формула рейтинга готовности (0–100)
5. ADR-0005: Выделение автономного веб-приложения на FastAPI
6. ADR-0006: Минималистичная дизайн-система и палитра Zinc
7. ADR-0007: Эргономичная иерархия действий и навигационные вкладки
8. ADR-0008: Логическое разделение навигации и ролевой сегментированный контрол
9. ADR-0009: Проектно-центричная структура кабинета студенческой команды

---

6. Структура репозитория

hack-0c02bd80-mussels/
├── CONTEXT.md                 # Доменный словарь платформы (Domain Modeling)
├── README.md                  # Финальная документация проекта
├── server.py                  # Основной веб-сервер FastAPI (порт 8000)
├── run_web.sh                 # Скрипт запуска веб-приложения FastAPI
├── run.sh                     # Алиас запуска основного приложения
├── config.py                  # Конфигурация, веса скоринга и справочники
├── conftest.py                # Конфигурация фикстур pytest
├── requirements.txt           # Зависимости проекта
├── case_doc.txt               # Исходное задание хакатона (RU, KZ, EN)
├── docs/
│   └── adr/                   # Архитектурные решения (ADR 0001 — 0009)
├── models/                    # Pydantic модели данных (Task, Proposal, Team, Milestone)
├── services/                  # Бизнес-логика (Scoring, Storage, AI Generator, Recommendation, Seed, UI)
├── static/                    # Статические ресурсы
├── templates/                 # Шаблоны Jinja2 + Tailwind CSS + Alpine.js
│   ├── base.html              # Базовый каркас с ролевым навбаром и тостами
│   ├── index.html             # Конструктор задачи с AI-диалогом и спидометром
│   ├── catalog.html           # Общий каталог задач с живой фильтрацией
│   ├── student.html           # Кабинет студенческой команды и проектный трекер XP
│   ├── business.html          # Кабинет бизнеса и ручной выбор откликов
│   └── jury_demo.html         # Экспресс-демонстрация и путеводитель для жюри
└── tests/                     # Автоматические тесты (Scoring, Fallback, Web App, Emojis)