Integration
1. Service anh em
Direction:→gọi /←được gọi bởi /↔hai chiều. Phụ thuộc lúc build chỉ là@nx/core; mọi liên kết bên dưới đều qua shared DB hoặc Kafka CDC.
| Sister | Direction | Surface | Contract | Auth | Failure Mode | Idempotency |
|---|---|---|---|---|---|---|
@nx/commerce | ← | Kafka public.Product (Debezium) | CDC envelope (TProductPgRow) | - | at-least-once; log + skip | (productId, taxGroupId, op) |
@nx/pricing | ← | Shared DB read pricing.TaxSet / pricing.Tax | Drizzle row shape | - | n/a (read) | n/a |
@nx/invoice | ← | Bên tiêu thụ TaxInfo (không có bề mặt taxation) | chỉ ghép nối qua core model | - | n/a | n/a |
@nx/identity | ← | JWT issuer; JWKS được xác minh mỗi request | ES256 JWKS | JWT | request lỗi 401 | n/a |
commerce MerchantRepository | → | In-process DI (MerchantRepository) để tra cứu taxMethod | repository contract | - | ném lỗi khi không tìm thấy | n/a |
TaxGroupServiceinject một binding kiểuMerchantRepositoryđể đọc merchanttaxMethodtrong lúc kiểm tra. Binding được phân giải từ shared DI graph, không qua HTTP.
2. Hệ thống bên ngoài
| System | Direction | Surface | Auth | Failure Mode |
|---|---|---|---|---|
| Kafka / Debezium | ← | Tiêu thụ public.Product | SASL SCRAM-SHA-512 | broker kết nối lại (có log) |
| PostgreSQL | ↔ | Schema tax + pricing | user/pass | pool error |
3. Luồng cross-service quan trọng
3.1 Thay đổi sản phẩm → provisioning thuế
| Bước | Chi tiết |
|---|---|
| 1-2 | Commerce sở hữu Product; Debezium bắt thay đổi của dòng |
| 3-4 | Taxation reconcile: provision khi có taxGroupId, ngược lại deprovision |
| 5 | Pricing đọc trực tiếp TaxSet/Tax đã provision - không có event từ taxation |
3.2 Kiểm tra phương pháp thuế của merchant
| Bước | Chi tiết |
|---|---|
| 4 | Merchant DIRECT không thể dùng group DEDUCTION (và ngược lại); nếu merchant chưa đặt taxMethod thì cho phép bất kỳ group nào |
4. Tính ổn định Contract
| Surface | Stability | Versioning |
|---|---|---|
HTTP /tax-groups, /tax-group-items | stable | URL /v1/ |
HTTP /tax-provisioning/* | stable | URL /v1/ |
HTTP /vn-* reads | stable | URL /v1/ |
Kafka public.Product (inbound) | external (Debezium-defined) | Debezium schema |
Shared read pricing.TaxSet / pricing.Tax | stable (core-owned) | schema migration |