# Backend — правила работы агента

## Стек

- Go `1.26`;
- gRPC + grpc-gateway;
- PostgreSQL через `pgx`;
- миграции Goose;
- S3-совместимое хранилище для файлов;
- MCP встроен в основной сервис.

## Структура

- `api/` — protobuf-контракт;
- `proto/` — сгенерированный Go-код;
- `internal/app/` — gRPC/HTTP handlers;
- `internal/services/` — бизнес-логика;
- `internal/repos/` — работа с PostgreSQL;
- `internal/modules/` — переиспользуемые модули;
- `migrations/` — миграции базы данных.

## Правила

1. Сначала найди всех callers изменяемой функции и существующий паттерн.
2. Делай минимальное изменение; каждый модуль разделяй на интерфейс и реализацию.
3. Бизнес-логику держи в services, SQL — в repos, транспорт — в app.
4. Новые HTTP-методы добавляй через `api/main.proto` и регенерируй код.
5. `proto/` и Swagger — сгенерированные файлы; руками их не редактируй.
6. Изменения схемы БД оформляй отдельной миграцией, совместимой с предыдущей версией.
7. Не добавляй `.env`, ключи, пароли или локальные артефакты в Git.
8. Коммиты и push выполняет только пользователь; агент никогда не коммитит и не отправляет изменения.

## Проверки

```sh
gofmt -w <изменённые-go-файлы>
go test ./...
```

После изменения protobuf:

```sh
make generate
```

Для проверки с PostgreSQL используй отдельную тестовую базу через
`TEST_DATABASE_URL`; интеграционные тесты не должны зависеть от production-базы.

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

```sh
docker compose -f docker-compose-db.yml up -d
cp .env.example .env
make run
```

gRPC слушает `:8080`, REST gateway — `:8090`.