PRD: Bộ máy định giá Fare & Thuế

Module	Định giá	PRD ID	PRD-FARE-001
Trạng thái	Sẵn sàng dev	FEAT	FARE
Epic	—	Plane	BANA-1513
Ngày	2026-06-05	Phiên bản	v1.0
Gói	@nx/pricing	URD	FARE
Surface	BackendClient · Chủ/QL
Phụ trách	Phát Nguyễn

Bộ máy định giá Fare & Thuế là gì

Mỗi biến thể sản phẩm có một fare set (Fare Set) - nơi chứa giá gốc và các fare con có điều kiện; hệ thống tự tạo fare set + giá gốc ngay khi biến thể xuất hiện, nên biến thể nào cũng định giá được ngay. Chủ merchant đặt một fare cha theo một trong hai chiến lược - OVERRIDE (luôn ghi đè) hoặc SALE (cạnh tranh như một mức giảm) - rồi thêm các fare con mang giá riêng và quy tắc điều kiện (số lượng, khung giờ...). Bộ máy chọn fare thắng theo tầng ưu tiên cao nhất trước; trong tầng đó một fare OVERRIDE luôn thắng SALE, còn giữa các fare hợp lệ cùng loại thì giá thấp nhất thắng; không có fare con nào hợp lệ thì quay về giá gốc.

Song song đó, chủ merchant gắn thuế (Tax) phần trăm, cố định hoặc theo đơn vị vào một tax set (Tax Set) của biến thể, chọn inclusive (gộp trong giá) hay exclusive (cộng thêm), và thuế có thể lũy tiến chồng lên thuế trước theo thứ tự ưu tiên. Khi thanh toán, luồng bán hàng gọi một mô phỏng định giá duy nhất; kết quả là một pricing snapshot bất biến - phân rã fare và thuế theo từng dòng cộng tổng đơn hàng - để việc định giá luôn nhất quán và truy vết được. Một dòng không có cấu hình thuế vẫn định giá được, chỉ là thuế bằng 0 - không bao giờ bị chặn vì thiếu cấu hình.

Vì sao cần một bộ máy duy nhất

Trước đây giá bị gắn cứng trên sản phẩm hoặc tính tùy hứng khi thanh toán - không có chỗ thống nhất nào cho thuế, giá theo quy tắc, hay một bảng phân rã truy vết được. Chủ merchant cần một bộ máy duy nhất chọn đúng fare cho từng biến thể, tính thuế chính xác (inclusive/exclusive, lũy tiến, cấp dòng hàng), và trả về một kết quả định giá nhất quán mà luồng bán hàng dùng lại khi thanh toán thay vì tự viết lại logic định giá. Đó là nền tảng cho việc báo cáo giá vốn, thuế và biên lợi nhuận đáng tin cho bài toán sổ sách HKD/SME mà BANA hướng tới.

Bộ máy đặt việc chọn fare và tính thuế trên nền danh mục biến thể sản phẩm, giới hạn mọi bản ghi trong merchant của chính người dùng, và mở một mô phỏng định giá cho luồng bán hàng dùng.

Một ví dụ từ đầu tới cuối

Biến thể "Áo thun trắng" có giá gốc 100.000đ. Chủ merchant thêm một fare cha SALE với một fare con giá 80.000đ, mang quy tắc "số lượng mua từ 10 trở lên". Tax set của biến thể này gắn một thuế VAT 10%, chưa gộp.

Bước	Việc xảy ra	Kết quả
Khách mua 12 áo	Bộ máy đánh giá quy tắc số lượng: 12 ≥ 10, fare con hợp lệ	Fare con 80.000đ thắng, không phải giá gốc 100.000đ
Tính thuế trên đơn giá đã chọn	VAT 10% chưa gộp, cộng thêm lên trên	Thuế một áo = 80.000 × 10% = 8.000đ
Mô phỏng định giá trả về ảnh chụp dòng	12 áo, đơn giá 80.000đ	subtotal 960.000đ, thuế 96.000đ, total 1.056.000đ
Khách mua 5 áo (một đơn khác)	Quy tắc số lượng sai (5 < 10), fare con bị loại	Bộ máy quay về giá gốc 100.000đ/áo, không báo lỗi

Chỗ dễ sai nhất

Giá gốc cũng cạnh tranh theo tầng ưu tiên của chính nó

Giá gốc không tự động thua một fare con nằm chung tầng ưu tiên. Giá gốc mặc định đứng ở mức ưu tiên 0; một fare con cũng đặt ưu tiên 0 phải so giá sòng phẳng với giá gốc như hai đối thủ ngang hàng, không phải cứ có fare con là fare con thắng.

