импульс.

От короткой идеи бизнеса — к понятному проекту для студенческой команды.

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

HackAlem · MVP · FastAPI + SQLite · OpenAI Responses · Docker

Для полноценной работы AI-помощника нужен OpenAI API key: задайте OPENAI_API_KEY и AI_MODE=auto на сервере. Локально это можно сделать в .env в корне проекта, а при размещении — в переменных окружения хостинга. Без ключа сайт продолжит работать с шаблонными вопросами в резервном режиме. См. настройки AI.

Для бизнеса	Для команды	Для жюри
Уточнить задачу и увидеть, чего не хватает	Найти проект и предложить план работы	Повторить весь путь от описания до подтверждённого этапа

Серверные маршруты marketplace и пять экранов подключены к общей навигации. Экраны используют общий HTTP-клиент и также доступны в автономной странице. Шаги 1.5–1.6 завершены: бизнес-сценарий, навигация и marketplace проверены в Edge 23.09.2026; результаты и границы проверки — в отчёте браузерной приёмки.

Быстрый маршрут: запустить проект → повторить сценарий → посмотреть тесты и отчёты.

Оглавление

• Проблема и аудитория
• Что реализовано
• Сценарий для демонстрации
• Технологии
• Архитектура и структура
• Установка и запуск
• Повторяемая проверка для жюри
• Данные и интеграции
• Проверки проекта
• Ограничения MVP
• Развёрнутая версия

Проблема и аудитория

Проект посвящён подготовке бизнес-задач для студенческих команд. Его исходный сценарий — неполное описание, в котором нужно уточнить контекст, пользователей, данные, ограничения и критерии успеха. Цель и требования к этому сценарию зафиксированы в плане разработки.

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

Кому предназначен прототип:

• представителям бизнеса, которым нужно сформулировать прикладную задачу;
• студенческим командам, ищущим проекты с понятными ожиданиями;
• жюри и организаторам, которым нужно увидеть путь от описания до результата в одном интерфейсе.

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

Возможность	Что получает пользователь
AI-помощник	Анализ описания, минимум три уточняющих вопроса и предложения по заполнению карточки
Редактируемая карточка	12 полей с отдельными отметками «Подтверждаю»; все предложения AI можно изменить
Рейтинг готовности	Балл 0–100, расшифровка весов, уровень готовности и список недостающих сведений
Черновик и публикация	Сохранение рабочей версии и отдельный публичный снимок подтверждённых значений
Каталог	Сортировка по рейтингу, фильтры темы и готовности, выделение приоритетных задач
Профили команд	Название, интересы, навыки, технологии и накопленные баллы за этапы
Отклики	Идея, план, срок и необязательная HTTP(S)-ссылка на прототип
Решение бизнеса	Ручной выбор одной или нескольких команд, отказ либо отсутствие решения
Подтверждённые этапы	Сохранение результата и отдельное подтверждение с однократными +10 команде
Сохранение и конфликты	SQLite, восстановление данных после перезапуска и обнаружение устаревшей версии при редактировании
3.4 — демоданные	Готово: 5 описаний/карточек, 5 команд, 5 откликов; баллы 0/40/70/90/100; отдельная демо-БД
3.5 — тесты marketplace	Готово: фикстура исправлена, 5/5 серверных тестов
3.6 — интеграция и браузер	Общая оболочка подключена; сценарии каталога, откликов, выбора команд и этапов пройдены в браузерной приёмке участника 1 от 23.09.2026
3.7 — README	Готово: актуальные запуск, архитектура, контракты и проверки
3.8 — защита	Материалы готовы; общая репетиция ещё не проведена

Как устроен рейтинг

Баллы начисляются сервером за непустые подтверждённые поля. Каждая группа даёт полный вес, если выполнены все её условия; иначе — 0. Формула реализована в backend/scoring.py.

В сохранённой карточке блок «Следующий шаг» предлагает конкретное улучшение: вопрос, пример и возможный прирост баллов за всю группу. Кнопка переводит к пустому полю, подтверждению заполненного поля или сохранению. Сначала предлагаются группы, готовые к сохранению или подтверждению, затем — группы с большим весом. Примеры не вставляются в карточку автоматически.

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

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

Тема и название не добавляют баллов. Название нужно подтвердить для публичного заголовка, тему — для её отображения и фильтрации в каталоге.

Баллы	Уровень	Код API
0–39	Черновик	draft
40–69	Рабочая	working
70–89	Готовая	ready
90–100	Приоритетная	priority

Даже опубликованная задача с 0 баллами видна в каталоге и принимает отклики. Уровень «Черновик» характеризует полноту описания; отсутствие публикации — отдельное состояние.

Две независимые оценки: рейтинг задачи показывает готовность её описания. Баллы команды растут на +10 за каждый этап, подтверждённый бизнесом после выбора команды. Отклик сам по себе баллов не даёт; повторное подтверждение того же этапа не удваивает начисление.

Сценарий для демонстрации

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

