API Events

Bề mặt async duy nhất là một CDC consumer. Không có Kafka producer, BullMQ queue hay WebSocket emission.

1. Inbound - Kafka

Topic	Producer	Handler	Idempotency Key	Failure Mode
public.Product (CDCKafkaTopics.PRODUCT)	Debezium (commerce)	TaxationWorkerService.handleProductCDC	(productId, taxGroupId, op) - provision idempotent	log + bỏ qua (autocommit; không DLQ)

Cấu hình consumer (ApplicationKafkaComponent):

Setting	Giá trị
Client ID	APP_ENV_KAFKA_CLIENT_ID (mặc định SVC-00130-TAXATION_CONSUMER)
Group ID	APP_ENV_KAFKA_GROUP_ID (mặc định SVC-00130-TAXATION_CONSUMER_GROUP)
Key deserializer	stringDeserializer
Value deserializer	jsonDeserializer
fallbackMode	latest (không nạp bù lịch sử)
autocommit	true
requestTimeout / connectTimeout / maxWaitTime	60000 / 30000 / 5000 ms

Định tuyến theo op:

Debezium op	Hành động
c, u, r	_reconcileTaxProvisions(after)
d	deprovisionForProduct(before.id ?? after.id)
khác	bỏ qua

Nhánh reconcile (c/u/r):

Trạng thái sản phẩm	Hành động
có deletedAt	deprovision
không có taxGroupId	deprovision
có taxGroupId	provision (idempotent)

2. Outbound - Kafka

Không có. Taxation không tạo event. Các dòng TaxSet/Tax đã provision được pricing đọc trực tiếp từ shared DB.

3. Inbound - BullMQ

Không có.

4. Outbound - BullMQ

Không có.

5. WebSocket Emissions

Không có.

6. Payload Schemas

Payload inbound là một Debezium envelope bọc quanh một dòng Product. Kiểu lấy từ @nx/core (TDebeziumMessage, TDebeziumPayload, TProductPgRow). Các key snake_case của dòng được chuyển qua toCamelCaseKeys trước khi dùng.

// CDCKafkaTopics.PRODUCT - message.value
interface TDebeziumMessage<TProductPgRow> {
  payload: TDebeziumPayload<TProductPgRow>;
}

interface TDebeziumPayload<T> {
  op: 'c' | 'u' | 'r' | 'd';
  before: T | null; // snake_case
  after: T | null;  // snake_case
}

// Các trường mà worker đọc (sau toCamelCaseKeys):
//   id: string
//   taxGroupId: string | null
//   deletedAt: string | null

7. Idempotency & Ordering

Topic	Delivery	Ordering	Recovery
public.Product	at-least-once (autocommit)	per-partition (theo từng product key)	gửi lại sẽ chạy lại reconcile; provision bỏ qua khi đã provision với cùng TaxGroup

Không có DLQ: onMessageError chỉ ghi log. fallbackMode: latest nghĩa là các dòng thay đổi khi consumer down, trước cửa sổ offset, sẽ không được xử lý lại - không có backfill job (ADR-0001).

8. Trang liên quan

• Integration
• Architecture - Kịch bản Runtime