Ngược lại, khi một fare OVERRIDE hợp lệ có mặt trong tầng ưu tiên đang thắng, nó thắng ngay lập tức, không so giá với bất kỳ ai trong tầng đó - kể cả một fare SALE rẻ hơn.

1. Mục tiêu & Loại trừ

Mục tiêu

• Chọn fare thắng cho từng biến thể theo tầng ưu tiên cao nhất trước: giá gốc cạnh tranh ở mức ưu tiên riêng của nó (mặc định 0); trong tầng thắng, một fare OVERRIDE luôn thắng SALE, còn nếu không có OVERRIDE thì fare hợp lệ rẻ nhất thắng, kèm đánh giá quy tắc (attribute, operator, value; logic AND).
• Tính thuế theo thứ tự ưu tiên với các chế độ percentage, fixed-amount và per-unit-amount, cách xử lý inclusive/exclusive, thuế lũy tiến tax-on-tax, ở phạm vi cấp dòng hàng.
• Cung cấp một mô phỏng định giá trả về một pricing snapshot bất biến - fare và thuế áp dụng theo từng dòng cộng với tổng đơn hàng.
• Tự động tạo một fare set + giá gốc ngay khi một biến thể sản phẩm xuất hiện, để mọi biến thể đều có thể định giá ngay lập tức.
• Định giá một dòng với thuế bằng 0 khi nó không có cấu hình thuế, thay vì báo lỗi.

Loại trừ

• Áp dụng giảm giá khuyến mãi khi thanh toán - bộ tính giảm giá chưa được nối trong increment này (thuộc về feature Khuyến mãi).
• Tính thuế cấp đơn hàng (order-level) - tax set toàn merchant đã được mô hình hóa nhưng chưa được tính trong bất kỳ pipeline định giá nào.
• Định giá đa tiền tệ.
• Lưu đơn hàng, phát hành hóa đơn, hay thay đổi tồn kho.

2. Thước đo thành công

Thước đo	Mục tiêu / tín hiệu
Độ chính xác định giá	Giá khi thanh toán khớp với fare + thuế đã cấu hình cho các giỏ hàng lấy mẫu; không sai lệch so với tính tay
Độ phủ fare	100% biến thể sản phẩm có thể định giá ngay (tự tạo fare set + giá gốc)
Tính toàn vẹn snapshot	Mỗi đơn hàng đã định giá tạo ra một snapshot bất biến với bảng phân rã fare/thuế theo từng dòng
Độ chính xác số học	Tính tiền khớp đến độ chính xác 4 chữ số thập phân xuyên suốt

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Owner / Manager	Đặt giá gốc và giá có điều kiện theo từng biến thể, gắn thuế, kiểm soát cách chọn giá
Cashier	Nhận kết quả định giá đúng và nhất quán khi thanh toán mà không phải cấu hình gì
System	Tự tạo fare set + giá gốc khi một biến thể xuất hiện, để không có gì không định giá được

Kịch bản cốt lõi: owner đặt một fare gốc và các fare con tùy chọn theo quy tắc + thuế cho từng biến thể → khi thanh toán luồng bán hàng gọi mô phỏng định giá → bộ máy chọn fare thắng cho từng dòng theo tầng ưu tiên, tính thuế cấp dòng hàng theo thứ tự ưu tiên → trả về một pricing snapshot bất biến với tổng theo từng dòng và theo đơn hàng.

4. User Stories

#	Là một	Tôi muốn	Để
01	owner	đặt giá gốc cho từng biến thể và các giá con theo quy tắc	đúng giá được áp dụng tự động
02	owner	chọn xem một fare con đóng vai trò OVERRIDE (luôn được ưu tiên) hay SALE (cạnh tranh như một mức giảm giá, giá hợp lệ rẻ nhất thắng)	tôi kiểm soát chiến lược giá của mình
03	owner	gắn thuế percentage, fixed hoặc per-unit ở cấp dòng hàng, inclusive hoặc exclusive, lũy tiến khi cần	tổng phản ánh đúng cách xử lý thuế
04	cashier	việc thanh toán trả về một kết quả định giá nhất quán cho giỏ hàng	tôi không phải nhập lại hay tính lại giá
05	cashier	một bảng phân rã có thể truy vết cho mọi fare và thuế đã áp dụng	một mức giá bị tranh chấp có thể được giải thích
06	system	một fare set + giá gốc được tạo tự động khi một biến thể xuất hiện	mọi biến thể đều có thể định giá ngay

5. Yêu cầu chức năng

