Метод (Event Handler) ProcessBillingTransaction

Домен: INVENTORY | Сервис: receipt-service | Тип: Kafka Consumer

Общее описание

Асинхронный метод-обработчик (Event Handler) ProcessBillingTransaction развернут внутри микросервиса receipt-service. Он отвечает за сохранение истории покупок и персистентное логирование структуры чеков со всем набором продуктов и ценой для каждого из них.

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

Критические задачи метода

  1. Регистрация структуры чека: Получение из топика дистрибуции полного массива распарсенных товаров с сохранением стоимости и валюты по каждой отдельной позиции.
  2. Персистентность сырых аналитических данных: Атомарная запись элементов чека в реляционную базу данных в неизменном виде (с ценами) для последующей обработки движком отчетности.

Протокол взаимодействия (Event Contract)

  • Имя метода: ProcessBillingTransaction
  • Брокер сообщений: Apache Kafka
  • Входной топик (Subscription): bpds.mdm.out.product.templated
  • Формат данных: application/json

Диаграмма последовательности (Финансовый поток чеков)

sequenceDiagram
    autonumber
    participant K as Kafka: ...product.templated
    participant Receipt as receipt-service
    participant DB as PostgreSQL (receipt_db)

    K->>Receipt: Шаг 7: Handler: ProcessBillingTransaction()
    activate Receipt
    Note over Receipt: Шаг 7.1: Извлечение массива продуктов<br/>и маппинг цен без их суммирования
    Receipt->>DB: Шаг 7.2: SQL: INSERT INTO purchase_receipts
    Receipt->>DB: SQL: INSERT INTO receipt_items (С сохранением цен)
    deactivate Receipt

Расшифровка шагов метода по канону

Шаг Действие Параметры / Запросы / DTO Ошибки (Исключения / Статусы)
7 (K -> Receipt) Сервис вычитывает событие с распознанным шаблоном продуктов из веерного топика дистрибуции. Kafka Ingress Payload:
{ "trace_id": "req-manual-text-99aa", "user_id": "usr_9876", "home_group_id": "group_abc123", "parsed_items": [{ "product_name": "Молоко Юрта", "price": 1029.0, "currency": "KZT" }] }		 Бизнес-ошибки отсутствуют
7.1 (Receipt -> Receipt) Внутренняя логика: Маппинг и валидация входящего списка позиций. Сервис просто подготавливает строки для вставки, сохраняя исходную структуру записей и цены для каждой позиции. Внутренний маппер:
ReceiptMapper.toDatabaseRows(payload.parsed_items)		 IAD-REC-422 (ошибка разбора структуры чека, пропущены или деформированы обязательные атрибуты элементов)
7.2 (Receipt -> DB) Сервис выполняет транзакционную запись заголовка чека (для связи) и всего массива продуктов с сохранением их цен построчно. SQL-запрос:
INSERT INTO purchase_receipts (trace_id, group_id, user_id) VALUES ('req-99aa', 'group_abc123', 'usr_9876') RETURNING id;
INSERT INTO receipt_items (receipt_id, name, price, currency) VALUES (1, 'Молоко Юрта', 1029.0, 'KZT');		 Бизнес-ошибки отсутствуют