Microservice: Иммитация SOAP сервиса, получение данных из внешней системы

Спецификация интеграционного шлюза и структуры БД абстрактного реестра

Published

June 11, 2026

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

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

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

1 Общее назначение сервиса

Создадим микросервис для иммитации внешнего эндпоинта реализующий протокол SOAP/XML. Сервис будет иметь синхронный метод и возвращать из базы данных fake_governance_db набор персональных данных о пользователях подтверждая, либо опровергая информацию и являться неким единным источником правды (Single Source of Truth).

1.1 Основные бизнес-функции:

  1. Аутентификация запросов: Проверка входящего master_token на наличие в реестре разрешенных систем и его статус активности.
  2. Предоставление данных: Сборка и отгрузка расширенного профиля сотрудника (ФИО, ИНН, СНИЛС, Паспорт, статус ЭЦП) по его уникальному user_id.

2 Структура базы данных (Реестр СУБД)

Примечание: Таблицы не имеют жесткой связи на уровне базы данных (FOREIGN KEY), так как service_access_tokens авторизует внешнюю систему целиком (Agro_Main_Service), а не конкретного сотрудника, а digital_employees является изолированным справочником физических лиц. Кросс-валидация происходит на уровне бизнес-логики Go-сервиса.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'actorBkg': '#E3F2FD',
    'actorBorder': '#90CAF9',
    'actorTextColor': '#0D47A1',
    'rectBkg': '#FFF9C4',
    'rectBorder': '#FFF59D',
    'noteBkgColor': '#EDE7F6',
    'noteBorderColor': '#D1C4E9',
    'signalColor': '#546E7A',
    'signalLineColor': '#B0BEC5'
  }
}}%%

erDiagram
    SERVICE-ACCESS-TOKENS {
        int token_id PK
        uuid token_value UK
        varchar client_name
        boolean is_active
        timestamp created_at
    }

    DIGITAL-EMPLOYEES {
        int user_id PK
        varchar inn UK
        varchar passport_number
        varchar first_name
        varchar last_name
        varchar digital_signature_status
        varchar insurance_number
    }

2.1 Таблица service_access_tokens

Хранит мастер-токены внешних систем (потребителей данных), которым разрешен доступ к шлюзу.

  • token_id (SERIAL, PRIMARY KEY) — Внутренний суррогатный ключ.
  • token_value (UUID, UNIQUE, NOT NULL) — Секретный токен авторизации (По умолчанию: gen_random_uuid()).
  • client_name (VARCHAR(100), NOT NULL) — Наименование системы-клиента (например, ‘Agro_Main_Service’).
  • is_active (BOOLEAN, По умолчанию: TRUE) — Флаг активности токена (позволяет отозвать доступ).
  • created_at (TIMESTAMP, По умолчанию: CURRENT_TIMESTAMP) — Дата и время регистрации токена.

2.2 Таблица digital_employees

Основной реестр цифровых профилей государственных сотрудников.

  • user_id (INT, PRIMARY KEY) — Уникальный идентификатор сотрудника.
  • inn (VARCHAR(12), UNIQUE, NOT NULL) — ИНН (12 символов).
  • passport_number (VARCHAR(20), NOT NULL) — Серия и номер паспорта.
  • first_name (VARCHAR(100), NOT NULL) — Имя сотрудника.
  • last_name (VARCHAR(100), NOT NULL) — Фамилия сотрудника.
  • digital_signature_status (VARCHAR(50), По умолчанию: ‘ACTIVE’) — Статус проверки или работы ЭЦП.
  • insurance_number (VARCHAR(20), NULL) — СНИЛС сотрудника (опциональное поле).

3 Спецификация SOAP-интерфейса (Контракт)

  • Протокол: HTTP 1.1 / SOAP 1.1
  • Метод: POST
  • Эндпоинт: /
  • Content-Type: text/xml; charset=utf-8

3.1 Входящий запрос (Request)

Метод: fetch_secure_employee_data
Namespace: http://xmlsoap.org Envelope

<Envelope xmlns="http://xmlsoap.org">
    <Body>
        <fetch_secure_employee_data>
            <user_id>4512</user_id>
            <master_token>deadbeef-1111-2222-3333-444455556666</master_token>
        </fetch_secure_employee_data>
    </Body>
</Envelope>

3.2 Исходящий ответ (Response)

Корневой элемент: soapenv:Envelope
Пространства имен: xmlns:soapenv=“http://xmlsoap.org”, xmlns:gov=“gov.service.m4”

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://xmlsoap.org" xmlns:gov="gov.service.m4">
  <soapenv:Body>
    <soapenv:fetch_secure_employee_dataResponse>
      <gov:fetch_secure_employee_dataResult>
        <gov:user_id>4512</gov:user_id>
        <gov:inn>771234567890</gov:inn>
        <gov:full_name>Иванов Иван</gov:full_name>
        <gov:passport>4508123456</gov:passport>
        <gov:snils>123-456-789 01</gov:snils>
        <gov:signature_status>ACTIVE</gov:signature_status>
        <gov:authorized>true</gov:authorized>
        <gov:error_message>SUCCESS</gov:error_message>
      </gov:fetch_secure_employee_dataResult>
    </soapenv:fetch_secure_employee_dataResponse>
  </soapenv:Body>
</soapenv:Envelope>

4 Диаграмма последовательности (Sequence Diagram)

Обработка входящего SOAP-запроса, валидации мастер-токена и извлечения персональных данных пользователя.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'actorBkg': '#E3F2FD',
    'actorBorder': '#546E7A',
    'actorTextColor': '#0D47A1',
    'rectBkg': '#FFF9C4',
    'rectBorder': '#FBC02D',
    'noteBkgColor': '#F3E5F5',
    'noteBorderColor': '#7E57C2',
    'noteTextColor': '#311B92',
    'signalColor': '#2C3E50',
    'signalLineColor': '#2C3E50'
  }
}}%%

