AI Sana — бизнес-задачи для студенческих команд

1. Краткое описание

Бизнесу сложно превратить короткую потребность в понятное задание, а студентам — оценить, достаточно ли сведений для начала работы. AI Sana помогает бизнесу подготовить такую задачу, а студенческим командам — найти её и предложить решение.

Бизнес вводит описание, отвечает на вопросы AI, проверяет карточку и публикует её. Рейтинг готовности показывает, каких сведений не хватает. Команды откликаются самостоятельно; бизнес вручную принимает или отклоняет предложения. Автоматического назначения команды нет.

Проект — хакатонный MVP для локальной демонстрации. Требования: docs/CASE.md. Правила совместной разработки: AGENTS.md.

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

Возможность	Текущая реализация
Вход	Выбор роли «Бизнес» / «Команда» и подготовленного пользователя, без пароля
Конструктор	Черновик из свободного текста, уточняющие вопросы AI, сборка и ручное редактирование карточки
Подтверждение	Бизнес отдельно подтверждает заполненные поля; публикация без подтверждения запрещена
Рейтинг	0–100, семь показателей, четыре уровня, подсказки «+N баллов», отдельный прогноз до подтверждения
Каталог	Опубликованные задачи, сортировка по рейтингу, поиск, фильтры по теме и готовности, рекомендации по интересам команды
«Мои задачи»	Собственные карточки бизнеса, фильтр статуса, редактирование и удаление с подтверждением
Отклики	Идея решения, план, срок и необязательная ссылка; просмотр и сравнение предложений
Решение бизнеса	Принять, отклонить или вернуть отклик на рассмотрение; допускается выбрать несколько команд
Результат команды	Принятая команда передаёт результат одного этапа; бизнес подтверждает его и однократно начисляет команде 10 баллов
Настройки AI	Адрес API, API-ключ, получение списка моделей и выбор модели для текущего бизнес-пользователя

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

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

Основной сценарий — 8 шагов

Шаг	Действие пользователя	Результат
1	Бизнес создаёт задачу и вводит описание проблемы	Сохраняется черновик
2	Нажимает «Проверить полноту», отвечает на вопросы	AI запрашивает недостающие сведения; возвращается минимум три вопроса
3	Нажимает «Собрать карточку», редактирует и подтверждает поля	Появляется структурированное задание с ручным подтверждением бизнеса
4	Изучает рейтинг и подсказки	Видны заработанные баллы, уровень и возможности улучшения
5	Переходит к публикации, проверяет сведения и подтверждает действие	Задача появляется в каталоге
6	Команда выбирает задачу и отправляет предложение	Отклик получает статус «На рассмотрении»
7	Владелец задачи сравнивает отклики и принимает решение	Только выбранные вручную отклики становятся принятыми
8	Принятая команда передаёт результат; бизнес проверяет его	После подтверждения команда получает 10 баллов

Рейтинг готовности задачи

Формула реализована чистой функцией в app/modules/rating/service.py; веса и пороги вынесены в константы.

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

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

• Пустое или неподтверждённое поле — 0. Распознаваемые заглушки вроде «не знаю» и примитивные повторы также дают 0.
• Подтверждённый текст длиной 1–29 символов — половина веса.
• Подтверждённый текст от 30 символов — полный вес.

Контекст и потребность рассчитываются отдельно, но отображаются одним показателем. Возможны дробные баллы, например 37,5. Название, отрасль и исходный текст сами по себе баллов не дают.

Балл	Уровень
От 0 до менее 40	«Черновик» (draft)
От 40 до менее 70	«Рабочая» (working)
От 70 до менее 90	«Готовая» (ready)
От 90 до 100 включительно	«Приоритетная» (priority)

При каждом сохранении рейтинг пересчитывается. Изменение поля снимает подтверждение его прежнего значения: новые баллы начисляются после повторного ручного подтверждения. Прогноз potential_score не влияет на место в каталоге.

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

Правила каталога

• По умолчанию выше задачи с большим подтверждённым рейтингом; при равенстве выше более новая задача. Есть сортировка по новизне и меньшему числу откликов.
• Доступны поиск, фильтры по теме/отрасли и уровню готовности, сброс фильтров.
• Низкий рейтинг не скрывает опубликованную задачу и не запрещает отклик. Уровень «Черновик» помечается как требующий уточнения.
• Неопубликованный рабочий черновик в каталог не входит. Статус публикации и уровень готовности — разные свойства.
• Рекомендации сопоставляют отрасль с интересами команды и оставляют задачи с рейтингом от 40. Это простой фильтр, не AI-подбор и не назначение; полный каталог остаётся доступен.

