Kiến trúc Sự kiện
Các dịch vụ BANA giao tiếp bất đồng bộ thông qua ba cơ chế: Kafka (event streaming + CDC), Redis pub/sub (event bus nhẹ), và WebSocket (thông báo realtime cho client). Trang này liệt kê đầy đủ mọi topic, channel và loại event.
Kafka Topic
Định nghĩa trong packages/core/src/queues/kafka/topics.ts.
Sự kiện Ứng dụng
| Topic | Producer | Consumer | Mục đích |
|---|---|---|---|
payment.success | sale | finance, inventory | Thanh toán cho đơn hàng đã hoàn tất |
purchase-order.received | inventory | finance | Đơn mua đã được nhận và xác nhận |
commerce.initialized | commerce | finance, inventory | Onboarding merchant mới hoàn tất |
merchant.created | commerce | inventory | Merchant mới được tạo (cài đặt inventory) |
product.created | commerce | taxation | Sản phẩm mới được tạo |
product.updated | commerce | taxation | Sản phẩm được cập nhật |
product-variant.created | commerce | pricing | Biến thể sản phẩm mới được tạo |
product-variant.updated | commerce | pricing | Biến thể sản phẩm được cập nhật |
ledger.generate | ledger (producer) | ledger (consumer) | Tác vụ tạo PDF/XLSX ledger |
Topic CDC (Debezium)
Định nghĩa trong packages/search/src/common/kafka-topics.ts. Debezium nắm bắt các thay đổi WAL của PostgreSQL và publish chúng lên Kafka, dịch vụ search consume các thay đổi này để đồng bộ Typesense.
| Topic CDC | Bảng nguồn | Collection Typesense |
|---|---|---|
nx.seller.public.Organizer | public.Organizer | organizers |
nx.seller.public.Merchant | public.Merchant | merchants |
nx.seller.public.Category | public.Category | categories |
nx.seller.public.Device | public.Device | devices |
nx.seller.public.SaleChannel | public.SaleChannel | sale-channels |
nx.seller.public.Product | public.Product | products |
nx.seller.public.ProductInfo | public.ProductInfo | (làm giàu products) |
Dead letter queue: nx.seller.cdc.dlq
Consumer Group Kafka
| Dịch vụ | Client ID | Group ID | Topic |
|---|---|---|---|
| finance | SVC-00040-FINANCE_CONSUMER | SVC-00040-FINANCE_CONSUMER_GROUP | payment.success, purchase-order.received, commerce.initialized |
| inventory | SVC-00050-INVENTORY_CONSUMER | SVC-00050-INVENTORY_CONSUMER_GROUP | payment.success, commerce.initialized, merchant.created |
| pricing | SVC-00070-PRICING_CONSUMER | SVC-00070-PRICING_CONSUMER_GROUP | product-variant.created, product-variant.updated |
| taxation | SVC-00130-TAXATION_CONSUMER | SVC-00130-TAXATION_CONSUMER_GROUP | product.created, product.updated |
| ledger | SVC-00060-LEDGER-{n} | SVC-00060-LEDGER_GROUP | ledger.generate |
| search (CDC) | commerce-cdc-consumer | commerce-cdc-group | Tất cả các topic CDC nx.seller.public.* |
Client ID của Producer Kafka
| Dịch vụ | Client ID |
|---|---|
| commerce | SVC-00020-COMMERCE_PRODUCER |
| sale | SVC-00030-SALE_PRODUCER |
| inventory | SVC-00050-INVENTORY_PRODUCER |
| ledger | SVC-00060-LEDGER-01 |
Kênh Event Redis Pub/Sub
Các kênh sự kiện nhẹ cho giao tiếp nội bộ giữa các dịch vụ. Các kênh này không đi qua Kafka — chúng là Redis pub/sub trực tiếp.
Sự kiện Payment
Định nghĩa trong packages/core/src/common/events/payment-events.ts.
| Channel | Publisher | Subscriber | Mục đích |
|---|---|---|---|
payment.order.success | sale (payment webhook handler) | finance, inventory | Thanh toán đơn hàng hoàn tất — kích hoạt ghi nhận thu nhập và điều chỉnh tồn kho |
Sự kiện Sale Check
Định nghĩa trong packages/sale/src/common/sale-check.constants.ts.
| Sự kiện | Mô tả |
|---|---|
sale.check.created | Check mới được tạo cho một đơn hàng |
sale.check.updated | Số tiền/mục của check được cập nhật |
sale.check.merged | Hai check được gộp lại |
sale.check.rolledBack | Hoàn tác việc gộp check |
sale.check.paid | Check được thanh toán đầy đủ |
sale.order.merged | Hai đơn hàng được gộp |
sale.order.mergeRolledBack | Hoàn tác việc gộp đơn hàng |
sale.order.split | Đơn hàng được tách thành nhiều đơn |
Topic WebSocket
Topic WebSocket theo pattern ws:{namespace}.{domain}.{entity}. Tên phòng theo wr:{namespace}/{path}.
Tiện ích Builder
Định nghĩa trong packages/core/src/common/events/websocket-events.ts:
WebSocketTopics— xây dựng chuỗi topic:ws:observation.sale.sale-orderWebSocketRooms— xây dựng tên phòng:wr:observation/merchants/{merchantId}
Topic theo từng dịch vụ
Sale (packages/sale/src/common/websocket.ts):
| Topic | Mục đích |
|---|---|
ws:observation.sale.sale-order | Đơn hàng được tạo/cập nhật |
ws:observation.sale.sale-order-item | Thay đổi mục đơn hàng |
ws:observation.sale.sale-check | Thay đổi trạng thái check |
ws:observation.sale.kitchen-ticket | Ticket bếp được gửi |
ws:observation.sale.kitchen-ticket-item | Cập nhật mục ticket bếp |
ws:observation.allocation.allocation-usage | Thay đổi sử dụng chỗ ngồi/phân bổ |
Payment (packages/payment/src/common/websocket.ts):
| Topic | Mục đích |
|---|---|
ws:observation.payment.transaction | Cập nhật trạng thái giao dịch thanh toán |
ws:observation.payment.payment-attempt | Sự kiện lần thử thanh toán riêng lẻ |
Outreach (packages/outreach/src/components/websocket/topics.ts):
| Topic | Mục đích |
|---|---|
ws:observation.outreach.inquiry.submitted | Yêu cầu mới được gửi (thông báo realtime cho admin) |
Loại Webhook Event
MQ-Pay → Sale (Payment Webhook)
Định nghĩa trong packages/sale/src/common/webhook-types.ts. Dịch vụ sale nhận các sự kiện này từ MQ-Pay qua HTTP header X-Webhook-Event-Type:
| Loại sự kiện | Hướng | Mục đích |
|---|---|---|
mq-pay:attempt.success | MQ-Pay → Sale | Lần thử thanh toán thành công |
mq-pay:attempt.failed | MQ-Pay → Sale | Lần thử thanh toán thất bại |
mq-pay:attempt.expired | MQ-Pay → Sale | Lần thử thanh toán hết hạn |
mq-pay:attempt.cancelled | MQ-Pay → Sale | Lần thử thanh toán bị người dùng hủy |
mq-pay:transaction.settled | MQ-Pay → Sale | Giao dịch hoàn tất đầy đủ (tất cả mục đã thanh toán) |
mq-pay:transaction.cancelled | MQ-Pay → Sale | Giao dịch bị hủy |
Sự kiện Nội bộ MQ-Pay
Được publish qua EventEmitter của Node.js trong thư viện MQ-Pay:
| Sự kiện | Mục đích |
|---|---|
mq-pay:transaction.created | Giao dịch thanh toán mới được tạo |
mq-pay:transaction.settled | Giao dịch hoàn tất đầy đủ |
mq-pay:transaction.cancelled | Giao dịch bị hủy |
mq-pay:attempt.created | Lần thử thanh toán được khởi tạo |
mq-pay:attempt.sent | Đã gửi yêu cầu đến nhà cung cấp |
mq-pay:attempt.success | Nhà cung cấp xác nhận thành công |
mq-pay:attempt.failed | Nhà cung cấp báo cáo thất bại |
mq-pay:attempt.expired | Lần thử hết hạn |
mq-pay:attempt.cancelled | Lần thử bị hủy |
mq-pay:refund.success | Hoàn tiền thành công |
mq-pay:refund.failed | Hoàn tiền thất bại |
Các sự kiện này được bridge sang dịch vụ sale qua MQPaySaleEventAdapter → SaleEventMapperService → SalePaymentEventHandlerService.
Sơ đồ Luồng Sự kiện
Onboarding Merchant Mới
Luồng Thanh toán
Đồng bộ Sản phẩm (CDC)
Trang Liên quan
| Trang | Mô tả |
|---|---|
| Kiến trúc | Danh mục dịch vụ, chuỗi phụ thuộc, ma trận component |
| Hạ tầng — Kafka | Cài đặt cluster Kafka KRaft |
| Hạ tầng — CDC | Cấu hình pipeline CDC Debezium |
| Tổng quan Packages | Tài liệu theo từng package |