МОСТ

Платформа, которая помогает бизнесу превратить описание проблемы в понятную задачу, а студенческим командам — предложить решение.

Сценарий: описание → уточняющие вопросы → редактируемая карточка → рейтинг готовности → подтверждение → публикация → отклик → решение бизнеса.

Хакатонный MVP. Роли переключаются без регистрации; это демонстрационный режим, а не система разграничения доступа.

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

Нужны Git, Docker Engine с Compose v2 либо Docker Desktop. Для сборки образов нужен доступ к реестрам образов и пакетам. Доступ к приватному репозиторию должен быть настроен отдельно.

git clone https://github.com/BAITC-Hacks/hack-b70aa203-shmaloogles.git
cd hack-b70aa203-shmaloogles
cp .env.example .env
docker compose up -d --build
docker compose ps

Сервис	Адрес по умолчанию
Приложение	http://localhost:3000
REST API	http://localhost:8080/api
Проверка API и подключения к БД	http://localhost:8080/health
PostgreSQL	localhost:5432

При первом запуске пустой БД автоматически выполняются SQL-схема и демоданные из backend/db/. Данные сохраняются в Docker volume postgres_data.

По умолчанию включён mock AI: ключ не нужен, но ответы заглушки не доказывают качество реальной модели.

curl -fsS http://localhost:8080/health
# {"status":"healthy"}
curl -fsS 'http://localhost:8080/api/tasks?sort=readiness_desc'
curl -fsS http://localhost:8080/api/teams

Настройки

Compose читает корневой .env. Не добавляйте его и API-ключи в Git.

Переменная	По умолчанию	Назначение
FRONTEND_PORT	3000	Порт интерфейса на хосте
API_PORT	8080	Порт API на хосте
POSTGRES_PORT	5432	Порт БД на хосте
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD	shmaloogles	Параметры первоначального создания БД
NUXT_PUBLIC_API_BASE	http://localhost:8080	Адрес API, доступный браузеру; без завершающего /
CORS_ORIGIN	http://localhost:3000	Точный origin интерфейса: схема, хост и порт
AI_MODE	mock	mock или openai
OPENAI_API_KEY	пусто	Ключ провайдера для режима openai
AI_MODEL	gpt-4.1-mini	Модель, настроенная в Compose
AI_BASE_URL	https://api.openai.com/v1	Базовый адрес провайдера; при необходимости добавьте в .env
AI_TIMEOUT	20s	Таймаут AI-запроса
AI_FALLBACK	false	Разрешить переход на заглушку при ошибке реального AI
DATABASE_URL	см. .env.example	Подключение при локальном запуске Go; Compose собирает свой URL из POSTGRES_*

В Compose внутренний адрес API для Nuxt задан как NUXT_API_BASE=http://api:8080. Браузер использует отдельный NUXT_PUBLIC_API_BASE: имя контейнера api ему недоступно.

Для реального AI измените .env:

AI_MODE=openai
OPENAI_API_KEY=replace-with-your-key
AI_MODEL=gpt-4.1-mini
AI_FALLBACK=false

Примените настройки:

docker compose up -d

AI возвращает режим provider, mock или fallback. При разрешённом fallback ошибка провайдера может завершиться успешным ответом заглушки — учитывайте это на демонстрации. Промпты, контракты и обработка ошибок описаны в AI_SCORING.md.

Развёртывание на сервере

Существующие Dockerfile собирают Go-бинарник и production-сборку Nuxt. Compose запускает три сервиса: frontend, api, postgres, с проверками готовности API/БД и политикой restart: unless-stopped.

Закрытый демостенд

На сервере выполните быстрый запуск. Если открываете интерфейс непосредственно по IP сервера, задайте в его .env реальные адреса, например:

NUXT_PUBLIC_API_BASE=http://192.168.1.50:8080
CORS_ORIGIN=http://192.168.1.50:3000

После docker compose up -d открывайте http://192.168.1.50:3000. Замените пример на IP своего сервера. При изменении портов обновите и оба URL. localhost в браузере посетителя означает компьютер посетителя, а не сервер.

Для доступа через SSH-туннель можно оставить исходные URL. На своём компьютере выполните:

ssh -N -L 3000:127.0.0.1:3000 -L 8080:127.0.0.1:8080 user@server

Откройте http://localhost:3000. Сам туннель не закрывает опубликованные Docker-порты на сервере.

Перед публикацией в интернете

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

• Ограничьте доступ к демостенду VPN, SSH или авторизацией на reverse proxy.
• Уберите внешнюю публикацию PostgreSQL. Для proxy на хосте привяжите порты frontend/API к 127.0.0.1 в Compose.
• Настройте HTTPS на reverse proxy; HTTPS-интерфейс должен обращаться к HTTPS API.
• Укажите публичный адрес API в NUXT_PUBLIC_API_BASE, адрес интерфейса — в CORS_ORIGIN.
• Замените демонстрационный пароль БД до её первого запуска. В текущем Compose пароль включается в URL, поэтому используйте URL-безопасное значение.

TLS, домен и авторизация на proxy в репозитории не настроены. Это необходимые отдельные шаги для внешнего стенда, а не готовые возможности Compose.

Обслуживание и данные

# Последние сообщения сервисов
docker compose logs --tail=100 api frontend postgres

# Следить за API
docker compose logs -f api

# Остановка с сохранением БД
docker compose down

# Пересборка после обновления исходников
docker compose up -d --build

Скрипты docker-entrypoint-initdb.d выполняются только на пустой БД. Пересборка контейнеров не применяет новые миграции к существующему volume. Изменение POSTGRES_PASSWORD в .env также не меняет пароль уже созданного пользователя.

Резервная копия из запущенного контейнера, команда выполняется из корня проекта:

docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > most-backup.dump

Проверка читаемости архива:

docker compose exec -T postgres pg_restore --list < most-backup.dump

Храните копию отдельно от сервера. Проверка списка не заменяет пробное восстановление в отдельную БД.

Полный сброс только для ненужных демоданных:

# Удаляет volume и все данные проекта в нём
docker compose down -v
docker compose up -d --build

Локальная разработка

Для работы без контейнеров приложения: Go 1.22+, Node.js 22 и npm; PostgreSQL 16 можно оставить в Docker. Команды ниже предполагают стандартные порты и учётные данные из .env.example.

docker compose up -d postgres

Backend в отдельном терминале:

cd backend
export DATABASE_URL='postgres://shmaloogles:shmaloogles@localhost:5432/shmaloogles?sslmode=disable'
export CORS_ORIGIN='http://localhost:3000'
export AI_MODE=mock
go run ./cmd/api

Go-сервер читает переменные окружения, но сам не загружает корневой .env. При необходимости экспортируйте параметры реального AI. PORT задаёт порт локального Go-сервера; API_PORT используется Compose.

Frontend в другом терминале:

cd frontend
npm ci
npm run dev

Не запускайте контейнерные api/frontend одновременно с локальными процессами на тех же портах.

Проверки

Backend:

cd backend
test -z "$(gofmt -l .)"
go test ./... -count=1
go vet ./...
go build ./...

Для PostgreSQL-интеграционных тестов задайте AI_TEST_DATABASE_URL, указывающий на отдельную тестовую БД, предварительно применив к ней backend/db/migrations/000001_init.up.sql и backend/db/seed.sql. Без этой переменной проверки, зависящие от БД, могут быть пропущены. Готовая последовательность есть в backend CI.

Frontend:

cd frontend
npm ci
npm run typecheck
npm run build

В frontend/package.json нет отдельных команд lint и test. Существующий GitHub Actions workflow проверяет backend, включая тесты с PostgreSQL; он не подтверждает исправность frontend или полного браузерного сценария.

Архитектура

Часть	Реализация и ответственность
Интерфейс	Nuxt 4, Vue 3, TypeScript; формы, каталог, карточки и отклики
Backend	Go, REST/JSON; жизненный цикл задач, валидация, AI, скоринг и отклики
Хранение	PostgreSQL 16, pgx; задачи, команды и предложения
AI	Уточнение описания и генерация карточки; mock либо внешний провайдер

Браузер и серверная часть Nuxt обращаются к Go API; Go работает с PostgreSQL и AI-провайдером. Ключ AI находится только на backend.

Основные каталоги: frontend/app/, backend/cmd/api/, backend/internal/, backend/db/. Контракты REST: backend/API.md. Продуктовые требования: docs/SPEC.md.

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

Рейтинг измеряет заполненность, а не достоверность фактов или смысловое качество текста. Его рассчитывает Go-код, не LLM. null, пустая строка и строка из пробелов дают 0.

Категория	Правило	Максимум
Контекст и потребность	По 10 за context и need	20
Данные	Заполнено data	20
Ожидаемый результат	Заполнено expected_result	15
Критерии успеха	Заполнено success_criteria	15
Ограничения	Заполнено constraints	10
Пользователи	Заполнено users	10
Связь с бизнесом	По 5 за contact и interaction_format	10

title и topic входят в карточку и подсказки, но не добавляют баллы.

Баллы	Уровень
0–39	Draft — требует уточнения
40–69	Workable — рабочая
70–89	Ready — готовая
90–100	Priority — приоритетная

Статусы публикации отдельные: draft → confirmed → published. Подтверждение не публикует задачу автоматически. Каталог показывает опубликованные задачи, по умолчанию сортирует по убыванию рейтинга, поддерживает фильтры topic, readiness_level и сортировку readiness_asc / readiness_desc. Значения фильтра уровня передаются в нижнем регистре.

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

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

Демонстрация за 5 минут

1. В роли бизнеса создайте задачу: «Теряем заявки клиентов в переписке. Хотим навести порядок».
2. Получите уточняющие вопросы и ответьте на часть из них. Покажите, используется реальный AI или mock.
3. Откройте сгенерированную карточку, проверьте сведения и исправьте текст.
4. Покажите текущие баллы и недостающие поля. Допишите конкретный результат и критерии успеха, сохраните и покажите рост рейтинга.
5. Подтвердите задачу, затем опубликуйте. Найдите её в каталоге, покажите сортировку и фильтр.
6. Переключитесь на команду, отправьте идею, план, срок и ссылку на прототип.
7. Вернитесь к бизнесу и примите либо отклоните предложение.

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

Если что-то не работает

Симптом	Что проверить
port is already allocated	Занятый порт; измените *_PORT и соответствующие URL либо остановите другой процесс
Интерфейс открыт, запросы не проходят	NUXT_PUBLIC_API_BASE доступен с компьютера пользователя, API работает, CORS_ORIGIN точно совпадает с origin страницы
Работает серверный запрос, но не браузерный	Различие NUXT_API_BASE и NUXT_PUBLIC_API_BASE; HTTP API под HTTPS-интерфейсом
API unhealthy или не стартует	docker compose logs --tail=100 api postgres; доступность БД и фактический пароль существующего volume
Таблицы отсутствуют после изменения SQL	Инициализация не повторяется на существующем volume; нужна явная миграция
AI возвращает заглушку	AI_MODE, AI_FALLBACK, поле mode и причина fallback в ответе
AI падает при запуске или запросе	Ключ, модель, настройки провайдера, доступность сети и AI_TIMEOUT

Инструкция сверена с исходниками main на коммите 5ff167b. Это сверка кода и конфигурации; она не означает, что развёртывание было выполнено в окружении автора README.