4. Технологии

Компонент	Технология
Язык сервера	Python 3.11
HTTP API и сервер	FastAPI 0.115.12, Uvicorn 0.34.2
Данные	SQLAlchemy 2.0.40, SQLite
Валидация	Pydantic 2.11.3
Конфигурация	Переменные окружения и .env, python-dotenv 1.1.0
AI-интеграция	HTTPX 0.28.1, OpenAI-совместимые GET /models и POST /chat/completions
Интерфейс	Статические HTML/CSS/JavaScript, ES-модули, без frontend-фреймворка и сборки
Автоматические тесты	pytest 8.3.5, FastAPI TestClient, HTTPX MockTransport

Зависимости закреплены в requirements.txt. Для работы приложения не нужны Node.js, Docker или отдельный frontend-сервер. Дополнительные браузерные проверки .cjs используют Playwright; он не входит в зависимости запуска приложения.

AI-клиент настоящий, без шаблонной подмены ответов в рабочем приложении. Конкретная модель не закреплена: её выбирают в настройках подключения. OpenAI SDK не используется — запросы выполняются через HTTPX. По умолчанию адрес указывает на локальный LM Studio; подключение OpenAI описано ниже.

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

Модульный монолит: один процесс FastAPI обслуживает JSON API под /api и статический интерфейс. Браузер обращается к API, роутеры вызывают сервисы, сервисы работают с SQLite и при необходимости с AI-провайдером.

