# Стандарт Go-бэкенда

Обязательный стандарт для Go-кода в `evening_detective_server`. Он описывает
основной вариант решения; отклонение требует разрешения пользователя и
короткого письменного обоснования в задаче или рядом с изменением.

## 1. Основной принцип

Пиши самый маленький код, который явно выражает бизнес-правило. Перед новым
типом, интерфейсом или пакетом проверь, нельзя ли использовать существующий
код или стандартную библиотеку.

Перед изменением функции найди всех её callers и существующий паттерн
использования. Исправляй общее место, через которое проходят все callers, а не
только первый найденный путь.

Не добавляй:

- абстракцию с одной реализацией без границы подмены;
- исключение: для `internal/modules` интерфейс обязателен даже при одной
  реализации;
- общий пакет для одной функции;
- конфигурацию для значения, которое не меняется;
- дублирующую валидацию в каждом handler-е;
- DTO, если существующая структура уже является контрактом нужного слоя.

## 2. Структура и зависимости

```text
api/                         protobuf-контракт
proto/                       сгенерированный Go-код
internal/app/                gRPC/HTTP handlers и mapping транспорта
internal/services/<name>/    прикладные сценарии и бизнес-правила
internal/repos/<name>/       PostgreSQL и модели хранения
internal/modules/<name>/     переиспользуемая техническая возможность
migrations/                  изменения схемы базы данных
cmd/<name>/                  сборка и запуск приложения
```

Допустимое направление зависимостей:

```text
cmd → app → services → repos
              ↘ modules
```

- По прикладной логике `app` зависит только от `services`; `proto` используется
  как транспортный контракт. Прямые зависимости от `repos` и `modules` в
  handlers и mapping запрещены.
- `cmd` собирает граф зависимостей и может импортировать `services`, `repos` и
  `modules` для wiring.
- `services` не импортируют `app` и `proto`.
- `repos` не знают о protobuf, HTTP, gRPC, ролях транспорта и UI.
- `modules` не знают о конкретном use case приложения. Если код нужен только
  одному сервису, он остаётся в этом сервисе.
- Циклические зависимости запрещены; не исправляй их дополнительным
  `common`-пакетом без конкретной общей ответственности.

Новый пакет получает имя по ответственности в `snake_case`, как принято в
репозитории: `game_service`, `teams_repo`, `file_storage`. Не используй
`utils`, `helpers`, `common` и `misc` для несвязанных функций.

## 3. Handler (`internal/app`)

Handler делает только транспортную работу:

1. получает request и `context.Context`;
2. извлекает пользователя, роль и параметры запроса;
3. вызывает один прикладной метод сервиса;
4. преобразует результат в protobuf response;
5. возвращает ошибку через существующий gRPC/gateway-механизм.

Handler не содержит SQL, транзакций, правил перехода состояний, расчётов и
проверок, которые должны быть одинаковыми для нескольких callers.

Именуй методы по protobuf RPC. Вспомогательные mapping-функции держи в
отдельном `*_mapper.go` рядом с handler-ом; они не должны выполнять запросы в
базу. Данные, которые нельзя показывать конкретному caller-у, фильтруй на
границе выдачи или в сервисе — в зависимости от того, является ли это
транспортным представлением или бизнес-правилом доступа.

```go
func (s *server) GetGame(ctx context.Context, req *proto.GetGameReq) (*proto.GetGameRsp, error) {
	game, err := s.gameService.Get(ctx, req.GetId(), currentUserID(ctx))
	if err != nil {
		return nil, err
	}
	return mapGetGameResponse(game), nil
}

// game_mapper.go
func mapGetGameResponse(game *Game) *proto.GetGameRsp {
	return &proto.GetGameRsp{Game: &proto.Game{Id: int32(game.ID), Name: game.Name}}
}
```

## 4. Service (`internal/services`)

Сервис представляет один прикладной сценарий или связную область. В нём
находятся:

