Метод POST /api/v1/auth/register

Документация API: Регистрация пользователей с инициализацией Multi-Tenancy контуров HOME и OFFICE

Published

July 2, 2026

1 Функциональное назначение

Метод предназначен для первичной регистрации пользователя в экосистеме.

Помимо стандартного создания учетной записи (хэширования паролей), данный метод решает фундаментальную задачу инициализации инфраструктуры хранения ресурсов:

  1. Динамическое ветвление пространств: На основе параметра space_creation_mode метод либо генерирует абсолютно новый изолированный холодильник со своим уникальным home_group_id (для семьи или офиса), либо привязывает нового пользователя к уже существующей группе на основе переданного инвайт-кода (invite_token).
  2. Первичная разметка бизнес-логики: Фиксирует для создаваемой группы флаг account_type (HOME или OFFICE), который в дальнейшем определяет, разрешены ли скрытые виртуальные минусы при готовке и утилизации, или система должна работать в режиме строгого складского контроля.

2 Протокол взаимодействия (HTTP Контракт)

  • Метод: POST
  • Маршрут: /api/v1/auth/register
  • Формат данных: application/json

2.1 Спецификация заголовков (HTTP Headers)

Заголовок Обязательный Описание Пример значения
Content-Type Да Указывает на передачу строго типизированного JSON-пакета application/json
X-Request-ID Да Сквозной ID запроса для трассировки создания новой учетной записи req-auth-reg-001a

2.2 Спецификация тела запроса (Request Body)

Поле Тип Обязательный Описание Пример значения
email String Да Уникальный адрес электронной почты (валидируется регулярным выражением) user@somedomain.kz
password String Да Пароль пользователя (строго не менее 8 символов) SecretSecurePassword123
space_creation_mode String (Enum) Да Режим инициализации складского пространства "CREATE_NEW_OFFICE"
invite_token String Нет UUID инвайт-кода для вступления в уже созданную семью/офис null (или UUID)

2.2.1 Допустимые константы space_creation_mode (Enum):

  • CREATE_NEW_HOME — создать новую семью (разрешены виртуальные минусы).
  • CREATE_NEW_OFFICE — создать новый офис (строгий контроль остатков, блокировка дефицита).
  • JOIN_EXISTING — вступить в готовую группу по инвайт-коду из поля invite_token.

2.2.2 Пример сырого JSON-запроса (Payload — Сценарий: регистрация компании с созданием нового офисного пространства):

{
  "email": "user@somedomain.kz",
  "password": "SecretSecurePassword123",
  "space_creation_mode": "CREATE_NEW_OFFICE",
  "invite_token": null
}

3 Схема обработки запроса пользователя (Mermaid)

На диаграмме представлена логика регистрации. Сервис Auth открывает атомарную транзакцию, создаёт запись в таблице пользователей, генерирует уникальный home_group_id для нового пространства (или связывает пользователя с существующим по инвайт-коду) и надёжно хэширует пароль.

sequenceDiagram
    autonumber
    
    actor App as APP (Мобильное приложение)
    participant Nginx as Nginx Proxy
    participant GW as GATEWAY (backend-api)
    participant Auth as AUTH (auth-service)
    participant DB as DB_AUTH (PostgreSQL)

    App->>Nginx: Шаг 1: POST /api/v1/auth/register (email, password)
    activate Nginx
    Nginx->>GW: Шаг 2: POST /backend-api/v1/auth/register
    activate GW
    GW->>Auth: Шаг 3: gRPC: RegisterUser(RegisterRequest)
    activate Auth
    
    Auth->>DB: Шаг 4: SQL INSERT INTO users...
    activate DB
    DB-->>Auth: Шаг 5: Result: user_id
    deactivate DB
    
    note over Auth: Шаг 6: Внутренний метод<br/>GenerateTokenPair(user_id)
    
    Auth->>DB: Шаг 7: SQL INSERT INTO user_sessions...
    activate DB
    DB-->>Auth: Подтверждение записи сессии
    deactivate DB
    
    Auth-->>GW: Шаг 8: gRPC: RegisterResponse
    deactivate Auth
    GW-->>App: Шаг 9: HTTP 201 Created (access, refresh)
    deactivate GW
    deactivate Nginx
    
    note over App: Шаг 10: Внутренний метод<br/>SecureStorage.write(...)

Процесс регистрации нового аккаунта (Register)

4 Расшифровка шагов

