AI Sana — Город решений

Веб-приложение для подготовки бизнес-задач и открытого выбора студенческих команд. Проект создан как MVP для хакатона: от короткого описания проблемы до подтверждённой карточки, предложения команды и решения бизнеса.

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

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

Для бизнеса: конструктор карточки, уточняющие вопросы, рекомендации по заполнению и ручной выбор исполнителей.

Для студенческих команд: просмотр задач, фильтры, отправка предложений и работа над подтверждаемыми этапами.

Главная игровая механика — рейтинг готовности бизнес-задачи. Он влияет на порядок задач в каталоге. Команды выбирают задачи самостоятельно; приложение не назначает исполнителей автоматически.

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

• Конструктор задачи: свободное описание, от 3 до 5 уточняющих вопросов, сохранение вопросов и ответов, сборка редактируемой карточки и ручное подтверждение публикации.
• Рейтинг 0–100: расшифровка баллов, список недостающих сведений и подсказки о том, какие поля повысят рейтинг. При редактировании показывается предварительная полнота.
• Каталог: сортировка по рейтингу или новизне, поиск, фильтры по теме и уровню готовности.
• Два представления: список и город с изометрическими SVG-домами. Высота дома отражает готовность карточки. Режимы отображения и параметры размещения задач хранятся в базе.
• Команды и предложения: профили с интересами, навыками, технологиями и участниками; отклик с идеей, планом, сроком и необязательной ссылкой на прототип.
• Выбор бизнеса: просмотр предложений, выбор одной или нескольких команд, отклонение предложений. Можно не выбирать ни одну команду.
• Прогресс: этапы миссии, выбор подхода, подсказки, отправка результата и подтверждение бизнесом. За подтверждённые этапы начисляются опыт и монеты.
• Мастерская: покупка и выбор виртуальных предметов за игровые монеты, коллекция проекта и финальная проверка результата.
• Хранение данных: карточки, ответы, предложения, решения бизнеса и игровой прогресс сохраняются между запусками.
• Документация API: интерактивный Swagger и автоматические проверки сценариев.

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

За каждое непустое поле подтверждённой карточки начисляется его полный вес:

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

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

Низкий рейтинг опубликованной карточки не скрывает её и не запрещает отклик. Уровень готовности «черновая» и статус неопубликованного черновика — разные состояния.

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

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

1. Бизнес вводит название, категорию и исходное описание проблемы.
2. Помощник выделяет известные и недостающие сведения, предлагает уточняющие вопросы.
3. Пользователь отвечает; приложение собирает карточку из семи полей.
4. Бизнес проверяет и при необходимости исправляет текст, затем явно подтверждает публикацию.
5. Backend рассчитывает рейтинг. Карточка появляется в каталоге и городе.
6. Команда выбирает задачу и отправляет предложение.
7. Бизнес вручную выбирает или отклоняет предложение.
8. Выбранная команда отправляет результат этапа, бизнес подтверждает выполнение. Прогресс и награды сохраняются.

Технологии

Компонент	Технологии
Язык backend	Python; локальные проверки выполнены на Python 3.14
Веб-приложение и API	FastAPI, Uvicorn
Модели и работа с БД	SQLAlchemy
Проверка структуры запросов и ответов	Pydantic
Демонстрационная база	SQLite
Подключение основной базы	Microsoft SQL Server Express, pyodbc, ODBC Driver 17 for SQL Server
Интерфейс	HTML, CSS, JavaScript, SVG
Внешняя AI-интеграция	Anthropic Messages API через HTTPX
Настройки окружения	python-dotenv
Проверки	unittest, FastAPI TestClient, временная SQLite-база

Версии Python-зависимостей закреплены в requirements.txt. В конфигурации AI по умолчанию указана модель claude-sonnet-4-6; имя можно изменить через AI_MODEL. Реальный запрос к этой модели без предоставленного API-ключа не проверялся.

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

Браузер: HTML / CSS / JavaScript / SVG
                    |
                    | HTTP, относительные адреса /api/...
                    v
           FastAPI — app/main.py
             |               |
             v               v
        SQLAlchemy      Помощник задачи
             |          /             \
             v     Локальные       Anthropic API
   SQLite или SQL Server  правила   при настройке ключа

Один процесс FastAPI обслуживает страницу, статические файлы и API. Отдельный процесс frontend не нужен; для этого варианта запуска не требуется сборка через Node.js.

app/
  main.py          — запуск приложения, сайт и подключение маршрутов
  database.py      — настройки подключения и сессии базы данных
  models.py        — задачи, команды, предложения, вопросы и прогресс
  ui_models.py     — режимы отображения и размещение задач
  migrations.py    — обновление совместимой существующей схемы
  ai_service.py    — промпты, вызов модели и локальная обработка
  rating.py        — формула рейтинга
  progress.py      — начисление наград
  seed.py          — синтетические демонстрационные данные
  routers/         — операции API
