Integration
1. Service anh em
Direction:→gọi /←được gọi bởi (tiêu thụ từ) /↔hai chiều.
| Sister | Direction | Surface | Contract | Auth | Failure Mode | Idempotency |
|---|---|---|---|---|---|---|
@nx/sale | ← | Kafka payment.success | event → phiếu RECEIPT | — | at-least-once | (SALE_ORDER, attempt.uid) |
@nx/inventory | ← | Kafka purchase-order.received | event → phiếu PAYMENT (party VENDOR) | — | at-least-once | (PURCHASE_ORDER, purchaseOrderId) |
@nx/inventory | ← | Kafka inventory.issued-for-sale | event → COGS ADJUSTMENT | — | at-least-once | (SALE_ORDER, attemptUid) |
@nx/inventory | ← | Kafka inventory.adjusted | event → INVENTORY ADJUSTMENT | — | at-least-once | (INVENTORY_ADJUSTMENT, inventoryTrackingId) |
@nx/commerce | ← | Debezium CDC Merchant | row → đối soát tài khoản | — | at-least-once | kiểm tra tồn tại tài khoản |
@nx/core | → | in-process (repos/services re-export) | DI bindings | — | — | — |
@nx/asset | → | in-process component | dữ liệu tham chiếu ngân hàng VN | — | — | — |
@nx/identity | → | HTTP — JWKS verify (VerifierApplication) | JWT (ES256) | JWT | retry / cache | request-id được propagate |
Finance resolve
PurchaseOrder+Vendorqua repository@nx/coređược re-export (cùng DB) để enrich party của phiếu PAYMENT — không có lời gọi HTTP tới inventory.
2. Hệ thống bên ngoài
Không trực tiếp. Credential payment-gateway (VNPAY, banks, e-wallets) được lưu trong PaymentIntegration (encrypted) nhưng finance không gọi các gateway đó — @nx/mq-pay sở hữu traffic provider. @nx/asset cung cấp dữ liệu tham chiếu ngân hàng Việt Nam tĩnh.
3. Luồng cross-service quan trọng
3.1 Thanh toán bán hàng → thu nhập ledger
Contract: finance chỉ hạch toán khi payload sale mang theo tài khoản được chọn (attempt.finance.source.id). Tender tách post một RECEIPT cho mỗi attempt, dedup theo attempt.uid.
3.2 Đơn mua đã nhận → thanh toán vendor + tài sản tồn kho
3.3 Xuất/điều chỉnh tồn kho → hạch toán COGS & tài sản
3.4 Onboarding merchant (CDC)
4. Tính ổn định Contract
| Surface | Stability | Versioning |
|---|---|---|
HTTP /v1/api/finance/* | stable | URL prefix /v1/ |
Kafka payment.success (tiêu thụ) | stable | payload chỉ thêm trường |
Kafka purchase-order.received (tiêu thụ) | stable | payload chỉ thêm trường |
Kafka inventory.issued-for-sale / inventory.adjusted (tiêu thụ) | stable | payload chỉ thêm trường |
Debezium Merchant CDC | theo schema commerce | chỉ thêm cột |
| Kafka outbound | hiện không có | dự trữ |
5. Trang liên quan
- API Events
- Sale — tạo ra
payment.success - Decisions