207 lines
10 KiB
Markdown
207 lines
10 KiB
Markdown
# Вечерний детектив
|
||
|
||
Онлайн-детективная игра: команды проходят дело из точек, дверей, ключей и улик.
|
||
|
||
## Структура 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) — детали бэкенда.
|