ADR-0002. Chạy calculator v1 (/simulation) và v2 (/simulation-v2) song song; v2 canonical

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

Bối cảnh

• Pipeline v1 gốc (src/services/core/) trả response giá + thuế flat theo dòng. Nó hoạt động nhưng không thể diễn đạt ai gánh mỗi khoản (người mua / người bán / platform / nhà nước) hay mang một audit trail tự chứa.
• Nhu cầu hạ nguồn (refund, khai thuế, đối soát platform, biên lai bất biến) yêu cầu một snapshot với provenance applied-rule và một ledger theo từng role (byBearer).
• Sale đã lưu snapshot v2 trên SaleOrder.priceMetadata làm nguồn sự thật audit/refund.
• v1 và v2 chia sẻ khoảng 90% logic fare/tax, nên cutover cứng rủi ro regress đường flat vẫn đang dùng.

Quyết định

Giữ cả hai pipeline sống sau route riêng: v1 tại POST /simulation/calculate (flat) và v2 tại POST /simulation-v2/calculate (snapshot — OrderPricingSnapshot + LineItemPricingSnapshot[]). v2 là canonical cho mọi việc mới. Sale gọi cả hai lúc checkout trong giai đoạn chuyển tiếp; v2 là nguồn sự thật được lưu.

Hệ quả

Ưu	Nhược
Consumer mới nhận provenance rule đầy đủ + ledger by-bearer	Chồng lấp ~90% logic nghĩa sửa thường áp cả hai pipeline
Không rủi ro regression cho consumer giá-flat hiện có	Hai đường code phải bảo trì tới khi v1 nghỉ
Envelope snapshot version độc lập (v: 1 mỗi lớp)	Latency calculate gấp đôi lúc checkout khi gọi cả hai

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

Phương án	Ưu	Nhược	Vì sao loại
Cutover cứng v1 → v2	Một đường code	Rủi ro regression cao; mọi caller phải migrate cùng lúc	Quá gây xáo trộn giữa chừng
Mở rộng response v1 tại chỗ	Không route mới	Phá hợp đồng flat; không thêm byBearer được mà không biến động	Không tương thích ngược
Chỉ tính v2, suy flat từ nó	Một engine	Caller v1 cần một lớp downshaping; chưa xây	Hoãn tới khi v1 nghỉ

Tham chiếu

• pricing/src/services/core/ (v1)
• pricing/src/services/core-v2/ (v2 + pricing-snapshot/)
• pricing/src/controllers/simulation/, pricing/src/controllers/simulation-v2/