Tích hợp
1. Các service anh em
| Service anh em | Hướng | Bề mặt | Auth | Chế độ lỗi | Tính idempotent |
|---|---|---|---|---|---|
@nx/mq-pay | ← | HTTP webhook /webhooks/payment | không (tin cậy) | MQ-Pay thử lại khi 5xx | webhook handler no-op với chuyển trạng thái đã áp dụng |
@nx/inventory | → | Kafka payment.success | - | sau commit, fire-and-forget | theo (saleOrderId, stockId) ở phía consumer |
@nx/inventory | → | Kafka kitchen-ticket-item.status-changed | - | sau commit, fire-and-forget | theo (saleOrderId, kitchenTicketItemId, materialId) ở phía consumer |
@nx/inventory | ← | Kafka material.stock-changed | - | (sale hiện không tiêu thụ - phát cho UI consumer) | - |
@nx/finance | → | Kafka payment.success | - | sau commit, fire-and-forget | theo saleOrderId ở phía consumer |
@nx/commerce | → | HTTP - đọc ProductVariant, ProductInfo, SaleChannel, Category cho snapshot | JWT (service-to-service) | thử lại 3 lần | snapshot lưu trên order |
@nx/pricing | → | HTTP - PricingNetworkService.calculate() + calculateV2() | JWT | thử lại; checkout thất bại khi lỗi liên tục | request checkout idempotent (không gây tác dụng phụ khi thử lại) |
@nx/identity | → | HTTP - xác minh JWT qua JWKS (/jw-certs) | JWT | thử lại / circuit-break | request-id được lan truyền |
@nx/identity | → | HTTP - PolicyDefinitionService tra cứu permission | JWT | quay về Redis cache | theo (role, action) |
@nx/signal | → | Phát WebSocket qua ApplicationWebSocketComponent | - | giao tốt nhất có thể | broadcast |
2. Hệ thống bên ngoài
Tích hợp trực tiếp với bên ngoài: không có. Sale dùng MQ-Pay (service anh em) để trừu tượng hoá nhà cung cấp thanh toán. Các nhà cung cấp thanh toán bên thứ ba (VNPay, v.v.) thuộc về @nx/mq-pay.
3. Các luồng liên service quan trọng
3.1 Thanh toán thành công → Trừ kho + Ghi nhận thu nhập
Hợp đồng:
- Sale đảm bảo
PAYMENT_SUCCESSđược phát đúng một lần cho mỗi lần chuyển trạng thái (sau commit). - Webhook là nguồn sự thật cho trạng thái - Sale không poll MQ-Pay.
- Tính idempotent: webhook handler thoát sớm nếu order đã ở trạng thái đích.
3.2 Kitchen Item READY → Tiêu thụ Material
3.3 Gọi Pricing khi Checkout
3.4 MQ-Pay Webhook Retry (lưới an toàn của Sale)
4. Ổn định hợp đồng
| Bề mặt | Mức ổn định | Phiên bản |
|---|---|---|
HTTP /v1/api/sale/* | stable | tiền tố URL /v1/ |
HTTP webhook /webhooks/payment | stable | request schema được đánh phiên bản qua namespace eventType |
Kafka topic payment.success | stable | payload chỉ thêm field |
Kafka topic kitchen-ticket-item.status-changed | stable | payload chỉ thêm field |
WebSocket topic observation/sale/* | stable | payload chỉ thêm field |
5. Mối quan tâm xuyên suốt
| Mối quan tâm | Xử lý |
|---|---|
| Ranh giới tin cậy | Endpoint webhook tin cậy MQ-Pay (không auth). Việc cô lập ở cấp mạng qua Cilium policy đảm bảo điều này. |
| Bảo vệ race | SELECT FOR UPDATE trên dòng order khi checkout + add-item. |
| Chụp snapshot | Khi checkout, sale chụp snapshot: pricing (v1+v2), trạng thái allocation, metadata product variant, recipe id. Vòng đời = order. |
| Tiền tệ | Lưu ở cấp order. Đa tiền tệ yêu cầu snapshot exchangeRate cho mỗi order. |
6. Trang liên quan
- API Sự kiện
- Payment Webhooks - chi tiết luồng webhook
- Quyết định