frontend/
  templates/index.html — страница приложения
  static/css/          — оформление
  static/js/           — интерфейс и обращения к API
tests/                 — автоматические проверки
.run/                  — конфигурации запуска PyCharm
.env.example           — пример настроек
requirements.txt       — зависимости
run_demo.cmd           — демо с SQLite и локальным помощником
run_local.cmd          — запуск с настройками основной базы
database_schema.py     — отдельный вход для инициализации общей схемы
DEMO.md                — сценарий защиты до пяти минут

Файл frontend/models.py сохранён от первоначального макета и не используется для загрузки данных в объединённом приложении.

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

Быстрый запуск демо на Windows

1. Скачайте исходники или распакуйте архив. Откройте терминал в корне проекта — там должны находиться requirements.txt, app и run_demo.cmd.

2. Если виртуальное окружение ещё не создано, выполните:

   python -m venv .venv
   

3. Установите зависимости:

   .\.venv\Scripts\python.exe -m pip install -r requirements.txt
   

4. Запустите демонстрационную версию:

   .\run_demo.cmd
   

5. Дождитесь Application startup complete и откройте:

   • Сайт
   • Swagger API
   • Проверка состояния процесса

Этот способ создаёт отдельный SQLite-файл aisana-demo.db, добавляет демонстрационные записи и принудительно использует локальную обработку без обращения к внешнему AI. Установка SQL Server для демо не нужна. Терминал должен оставаться открытым; остановка — Ctrl+C.

Запуск из PyCharm

1. Откройте всю папку проекта Hackathon.
2. Выберите интерпретатор .venv\Scripts\python.exe и установите зависимости командой выше.
3. В верхнем списке конфигураций выберите AI Sana Demo и нажмите ▶.
4. Откройте главную страницу.

Если конфигурация не появилась, выполните .\run_demo.cmd во встроенном терминале PyCharm из корня проекта.

Одновременно используйте один способ запуска. Если порт 8000 занят другой копией приложения, сначала остановите её. Например, после запуска из терминала не нужно дополнительно запускать тот же сервер кнопкой PyCharm.

Запуск с SQL Server

Для этого режима нужны SQL Server Express, ODBC Driver 17 и доступ Windows-пользователя к выбранной базе.

1. Создайте .env по образцу, если такого файла ещё нет:

   if (!(Test-Path .env)) { Copy-Item .env.example .env }
   

2. Укажите в .env своё имя SQL Server и базу. В текущем примере настроено:

   DB_SERVER=DESKTOP-D5H3SMJ\SQLEXPRESS
   DB_NAME=aetherix_backend
   DB_DRIVER=ODBC Driver 17 for SQL Server
   DATABASE_URL=
   SEED_DEMO=true
   

   Пустой DATABASE_URL включает подключение SQL Server через параметры DB_*. Непустой URL имеет приоритет. Подключение использует Windows-аутентификацию от имени пользователя, запустившего Python.

3. Если база отсутствует, выполните в SSMS:

   IF DB_ID(N'aetherix_backend') IS NULL
   BEGIN
       CREATE DATABASE aetherix_backend;
   END;
   

4. Остановите демоверсию. В новом терминале из корня проекта выполните:

   .\run_local.cmd
   

   В PyCharm этому режиму соответствует конфигурация AI Sana.

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

Первоначальная база aetherix_db от отдельной старой схемы не объединяется автоматически с aetherix_backend. Текущий database_schema.py использует общие модели приложения; отдельно запускать его перед каждым стартом не требуется.

Реальное подключение и миграция SQL Server из среды проверки не подтверждены: Windows-аутентификация вернула ошибку получения учётных данных. Демонстрация и проверки выполнялись на SQLite.

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

Готовые тексты и план выступления находятся в DEMO.md в корне проекта.

1. Выберите демо-роль Бизнес и нажмите Создать задачу.

2. Введите название «Демо жюри — очередь в кофейне», категорию «ритейл» и описание:

   Контекст: В кофейне посетители долго стоят в очереди.
   

3. Нажмите Сохранить и уточнить. Проверьте, что показаны известные сведения, недостающие поля и не менее трёх вопросов.

4. Для первой версии оставьте ответы пустыми, соберите карточку и убедитесь, что заполнен только контекст. Подтвердите публикацию: рейтинг составит 20/100.

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

   Поле	Пример
   Данные и материалы	Учебная таблица из 20 заказов с номером и временем выдачи.
   Ожидаемый результат	Работающий прототип экрана очереди заказов.
   Критерии успеха	На 10 тестовых заказах можно добавить заказ, увидеть номер и отметить выдачу.
   Ограничения	Три дня на прототип; без интеграции с кассой.
   Пользователи	Бариста и посетители кофейни.
   Связь с бизнесом	Представитель кофейни отвечает в чате команды и проверяет демонстрацию.

6. Убедитесь, что предварительный рейтинг вырос до 100/100, и повторно подтвердите публикацию. Проверьте карточку в городе и списке.

