Метод GET /api/v1/auth/error-directory

Документация API: Аутентификация пользователя (Login) с генерацией JWT, содержащего Multi-Tenancy клеймы

Published

July 2, 2026

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

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

В рамках новой архитектуры этот метод выполняет роль поставщика локализации и каноничных кодов (Error Context Provider):

  1. Извлечение реестра исключений: Вычитывает из СУБД активные связки низкоуровневых ошибок (СУБД, gRPC), каноничных кодов симулятора и их локализованных описаний.
  2. Обеспечение независимости интерфейса (Zero-Update Client): Позволяет мобильному приложению мгновенно узнавать о новых типах ошибок ИИ-модулей и бизнес-правил бэкенда без необходимости повторной публикации сборки в App Store или Google Play. Локальный стейт-менеджер налету подменяет системные алерты на основе актуального JSON-реестра.

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

  • Метод: GET
  • Маршрут: /api/v1/auth/error-directory
  • Формат данных: application/json

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

Заголовок Обязательный Описание Пример значения
X-App-Version Да Текущая версия сборки мобильного приложения для фильтрации совместимых кодов 1.4.2
X-Request-ID Да Сквозной ID запроса для трассировки сессии синхронизации справочника req-err-dir-99aa

2.2 Спецификация параметров запроса (Query Parameters)

Параметр Тип Обязательный Описание Пример значения
app_lang String Да Целевой язык локализации возвращаемых сообщений об ошибках ru

2.2.1 Пример сырого HTTP-запроса (URL):

GET /api/v1/auth/error-directory?app_lang=ru HTTP/1.1
Host: foodlifecycle.com
X-App-Version: 1.4.2
X-Request-ID: req-err-dir-99aa

2.3 Спецификация успешного ответа (Response Body)

2.3.1 HTTP 200 OK

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

{
  "status": "success",
  "error_directory": [
    {
      "system_trigger": "PostgreSQL: users_email_key violation",
      "grpc_status": "ALREADY_EXISTS (6)",
      "http_status": "409 Conflict",
      "canonical_code": "IAD_AUTH_EMAIL_DUPLICATE",
      "localized_text": "Данный Email уже зарегистрирован.",
      "ui_reaction": "Подсветить поле ввода Email красным цветом."
    },
    {
      "system_trigger": "Redis: refresh_token blacklist match",
      "grpc_status": "UNAUTHENTICATED (16)",
      "http_status": "401 Unauthorized",
      "canonical_code": "IAD_JWT_REFRESH_STOLEN",
      "localized_text": "Сессия скомпрометирована. Войдите заново.",
      "ui_reaction": "Очистить secure storage, принудительный вылет на экран Login."
    }
  ],
  "synced_at": 1783309600
}

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

На диаграмме представлена логика аутентификации. Сервис Authorization сверяет хэш пароля в PostgreSQL, извлекает параметры привязки к пространству и генерирует JWT-токен, содержащий зашитые JWT Claims.

3.1 Диаграмма последовательности: GetErrorDirectory

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: GET /api/v1/auth/error-directory (Headers: X-App-Version, app_lang)
    activate Nginx
    Nginx->>GW: Шаг 2: GET /backend-api/v1/auth/error-directory
    activate GW
    GW->>Auth: Шаг 3: gRPC: GetErrorDirectory(DirectoryRequest)
    activate Auth
    
    Auth->>DB: Шаг 4: SQL SELECT * FROM error_directory WHERE is_active = true
    activate DB
    DB-->>Auth: Шаг 5: Возврат реестра кодов и локализованных текстов
    deactivate DB
    
    Auth-->>GW: Шаг 6: gRPC: DirectoryResponse (Полный реестр)
    deactivate Auth
    GW-->>Nginx: Шаг 7: HTTP 200 OK (Трансляция справочника в JSON)
    deactivate GW
    Nginx-->>App: Шаг 8: Доставка JSON-реестра в приложение
    deactivate Nginx
    
    note over App: Шаг 9: Внутренний метод<br/>Парсинг и динамический маппинг токенов ошибок<br/>в локальный стейт-менеджер (без апдейта из App Store)

Процесс динамической синхронизации системного справочника ошибок (GetErrorDirectory)

4 Расшифровка шагов и Анатомия JWT Payload