Описание бизнеса → вопросы AI → ответы и редактирование
       → подтверждение → рейтинг → публикация
       → отклик команды → выбор бизнеса → этап → +10 команде

1. Бизнес описывает проблему. Например: «Хотим сократить очереди в кафе в обед».
2. AI помогает уточнить задачу. Возвращает вопросы и предложения по полям; неизвестные сведения должны оставаться пустыми. В резервном режиме вопросы формируются локально.
3. Человек проверяет содержание. Редактирует карточку и подтверждает выбранные поля. Сервер пересчитывает полноту описания.
4. Бизнес публикует задачу. В каталог попадает снимок подтверждённых значений; последующие правки черновика не меняют его до новой публикации.
5. Команда предлагает решение. Находит задачу, выбирает профиль и отправляет идею, план и срок.
6. Бизнес принимает решение. Выбирает одну или несколько команд либо отклоняет предложения. Автоматического назначения нет.
7. Прогресс подтверждается отдельно. Создаётся этап с описанием результата; после подтверждения выбранная команда получает +10 один раз за этот этап.

Ниже — готовые значения и точные кнопки для повторения этого сценария.

Технологии

Слой	Технологии	Назначение
Интерфейс	HTML5, CSS, JavaScript ES modules	Оболочка, редактор задачи и marketplace; отдельная сборка frontend не требуется
Среда сервера	Python 3.10+; в Docker — Python 3.13 slim	Выполнение серверного приложения
HTTP API	FastAPI 0.115.0, Uvicorn 0.30.6	REST API, Swagger UI, раздача статических файлов
Валидация	Pydantic 2.13.5	Проверка типов, полей и ограничений запросов
Данные	SQLite, стандартный модуль sqlite3	Задачи, публикации, команды, отклики и этапы
AI	OpenAI Platform, Responses API, модель gpt-4.1-mini по умолчанию	Уточнение бизнес-задачи; модель меняется через OPENAI_MODEL
HTTP к AI	Стандартные urllib.request и json, JSON Schema	Серверный запрос к OpenAI и проверка структурированного ответа; отдельный OpenAI SDK не используется
Конфигурация	python-dotenv 1.2.3, переменные окружения	Локальная конфигурация и ключ API
Запуск	Dockerfile, Docker Compose, Windows BAT, macOS/Linux SH	Повторяемая сборка и запуск
Проверки	Python unittest, Node.js node:test	Core, HTTP/repository и модульные JS-регрессии

Версии рабочих Python-зависимостей зафиксированы в backend/requirements.txt. Node.js нужен только для JS-тестов; React, npm-сборка и отдельный сервер frontend для MVP не требуются.

Архитектура и структура

В стандартной конфигурации интерфейс и API обслуживает один сервис FastAPI. Он отдаёт статические файлы и принимает запросы /api/...; сервис задач и marketplace используют общий SQLite-файл.

flowchart LR
    UI["Браузер<br/>Бизнес / Команда"] -->|"REST / JSON"| API["FastAPI<br/>backend/app.py"]
    API -->|"HTML / CSS / JS"| UI
    API --> TASKS["Задачи и версии<br/>TaskService"]
    TASKS --> SCORE["Рейтинг<br/>scoring.py"]
    TASKS --> REPO["Задачи и публикации<br/>TaskRepository"]
    REPO --> DB[("SQLite")]
    API --> MARKET["Маршруты marketplace<br/>Каталог, команды, отклики, этапы"]
    MARKET -->|"Публичные снимки"| REPO
    MARKET --> MREPO["MarketplaceRepository"]
    MREPO --> DB
    API --> AI["AI-адаптер<br/>Проверка JSON"]
    AI -->|"auto + ключ"| OPENAI["OpenAI Responses API"]
    AI -->|"fallback / нет ключа / ошибка"| LOCAL["Локальные вопросы"]
    SEED["Синтетический JSON<br/>data.seed_demo"] --> TASKS
    SEED --> MREPO
    classDef client fill:#e9f3d6,stroke:#587b39,color:#213618
    classDef core fill:#e8f1ed,stroke:#2f6650,color:#193c2d
    classDef external fill:#f3efe4,stroke:#8a7545,color:#473d26
    class UI client
    class API,TASKS,SCORE,REPO,MARKET,MREPO,DB core
    class OPENAI,LOCAL,SEED,AI external

Правила взаимодействия

• Подтверждение и публикация — отдельные действия. В опубликованном снимке неподтверждённые значения пустые. Каталог читает снимки через TaskRepository.list_published_tasks().
• Редактирование снимает подтверждение изменённых полей. Рабочий рейтинг пересчитывается, а старая публикация сохраняется до следующей публикации.
• Запись требует актуальную версию. PATCH, подтверждение и публикация получают expectedRevision; при конфликте сервер возвращает 409 и текущую задачу. Интерфейс сохраняет ввод и предлагает выбрать версию.
• Этапы сохраняются отдельно от начисления. SQLite-транзакция проверяет выбор команды и факт предыдущего подтверждения, чтобы повторный запрос не добавлял баллы.

