agents/README.md

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

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

Структура 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.

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

Сервер:

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 на фронтенде. Сгенерированные файлы руками не редактируйте.

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

Файлы .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 — детали бэкенда.