#	Yêu cầu	Trạng thái	URD ref
FR-001	Mỗi biến thể sản phẩm có một fare set - nơi chứa toàn bộ fare của biến thể đó. Owner đặt một giá gốc (fare không cha, không con) làm phương án dự phòng.	✅	URD-FARE-001 · URD-FARE-003
FR-002	Một fare set + giá gốc được tạo tự động khi một biến thể sản phẩm xuất hiện (qua sự kiện đồng bộ dữ liệu).	✅	URD-FARE-002
FR-003	Owner tạo một fare cha theo một trong hai chiến lược - OVERRIDE hoặc SALE - rồi thêm các fare con dưới fare cha đó. • Mỗi fare con mang giá riêng. • Mỗi fare con mang quy tắc điều kiện (attribute, operator, value). • Mọi quy tắc của một fare con phải cùng đúng thì fare con đó mới hợp lệ (logic AND).	✅	URD-FARE-004 · URD-FARE-005 · URD-FARE-006
FR-004	Bộ máy chọn fare thắng theo tầng ưu tiên. • Thu hẹp về tầng ưu tiên cao nhất trong số các fare con hợp lệ và giá gốc; giá gốc cạnh tranh ở mức ưu tiên riêng của nó, mặc định 0. • Trong tầng đó, nếu có ít nhất một fare OVERRIDE hợp lệ thì OVERRIDE luôn thắng SALE, và OVERRIDE rẻ nhất được chọn. • Nếu tầng đó không có OVERRIDE nào, fare có giá thấp nhất trong tầng thắng.	✅	URD-FARE-007 · URD-FARE-008
FR-005	Khi không có fare con nào hợp lệ, giá gốc được chọn.	✅	URD-FARE-009
FR-006	Owner có thể tạo loại thuế và một tax set, thêm thuế vào đó trong một lần lưu.	✅	URD-TAX-001 · URD-TAX-002
FR-007	Một thuế có ba cách tính: percentage, fixed amount, hoặc per-unit amount. • Thuế áp theo thứ tự ưu tiên tăng dần. • Các thuế cùng mức ưu tiên được gom thành một nhóm và tính chung.	✅	URD-TAX-003 · URD-TAX-004
FR-008	Một thuế là exclusive hoặc inclusive. • Exclusive: cộng thêm lên trên giá. • Inclusive: tính ngược ra từ giá, không bao giờ làm tăng tổng. • Thuế lũy tiến tính trên tổng đang chạy, đã gồm các nhóm ưu tiên trước đó.	✅	URD-TAX-005 · URD-TAX-006
FR-009	Thuế cấp dòng hàng áp theo từng dòng. • Thuế lấy từ tax set của biến thể; biến thể chưa có tax set riêng thì lấy tax set của sản phẩm. • Tax set toàn merchant (cấp đơn hàng) đã được mô hình hóa, nhưng thuế cấp đơn hàng chưa được tính trong bất kỳ pipeline định giá nào.	🔶	URD-TAX-008
FR-010	Một dòng không có cấu hình thuế được định giá với thuế bằng 0, thay vì báo lỗi.	✅	URD-TAX-009
FR-011	Mô phỏng định giá trả về một pricing snapshot bất biến. • Theo từng dòng: fare đã chọn và các khoản thuế đã áp. • Theo đơn hàng: tổng đơn, cùng một sổ cái theo từng bên chịu (người mua / người bán).	✅	URD-CON-004
FR-012	Giá trị tiền dùng độ chính xác 4 chữ số thập phân xuyên suốt tính toán.	✅	URD-CON-003
FR-013	Fare, fare set, thuế và tax set là dữ liệu riêng của từng merchant. • Mọi bản ghi được giới hạn trong merchant của chính owner. • Xóa là xóa mềm, khôi phục được.	✅	URD-FARE-011 · URD-TAX-010

5.1 Tiêu chí nghiệm thu