Путь	Содержимое
frontend/index.html, frontend/styles.css	Общая оболочка, стили и навигация
frontend/app.js	Текущий сценарий бизнеса, редактор, рейтинг, переключение ролей и подключение экранов
frontend/business/	Выделенная зона участника 1; сейчас содержит правила, код сценария находится в app.js
frontend/shared/api.js	Общий HTTP-клиент и обработка ошибок API
frontend/marketplace/	Каталог, профили, отклики, этапы, отдельная демо-страница и JS-тесты
backend/app.py	Сборка FastAPI, маршруты ядра, подключение marketplace и статики
backend/tasks.py, backend/scoring.py, backend/db.py, backend/schemas.py	Жизненный цикл задач, рейтинг, SQLite и схемы данных
backend/ai.py, backend/config.py	AI-адаптер, резервный режим и настройки
backend/marketplace/	Собственные маршруты, схемы и репозиторий команд, откликов и этапов
backend/tests/core/, backend/tests/marketplace/	Серверные тесты
data/marketplace-seed.json, data/seed_demo.py	Демоданные и загрузчик через сервис задач и marketplace-репозиторий
Dockerfile, compose.yaml, start.bat, start.sh	Способы запуска
backend/runtime/	Локальная SQLite и временные файлы; исключены из Git
DEVELOPMENT_PLAN.md, docs/PARTICIPANT_2.md	Разделение работ, контракты и подробный отчёт проверок

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

Получить исходники

Скачайте архив репозитория и распакуйте его либо используйте Git:

git clone https://github.com/BAITC-Hacks/hack-4d63cc53-team.git
cd hack-4d63cc53-team

Все дальнейшие команды выполняются из корня проекта. Выберите один способ: Docker, start.bat для Windows, start.sh для macOS/Linux или ручной запуск. Команды PowerShell и терминала macOS/Linux приведены отдельно; команды docker compose одинаковы для всех трёх ОС. Для Docker локальный Python не нужен; для остальных вариантов нужен Python 3.10+ и интернет при первой установке зависимостей. Node.js для запуска сайта не требуется.

Вариант 1. Docker Compose

Нужно: установленный и запущенный Docker с Compose, свободный порт 8000 и интернет при первой сборке. На Windows/macOS можно использовать Docker Desktop с Linux-контейнерами, на Linux — Docker Engine с плагином Compose либо Docker Desktop.

1. Создайте файл настроек, если его ещё нет.

   Windows, PowerShell:

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

   macOS/Linux, терминал:

   [ -f .env ] || cp .env.example .env
   

2. Для повторяемого демо добавьте или установите в .env строку AI_MODE=fallback. Существующий ключ сохраняется, но в этом режиме не используется. Для настоящего OpenAI см. настройки интеграции.

3. Соберите и запустите приложение:

   docker compose up -d --build
   docker compose ps
   

4. Откройте http://127.0.0.1:8000/. Статус контейнера после запуска должен стать healthy.

Действие	Команда
Повторный запуск	docker compose up -d
Обновить после изменения кода	docker compose up -d --build
Посмотреть логи	docker compose logs -f app
Остановить приложение	docker compose stop

Пакеты устанавливаются при сборке в отдельный слой перед копированием кода. При неизменных зависимостях, базовом образе и сохранённом кэше Docker использует этот слой повторно. При запуске контейнера pip install не выполняется.

SQLite находится в томе app_runtime по пути /app/backend/runtime/app.sqlite3. Он сохраняется после обычной остановки, пересборки и пересоздания контейнера. Это отдельная база от локальной backend/runtime/app.sqlite3; данные автоматически между ними не копируются. Команда docker compose down -v удаляет том вместе с данными — для обычной остановки используйте команду из таблицы.

Вариант 2. Windows — двойной щелчок

Запустите start.bat двойным щелчком либо из PowerShell:

.\start.bat

Скрипт находит установленный Python 3.10+, создаёт отсутствующую .venv, копирует .env.example только при отсутствии .env, устанавливает зависимости и запускает сервер. Браузер открывается после успешной проверки /api/health; существующий ключ не перезаписывается. При ошибке окно остаётся открытым с пояснением. Для остановки нажмите Ctrl+C.

Вариант 3. macOS/Linux — start.sh

В терминале выполните:

sh start.sh

start.sh сам переходит в папку проекта, находит Python 3.10+ (python3 либо python), создаёт .venv при её отсутствии и устанавливает зависимости из backend/requirements.txt. Готовое совместимое окружение используется повторно, существующий .env сохраняется; при первом запуске настройки копируются из .env.example. После проверки /api/health сервер попробует открыть браузер. Если браузер не открылся, перейдите на http://127.0.0.1:8000/ вручную. Остановка — Ctrl+C в том же терминале.

Вместо sh start.sh можно один раз выдать право на выполнение и затем запускать файл напрямую:

chmod +x start.sh
./start.sh

