Tích hợp
1. Sister Services
| Sister | Hướng | Bề mặt | Auth | Chế độ lỗi | Idempotency |
|---|---|---|---|---|---|
@nx/mq-pay | ← | HTTP webhook /webhooks/payment | không (tin cậy) | MQ-Pay retry 5xx | webhook handler no-op trên transition đã áp dụng |
@nx/inventory | → | Kafka payment.success | — | post-commit fire-and-forget | per (saleOrderId, stockId) phía consumer |
@nx/inventory | → | Kafka kitchen-ticket-item.status-changed | — | post-commit fire-and-forget | per (saleOrderId, kitchenTicketItemId, materialId) phía consumer |
@nx/inventory | ← | Kafka material.stock-changed | — | (sale hiện không tiêu thụ — sản xuất cho UI consumer) | — |
@nx/finance | → | Kafka payment.success | — | post-commit fire-and-forget | per saleOrderId phía consumer |
@nx/commerce | → | HTTP — đọc ProductVariant, ProductInfo, SaleChannel, Category cho snapshot | JWT (service-to-service) | retry 3x | snapshot lưu trên order |
@nx/pricing | → | HTTP — PricingNetworkService.calculate() + calculateV2() | JWT | retry; checkout fail khi lỗi liên tục | request checkout idempotent (không side-effect khi retry) |
@nx/identity | → | HTTP — xác minh JWT qua JWKS (/jw-certs) | JWT | retry / circuit-break | request-id được lan truyền |
@nx/identity | → | HTTP — PolicyDefinitionService lookup permission | JWT | Redis cache fallback | per (role, action) |
@nx/signal | → | Phát WebSocket qua ApplicationWebSocketComponent | — | giao hàng best-effort | broadcast |
2. Hệ thống bên ngoài
Tích hợp bên ngoài trực tiếp: không có. Sale dùng MQ-Pay (sister) để trừu tượng hóa payment provider. Payment provider bên thứ ba (VNPay, v.v.) thuộc về @nx/mq-pay.
3. Flow 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 per transition trạng thái (post-commit). - Webhook là source-of-truth cho trạng thái — Sale không poll MQ-Pay.
- Idempotency: webhook handler short-circuit nếu order đã ở trạng thái target.
3.2 Kitchen Item READY → Tiêu thụ Material
3.3 Fan-out 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 | Ổn định | Versioning |
|---|---|---|
HTTP /v1/api/sale/* | stable | URL prefix /v1/ |
HTTP webhook /webhooks/payment | stable | request schema được version 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ý |
|---|---|
| Trust boundary | Endpoint webhook tin cậy MQ-Pay (không auth). Cô lập cấp mạng qua Cilium policy áp đặt điều này. |
| Bảo vệ race | SELECT FOR UPDATE trên row order khi checkout + add-item. |
| Capture snapshot | Khi checkout, sale 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 per order. |
6. Trang liên quan
- API Sự kiện
- Payment Webhooks — chi tiết flow webhook
- Quyết định