7. Переключите роль на Команда, выберите активную команду и отправьте предложение с идеей, планом и сроком.

8. В роли Бизнес выберите или отклоните предложение. До этого действия исполнитель автоматически не назначается.

9. Если команда выбрана, отправьте результат первого этапа миссии от её имени, затем подтвердите его от бизнеса. Проверьте начисление награды.

10. Перезагрузите страницу и снова откройте задачу: сохранённые данные должны остаться.

Автоматические проверки

Из корня проекта:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

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

Тесты используют временную SQLite-базу и подменяют внешние AI-вызовы. Проверки SQL Server охватывают генерацию схемы и моделируемые зависимости миграции, а не живое подключение к серверу. Основной пользовательский сценарий и обновление подсказок также проверялись в браузере.

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

Демонстрационные данные

При SEED_DEMO=true приложение добавляет синтетические примеры:

Набор	Количество	Содержание
Исходные черновики	5	Описание проблемы и категория
Опубликованные карточки	5	Поля задачи с разной полнотой и текущий рейтинг
Профили команд	5	Название, интересы, навыки, технологии и участник
Предложения	5	Команда, идея, план, срок и демонстрационная ссылка

Примеры отмечены [Демо] или [Демо-черновик]. Ссылки example.com обозначают вымышленные прототипы. Повторный запуск не восстанавливает уже изменённые пользователем примеры после отметки завершённой инициализации. Для запуска без добавления этих примеров используйте SEED_DEMO=false при обычном запуске; run_demo.cmd намеренно включает их.

AI-помощник

В app/ai_service.py реализованы две операции:

• Анализ исходного описания: определение покрытых и недостающих полей, генерация 3–5 вопросов.
• Сборка карточки из описания и ответов пользователя с последующим редактированием и подтверждением человеком.

Интеграция использует Anthropic Messages API. Для внешней модели настройте .env:

AI_API_KEY=ваш_ключ
AI_BASE_URL=https://api.anthropic.com/v1/messages
AI_MODEL=claude-sonnet-4-6
AI_FORCE_FALLBACK=false

Укажите модель, доступную вашему API-аккаунту. Ключ используется backend и не передаётся в браузер. Файл .env исключён из Git.

Для проверки внешней модели с той же SQLite-базой запустите приложение напрямую из нового терминала, предварительно остановив демоверсию:

$env:DATABASE_URL = 'sqlite:///./aisana-demo.db'
$env:AI_FORCE_FALLBACK = 'false'
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

run_demo.cmd и AI Sana Demo принудительно отключают внешний AI, даже если ключ указан в .env.

Модели передаются текст задачи и ответы пользователя. Подключение к SQL Server и вся база целиком модели не передаются. Обучения собственной ML-модели нет.

При отсутствии ключа, сетевой ошибке или некорректном результате включается локальная заглушка по правилам. Она распознаёт явно подписанные поля и характерные формулировки, выбирает вопросы по пробелам и переносит исходные фрагменты в карточку. Если основные поля уже упомянуты, задаются вопросы для уточнения деталей. Интерфейс сообщает режим, API возвращает ai_used=false и причину.

Промпты находятся в ANALYZE_SYSTEM_PROMPT и ASSEMBLE_SYSTEM_PROMPT; схемы запросов и ответов — в app/schemas.py и Swagger. Примеры JSON и объяснение обработки ошибок приведены в DEMO.md.

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

• Демонстрационные роли: полноценная регистрация, вход по паролю и серверное разграничение прав не реализованы. Выбор «Бизнес / Команда» не подтверждает личность пользователя.
• Полнота вместо смысловой оценки: рейтинг проверяет непустые подтверждённые поля. Он не доказывает достоверность текста, измеримость критериев или качество будущего решения.
• Локальный разбор ограничен правилами: он может не распознать нестандартную формулировку. Пользователь уточняет сведения ответами или вручную в карточке.
• Внешняя модель не проверена вживую: интеграционный код есть, но успешный запрос с реальным ключом пока не подтверждён. Проверка структуры JSON не гарантирует отсутствие выдуманных фактов; текст проверяет бизнес перед публикацией.
• SQL Server требует отдельной проверки: реальная Windows-аутентификация и миграция на пользовательском сервере не подтверждены локальными тестами SQLite.
• Общий маршрут миссии: этапы относятся к задаче. Независимый проектный трекер для каждой выбранной команды не реализован.
• Обновление финальных критериев: они создаются при первой публикации; последующее редактирование карточки не пересобирает существующие критерии автоматически.
• Нет чата, уведомлений и загрузки файлов. Предложения содержат текст и ссылку на прототип.
• Локальная конфигурация: производственная инфраструктура и защита для публичного доступа не подготовлены.

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

Подтверждённая ссылка на публичный deployment в текущем проекте отсутствует.

После локального запуска приложение доступно по адресу http://127.0.0.1:8000/. Этот адрес работает только на компьютере, где запущен сервер, и не является публичной ссылкой для других участников.