Integration

1. Service anh em

Direction: → gọi / ← được gọi / ↔ hai chiều.

Anh em	Hướng	Bề mặt	Hợp đồng	Auth	Failure Mode	Idempotency
@nx/sale	←	HTTP POST /simulation/calculate (v1)	types @nx/pricing/contracts qua PricingNetworkService.calculate()	BASIC (service-to-service)	sale lan truyền 4xx thượng nguồn (vd không fare active); throw khi network/5xx	request không side-effect, retry an toàn
@nx/sale	←	HTTP POST /simulation-v2/calculate (v2)	types @nx/pricing/contracts qua PricingNetworkService.calculateV2()	BASIC	như trên	như trên
@nx/commerce	←	Kafka CDCKafkaTopics.PRODUCT_VARIANT (Debezium)	@nx/core TProductVariantPgRow	—	at-least-once, commit thủ công	theo (productVariantId)
@nx/identity	→	HTTP — xác minh JWT qua JWKS	JWT (ES256)	retry / fallback cache Redis	theo request

Commerce không phụ thuộc pricing trực tiếp. Liên kết commerce → pricing duy nhất là hàng ProductVariant rơi vào luồng CDC mà worker của pricing consume.

2. Ranh giới @nx/pricing/contracts

Sale tiêu thụ pricing qua export subpath chuyên dụng ./contracts (src/contracts/index.ts), không phải package root. Export hầu hết là khai báo export type cộng một tập nhỏ runtime const container mà sale cần lúc runtime để diễn giải snapshot.

Loại	Symbols (từ contracts)
Request types	TSimulationCalculateRequest, TPricingContext, TPricingV2CalculateRequest, TPricingV2ContextRequest, TPricingV2ItemContext, TPricingV2ItemRequest
Response types	TSimulationCalculateResponse, TPricingV2CalculateResponse
Snapshot types	TAppliedPrice/Tax/Discount/Fee/Rule, TLineItemPricingSnapshot, TOrderPricingSnapshot, TByBearerTotals, TFareSource(Type), TPartyRole, TRuleBasis, TMoney, TCurrencyCode, TTransactionDirection, TSnapshot{Discount,Fee,Tax}Type, TFeeScope
Runtime const containers	AppliedRuleSourceTypes, FareSourceTypes, FeeScopes, PartyRoles, RuleBasises, SnapshotDiscountTypes, SnapshotFeeTypes, SnapshotTaxTypes, TransactionDirections

Consumer đã xác minh:

• sale/src/services/pricing-network.service.ts — import types request/response (import type { ... }) để type các lệnh gọi Axios.
• sale/src/services/checkout.service.ts — import TPricingV2CalculateResponse (type) và TransactionDirections (giá trị runtime, để đặt direction: TransactionDirections.SALE trên request và thu hẹp ledger byBearer của snapshot).

Cái này giữ sale không có phụ thuộc runtime nào vào engine của pricing — nó chỉ ship types xoá được cộng một nhúm bảng const đông cứng. Sale không bao giờ mount pricing như một component IGNIS. Xem ADR-0001.

3. Luồng xuyên service quan trọng

3.1 Fan-out định giá Checkout

Hợp đồng:

• Pricing stateless — nó trả snapshot; sale lưu nó. Pricing không giữ bản ghi order.
• Một 4xx thượng nguồn (vd variant không có FareSet ACTIVATED) được sale surface với status thượng nguồn, không che thành 500.
• v2 là canonical; sale lưu snapshot v2 làm nguồn sự thật audit/refund.

3.2 ProductVariant CDC → Seed Fare

4. Độ ổn định hợp đồng

Bề mặt	Độ ổn định	Versioning
HTTP /simulation/calculate (v1)	ổn định, đang bảo trì	URL /v1/; v2 là canonical cho việc mới
HTTP /simulation-v2/calculate (v2)	ổn định	URL /v1/; envelope snapshot mang v: 1 literal riêng
Snapshot types @nx/pricing/contracts	ổn định	v literal theo từng envelope (Order / LineItem / theo từng applied-rule version độc lập)
Kafka PRODUCT_VARIANT	ổn định	Schema Debezium; chỉ thêm trường

5. Trang liên quan

• API Events
• Fare System
• ADR-0001 — ranh giới contracts
• Decisions