Не переносите .venv между Windows, macOS и Linux: создавайте окружение на каждой машине отдельно. Если скрипт обнаружит несовместимую или повреждённую .venv, он остановится с пояснением и сохранит её. Используйте отдельный клон или вручную пересоздайте только виртуальное окружение. В Debian/Ubuntu для создания окружения может потребоваться пакет python3-venv.

Вариант 4. Python вручную

Windows, PowerShell:

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

macOS/Linux, терминал:

[ -d .venv ] || python3 -m venv .venv
[ -f .env ] || cp .env.example .env
.venv/bin/python -m pip install -r backend/requirements.txt
.venv/bin/python -m uvicorn backend.app:app --host 127.0.0.1 --port 8000

Используйте .venv, созданную на этой ОС. Откройте основной адрес вручную; остановка — Ctrl+C. Для автоматического открытия браузера замените последнюю команду на .\.venv\Scripts\python.exe -m backend.launch в PowerShell или .venv/bin/python -m backend.launch на macOS/Linux. Для разработки Uvicorn поддерживает --reload.

Проверка start.sh, 23.09.2026: скрипт запущен в Linux-контейнере с Python 3.13.15. Проверены создание чистой .venv и установка зависимостей, запуск из другой рабочей папки по пути с пробелами, доступность сайта и API, резервный AI без внешнего запроса, остановка через SIGINT (Ctrl+C), немедленный повторный запуск с сохранением .env и ошибочный запуск при занятом порте. Синтаксис проверен в sh и bash; три регрессионных теста TCP-порта прошли в Linux. Для повторного запуска исправлен захват порта в backend/launch.py на POSIX-системах. Непосредственный запуск на macOS и автоматическое открытие графического браузера в этой проверке не проверялись; контейнер работал без графической среды.

Адреса после запуска

Адрес	Назначение
Основной интерфейс	Весь пользовательский сценарий
Отдельное демо marketplace	Каталог, команды, отклики и этапы вне основной оболочки
Проверка сервера	JSON {"status":"ok"}
Swagger UI	Интерактивная документация API
OpenAPI JSON	Машиночитаемая схема API

Если запуск не получается

Симптом	Что проверить
Порт 8000 занят	Остановить предыдущий запуск через BAT/SH/Uvicorn или Docker-контейнер; использовать один способ запуска
Docker не соединяется с движком	Запустить Docker Desktop либо службу Docker Engine на Linux и дождаться её готовности
Python 3.10 or newer was not found	Установить Python 3.10+; на macOS/Linux проверить python3 --version
Не удалось создать .venv	Проверить возможность записи в папку и наличие модуля venv; в Debian/Ubuntu может понадобиться python3-venv
.venv/bin/python is unavailable	Использовать окружение для текущей ОС; start.sh не перезаписывает Windows или повреждённую .venv
Браузер не открылся автоматически	Открыть http://127.0.0.1:8000/ вручную после сообщения о готовности сервера
Вместо OpenAI показан резервный режим	Проверить AI_MODE, наличие ключа в .env именно этого сервера и причину в интерфейсе; после изменения настроек перезапустить сервер
Нет связи с сервером	Открывать страницу через http://127.0.0.1:8000/, а не двойным щелчком по HTML
После смены настроек ничего не изменилось	Перезапустить BAT/SH/Uvicorn; для Compose повторить docker compose up -d

Повторяемая проверка для жюри

Основной маршрут: одна новая задача от идеи до +10

Подготовка: до запуска установите AI_MODE=fallback в .env, затем запустите проект любым способом выше. Так демонстрация не зависит от ключа или внешнего сервиса; если сервер уже работает, перезапустите его после изменения настройки. Пример использует синтетические сведения. Новую задачу назовём «Предзаказ кафе — демо», новую команду — «Flow Makers Demo». На протяжении всего маршрута открывайте именно эту карточку.

1. Получить вопросы и заполнить карточку

В режиме «Бизнес» нажмите «Создать задачу». Введите:

Хотим сократить очереди в кафе в обед.

Нажмите «Проанализировать». Появятся минимум три уточняющих вопроса и явная отметка резервного режима. Можно ответить: нужно сократить ожидание; пользователи — гости и кассиры; доступны обезличенные времена заказов. Нажмите «Перейти к карточке» и заполните поля:

Поле	Готовое значение для демонстрации
Тема	Кафе
Название	Предзаказ кафе — демо
Контекст	В будни с 12:00 до 14:00 гости долго ждут у кассы
Потребность	Сократить время ожидания заказа
Пользователи	Гости кафе и кассиры
Данные	Обезличенные времена заказа и выдачи за две недели
Ограничения	Веб-прототип за две недели, без изменения кассы и интеграции с оплатой
Ожидаемый результат	Прототип предзаказа и отчёт о пилоте
Критерии успеха	Среднее ожидание на тестовой выборке сократилось на 20%
Контакт	Демо-менеджер кафе
Формат взаимодействия	Созвон по вторникам на 15 минут
Обратная связь	Менеджер проверяет прототип и отвечает в течение двух рабочих дней

Это условия демонстрационной задачи, а не заявленный достигнутый экономический эффект проекта.