- валидация входных данных и бизнес-инварианты;
- проверка прав, если она относится к правилу операции;
- orchestration нескольких repositories/modules;
- границы транзакции, когда операция должна быть атомарной;
- преобразование данных хранения в модель, нужную use case.

Публичные методы сервиса принимают `context.Context` первым аргументом,
возвращают результат и `error`, не принимают protobuf-типы и не формируют
HTTP/gRPC-ответы.

Называй сервис по области (`ScenarioService`), а методы — по действию
(`Create`, `Get`, `Update`, `Delete`, `List`). Не создавай интерфейс сервиса
только ради mock-а: интерфейс нужен на границе, где есть подмена или его
использует другой пакет как зависимость. Интерфейс объявляет потребитель; для
внутреннего concrete-сервиса используй структуру напрямую, если другого
варианта нет.

Повторяющееся правило размещай в общем сервисном методе или repository, через
который проходят все callers. Не копируй guard в handlers.

Mapping-функции не определяй внутри методов сервиса. Выноси их в отдельные
функции и файл `*_mapper.go` рядом с сервисом. Mapping только преобразует типы:
он не выполняет I/O, не меняет состояние и не принимает бизнес-решения.

```go
// service.go
func (s *Service) Get(ctx context.Context, id int) (*Game, error) {
	game, err := s.games.GetGameByID(ctx, id)
	if err != nil {
		return nil, err
	}
	return mapStoredGame(game), nil
}

// service_mapper.go
func mapStoredGame(game *games_repo.Game) *Game {
	return &Game{ID: game.ID, Name: game.Name}
}
```

## 5. Repository (`internal/repos`)

Repository — единственное место для SQL и обращения к PostgreSQL. Он:

- принимает `context.Context`;
- использует параметризованные запросы, никогда не склеивает значения в SQL;
- возвращает типы своей предметной области и ошибки;
- проверяет `rows.Err()` после итерации;
- закрывает `rows` через `defer` сразу после успешного запроса;
- переводит известные ошибки драйвера в sentinel-ошибки пакета.

SQL держи рядом с методом, которому он нужен. Не вводи query builder и общий
репозиторный слой без повторяющейся проверенной потребности.

Методы репозитория не проверяют права пользователя и не знают о protobuf.
Уникальность, внешние ключи и другие инварианты, которые база может обеспечить
надёжно, фиксируй также ограничением или индексом миграции.

Изменение схемы оформляй отдельным SQL-файлом с уникальным timestamp-именем,
совместимым с предыдущей схемой. Изменение модели и миграции делай в одной
задаче.

## 6. Modules (`internal/modules`)

Модуль содержит техническую или переиспользуемую возможность, независимую от
конкретного прикладного сценария: хранилище файлов, JWT, отправка email,
очистка текста, генерация PDF.

Каждый модуль разделяй на интерфейс и реализацию. Интерфейс размещай в его
пакете, реализацию держи непубличной, а конструктор возвращай как интерфейс.
Не превращай каждый маленький helper в модуль; если код уже является модулем,
для него интерфейс обязателен.

## 7. Типы, mapping и protobuf

- Protobuf — внешний транспортный контракт. Сгенерированные файлы в `proto/`
  и Swagger вручную не редактируй.
- Новые HTTP-методы добавляй через `api/main.proto`, затем запускай генерацию
  `make generate`.
- Преобразование `proto ↔ domain/storage` находится в `app` или пакете,
  которому принадлежат обе модели; бизнес-правила в mapping не прячь.
- Любой mapping, принадлежащий сервису, находится в отдельной функции и файле
  `*_mapper.go`, а не внутри метода сервиса.
- Модель, которой владеет один пакет, объявляй в этом пакете. Не создавай
  дубликаты структуры в `internal/repos` и `internal/services` без различий
  ответственности.
- Публичные типы, функции и поля документируй, если их назначение не очевидно
  из имени. Непубличные имена предпочтительнее, если символ не нужен за
  пределами пакета.
- Используй `int` для идентификаторов, если контракт проекта не требует
  другого типа; не добавляй конвертацию без границы API или базы.

## 8. Ошибки и context

