# Вечерний детектив Онлайн-детективная игра: команды проходят дело из точек, дверей, ключей и улик. ## Структура workspace Корневой репозиторий `agents` хранит рабочие инструкции и документацию. Код живёт в двух отдельных репозиториях: - [`evening_detective_server/`](evening_detective_server/) — Go-бэкенд; - [`evening_detective_frontend/`](evening_detective_frontend/) — Vue/TypeScript-фронтенд; - [`email_server/`](email_server/) — старый собственный почтовый сервер, не нужен для локального запуска. У каждого из двух основных проектов своя история Git и свой remote. Не удаляйте вложенные `.git` и не смешивайте коммиты между репозиториями. ## Локальный запуск Требования: Go, Docker Compose, Node.js 20.19+ или 22.12+, npm. ### 1. Зависимости сервера ```sh 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` укажите: ```dotenv VITE_API_URL=http://localhost:8090 ``` ### 2. Фронтенд В другом терминале: ```sh cd evening_detective_frontend npm install cp .env.example .env npm run dev ``` Фронтенд будет доступен на `http://localhost:5173`. ### 3. Локальный пользователь ```sh cd evening_detective_server make dev-user ``` По умолчанию создаётся пользователь `dev@example.com` с паролем `dev123456`. Для изменения используйте `DEV_USER_EMAIL` и `DEV_USER_PASSWORD`. ## Автономная площадка (ED-029, этапы 1–2) `venue/` — окружение для проведения игры на площадке без интернета. Локальная разработка описана выше и запускается отдельно. Из корня workspace запустите: ```sh make venue ``` Первый запуск с интернетом сам создаёт настройки и случайные секреты в `venue/.env`, готовит образы, запускает миграции и создаёт организатора. Повторные запуски используют готовое окружение без интернета. Email и пароль для входа указаны в `VENUE_USER_EMAIL` и `VENUE_USER_PASSWORD` в `venue/.env`; существующий файл настроек не перезаписывается. Аккаунт организатора при запуске синхронизируется с этими значениями. После изменения кода обновите площадку, пока интернет доступен: ```sh 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 выполняются до старта приложения. Для остановки без потери данных: ```sh 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: ```sh 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` перед проверкой. ## Проверки перед изменениями Сервер: ```sh cd evening_detective_server make test ``` Фронтенд: ```sh 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 одной командой: ```sh 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/`. Для сборки артефактов обоих окружений используйте: ```sh 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`](AGENTS.md) и инструкции целевого проекта. 2. Делайте минимальное изменение в одном дочернем репозитории. 3. Запускайте релевантные проверки. 4. Коммиты и push выполняет только пользователь; агент никогда не коммитит и не отправляет изменения. Текущие подробные инструкции: - [`AGENTS.md`](AGENTS.md) — правила workspace; - [`evening_detective_frontend/AGENTS.md`](evening_detective_frontend/AGENTS.md) — правила фронтенда; - [`evening_detective_server/README.md`](evening_detective_server/README.md) — детали бэкенда.