2. Показать рост рейтинга и опубликовать

1. Отметьте «Подтверждаю» только у темы, названия, контекста, потребности и данных.
2. Нажмите «Сохранить и пересчитать». Ожидаемый рейтинг — 40/100: контекст/потребность дают 20, данные — ещё 20.
3. Подтвердите остальные заполненные поля и снова нажмите «Сохранить и пересчитать». Ожидаемый рейтинг — 100/100.
4. Нажмите «Опубликовать задачу». Появится подтверждение публикации; задача доступна в каталоге как приоритетная.

3. Отправить предложение команды

Переключитесь на «Команда» → «Команды». Создайте профиль:

Поле	Значение
Название	Flow Makers Demo
Интересы	Сервисы для кафе, UX
Навыки	JavaScript, исследование пользователей
Технологии	HTML, CSS

Нажмите «Создать профиль», затем «Каталог проектов». Найдите «Предзаказ кафе — демо» (можно использовать тему «кафе» и готовность «Приоритет»), нажмите «Открыть задачу».

В форме отклика вручную выберите Flow Makers Demo в списке команд — создание профиля не выбирает его автоматически. Заполните:

Поле	Значение
Идея	Экран предварительного заказа обедов для гостей кафе
План	Провести интервью, собрать макет и проверить его на пяти гостях
Срок	Две недели
Прототип	https://example.com/cafe-prototype — демонстрационная ссылка, необязательное поле

Нажмите «Отправить предложение». Отклик сохранится в статусе ожидания решения; баллы команды пока 0.

4. Выбрать команду и подтвердить этап

1. Переключитесь на «Бизнес» → «Мои задачи». У «Предзаказ кафе — демо» нажмите «Отклики».
2. У предложения Flow Makers Demo нажмите «Выбрать». Статус станет «Выбрана».
3. В верхнем списке выбранных команд укажите Flow Makers Demo и нажмите «＋ Зафиксировать этап».
4. В поле «Что сделано» введите Подготовлен и показан прототип предзаказа. В поле «Ссылка или описание результата» — Демонстрация пяти сценариев заказа на встрече с демо-менеджером.
5. Нажмите «Зафиксировать этап». Этап сохранится, но баллы ещё не начислены.
6. Нажмите «Подтвердить и начислить +10». Этап станет подтверждённым, а баллы этой команды увеличатся до 10. Рейтинг задачи останется 100.
7. Перезагрузите страницу. Снова откройте отклики и этапы, затем профиль команды: выбор, подтверждённый этап и баллы сохраняются. Кнопки повторного подтверждения этого этапа больше нет.

Результат показа: жюри видит подготовку задачи, объяснимый рост 40 → 100, публикацию, самостоятельный отклик, решение бизнеса и подтверждённый прогресс команды.

Дополнительные проверки

Действие	Ожидаемый результат
Изменить поле «Данные» и сохранить черновик	Подтверждение этого поля снимается; рабочий рейтинг становится 80. В каталоге остаётся прежняя публикация до отдельного обновления
Отправить отклики от разных команд	Бизнес может выбрать несколько, отклонить остальные либо оставить без решения
Открыть опубликованную seed-задачу кафе с 0 баллами	Она видна и принимает отклики наравне с другими опубликованными задачами
Одновременно редактировать задачу в двух вкладках	Устаревшее сохранение получает конфликт; интерфейс сохраняет ввод и предлагает выбрать версию

Готовые данные для каталога и повторной репетиции

Основной маршрут выше можно пройти на пустой базе. Для быстрого обзора разных уровней готовности есть готовый seed-набор.

Docker, добавить данные в текущую контейнерную базу:

docker compose exec app python -m data.seed_demo

Команда добавляет 5 задач, 5 команд и 5 откликов; повторный вызов добавит ещё один набор. Она не очищает том и не выполняет AI-запросы.

Python, отдельная новая база для чистой репетиции: сначала подготовьте .venv по инструкции ручного запуска и остановите другой сервер на порту 8000.

.\.venv\Scripts\python.exe -m data.seed_demo --database backend/runtime/jury-demo.sqlite3
$env:DATABASE_PATH = 'backend/runtime/jury-demo.sqlite3'
$env:AI_MODE = 'fallback'
.\.venv\Scripts\python.exe -m uvicorn backend.app:app --host 127.0.0.1 --port 8000

Параметр --database откажет, если файл уже существует, сохранив его содержимое. Для следующей репетиции выберите новое имя и задайте тот же путь в DATABASE_PATH. Уже запущенный сервер не переключит базу из-за изменения переменной в другом терминале.

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

Настройки

Переменная	Назначение
DATABASE_PATH	SQLite-файл; по умолчанию backend/runtime/app.sqlite3
AI_MODE	auto по умолчанию или fallback для явного локального режима
OPENAI_API_KEY	Ключ только на сервере, задаётся в локальном .env
OPENAI_MODEL	Модель адаптера; значение в коде по умолчанию — gpt-4.1-mini
CORS_ORIGINS	Разрешённые origin через запятую для отдельного frontend

