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

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

Published

July 2, 2026

WarningОграничение публичной документации

В открытом доступе представлена демонстрационная версия метода. В настоящей публичной документации отображены не все шаги, технические сценарии и приватные эндпоинты для системы цифровых симуляторов бизнес-процессов.

  • Полная спецификация метода: Будет доступна только во внутреннем контуре разработки (Confluence / Swagger Enterprise).

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

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

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

  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 Шаги

Шаг Действие Параметры / Запросы / DTO Ошибки (Исключения / Статусы)
Шаг 1 (App -> Nginx) Клиент отправляет регистрационные данные и режим инициализации пространства на эндпоинт создания профиля. HTTP POST /api/v1/auth/register
Payload (UserRegisterRequestDTO):
{ "email": "user@somedomain.kz", "password": "SecretSecurePassword123", "space_creation_mode": "CREATE_NEW_OFFICE", "invite_token": null }		 DioException: send timeout
HTTP 400 Bad Request (некорректный email/короткий пароль)
HTTP 429 Too Many Requests (сработал Rate Limit)
Шаг 2 (Nginx -> Gateway) Прокси-сервер выполняет базовую маршрутизацию запроса на шлюз с добавление сквозного ID трассировки. HTTP POST /backend-api/v1/auth/register
Headers:
X-Request-ID: "req-auth-reg-001a"		 HTTP 502 Bad Gateway (контейнер backend-api недоступен)
HTTP 504 Gateway Timeout
Шаг 3 (Gateway -> Auth) API-шлюз валидирует контракт параметров и транслирует вызов в сервис авторизации. Протокол: gRPC
Метод: RegisterUser(RegisterRequest)
Параметры: email, password, space_creation_mode, invite_token		 gRPC Status: INVALID_ARGUMENT (ошибка валидации параметров)
gRPC Status: UNAVAILABLE (сервис Auth недоступен)
Шаг 4 (Auth -> DB_Auth) Сервис выполняет SQL-запрос на создание учетной записи пользователя в контуре. SQL-запрос:
INSERT INTO users (email, password_hash, space_creation_mode) VALUES ('user@somedomain.kz', 'hash_bcrypt...', 'CREATE_NEW_OFFICE') RETURNING id;		 PostgreSQL Exception: UniqueViolation (email уже зарегистрирован в системе)
PostgreSQL Exception: ConnectionPoolTimeout
Шаг 5 (DB_Auth -> Auth) База данных выполняем запись и возвращает сгенерированный UUID нового пользователя. Набор данных СУБД (RecordSet): возвращается значение id (например, usr-8822-fa41). PostgreSQL Exception: DiskFull
PostgreSQL Exception: TransactionAborted
Шаг 6 (Auth -> Auth) Сервис инициализирует пространство (home_group_id), определяет тип аккаунта и генерирует пару JWT, внедряя бизнес-контекст в Claims. Внутренний метод: GenerateTokenPair(user_id).
JWT Access Claims Payload:
{ "sub": "usr-8822-fa41", "home_group_id": "8a71d11e-9500-4b11-9a2c-d2b0d7b3dcba", "account_type": "OFFICE" }		 CryptoException: KeySigningError (ошибка доступа к приватному ключу подписи токенов)
Шаг 7 (Auth -> DB_Auth) Сервис сохраняет хэш долгоживущего Refresh-токена для управления активной сессией клиента. SQL-запрос:
INSERT INTO user_sessions (user_id, refresh_token_hash, expires_at) VALUES ('usr-8822-fa41', 'hash...', '2026-08-27');		 PostgreSQL Exception: ForeignKeyViolation (пользователь не найден)
PostgreSQL Exception: CommandTimeout
Подтверждение (DB_Auth -> Auth) База данных подтверждает успешную запись сессии. Ответ СУБД: Статус INSERT 0 1 (успешная фиксация 1 строки). PostgreSQL Exception: DatabaseIsShuttingDown
Шаг 8 (Auth -> Gateway) Сервис возвращает сформированную структуру токенов и метаданные профиля на API-шлюз. Протокол: gRPC
Ответ: RegisterResponse
Payload: access_token, refresh_token, user_id, home_group_id, account_type		 gRPC Status: INTERNAL (ошибка маршаллинга сообщения бэкенда)
Шаг 9 (Gateway -> App) Шлюз транслирует ответ через Nginx, возвращая приложению статус успешного создания сущностей и авторизационные токены. HTTP Статус: 201 Created
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", "access": "eyJhbGci...", "refresh": "def456..." } }		 DioException: receive timeout (клиент потерял соединение сотовой сети на выходе из Nginx)
Шаг 10 (App -> App) Мобильное приложение изолированно сохраняет полученные токены на аппаратном уровне устройства. Внутренний метод: SecureStorage.write(...)
Запись в iOS Keychain или Android Keystore.		 SecureStorageException (ошибка аппаратного шифрования / сбой Keychain)

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

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

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

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

  • Заголовки ответа (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"
  }
}