Шаг Действие Параметры Ошибки (Исключения / Статусы)
Шаг 1 (APP -> NGINX) Сетевой слой мобильного приложения отправляет запрос на создание учетной записи. HTTP POST /api/v1/auth/register
Body: {"email": "...", "password": "..."}		 DioException: connection timeout
HTTP 502 Bad Gateway
Шаг 2 (NGINX -> GATEWAY) Шлюз Nginx Proxy маршрутизирует запрос во внутренний периметр. HTTP POST /backend-api/v1/auth/register HTTP 413 Payload Too Large
Шаг 3 (GATEWAY -> AUTH) backend-api (Gateway) валидирует Pydantic-контракт и инициирует внутренний gRPC-метод создания пользователя. gRPC: RegisterUser(RegisterRequest) HTTP 422 Unprocessable Entity
gRPC: INVALID_ARGUMENT
Шаг 4 (AUTH -> DB_AUTH) Микросервис auth-service выполняет атомарную попытку записи нового пользователя в базу данных. SQL INSERT INTO users (email, password_hash) VALUES ($1, $2) PostgreSQL: users_email_key violation
gRPC: ALREADY_EXISTS \(\rightarrow\) HTTP 409 Conflict
Шаг 5 (DB_AUTH -> AUTH) СУБД подтверждает успешное создание записи и возвращает сгенерированный системный ID пользователя. Result: user_id PostgreSQL: connection pool timeout
Шаг 6 (AUTH -> AUTH) Внутреннее действие: Сервис запускает метод генерации токенов для автоматического входа после регистрации. Вызов: GenerateTokenPair(user_id) JWT: SignatureGenerationError
Шаг 7 (AUTH -> DB_AUTH) Сервис регистрирует стартовую долгоживущую сессию в базе данных. SQL INSERT INTO user_sessions ... PostgreSQL: unique_violation
Шаг 8 (AUTH -> GATEWAY) auth-service возвращает сформированный gRPC-ответ с парой токенов на шлюз. gRPC: RegisterResponse gRPC: INTERNAL
Шаг 9 (GATEWAY -> APP) API Gateway оборачивает данные в REST-контракт и отдает их клиенту через Nginx. HTTP 201 Created
Body: {"access_token": "...", "refresh_token": "..."}		 HTTP 500 Internal Server Error
Шаг 10 (APP -> APP) Сетевой перехватчик приложения изолированно записывает полученные ключи в secure storage. Вызов: SecureStorage.write(...) SecureStorageException

5 Спецификация ответов сервера (Response Body) и ошибок

5.1 Успешный ответ (Success Response)

5.1.1 HTTP 201 Created (Ответ на Шаге 12)

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

  • Заголовки ответа (Response Headers):
    • Content-Type: application/json
  • Тело ответа (Response Body):
{
  "status": "success",
  "data": {
    "user_id": "usr-8822-fa41",
    "home_group_id": "8a71d11e-9500-4b11-9a2c-d2b0d7b3dcba",
    "account_type": "OFFICE",
    "timestamp": "2026-07-02T02:15:00Z"
  }
}

5.2 Вилки исключений и обработка ошибок

5.2.1 Ошибка коллизии: Email уже зарегистрирован (HTTP 409 Conflict — Шаг 5)

Выбрасывается на Шаге 5, если проверка в базе данных выявила, что указанный адрес электронной почты уже занят другой учетной записью. Это предотвращает дублирование профилей в СУБД.

  • Заголовки ответа (Response Headers):
    • Content-Type: application/json
  • Тело ответа (Response Body):
{
  "error_code": "ERR-EMAIL-ALREADY-EXISTS",
  "message": "Пользователь с таким email-адресом уже зарегистрирован в системе.",
  "details": {
    "rejected_email": "manager@bupar-office.kz",
    "action": "Redirect user to login screen or trigger password recovery flow."
  }
}

5.2.2 Ошибка: Невалидный или просроченный инвайт-код (HTTP 410 Gone / 404 Not Found — Шаг 6)

Выбрасывается на Шаге 6 в режиме JOIN_EXISTING, если переданный invite_token отсутствует в таблице инвайтов, аннулирован создателем пространства или истек по времени жизни.

{
  "error_code": "ERR-INVITE-TOKEN-INVALID",
  "message": "Указанный пригласительный код недействителен, просрочен или аннулирован.",
  "details": {
    "provided_token": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "action": "Prompt user to request a fresh invite token from the space administrator."
  }
}