Настройки запуска задавайте в .env. Переменные процесса имеют приоритет над файлом: если раньше задавали их вручную, используйте чистый терминал без этих значений. Для демо без внешнего запроса задайте AI_MODE=fallback; отдельная конфигурация демо описана ниже. Compose передаёт ключ, модель, собственный путь БД и AI_MODE из .env с учётом приоритета окружения; если AI_MODE не задана или пуста, используется auto. Без ключа контейнер также использует fallback.

Демоданные и восстановление демо

Набор — data/marketplace-seed.json, загрузчик — data/seed_demo.py. Он создаёт задачи через обычный core-сервис, подтверждает поля, вычисляет баллы и публикует снимки, затем связывает команды и отклики по фактическим новым ID. AI не вызывается.

Для воспроизводимой демонстрации создайте в корне отдельный файл .env.demo со следующим содержимым. Корневой .env сохраняется. Файлы .env.* уже исключены из Git, кроме .env.example.

DATABASE_PATH=backend/runtime/demo-new.sqlite3
AI_MODE=fallback
OPENAI_API_KEY=

Затем создайте новую базу и запустите сервер с конфигурацией из этого файла:

.\.venv\Scripts\python.exe -m data.seed_demo --database backend/runtime/demo-new.sqlite3
.\.venv\Scripts\python.exe -m uvicorn backend.app:app --host 127.0.0.1 --port 8000 --env-file .env.demo

--env-file поддерживается установленным Uvicorn; python-dotenv зафиксирован в backend/requirements.txt. Запускайте команды в чистом терминале, если ранее задавали DATABASE_PATH, AI_MODE или OPENAI_API_KEY как переменные процесса: они имеют приоритет и над .env.demo. Пустой ключ и AI_MODE=fallback в файле задают локальный анализ без OpenAI API. Перед запуском остановите другой сервер на порту 8000.

При активированном окружении: python -m data.seed_demo --database backend/runtime/demo-new.sqlite3. Запускать следует модулем из корня, не командой python data/seed_demo.py.

Если файл базы существует, --database откажет и сохранит его содержимое. Для повторной репетиции выберите новый путь, например backend/runtime/demo-rehearsal-2.sqlite3, укажите его в параметре --database и в DATABASE_PATH файла .env.demo, затем запустите сервер заново. Старую базу удалять не нужно. Уже работающий сервер не перечитывает настройки при изменении .env.demo.

Источники данных

Источник	Что используется
Ввод бизнеса	Исходное описание, ответы на вопросы, содержимое карточки и ручные подтверждения
Ввод команды	Профиль, идея, план, срок и ссылка на прототип
Решение бизнеса	Статус отклика и подтверждение результата этапа
Синтетический набор	5 описаний/карточек, 5 команд и 5 откликов для воспроизводимого показа
OpenAI Platform	Ответ на серверный запрос анализа в режиме auto при наличии ключа

Реальные выгрузки компаний, CRM, университетские базы и внешние каталоги команд не подключены. Контакты, ссылки и метрики в демонстрационном наборе условные. Упоминание технологий в профилях seed-команд не означает, что эти библиотеки используются приложением.

Демозадача	Баллы	Уровень
Кафе — очереди в обед	0	Черновик
Магазин — аналитика возвратов	40	Рабочая
Склад — проверка комплектации	70	Готовая
Образование — запись на консультации	90	Приоритетная
Сервис — маршрутизация обращений	100	Приоритетная

При загрузке набора публикуются все пять задач. Один seed-отклик получает статус selected, четыре — pending; этапы заранее не создаются. Загрузчик проходит обычные правила подтверждения, расчёта и публикации, затем связывает сущности по фактическим ID.

Как используется AI

Внешний вызов выполняется только сервером: POST https://api.openai.com/v1/responses. Модель по умолчанию — gpt-4.1-mini.

• Вход: description и answers. В режиме внешнего AI этот введённый текст передаётся OpenAI.
• Выход провайдера: JSON с fields, questions и missingFields. Сервер добавляет mode и reason для интерфейса.
• Промпт: требует минимум три разных уместных вопроса на русском, не выдумывать неизвестные контакты, сроки, метрики и источники; пользовательский текст рассматривается как данные.
• Проверка: строгая JSON Schema, завершённость ответа, точные ключи и типы, все 12 полей, допустимые длины, минимум три непустых уникальных вопроса.
• Параметры запроса: таймаут 15 секунд, max_output_tokens: 1600, store: false. Это настройки адаптера, а не гарантия достоверности содержания.
• Резервный режим: AI_MODE=fallback, отсутствие ключа, ошибка сети, таймаут или некорректный ответ приводят к локальным вопросам с явным объяснением причины. Шаблонные вопросы не выдаются за результат внешней модели.

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

Настройки

backend/config.py читает переменные окружения и локальный .env из корня репозитория. Переменные процесса имеют приоритет над .env. Ключ используется серверным AI-адаптером. Локальный .env исключён правилами .gitignore и .dockerignore из обычного добавления в Git и контекста Docker-сборки.