sequenceDiagram
    autonumber
    actor Client as Внешняя система (Agro_Main_Service)
    participant Go as Gov Registry Gateway
    participant DB as База Данных (PostgreSQL)

    Client->>Go: HTTP POST / (SOAP XML-запрос fetch_secure_employee_data)
    activate Go
    
    note over Go: Шаг 2: Валидация HTTP-метода POST и структуры входящего XML
    note over Go: Шаг 3: Очистка токена (Удаление пробелов и перевод в нижний регистр)
    
    Go->>DB: Запрос на проверку активности мастер-токена в service_access_tokens
    activate DB
    DB-->>Go: Возвращает статус активности токена (is_active)
    deactivate DB

    note over Go: Шаг 6: Если токен валиден, запрашиваем данные сотрудника по user_id
    
    Go->>DB: SELECT из таблицы digital_employees по идентификатору user_id
    activate DB
    DB-->>Go: Возвращает персональные данные (ФИО, ИНН, Паспорт, СНИЛС)
    deactivate DB
    
    note over Go: Шаг 9: Сборка full_name (last_name + first_name) и проверка на ошибки
    
    Go-->>Client: HTTP 200 OK (SOAP-конверт с флагом authorized и данными сотрудника)
    deactivate Go

4.1 Таблица расшифровки шагов сценария

Шаг Действие Параметры / Запросы / DTO Код ошибки (canonical_code) HTTP статус
1 (Client -> Go) Внешняя система Agro_Main_Service отправляет синхронный HTTP POST запрос для получения защищенных персональных данных сотрудника по его идентификатору. SOAP Request Envelope:
{ "user_id": 4512, "master_token": "deadbeef-1111-2222-3333-444455556666" }		 SOAP_XML_BAD_REQUEST 400 / 405
2 (Go -> Go) Внутренняя логика: Шлюз производит очистку и нормализацию входящего секретного токена для предотвращения сбоев поиска из-за регистра букв или лишних отступов. Внутренний метод Go:
strings.ToLower(strings.TrimSpace(reqData.MasterToken))		 Нет 200
3 (Go -> DB) Сервис выполняет SQL-запрос кросс-валидации к таблице авторизации внешних клиентов для проверки существования и активности предоставленного ключа доступа. SQL-запрос:
SELECT is_active FROM service_access_tokens WHERE token_value::text = $1;		 DB_GOV_POSTGRES_DOWN 500
4 (DB -> Go) База данных возвращает флаг состояния токена или выбрасывает исключение отсутствия записи, если UUID не зарегистрирован в системе. SQL Response:
Булевое значение is_active (true / false) или исключение драйвера sql.ErrNoRows.		 GOV_AUTH_DENIED 200
5 (Go -> DB) Условие: Токен успешно прошел проверку активности. Сервис инициирует SELECT-запрос в основную таблицу госреестра для извлечения персональных данных. SQL-запрос:
SELECT inn, passport_number, first_name, last_name, digital_signature_status, insurance_number FROM digital_employees WHERE user_id = $1;		 DB_GOV_POSTGRES_DOWN 500
6 (DB -> Go) База данных возвращает сырые строки персональных данных сотрудника госреестра либо пустой результат поиска. SQL Response:
Кортеж полей (inn, passport_number, first_name, last_name, digital_signature_status, insurance_number).		 DB_EMPLOYEE_NOT_FOUND 200
7 (Go -> Go) Внутренняя логика: Шлюз склеивает составные части имени сотрудника в единую строку full_name и формирует успешный статус выполнения операции. Внутренний метод Go:
fmt.Sprintf("%s %s", lastName, firstName)		 Нет 200
8 (Go -> Client) Сервис упаковывает извлеченные персональные данные в финальный SOAP-конверт, проставляет флаг успешной проверки и отгружает HTTP-ответ клиенту. SOAP Response Envelope:
{ "user_id": 4512, "full_name": "Иванов Иван", "inn": "771234567890", "authorized": true, "error_message": "SUCCESS" }		 Нет 200

5 Справочник ошибок

Для обеспечения сквозного мониторинга (Observability) работы сервиса, анализа качества интеграции и сбора метрик, каждая нештатная ситуация классифицируется по внутреннему коду.

При возникновении ошибки сервис формирует структурированный лог, содержащий контекст для внешних систем и метрики для аналитической СУБД.

1. Код (canonical_code) 2. Уровень (log_level) 3. Статусы (transport_statuses) 4. Получатель (error_target) 5. JSON для Фронтенда (ui_payload) 6. Метрики для ClickHouse (observability_json)
GOV_AUTH_DENIED WARN {“grpc”: 16, “http”: 401} EXTERNAL_SYSTEM null {“metric”: “auth_fail”, “labels”: {“service”: “gov_gateway”, “reason”: “token_invalid_or_revoked”}}
DB_GOV_POSTGRES_DOWN FATAL {“grpc”: 14, “http”: 500} INTERNAL_SYSTEM null {“code”: “DB_GOV_POSTGRES_DOWN”, “metric”: “db_conn_lost”, “labels”: {“db”: “gov_registry_db”}}
DB_EMPLOYEE_NOT_FOUND INFO {“grpc”: 5, “http”: 200} EXTERNAL_SYSTEM null {“metric”: “registry_miss”, “labels”: {“service”: “gov_gateway”, “reason”: “user_id_absent”}}
SOAP_XML_BAD_REQUEST WARN {“grpc”: 3, “http”: 400} EXTERNAL_SYSTEM null {“metric”: “contract_fail”, “labels”: {“validator”: “go_xml_unmarshal”}}