• Tạo một biến thể sản phẩm mới với giá bán → một fare set + một fare gốc được tạo tự động, biến thể định giá được ngay không cần thao tác thêm.
• Tạo một fare cha OVERRIDE và một fare cha SALE, mỗi bên có fare con hợp lệ cùng tầng ưu tiên cao nhất → định giá dòng đó → fare OVERRIDE thắng dù giá SALE thấp hơn.
• Một biến thể có giá gốc 100 và một fare con SALE 80 (quy tắc: số lượng ≥ 10) → định giá 12 đơn vị → fare con 80 thắng; định giá 5 đơn vị → giá gốc 100 thắng vì không quy tắc nào khớp.
• Tạo một tax set cho biến thể, thêm một thuế 10% exclusive trên giá 110 → tính giá → thuế 11, tổng 121.
• Đổi thuế đó thành inclusive → tính giá → thuế xấp xỉ 10, tổng vẫn giữ 110 (tính ngược ra từ giá).
• Thêm hai thuế lũy tiến (10% rồi 5%) trên cơ sở 100 → tính giá → thuế đầu 10 đưa cơ sở lên 110, thuế sau 5,5; tổng thuế 15,5.
• Định giá một dòng của biến thể chưa gắn tax set nào → dòng vẫn được định giá, phần thuế bằng 0, không báo lỗi.
• Gọi mô phỏng định giá cho một giỏ nhiều dòng → nhận về một pricing snapshot bất biến với fare và thuế áp dụng theo từng dòng, cộng tổng đơn hàng và sổ cái theo bên chịu.
• Cấu hình một tax set cấp merchant (order-level) rồi định giá một đơn → phần thuế cấp đơn hàng không xuất hiện trong kết quả, chỉ thuế cấp dòng hàng được tính.
• Xóa một fare, fare set, thuế hoặc tax set → bản ghi chuyển sang trạng thái đã xóa (soft-delete) và không còn được dùng để định giá, nhưng vẫn khôi phục được.

6. Yêu cầu phi chức năng

Khía cạnh	Yêu cầu
Toàn vẹn dữ liệu	Một pricing snapshot đã tính là bất biến sau khi tạo ra; bảng phân rã không bị sửa về sau
Phân quyền theo merchant	Mọi fare, thuế và bản ghi đều được giới hạn trong merchant của chính người dùng và được xóa mềm (khôi phục được); truy cập yêu cầu xác thực
Độ chính xác	Tính tiền dùng độ chính xác 4 chữ số thập phân; thuế inclusive không bao giờ làm tăng tổng
Hiệu năng / quy mô	Mô phỏng định giá cả giỏ hàng trong một lần gọi
Tính nhất quán fare set	Việc tự tạo fare set khi có biến thể mới chỉ được canh giữ bằng kiểm tra tồn tại ở tầng đồng bộ dữ liệu (bỏ qua nếu fare set đã có cho biến thể đó), không phải một ràng buộc ở tầng cơ sở dữ liệu buộc đúng một fare set cho mỗi biến thể
i18n	Nhãn hiển thị cho người dùng là song ngữ

7. UX & Luồng

Các màn hình cấu hình (fare, fare set, thuế, tax set) nằm trong back office hướng tới owner; kết quả định giá được luồng bán hàng dùng không giao diện khi thanh toán.

8. Dữ liệu & Miền nghiệp vụ

Khái niệm	Vai trò
Fare set	Bộ chứa tất cả fare cho một biến thể sản phẩm
Fare (mục giá)	Một mức giá - giá gốc (không cha không con), hoặc một fare cha (OVERRIDE/SALE) cùng các fare con của nó
Rule (điều kiện)	Một điều kiện (attribute, operator, value) trên một fare con; tất cả quy tắc phải qua (AND)
Tax set	Bộ chứa thuế cho một biến thể (cấp dòng hàng) hoặc merchant (cấp đơn hàng)
Tax	Một khoản percentage/fixed/per-unit với độ ưu tiên, cửa sổ thời gian, các cờ inclusive/exclusive/lũy tiến
Tax type (danh mục)	Một danh mục (vd VAT) - toàn hệ thống hoặc theo merchant
Pricing snapshot	Kết quả bất biến - fare và thuế áp dụng theo từng dòng, cộng với tổng đơn hàng và sổ cái theo bên chịu

Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong pricing domain model.

9. Phụ thuộc & Giả định

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	Product (biến thể)	Fare, tax set và giá vốn đều khóa theo biến thể sản phẩm; việc tạo biến thể kích hoạt việc tự tạo.
02	Commerce / Merchant	Fare, thuế và bản ghi đều được giới hạn trong merchant của chính người dùng.
03	Sự kiện tạo biến thể sản phẩm	Yếu tố kích hoạt việc tự tạo một fare set + giá gốc.

Giả định

#	Giả định	Sai thì sao
01	Mỗi biến thể sản phẩm báo hiệu việc tạo của nó để fare set của nó có thể được tạo.	Biến thể được tạo mà không báo hiệu thì không có fare set tự động, và biến thể đó không định giá được.
02	Một dòng không có cấu hình thuế là chấp nhận được và được định giá với thuế bằng 0.	Nếu coi thiếu cấu hình thuế là lỗi thay vì hợp lệ, một dòng chưa gắn tax set sẽ chặn cả giao dịch thay vì chỉ tính thuế 0.
03	Luồng bán hàng gọi mô phỏng định giá khi thanh toán thay vì tự tính giá.	Luồng bán hàng tự tính giá sẽ lệch khỏi kết quả của bộ máy định giá và làm mất đi tính nhất quán, truy vết được của pricing snapshot.

