Вечерний детектив

Онлайн-детективная игра: команды проходят дело из точек, дверей, ключей и улик.

Структура workspace

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

• evening_detective_server/ — Go-бэкенд;
• evening_detective_frontend/ — Vue/TypeScript-фронтенд;
• email_server/ — старый собственный почтовый сервер, не нужен для локального запуска.

У каждого из двух основных проектов своя история Git и свой remote. Не удаляйте вложенные .git и не смешивайте коммиты между репозиториями.

Локальный запуск

Требования: Go, Docker Compose, Node.js 20.19+ или 22.12+, npm.

1. Зависимости сервера

cd evening_detective_server
docker compose -f docker-compose-db.yml up -d
cp .env.example .env
make run

Сервис запускает:

• gRPC на http://localhost:8080;
• REST gateway и Swagger на http://localhost:8090.

Для локального фронтенда в evening_detective_frontend/.env укажите:

VITE_API_URL=http://localhost:8090

2. Фронтенд

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

cd evening_detective_frontend
npm install
cp .env.example .env
npm run dev

Фронтенд будет доступен на http://localhost:5173.

3. Локальный пользователь

cd evening_detective_server
make dev-user

По умолчанию создаётся пользователь dev@example.com с паролем dev123456. Для изменения используйте DEV_USER_EMAIL и DEV_USER_PASSWORD.

Автономная площадка (ED-029, этапы 1–2)

venue/ — окружение для проведения игры на площадке без интернета. Локальная разработка описана выше и запускается отдельно.

Из корня workspace запустите:

make venue

Первый запуск с интернетом сам создаёт настройки и случайные секреты в venue/.env, готовит образы, запускает миграции и создаёт организатора. Повторные запуски используют готовое окружение без интернета. Email и пароль для входа указаны в VENUE_USER_EMAIL и VENUE_USER_PASSWORD в venue/.env; существующий файл настроек не перезаписывается. Аккаунт организатора при запуске синхронизируется с этими значениями.

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

make venue-update

Сайт доступен по http://localhost:8088; API и материалы обслуживаются тем же прокси. Для подключения по LAN задайте VENUE_BIND_IP=0.0.0.0 и APP_BASE_URL=http://<постоянный-IP-ноутбука>:8088 в venue/.env, затем повторите make venue. Прежние домены и доверенный HTTPS требуют отдельной настройки DNS и сертификатов на этапе 3.

Образы приложения, мигратора и прокси готовятся заранее. Runtime запускается без сборки и скачивания; приложение, база и RustFS подключены только к внутренней Docker-сети. Прокси дополнительно подключён к сети публикации порта. База и RustFS сохраняются в именованных томах. Миграции Goose выполняются до старта приложения. Для остановки без потери данных:

docker compose -f venue/docker-compose.yml --env-file venue/.env down

Не используйте down -v: это удаляет данные. После изменений кода или миграций выполните make venue-update, пока интернет доступен. Секреты, сборка, сертификаты и пакеты игры игнорируются Git в venue/.

APP_MODE=venue отключает SMTP, фоновые письма участия/отзывов и внешний webhook регистрации. Аккаунты готовятся через bootstrap; почтовая регистрация аккаунта и сброс пароля возвращают явную ошибку без изменения данных. Команды создаёт организатор на странице игры; участие подтверждается по существующим правилам: при создании в последние 24 часа до игры или при первом игровом действии. Для дополнительных операторов используйте отдельные локальные email и пароли в .env и снова выполните make venue (старые аккаунты сохраняются). Используйте только тестовые игры до реализации возврата результатов онлайн.

Проверки для разработчика находятся в tests/venue/ и не нужны для запуска площадки. deploy.py проверяет сценарии запуска без Docker; smoke.py проверяет работающее окружение и создаёт тестовый сценарий, игру, команду и материал через API:

python3 tests/venue/deploy.py
python3 tests/venue/smoke.py
docker compose -f venue/docker-compose.yml --env-file venue/.env down
docker compose -f venue/docker-compose.yml --env-file venue/.env up -d --no-build --pull never
python3 tests/venue/smoke.py --verify

Последняя команда проверяет ранее созданные записи и файл после перезапуска. Тестовые данные остаются в локальной базе; повторное создание запускайте только когда нужен новый набор. Дождитесь ответа /api/test/ping перед проверкой.

Проверки перед изменениями

Сервер:

cd evening_detective_server
make test

Фронтенд:

cd evening_detective_frontend
npm run type-check
npm run lint
npm run lint:css

При изменении protobuf сначала обновляйте сгенерированный код существующими командами make generate на сервере и npm run proto:gen на фронтенде. Сгенерированные файлы руками не редактируйте.

Сборка и публикация

Из корня workspace можно собрать и опубликовать root, backend и frontend одной командой:

make publish MSG="Исправить подсчёт ходов в игре"

Команда вызывает локальные build-команды репозиториев, создаёт коммит с указанным сообщением и выполняет git push.

Общая команда собирает бэкенд один раз и сохраняет артефакты в обе папки: prod/ и venue/. Обе используют backend/evening_detective_server, frontend/dist/ и migrations/; Compose называется docker-compose.yml, образ бэкенда описан в Dockerfile.backend. Фронтенд собирается отдельно для каждого окружения: production сохраняет текущие Vite-настройки, venue использует API через свой прокси (VITE_API_URL=/.). Локальные Goose и SQL подготовки аккаунта лежат в venue/backend/.

Для сборки артефактов обоих окружений используйте:

make build

make prod-build выполняет ту же общую сборку. make venue-update вызывает её и дополнительно подготавливает Docker-образы для автономного запуска. Команды обновляют только генерируемые артефакты в prod; конфигурация prod не меняется.

Окружение и секреты

Файлы .env предназначены только для локальных значений и не коммитятся. Начинайте настройку с .env.example. Секреты SMTP, JWT, S3, webhook и внешних API храните только в окружении или секрет-хранилище.

Публичный адрес приложения задаётся через APP_BASE_URL; он используется в ссылках из писем и QR-кодах команд.

Рабочий процесс

1. Перед изменением прочитайте корневой AGENTS.md и инструкции целевого проекта.
2. Делайте минимальное изменение в одном дочернем репозитории.
3. Запускайте релевантные проверки.
4. Коммиты и push выполняет только пользователь; агент никогда не коммитит и не отправляет изменения.

Текущие подробные инструкции:

• AGENTS.md — правила workspace;
• evening_detective_frontend/AGENTS.md — правила фронтенда;
• evening_detective_server/README.md — детали бэкенда.