Переменная	Значение / назначение
AI_MODE	auto по умолчанию; fallback явно запрещает внешний AI-вызов. Другие значения не принимаются
OPENAI_API_KEY	Ключ OpenAI Platform, заданный локально; при отсутствии работает fallback
OPENAI_MODEL	gpt-4.1-mini по умолчанию
DATABASE_PATH	По умолчанию backend/runtime/app.sqlite3; Compose задаёт /app/backend/runtime/app.sqlite3
CORS_ORIGINS	Разрешённые origin через запятую для отдельного frontend; в обычном запуске интерфейс и API имеют один адрес

Для настоящего AI установите AI_MODE=auto и укажите свой ключ в OPENAI_API_KEY в .env в корне проекта или в переменных окружения хостинга. В примере замените your_openai_api_key_here на свой ключ; не добавляйте реальный ключ в Git и не вставляйте его во frontend.

AI_MODE=auto
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4.1-mini

После изменения настроек перезапустите сервер или перезапустите приложение на хостинге. Для Compose выполните docker compose up -d: ключ, модель и AI-режим передаются в контейнер при его создании. Другим участникам нужен собственный локальный .env или доступ к настроенному серверу: секретный файл через Git не передаётся.

Основные HTTP-маршруты

Точные схемы запросов и ответов доступны в Swagger UI и OpenAPI JSON после запуска.

Метод и путь	Назначение
GET /api/health	Доступность сервера
POST /api/analyze	Анализ описания и ответов
GET /api/tasks, POST /api/tasks	Список рабочих задач и создание
GET /api/tasks/{id}, PATCH /api/tasks/{id}	Чтение и изменение полей
POST /api/tasks/{id}/confirm	Подтверждение выбранных полей
POST /api/tasks/{id}/publish	Публикация отдельного снимка
GET /api/catalog?topic=кафе&readiness=draft	Каталог с необязательными фильтрами
GET /api/teams, POST /api/teams	Профили команд
POST /api/proposals, GET /api/tasks/{id}/proposals	Создание и просмотр предложений
PATCH /api/proposals/{id}	Ручной статус selected или rejected
POST /api/milestones, GET /api/tasks/{id}/milestones	Создание и просмотр этапов
POST /api/milestones/{id}/confirm	Подтверждение этапа; повтор возвращает awarded: false

Типовые ответы: 201 при создании, 200 при успешном чтении/изменении, 404 для отсутствующей сущности, 422 при неверном запросе, 409 при конфликте версии либо попытке начислить баллы невыбранной команде. expectedRevision обязателен для изменения, подтверждения и публикации задачи; берите его из последнего ответа сервера.

Проверки проекта

До выступления создайте отдельную демо-БД и откройте основной экран http://127.0.0.1:8000/. Проверьте пять баллов и режим AI. Общая навигация уже объединяет бизнес-сценарий и marketplace: используйте переключатель «Бизнес / Команда». Для выбора нескольких команд заранее добавьте ещё два отклика разных команд на исходную задачу кафе: seed уже содержит один отклик на неё. Подробный сценарий первых 90 секунд — в памятке участника 1.

Как запустить тесты

После установки Python-зависимостей выполните из корня проекта в отдельном PowerShell-терминале:

.\.venv\Scripts\python.exe -m unittest discover -s backend/tests/marketplace -p 'test_*.py' -v

После установки Python-зависимостей выполните из корня проекта в отдельном PowerShell-терминале:

$env:AI_MODE = 'auto'
.\.venv\Scripts\python.exe -m unittest discover -s backend/tests/core -p 'test_*.py' -v
.\.venv\Scripts\python.exe -m unittest discover -s backend/tests/marketplace -p 'test_*.py' -v

AI_MODE=auto нужен тестам ветки OpenAI: они подставляют ответы транспорта и не выполняют платные запросы. Тесты используют временные базы; настройка процесса не меняет режим уже работающего сервера. После проверки закройте этот тестовый терминал, чтобы его переменные не влияли на последующий запуск демо.

Выполненная проверка	Результат
Core unittest	20/20: рейтинг, подтверждения, версии, снимки, SQLite, API и AI с заглушками
Marketplace unittest	6/6: каталог, решения, этапы, целостность seed-данных и входные данные
JS marketplace	11/11 в тестовой DOM-среде: формы, фильтры, выбор команды, этапы и сообщения
Реальный Uvicorn, временная БД, свободный порт	HTTP smoke пройден: основной HTML, demo/static, docs, каталог/фильтр, отклик на низкий рейтинг, две выбранные команды/отказ, этап +10 один раз, пробельные тела 422
Перезапуск с той же БД	Решения, этап и баллы сохранены; рейтинг задачи не изменился
Seed CLI	5/5/5, баллы 0/40/70/90/100; отказ для существующего файла сохранил его байты
Браузерная приёмка 23.09.2026	Пройдена в Edge: создание и подтверждение карточки, публикация и снимки, навигация, каталог, отклики, выбор команд, этапы, конфликты вкладок и потеря связи; подробный отчёт
Общий HTTP-клиент, 23.09.2026	8 проверок с подменой API пройдены; синтаксис оболочки и клиента проверен. В тот же проход повторно пройдены 20 backend-тестов
Реальный AI	В этом проходе не вызывался

