Consumer:

Назначение

Consumer <ConsumerName> слушает событие <event.name> и обновляет <витрину / проекцию / кэш / поисковый индекс / факт>. 2–4 предложения простым языком: зачем этот consumer существует, какое бизнес-событие он обрабатывает и что в итоге меняется в owned-состоянии сервиса. Без ссылок на правила авторинга и деталей реализации.

Owning-сервис и триггер

Поле	Значение
Сервис/контекст	<context>
Consumer	<ConsumerName>
Обрабатываемое событие	<event.name>
Topic	<topic> (напр. pin.<context>.<event>.v1)
ContractVersion	<N>; при несовпадении версии — warn-and-proceed
Consumer group	<application>-<group>
Producer	<context/service>
Эффект (событие → что меняется)	<владелец состояния / проекция / факт, которые обновляет consumer>

Контекст события

• Из метаданных события доступны: TenantId, идентификатор и тип агрегата-источника (AggregateId/AggregateType), время события (CreatedAt/OccurredAt), идентификатор сообщения для дедупликации.
• Корреляция сквозного трейса восстанавливается из метаданных события.
• Ключ бизнес-идемпотентности: <eventType>:<AggregateId / бизнес-ключ> (подробнее — раздел «Идемпотентность и replay»).

Входные данные / payload события

Контракт входного события: <event.name>. Ниже — поля payload, которые consumer реально читает, и как маппит их в проекцию.

Поле payload	Тип	Обязательность	Как используется (маппинг)
<FieldName>	<Type>	Да/Нет	<в какое поле проекции / условие>

Алгоритм

Нумерованные бизнес-шаги — happy path и ветки отказа. Уровень изложения — по Правилам Документирования Алгоритма; consumer-специфика — в шагах приёма события и фиксации результата. Неприменимый шаг опускается целиком.

1. Контекст события. Восстановить метаданные события (идентификатор сообщения, агрегат-источник, время, tenant); сверить ContractVersion — при несовпадении warn-and-proceed. Проверить бизнес-идемпотентность по ключу: если событие уже обработано → пропустить как дубль (ack, no-op).
2. Проверка входа и предусловий. Формат/диапазоны/enum полей payload; неизвестное значение enum → <код ошибки> (обычно non-retriable → DLQ). Существование связанных сущностей (или допустимость их отсутствия — для upsert-проекции); допустимость состояния.
3. Что читаем. Какие сущности/проекцию загружаем, по каким условиям и зачем (проверка инварианта до записи, резолв целевой записи проекции).
4. Бизнес-правила и маппинг. Применить transform и бизнес-правила; переходы статусов From → To с условием; маппинг поле-в-поле: для каждого обновляемого поля проекции — источник (payload / загруженная сущность / вычисление).
5. Что меняется. Какие записи проекции/факта создаются/обновляются/удаляются; конкурентный доступ — как бизнес-условие («обновление не должно затирать более свежее состояние»).
6. Какие факты/события фиксируются (только если consumer порождает новые интеграционные события): имя события, топик, из каких полей собирается снапшот, кто потребители.
7. Согласованность. Обновление проекции, отметка идемпотентности и (если есть) исходящие события фиксируются в одном согласованном изменении; offset подтверждается только после успешной фиксации.
8. Результат. Успех → ack; контролируемая ошибка → retry/DLQ по политике из раздела «Retry и DLQ».

Диаграмма

Опциональна; для тривиального обновления проекции — не рисуется. Участники — бизнес/доменные роли (Kafka-топик, consumer контекста, витрина/хранилище проекции).

Идемпотентность и replay

• Business key: <tenantId:eventType:businessReference>; поведение дубля: <пропустить / обновить проекцию>.
• Version-guard: при несовпадении ContractVersion события — <warn-and-proceed / пропуск>; неизвестные additive-поля игнорируются.
• Replay: <да/нет> + runbook <link>.

Retry и DLQ

Сбой	Retry	DLQ	Ручное действие
<failure>	<policy>	Да/Нет	<action>

Наблюдаемость и безопасность

• Logs: consumed / skipped-duplicate / transformed / failed. Metrics: длительность обработки, retries, DLQ, дубликаты, lag (now − время события).
• Traces: span приёма события → span обработки → spans обращений к хранилищу/поиску; correlation из метаданных события.
• PII/masking: <нет/список>; несоответствие tenant → fail closed.

Обратные ссылки

Автоссылки: где используется этот документ.

• Консюмеры (17): Consumer: Agent Performance Projection, Consumer: Calendar CRM Booking Sync (calendar-crm-booking-events), Consumer: Calendar Identity User Sync (calendar-identity-users), Consumer: Chessboard Dimensions Sync (pin-rewards-chessboard-dimensions), Consumer: CRM Agent Offboarding (CrmAgentOffboardingConsumer), Consumer: CRM Calendar Appointments Sync (crm-calendar-appointments), Consumer: CRM Deal Cancelled, Consumer: CRM Deal Completed, Consumer: CRM Fixation Approved, Consumer: CRM Identity User Sync (CrmUserUpsertedConsumer), Consumer: Deal Chat Status (pin-crm-deal-chat-status), Consumer: Identity Agent Membership Changed (+5)
• algorithm-documentation-rules.md (1): Правила Документирования Алгоритма
• documentation-file-templates.md (1): Индекс Шаблонов Документации
• index.md (1): Шаблоны Документации
• command-query-template.md (1): Внутренняя операция: <НазваниеОперации>
• event-contract-template.md (1): Event Contract: <event.name> ()

Связанные документы

• Уровень изложения: spec-authoring-altitude-rules.md; структура алгоритма: algorithm-documentation-rules.md.
• Контракт входного события: <ссылка на events/<event>.md producer-сервиса>; целевые сущности/проекция: <entity links>.