Integration

1. Service anh em

Direction: → gọi / ← được gọi bởi / ↔ hai chiều. Phụ thuộc build-time chỉ là @nx/core; mọi coupling bên dưới 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	←	Consumer TaxInfo (không có bề mặt taxation)	ghép chỉ qua core model	—	n/a	n/a
@nx/identity	←	JWT issuer; JWKS verify mỗi request	ES256 JWKS	JWT	request fail 401	n/a
commerce MerchantRepository	→	In-process DI (MerchantRepository) để lookup taxMethod	repository contract	—	throw khi not-found	n/a

TaxGroupService inject một binding kiểu MerchantRepository để đọc merchant taxMethod trong lúc validate. Binding được resolve từ shared DI graph, không qua HTTP.

2. Hệ thống bên ngoài

System	Direction	Surface	Auth	Failure Mode
Kafka / Debezium	←	Consume public.Product	SASL SCRAM-SHA-512	broker reconnect (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 dòng
3-4	Taxation reconcile: provision khi taxGroupId set, ngược lại deprovision
5	Pricing đọc TaxSet/Tax đã provision trực tiếp — không có event từ taxation

3.2 Validate tax-method của merchant

Bước	Chi tiết
4	Merchant DIRECT không thể dùng group DEDUCTION (và ngược lại); merchant taxMethod chưa set thì cho phép bất kỳ

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

5. Trang liên quan

• API Events
• Pricing
• Commerce
• Decisions