- Возвращай ошибки, не паникуй в обработке пользовательского ввода, БД,
  файлов, сети и внешних сервисов.
- Для ожидаемых веток объявляй sentinel-ошибку в пакете, который владеет
  смыслом ошибки; проверяй её через `errors.Is`.
- Оборачивай ошибку с контекстом через `%w`, например
  `fmt.Errorf("загрузить сценарий %d: %w", id, err)`.
- Не сравнивай текст ошибки и не теряй исходную ошибку без причины.
- Каждый внешний вызов получает переданный `context.Context`; timeout нужен на
  границе долгой операции или фонового worker-а.
- Не помещай обязательные параметры операции в context. В context допустимы
  только request-scoped данные, уже принятые проектным middleware.
- Не логируй пароли, токены, персональные данные и содержимое пользовательских
  файлов.

## 9. SQL и транзакции

- SQL-шаблоны пиши в многострочном raw string с отступами и переносами по
  смысловым частям; не записывай запрос одной длинной строкой.
- Запросы должны быть читаемыми: явные поля вместо `SELECT *`, параметры вместо
  конкатенации.
- Все `Query`-результаты закрывай; ошибки итерации проверяй.
- Несколько изменений, которые должны пройти вместе, выполняй в одной
  транзакции. Не имитируй транзакцию последовательностью независимых вызовов.
- Не добавляй транзакцию для одной простой операции без требования атомарности.
- Конкурентные ограничения обеспечивай базой (`UNIQUE`, `CHECK`, FK) и
  корректно обрабатывай конфликт в Go.

## 10. Тесты

Тест размещай рядом с тестируемым пакетом в файле `*_test.go`.

- Чистые функции и mapping тестируй без базы и сети.
- Бизнес-правила сервиса тестируй через минимальные fake/stub-зависимости;
  тест не должен поднимать PostgreSQL, если это не проверка SQL или транзакции.
- SQL, ограничения и атомарность проверяй интеграционным тестом с отдельной
  тестовой базой через `TEST_DATABASE_URL`.
- Для endpoint-ов проверяй только транспортный mapping и доступ; полный
  бизнес-сценарий принадлежит тестам сервиса.
- Имена тестов описывают поведение: `TestCreateRejectsFinishedGame`.
- Все тесты оформляй как табличные, даже если в таблице только один кейс.
- Любая новая ветка с бизнес-правилом, SQL-ограничением или безопасностью
  должна иметь минимальный тест, который ломается при регрессии.

Команды проверки:

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

После изменения protobuf дополнительно запускай `make generate` и проверяй
сгенерированный diff.

## 11. Именование и стиль

- Имена короткие и предметные: `gameID`, `teamID`, `ctx`, `err` допустимы по
  общему Go-стилю.
- Аббревиатуры пишутся единообразно: `ID`, `URL`, `HTTP`, `JWT`, `SQL`.
- Используй префикс `I` в именах интерфейсов: `IFileStorage`, `IEmailSender`.
- Не прячь побочные эффекты в функциях с именами `Get`, `Map`, `Parse`.
- `New...` создаёт значение и возвращает ошибку только если создание реально
  может завершиться ошибкой.
- Форматируй код `gofmt`; не добавляй ручное форматирование, генераторы и
  линтеры без требования проекта.

## 12. Как выбрать место для нового кода

| Вопрос | Место |
| --- | --- |
| Как принять RPC/HTTP и вернуть protobuf? | `internal/app` |
| Какое бизнес-условие разрешает операцию? | `internal/services` |
| Как прочитать или изменить PostgreSQL? | `internal/repos` |
| Как переиспользовать S3, JWT, email или PDF? | `internal/modules` |
| Как изменить внешний контракт? | `api/`, затем генерация |
| Как изменить схему? | `migrations/` |
| Как преобразовать типы транспорта? | рядом с handler-ом или владельцем mapping |
| Как проверить поведение? | `*_test.go` рядом с владельцем поведения |

Если ответ не помещается в одну строку, сначала уточни границу ответственности,
а не создавай новый слой.