Последний локальный автоматический прогон прошёл 20 core-, 6 marketplace- и 21 JavaScript-тест (10 подсказок рейтинга и 11 marketplace), всего 47/47. В нём также прошли проверки синтаксиса frontend/app.js, frontend/business/rating-guide.js, frontend/marketplace/marketplace.js и git diff --check. Реальный AI, браузерный сценарий, Docker, HTTP smoke, чистый запуск на другом компьютере и общая репетиция в этом прогоне не выполнялись; сохранённые результаты этих отдельных проверок относятся к датированным отчётам выше.

При наличии Node.js можно проверить JS-модуль и синтаксис:

node --test frontend/business/rating-guide.test.mjs
node --test frontend/marketplace/marketplace.test.mjs
node --check frontend/app.js
node --check frontend/shared/api.js
node --check frontend/marketplace/marketplace.js
node --check frontend/marketplace/demo.js

Что проверяют тесты в репозитории

Набор	Объявлено тестов	Предмет проверки	Исходники
Core	20	Рейтинг, версии, подтверждения, публикации, SQLite, API и AI с подменой транспорта	test_core.py
Marketplace backend	6	Каталог, валидация запросов, целостность seed-сценария, ручные решения и однократные баллы за этап	test_marketplace.py, test_http.py
Подсказки рейтинга JavaScript	10	Выбор следующего шага, условия группы, подтверждения, несохранённые изменения и отсутствие мутаций	rating-guide.test.mjs
Marketplace JavaScript	11	Формы, фильтры, выбор команды, этапы и сообщения; используются подставные DOM и fetch	marketplace.test.mjs
Всего	47	Число объявленных тестов, без отдельного подсчёта subTest

Количество объявленных тестов не означает, что все они проходят. JS-наборы проверяют отдельные модули и не заменяют проверку интерфейса в браузере.

Проверка улучшения рейтинга

При проверке этой доработки 23.09.2026 прошли 10/10 тестов подсказок рейтинга, проверки синтаксиса frontend/app.js и frontend/business/rating-guide.js, а также git diff --check. В Chrome на отдельной временной SQLite и с AI_MODE=fallback проверены переходы 85 → 100 после подтверждения и 100 → 80 после удаления данных и сохранения. Для группы из двух полей проверены поочерёдный фокус подтверждений, переход к кнопке сохранения без автоматического действия и отсутствие повторного сообщения о приросте. Блок помещается в экран шириной 390 px; у существующего индикатора этапов на этой ширине остаётся горизонтальное переполнение.

JS-набор marketplace теперь проходит 11/11: тестовая имитация браузера дополнена window.dispatchEvent, который требуется общему HTTP-клиенту для события доступности API. Утверждения тестов не ослаблялись. В том же локальном прогоне прошли 20/20 core- и 6/6 marketplace Python-тестов; это автоматическая проверка модулей, а не повторная браузерная приёмка.

Сохранённые отчёты

В отчёте участника 2 описан прогон от 23.09.2026 на ревизии 8e3eace: автоматические тесты, сценарии Chrome и Docker. Более поздние отметки участников находятся в плане разработки. Указанные там результаты относятся к описанным проходам; для оценки текущей рабочей копии выполните команды и демонстрационный маршрут выше.

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

Ограничение	Что это означает
Нет регистрации и серверного разграничения ролей	«Бизнес / Команда» переключает демонстрационные экраны. Все профили доступны для выбора; это не авторизация
AI и рейтинг требуют участия человека	Модель может ошибаться. Формула показывает полноту подтверждённого описания, а не качество идеи или доказанную пользу решения
Исходное описание существующей задачи не обновляется	API изменяет поля карточки; при правке rawDescription интерфейс предупреждает, что исходный текст на сервере остаётся прежним
Этапы упрощены	Есть описание/evidence и подтверждение. Нет полноценного трекера, независимой проверки результата и приёмки файлов
Нет чата, уведомлений, платежей и файлового хранилища	Взаимодействие представлено полями карточки и откликами; ссылка на прототип ведёт на внешний ресурс
Локальная конфигурация запуска	Основной клиент по умолчанию обращается к API на порту 8000. Для другого адреса нужен window.API_BASE; Compose публикует порт только на 127.0.0.1
Демоданные условные	CRM, внешние базы компаний и реальные каталоги студенческих команд не подключены
Проверки имеют ограниченный охват	В сохранённых отчётах не приведены результаты нагрузочного тестирования, проверки других браузеров и чистого запуска на компьютере другого участника; повторная визуальная проверка последних изменений отмечена как незавершённая

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

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

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

• Исходный код на GitHub
• План разработки и разделение работ
• Серверные контракты и подробный отчёт проверок