Шаг Действие Параметры Ошибки (Исключения / Статусы)
Шаг 1 (APP -> NGINX) Мобильное приложение при холодном старте или обновлении сессии отправляет запрос на получение актуального реестра ошибок. HTTP GET /api/v1/auth/error-directory
Headers: X-App-Version, app_lang		 DioException: no internet connection
HTTP 502 Bad Gateway
Шаг 2 (NGINX -> GATEWAY) Nginx Proxy выполняет базовую маршрутизацию и пробрасывает системный запрос на API Gateway. HTTP GET /backend-api/v1/auth/error-directory HTTP 403 Forbidden (если заблокирован IP-диапазон)
Шаг 3 (GATEWAY -> AUTH) API Gateway (backend-api) направляет вызов в мастер-сервис через внутренний gRPC-интерфейс. gRPC Метод: GetErrorDirectory(DirectoryRequest)
Args: app_version, language		 gRPC: INVALID_ARGUMENT
HTTP 400 Bad Request (передан неподдерживаемый app_lang)
Шаг 4 (AUTH -> DB_AUTH) Микросервис auth-service обращается к СУБД для извлечения активных кодов ошибок и соответствующих локализованных текстов. SQL SELECT * FROM error_directory WHERE is_active = true PostgreSQL: table "error_directory" does not exist
gRPC: INTERNAL (13)
Шаг 5 (DB_AUTH -> AUTH) База данных возвращает полный реестр кодов, канонических имен и локализованных сообщений. Result: Набор строк (error_code, canonical_code, ru_text, ...) PostgreSQL: connection pool timeout
Шаг 6 (AUTH -> GATEWAY) Сервис формирует структуру данных справочника и возвращает gRPC-ответ на API Gateway. gRPC Response: DirectoryResponse
Fields: repeated ErrorItem errors		 gRPC: DEADLINE_EXCEEDED (4) (база отвечала слишком долго)
Шаг 7 (GATEWAY -> NGINX) API Gateway сериализует полученные данные в валидный JSON-контракт и транслирует его через Nginx. HTTP 200 OK
Body: [{"code": "IAD_AUTH_EMAIL_DUPLICATE", "text": "..."}, ...]		 HTTP 500 Internal Server Error (ошибка маппинга JSON структуры)
Шаг 8 (NGINX -> APP) Инфраструктурный шлюз доставляет JSON-реестр кодов ошибок симулятора обратно в мобильный клиент. Доставка сетевого пакета данных DioException: receive timeout
Шаг 9 (APP -> APP) Внутреннее действие: Сетевой слой передает JSON в локальный стейт-менеджер. Приложение парсит реестр и динамически обновляет карту соответствий. Вызов: StateManager.updateErrorDirectory(json) JsonUnsupportedObjectError (ошибка парсинга из-за поврежденной структуры JSON)

4.1 Анатомическая структура элемента реестра ошибок (Error Item Claims):

Когда мобильный клиент или внутренний шлюз парсят элемент массива error_directory, они без хардкода в коде приложения видят следующий стандартизированный JSON-датасет:

{
  "system_trigger": "PostgreSQL: users_email_key violation",
  "grpc_status": "ALREADY_EXISTS (6)",
  "http_status": "409 Conflict",
  "canonical_code": "IAD_AUTH_EMAIL_DUPLICATE",
  "localized_text": "Данный Email уже зарегистрирован.",
  "ui_reaction": "Подсветить поле ввода Email красным цветом."
}
  • system_trigger — исходное системное или платформенное исключение (низкоуровневый лог СУБД или gRPC).
  • grpc_status — стандартизированный gRPC статус-код внутренней межсервисной ошибки для трассировки.
  • http_status — HTTP REST статус, возвращаемый API шлюзом на мобильный клиент.
  • canonical_code — уникальный строковый токен ошибки симулятора, служащий ключом для стейт-менеджера.
  • localized_text — готовая для вывода на экран пользователя фраза на целевом языке (app_lang).
  • ui_reaction — инструкция-подсказка для фронтенд-команды, определяющая логику поведения интерфейса (алерт, подсветка поля, вылет).

5 Спецификация вилок исключений и обработки ошибок

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

5.1 1. Ошибка: Отказ подсистемы хранения токенов/кэша (HTTP 503 Service Unavailable)

Вызывается на Шаге 4, если API Gateway или мастер-сервис не могут проверить состояние периметра безопасности из-за недоступности кэш-инфраструктуры СУБД/Redis. Применяется жесткая стратегия Fail-Close.

  • Заголовки ответа (Response Headers):
    • Content-Type: application/json
  • Тело ответа (Response Body):
{
  "error_code": "ERR-SECURITY-PERIMETER-BROKEN",
  "message": "Критический сбой подсистемы безопасности. Доступ к справочникам заблокирован.",
  "details": {
    "action": "Hard block UI. Display full-screen technical maintenance error overlay."
  }
}

5.2 2. Ошибка валидации параметров запроса языка (HTTP 422 Unprocessable Entity)

Возвращается на Шаге 3 бэкенд-шлюзом, если переданная строка локализации в Query-параметре app_lang отсутствует в реестре поддерживаемых языков системы FoodLifeCycle.

{
  "error_code": "ERR-VALIDATION-FAILED",
  "message": "Передан некорректный или неподдерживаемый код локализации приложения.",
  "details": [
    {
      "loc": ["query", "app_lang"],
      "msg": "value is not a valid supported language code (ru, kz)",
      "type": "value_error.language"
    }
  ]
}