Tích hợp
1. Dịch vụ chị em
| Chị em | Hướng | Bề mặt | Auth | Chế độ lỗi | Idempotency |
|---|---|---|---|---|---|
@nx/identity | → | HTTP JWKS (/jw-certs) để xác thực JWT | — | retry / fail boot | request-id |
@nx/search | ↔ | Components (ApplicationSearchComponent, Typesense, Embedding); CDC consumer ở vai trò WORKER | — | replay offset CDC | upsert theo PK |
@nx/inventory | → (CDC) | public.Merchant, public.ProductVariant | — | replay Debezium | theo PK; seed location + InventoryItem |
@nx/pricing | → (CDC) | pricing.Fare*, public.ProductVariant | — | replay Debezium | theo PK; init fare |
@nx/taxation | → (CDC) | public.Product (taxGroupId) | — | replay Debezium | theo PK; cấp phát thuế |
@nx/invoice | → (CDC) | public.Merchant → TaxInfo | — | replay Debezium | theo PK; TaxInfo có thẩm quyền |
@nx/asset | ↔ | ApplicationAssetComponent (Minio); MetaLinks | — | retry upload | theo asset id |
@nx/sale | ← | HTTP đọc ProductVariant, ProductInfo, SaleChannel, Category | JWT (s2s) | retry | snapshot trên order |
Commerce không push trực tiếp tới inventory/pricing/taxation/invoice — cả bốn đều tiêu thụ CDC. Xem ADR-0002.
2. Hệ thống bên ngoài
| Hệ thống | Qua | Ghi chú |
|---|---|---|
| Minio | @nx/asset | Lưu trữ object cho media product/variant |
| Typesense | @nx/search | Engine tìm kiếm; được điền bởi CDC, không phải trực tiếp bởi commerce |
| Kafka / Debezium | infra | Commerce chỉ ghi Postgres; Debezium (Kafka Connect) thực hiện capture WAL |
| Provider thanh toán/hóa đơn điện tử | Configuration mã hóa | Commerce lưu thông tin đăng nhập (AES-256-GCM); cuộc gọi thực tế do dịch vụ payment/invoice sở hữu |
Không có cuộc gọi API bên thứ ba trực tiếp từ source commerce — thông tin đăng nhập provider được thu thập ở đây và tiêu thụ nơi khác.
3. Luồng cross-service quan trọng
3.1 Onboarding → Seed Inventory (CDC)
3.2 Product Variant → Inventory Item + Pricing Fare (CDC)
Variant COMBO không nằm trong
STOCKABLE_SET, nên inventory không seedInventoryItemcho chúng.
3.3 Thông tin thuế Merchant → TaxInfo (CDC)
3.4 Sao chép sản phẩm đa Merchant (nội bộ)
4. Tính ổn định của hợp đồng
| Bề mặt | Ổn định | Quản lý phiên bản |
|---|---|---|
HTTP /v1/api/commerce/* | ổn định | tiền tố URL /v1/ |
CDC topics (public.*) | gắn schema | thêm cột an toàn; đổi tên phá vỡ consumer — phối hợp |
Hình dạng Merchant.metadata.tax | ổn định | chỉ thêm trường (taxCode bắt buộc) |
| Khóa sự kiện EventBus | nội bộ | không phải hợp đồng công khai |
| Hình dạng job BullMQ | nội bộ | không phải hợp đồng công khai |
5. Trang liên quan
- API Events — danh sách bảng CDC + chi tiết EventBus/BullMQ
- Kiến trúc
- Quyết định