ADR-0001. Publish một subpath ./contracts gần-như-type-only thay vì mount pricing như một component

Trường	Giá trị
Status	Accepted
Date	2026-03
Deciders	pricing-team, sale-team
Supersedes	—

Bối cảnh

• Sale phải định giá giỏ hàng lúc checkout, nhưng pricing là một service runtime riêng với DB schema, Kafka consumer, và calculator riêng.
• Mount pricing như một component IGNIS nhúng được bên trong sale sẽ kéo repository, Kafka component, và ràng buộc DB của pricing vào process sale.
• Sale vẫn cần hình dạng request/response có kiểu mạnh, và vài hằng runtime (vd TransactionDirections.SALE, key PartyRoles) để dựng request và đọc ledger byBearer của snapshot.

Quyết định

Pricing expose một export subpath chuyên dụng @nx/pricing/contracts (src/contracts/index.ts) hầu hết là khai báo export type, cộng một tập nhỏ runtime const container đông cứng (AppliedRuleSourceTypes, FareSourceTypes, FeeScopes, PartyRoles, RuleBasises, Snapshot{Discount,Fee,Tax}Types, TransactionDirections). Sale gọi pricing qua HTTP (PricingNetworkService, BASIC auth) và chỉ import từ subpath này. Sale không bao giờ mount pricing như một component.

Hệ quả

Ưu	Nhược
Sale chỉ ship types xoá được + bảng const nhỏ — không runtime pricing trong bundle	Hai service phải còn tới được lúc checkout (network hop)
Ranh giới service sạch; pricing tiến hoá nội bộ tự do	Const container là một phụ thuộc runtime thật (nhỏ) để quản version
An toàn type qua ranh giới HTTP không cần một package schema dùng chung	Drift hợp đồng chỉ bắt được lúc type-check, không phải trên dây

Phương án đã cân nhắc

Phương án	Ưu	Nhược	Vì sao loại
Mount pricing như một component nhúng được trong sale	Không network hop	Kéo ràng buộc DB/Kafka/repo vào sale; phá cô lập service	Phá vỡ thiết kế service độc lập
Chia mọi types qua @nx/core thôi	Một nơi cho types	Hình dạng snapshot nội bộ của pricing không thuộc core	Làm bẩn core với hợp đồng riêng engine
Contracts thuần-type (không runtime const)	Zero phụ thuộc runtime	Sale sẽ phải tự khai báo lại giá trị TransactionDirections / PartyRoles, rủi ro phân kỳ	Trùng lặp tệ hơn một export const đông cứng

Tham chiếu

• pricing/src/contracts/index.ts
• sale/src/services/pricing-network.service.ts
• sale/src/services/checkout.service.ts