10. Kế hoạch phát hành & Tiêu chí

Khía cạnh	Kế hoạch
Phase	P1 (Fares + Taxes) - xem danh mục feature URD
Rollout	Mọi merchant; không feature flag
Migration	Không (entity mới; fare set tự tạo khi tạo biến thể sản phẩm)
Tiêu chí phát hành	Giá khi thanh toán khớp với fare + thuế đã cấu hình cho các giỏ hàng lấy mẫu; snapshot tạo ra cho mỗi đơn; toán thuế inclusive/exclusive/lũy tiến đã kiểm chứng
Theo dõi	Tỉ lệ sai lệch định giá so với tính tay, độ phủ tạo fare theo từng merchant, lỗi tạo snapshot

Tham chiếu

• URD: Định giá - Fares & Fare Sets · Tax Computation
• Liên quan: Cost Tracking · Promotions & Rules · Yêu cầu xuyên suốt
• Module: Định giá - URD
• Developer: @nx/pricing · domain model · Fare System · Tax System

Rủi ro & Câu hỏi mở

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Thứ tự giảm giá khuyến mãi so với thuế cấp đơn hàng trong pipeline snapshot	Mở: xác định bộ tính giảm giá chạy trước hay sau thuế cấp đơn hàng khi cả hai được nối vào pipeline
02	Thiếu cấu hình thuế sẽ khiến một dòng không bị tính thuế	Một dòng không có tax set được định giá với thuế bằng 0 thay vì báo lỗi (FR-010)
03	Biến thể được tạo mà không có fare sẽ không định giá được	Tự tạo một fare set + giá gốc khi một biến thể xuất hiện (FR-002)
04	Việc tự tạo fare set chỉ được canh giữ bằng kiểm tra tồn tại ở tầng đồng bộ dữ liệu, không phải một ràng buộc cơ sở dữ liệu, nên hai sự kiện đồng bộ trùng thời điểm về lý thuyết có thể tạo hơn một fare set cho cùng một biến thể	Mở: thêm một ràng buộc duy nhất ở tầng cơ sở dữ liệu cho cặp biến thể + trạng thái kích hoạt
05	Tax set cấp merchant (order-level) đã mô hình hóa được nhưng thuế cấp đơn hàng chưa tính trong bất kỳ pipeline nào, nên một khoản thuế cấu hình ở cấp đó hiện chưa phản ánh vào tổng đơn hàng	Mở: nối thuế cấp đơn hàng vào cả hai pipeline định giá (FR-009)

Câu hỏi thường gặp

#	Câu hỏi	Trả lời
01	Bộ máy chọn fare thắng như thế nào?	Nó đánh giá các fare con theo quy tắc của chúng, rồi chỉ giữ lại tầng ưu tiên cao nhất trong số các fare hợp lệ (giá gốc cũng cạnh tranh ở mức ưu tiên riêng của nó). Trong tầng đó, một fare OVERRIDE luôn thắng một fare SALE; nếu không có OVERRIDE, fare hợp lệ rẻ nhất trong tầng thắng; nếu không có fare con nào hợp lệ, giá gốc được dùng.
02	OVERRIDE và SALE khác nhau ở đâu?	Cả hai đều là chiến lược của một fare cha. OVERRIDE luôn thắng khi hợp lệ, bất kể giá cao hay thấp hơn fare khác cùng tầng. SALE cạnh tranh như một mức giảm - trong số các fare SALE hợp lệ cùng tầng, giá thấp nhất thắng.
03	Điều gì xảy ra nếu một biến thể không cấu hình thuế?	Dòng đó được định giá với thuế bằng 0 - không bao giờ bị chặn, chỉ là không tính thuế.
04	Thuế inclusive vs exclusive - khác nhau ở đâu?	Thuế exclusive được cộng thêm lên trên giá; thuế inclusive được tính ngược ra khỏi giá, nên một thuế inclusive không bao giờ làm tăng tổng.
05	Thuế cấp đơn hàng (order-level) có được tính không?	Chưa - tax set cấp merchant đã mô hình hóa được, nhưng phần thuế đó chưa được tính trong pipeline định giá. Chỉ thuế cấp dòng hàng (item-level) hiện được áp.
06	Bộ máy này có áp khuyến mãi khi thanh toán không?	Chưa - khuyến mãi có thể được cấu hình, nhưng bộ tính giảm giá chưa được nối vào pipeline định giá trong increment này.