app/
  main.py                  # приложение, роутеры, статика, CORS, ошибки
  config.py                # настройки окружения
  db.py                    # engine, сессии, Base, регистрация моделей
  modules/
    users/                 # пользователи и роли
    tasks/                 # жизненный цикл задач
    rating/                # чистая функция рейтинга
    ai/                    # HTTP-клиент, промпты, схемы, настройки, кэш
    catalog/               # каталог опубликованных задач
    teams/                 # профили команд
    proposals/             # отклики, решения и результаты
  seed/
    seed.py                # загрузка демонстрационных данных
    data/*.json
static/
  index.html
  css/
  js/api.js                # все fetch-вызовы
  js/*.js                  # экраны и общие компоненты
tests/
docs/
start.py                   # подготовка окружения и запуск
start.bat                  # запуск на Windows

Каждый предметный модуль содержит router.py (HTTP), schemas.py (Pydantic), service.py (бизнес-правила) и models.py (свои модели). Модули взаимодействуют через сервисы, без прямого импорта чужих моделей. Регистрация моделей в app/db.py, seed и тесты — инфраструктурные исключения. У rating и catalog нет собственных бизнес-таблиц.

Модуль	Ответственность и примеры API
users	Выбор пользователя, роль и X-User-Id; POST /api/users/login, GET /api/users
tasks	Черновик, вопросы, карточка, подтверждение, публикация, удаление; /api/tasks/...
rating	Расчёт баллов, уровней и недостающих сведений без БД и AI
ai	Подключение к модели, проверка JSON и источников, настройки пользователя, кэш вопросов
catalog	Опубликованные задачи и фильтры; GET /api/catalog?industry=Культура&level=draft
teams	Чтение профилей; GET /api/teams
proposals	Создание откликов, ручное решение владельца, проверка результата; /api/proposals/...

Основные сущности: User, Team, Task, Proposal. Пользователь бизнеса владеет задачами; пользователь команды связан с Team; отклик связывает команду и задачу. Дополнительные таблицы хранят снимки подтверждённых полей (TaskVerification), неопубликованные изменения (TaskRevision), результат этапа (ProposalProgress), настройки AI (AIConnection) и кэш анализа (AIAnalysis). Сохранено чтение прежней таблицы результатов ProposalMilestone.

Интерактивная документация эндпоинтов доступна на /docs запущенного сервера, проверка доступности — на /health.

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

Быстрый запуск на Windows

Нужен Python 3.11; при первой установке зависимостей нужен интернет. Откройте PowerShell в корне своей копии репозитория:

.\start.bat

Скрипт создаёт .venv, устанавливает зависимости, копирует отсутствующий .env из .env.example, загружает демонстрационные данные в пустую БД и запускает сайт вместе с API. Существующие настройки и записи не заменяются.

Обычно сайт открывается на http://127.0.0.1:8000. Если порт занят, скрипт выбирает свободный из 8001–8019 и печатает точный адрес. Остановка своего экземпляра — Ctrl+C в его окне. Другие серверы скрипт не завершает.

Для выбора порта и отключения автоматического открытия браузера:

.\start.bat --no-browser --port 8005

При первом запуске скрипт ищет Python через py -3.11, затем проверяет python. Если установленный Python 3.11 не находится этими командами, запустите start.py полным путём к его python.exe. Уже существующая .venv тоже должна использовать Python 3.11.

Ручная установка на Windows

Команды выполняются в корне проекта. Если python указывает именно на 3.11, им можно заменить py -3.11 в первой строке.

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
if (-not (Test-Path -LiteralPath .env)) { Copy-Item .env.example .env }
.\.venv\Scripts\python.exe -m app.seed.seed
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Активация виртуального окружения не обязательна. В другом окне PowerShell проверьте сервер; подставьте свой порт, если он отличается:

Invoke-RestMethod http://127.0.0.1:8000/health
Invoke-RestMethod http://127.0.0.1:8000/api/catalog

Ожидается status: ok; в свежей демонстрационной базе каталог содержит пять карточек. Сайт: http://127.0.0.1:8000/, API: http://127.0.0.1:8000/docs.

Автоматическая подготовка с нуля проверена в отдельном окружении Windows/Python 3.11. Для Linux/macOS предусмотрен python3.11 start.py, но отдельная проверка на этих ОС не выполнялась. Дополнительные варианты запуска: LOCAL_RUN.md.

Подключение настоящего OpenAI API

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

Самый простой вариант — через интерфейс:

1. Выберите «Бизнес» и пользователя, например Алию.
2. Откройте «Настройки AI».
3. В поле «Адрес API» укажите https://api.openai.com/v1.
4. Введите свой OpenAI API-ключ в поле «API-ключ».
5. Нажмите «Обновить список моделей», явно выберите доступную совместимую текстовую модель.
6. Нажмите «Сохранить настройки», затем проверьте анализ новой задачи.

Настройки сохраняются отдельно для каждого бизнес-пользователя. Список моделей не гарантирует, что каждая из них поддерживает используемый формат запроса. Клиент отправляет Chat Completions с параметром max_tokens; он не совместим с o-series. Конкретная модель OpenAI в проекте не зафиксирована. См. официальное описание Chat Completions.

Альтернатива — изменить .env перед запуском сервера:

DATABASE_URL=sqlite:///./ai_sana.db
AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=YOUR_OPENAI_API_KEY
AI_MODEL=MODEL_ID
AI_TIMEOUT=180
AI_MAX_TOKENS=4096
AI_RESPONSE_FORMAT=auto

YOUR_OPENAI_API_KEY и MODEL_ID — обозначения для замены, не готовые значения. Используется переменная AI_API_KEY, в ней хранится именно ваш OpenAI-ключ. Одного ключа недостаточно: адрес по умолчанию в .env.example — http://127.0.0.1:1234/v1, а не OpenAI. Сохранённые в интерфейсе настройки пользователя имеют приоритет над .env; меняйте их в том же интерфейсе. После изменения .env перезапустите свой сервер.

Ключ передаётся AI-провайдеру сервером в Bearer-заголовке, не включается во frontend-код и не возвращается API настроек. Не публикуйте .env, ключи и SQLite-базу: ключ, сохранённый через интерфейс, хранится в ней без шифрования. Для публичной эксплуатации такое хранение и демонстрационный вход нужно заменить. Правила обращения с ключами: официальная документация OpenAI.

Вместо OpenAI можно указать совместимый сервер LM Studio/llmster. Такой сервер запускается отдельно; start.bat его не устанавливает и не запускает.

Изоляция при командной работе

Для независимого демо используйте отдельную копию репозитория без чужих .env, .venv и .db либо отдельный DATABASE_URL. Другой порт сам по себе не создаёт отдельную базу. Не удаляйте рабочую БД коллег ради загрузки примера.

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

Воспроизводимое демо для жюри

Подготовьте свежую базу командой seed и настройте AI для бизнес-пользователя Алии. Тексты для копирования находятся в docs/DEMO.json. Ответ живой модели может различаться, поэтому для проверки точных баллов ниже приведена ручная нормализация карточки.

Действие	Ожидаемый результат
Бизнес → Алия → создать задачу: название «Демо: обращения клиентов», отрасль «Сервисы», описание «Нужен сервис»	Черновик, начислено 0
«Проверить полноту» → посмотреть вопросы → пока пропустить уточнения → «Собрать карточку»	AI возвращает вопросы и карточку; сведения требуют проверки человеком
В редакторе оставить в контексте только «Нужен сервис», очистить остальные семь рейтинговых полей и сохранить	Начислено 0, прогноз 5
«Подтвердить заполненные поля»	5, уровень «Черновик»; публикации ещё нет
Вставить восемь значений из answers в DEMO.json в соответствующие поля и сохранить	Начислено 0, прогноз 100: прежний контекст изменён и ещё не подтверждён
«Подтвердить заполненные поля»	100, «Приоритетная», заполнены все семь показателей
«Перейти к публикации» → обе галочки → «Опубликовать в каталоге»	Публичная задача с рейтингом 100, выше более старой seed-карточки с тем же баллом
Команда → Data Sparks → открыть эту задачу → отправить значения из proposal	Отклик на рассмотрении, команда ещё не выбрана
Повторить отправку от Civic Code	Два независимых отклика
Бизнес → Алия → «Предложения» → выбрать задачу → принять Data Sparks, отклонить Civic Code	Статусы accepted и rejected; решения принимает бизнес
Команда Data Sparks → «Мои отклики» → передать значения из progress	Результат ожидает проверки, за него ещё 0 баллов
Бизнес → «Подтвердить результат · +10»	Команде начислено 10, рейтинг задачи остаётся 100
Обновить страницу	Решения и баллы сохранены; повторное начисление за тот же результат недоступно

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

Дополнительно проверьте опубликованную seed-задачу с рейтингом 37,5: она видна при фильтре «Черновик» и доступна для отклика. В демо-карточке с рейтингом 100 замените поле «Данные» на «Команда получит CSV с тремястами обезличенными обращениями и их темами.». После сохранения рейтинг предварительной карточки 100 → 80; после нового подтверждения 80 → 100. Публикация без подтверждения возвращает 409, решение по чужому отклику — 403.

Автоматические тесты

В подготовленном окружении:

.\.venv\Scripts\python.exe -m pytest tests -q -p no:cacheprovider
# Только подготовленный сквозной пример:
.\.venv\Scripts\python.exe -m pytest tests/test_demo.py -q -p no:cacheprovider

Либо подготовить окружение, выполнить безопасный seed и запустить тесты одной командой:

.\start.bat --check

Покрыты расчёт и границы рейтинга 39/40, 69/70, 89/90, пересчёт, подтверждение и публикация, права владельца, отклики, результаты и повторное начисление, AI-протокол и ошибки, seed и запуск. tests/test_demo.py использует тот же DEMO.json.

При проверке текущей версии на Windows/Python 3.11 прошли 149 тестов; осталось одно предупреждение DeprecationWarning Starlette/AnyIO. Тестовые БД изолированы, AI-запросы в pytest подменяются HTTPX MockTransport и не расходуют API-ключ. Это не подтверждение успешного обращения к живому OpenAI: такой вызов при подготовке README не выполнялся. Прохождение pytest также не означает отсутствия всех UI-дефектов — известные ограничения перечислены ниже.

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

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

Источники — JSON-файлы в app/seed/data. Это синтетические примеры, а не выгрузка реальных клиентов.

Набор	Объём и содержимое
Пользователи	7: два представителя бизнеса и пять представителей команд
Черновики	5, разной полноты; начислено 0, потенциал 0/20/50/75/100
Опубликованные карточки	5, рейтинги 100/95/37,5/85/60; представлены все четыре уровня
Команды	5 профилей с интересами, навыками и технологиями
Отклики	5 демонстрационных предложений

Загрузка одной командой:

.\.venv\Scripts\python.exe -m app.seed.seed

Seed создаёт таблицы и загружает набор только если пользователей ещё нет. Если найден хотя бы один пользователь, вся загрузка пропускается: существующие записи не заменяются, частично заполненная база не восстанавливается. Пользователи 1 и 2 — Алия и Тимур; 3–7 — команды.

Ссылки example.com в примерах демонстрационные. CSV, упомянутый в DEMO.json, — часть описания задачи, не встроенный датасет и не реализованная загрузка файлов.

AI: данные, контракт и обработка ошибок

Провайдер получает исходный текст, ответы и уже известные поля карточки. Используйте обезличенные данные: при подключении OpenAI они отправляются внешнему сервису. SQLite хранит задачи, пользователей, отклики, результаты, настройки подключения и кэш вопросов.

Часть	Где реализована
Промпты анализа и сборки	app/modules/ai/prompts.py
Входные и выходные Pydantic-схемы	app/modules/ai/schemas.py
Реальный HTTP-клиент и протокол	app/modules/ai/provider.py
Проверка источников, настройки и кэш	app/modules/ai/service.py

analyze_draft(raw_text, ...) возвращает missing_fields, questions и detected_fields. build_card(raw_text, answers, ...) возвращает поля карточки: название, отрасль и восемь рейтинговых полей. Другие модули обращаются к этим функциям сервиса, не к HTTP-клиенту напрямую.

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

При явном отказе провайдера поддерживать формат автоматический режим последовательно пробует JSON Schema, JSON Object и JSON в тексте. Некорректный результат генерации запрашивается повторно один раз; затем возвращается понятная ошибка 502. Ошибка соединения даёт 503, тайм-аут — 504. Неудачный запрос не заменяет карточку заглушкой. Отсутствие ключа у OpenAI — ошибка подключения, а не переход на имитацию AI. Совместимый локальный сервер без авторизации может работать без ключа.

Других обязательных внешних API для бизнес-сценария нет. Интерфейс использует Google Fonts; при недоступности сети предусмотрены системные шрифты.

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

• Демонстрационная авторизация. Паролей и регистрации нет, X-User-Id можно подменить. Без доработки безопасности приложение нельзя считать готовым к публичной эксплуатации. Ключ AI в пользовательских настройках хранится в SQLite без шифрования.
• Живой OpenAI не проверен. Реальный HTTP-клиент реализован, но успешный вызов с действующим OpenAI-ключом при этой проверке не выполнялся. Требуются доступ к провайдеру и совместимая модель; не все модели из списка поддерживают используемые параметры. Нет офлайн-заглушки.
• Рейтинг — эвристика полноты. Длина текста и подтверждение не гарантируют полезность задания. Проверка источников AI также не заменяет проверку фактов человеком.
• Совместное редактирование ограничено. Нет realtime и слияния изменений. При работе с одной карточкой в нескольких вкладках устаревший редактор может перезаписать более свежие данные; одновременные противоположные решения по отклику также не полностью защищены от гонки. Для демо редактируйте одну карточку из одной вкладки.
• Есть известные UI-дефекты. Длинный текст и очень узкие экраны могут вызывать переполнение; требуют доработки клавиатурный переход к содержимому и отдельные переходы/подписи пустых и ошибочных состояний. После удаления задачи локальный несохранённый черновик результата может сохраняться в браузере и конфликтовать при повторном использовании ID. Полная исправность всех кнопок и размеров экрана не заявляется.
• Упрощённое взаимодействие. Нет чата, уведомлений, загрузки файлов, редактирования профилей команд и полноценного проектного трекера. Один отклик команды на задачу, один результат этапа и однократные 10 баллов.
• Хранилище для небольшого MVP. SQLite, без промышленной системы миграций, пагинации и нагрузочного тестирования. Старые подтверждённые записи без снимков считаются ранее подтверждёнными; подтвердить историю каждого их значения задним числом нельзя.
• Проверенная среда — Windows/Python 3.11. Linux/macOS и публичное развёртывание отдельно не проверены. .env, виртуальные окружения и SQLite-базы исключены из Git; они не должны попадать в публикуемый репозиторий.

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

Подтверждённой ссылки на публичную deployed-версию в репозитории нет. http://127.0.0.1:8000/ — только локальный адрес, доступный при запущенном сервере на вашем компьютере. При автоматическом выборе другого порта используйте адрес, напечатанный start.bat.