PRD: Mô phỏng định giá & xem trước giá đơn hàng

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

Mô phỏng định giá & xem trước giá đơn hàng là gì

Thu ngân dựng xong giỏ hàng thì luồng bán hàng gọi một lần định giá cho cả giỏ, tối đa 100 dòng, và không đơn nào được lưu, không tồn kho nào bị đụng. Kết quả trả về là một ảnh chụp định giá (Pricing Snapshot): một ảnh chụp cho cả đơn, cộng một ảnh chụp cho từng dòng hàng. Mỗi ảnh chụp mang đầy đủ quyết định đã áp lên dòng đó - giá nào, thuế nào, giảm giá nào, phí nào - và mỗi quyết định được sao chép ngay tại thời điểm tính, nên sau này có đổi tên hay tắt một quy tắc thì hóa đơn cũ vẫn đọc đúng như hôm bán.

Ảnh chụp còn ghi rõ ai gánh khoản nào: người mua trả bao nhiêu, người bán chịu bao nhiêu, phần nào thuộc nhà nước, nền tảng hay nhà cung cấp. Bên đọc lấy thẳng con số, không phải cộng lại. Trước khi thanh toán, khách được xem trước giá qua một thao tác chỉ-đọc: đơn được định giá lại và trả về ảnh chụp, còn trạng thái đơn thì không đổi. Lúc thanh toán, đơn được định giá bằng chính bộ máy đó, và ảnh chụp được lưu kèm đơn để về sau còn kiểm toán, khai thuế và xử lý tranh chấp.

Vì sao cần một bề mặt mô phỏng

Bộ máy fare và thuế quyết định fare thắng cho từng biến thể và tính thuế lũy tiến. Nó trả lời câu hỏi "giá ngay bây giờ của một biến thể là bao nhiêu". Nhưng luồng bán hàng cần định giá cả một giỏ hàng cùng lúc, cho khách thấy giá đó trước khi đơn được cam kết, và về sau giữ lại một bản ghi kiểm toán được về cách từng dòng đã được định giá.

Không có bề mặt mô phỏng, luồng bán hàng sẽ phải gọi fare và thuế từng dòng một, tự ráp lại tổng đơn, và tự cài lại quy tắc thuế đã gộp hay chưa gộp. Tệ hơn, sẽ không có bản ghi quyết định định giá nào bất biến và tự chứa để đính vào đơn cho việc khai thuế, ghi sổ và xử lý tranh chấp. Một merchant cũng không thể trưng ra con số "đây là số bạn sẽ trả" đáng tin, nếu giá chỉ được tính đúng vào lúc cam kết đơn.

Bước tăng trưởng này lấp khoảng trống đó bằng một bộ máy định giá không trạng thái trả về ảnh chụp định giá, cùng một xem trước chỉ-đọc mà luồng bán hàng dùng - không lưu đơn, không đổi trạng thái, không tác động tồn kho.

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

Bước	Việc xảy ra	Kết quả
Thu ngân dựng một giỏ ba dòng	Luồng bán hàng gọi xem trước giá đơn hàng	Đơn được định giá lại theo kiểu chỉ-đọc, trả về ảnh chụp định giá - mỗi dòng kèm giá, thuế, sổ cái theo bên - cộng tổng đơn, không lưu gì cả
Khách xem giá trước khi trả tiền	Đến lúc thanh toán	Đơn được định giá lại bằng chính bộ máy đó và ảnh chụp được lưu kèm đơn
Một dòng trong giỏ có biến thể chưa có fare set kích hoạt	Định giá dòng đó	Lý do từ chối thật từ thượng nguồn được phơi ra, thay vì một lỗi chung chung

Chỗ dễ sai nhất

Xem trước không lưu gì, kể cả khi trả về đúng ảnh chụp lúc thanh toán

Xem trước giá đơn hàng và mô phỏng định giá là phép đọc thuần. Chúng luôn định giá LẠI từ đầu và trả về một ảnh chụp mới - không bao giờ đọc lại một ảnh chụp đã lưu trước đó, và không bao giờ ghi gì vào đơn. Chỉ có bước thanh toán mới thật sự lưu ảnh chụp kèm đơn.

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

Mục tiêu

• Một bộ máy định giá giỏ hàng không trạng thái (1-100 dòng) không bao giờ lưu đơn hay chạm vào tồn kho.
• Một ảnh chụp định giá bất biến - một ảnh chụp đơn cộng một ảnh chụp cho từng dòng - mang mọi quyết định đã áp dưới dạng tự chứa, để hiển thị lịch sử sống sót qua các lần sửa quy tắc về sau.
• Một sổ cái theo bên (mua / bán / nền tảng / nhà cung cấp / nhà nước) trên ảnh chụp, để bên đọc lấy tổng trực tiếp thay vì tổng hợp lại.
• Một xem trước giá đơn hàng chỉ-đọc mà luồng bán hàng gọi để cho thấy giá trước khi thanh toán.
• Lúc thanh toán, đơn được định giá bằng chính bộ máy đó và ảnh chụp được lưu kèm đơn.

Loại trừ

• Lưu trữ đơn hàng, đổi trạng thái, phát hành hóa đơn hay thay đổi tồn kho - xem trước là chỉ-đọc; việc lưu thuộc về các bên gọi ở bán hàng.
• Áp khuyến mãi và giảm giá trong luồng tính - bộ tính giảm giá chưa được đấu nối (URD-PROMO-006); ảnh chụp chừa sẵn ô quyết định giảm giá và phí nhưng chưa điền.
• Quy đổi đa tiền tệ - một dòng mang mã tiền tệ, nhưng bộ máy không quy đổi (URD-CON).
• Bản thân các quy tắc chọn fare và tính thuế - đặc tả trong PRD-FARE-001.

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

Thước đo	Mục tiêu / tín hiệu
Không tác động phụ	Một lần xem trước hay mô phỏng không bao giờ lưu đơn, đổi trạng thái hay thay đổi tồn kho
Toàn vẹn tổng	tổng đơn = Σ tổng dòng đúng ở độ chính xác 4 chữ số thập phân; thuế đã gộp không bao giờ làm tăng tổng
Khả năng kiểm toán	Mọi quyết định đã áp trong ảnh chụp hiển thị đúng kể cả sau khi quy tắc nguồn bị đổi tên hay ngừng kích hoạt
Truy vết dòng	Mọi dòng đã định giá ánh xạ ngược về đúng dòng yêu cầu của nó qua id do bên gọi cấp
Trung thực khi từ chối	Một dòng bị từ chối từ thượng nguồn hiện ra đúng lý do thật, không phải lỗi chung chung

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Thu ngân	Thấy giá giỏ hàng đáng tin trước khi cam kết đơn
Khách hàng	Được cho thấy số mình sẽ trả, theo từng dòng, trước khi thanh toán
Chủ / Quản lý	Tin rằng mỗi đơn giữ một bản ghi kiểm toán được về cách nó đã được định giá
Luồng bán hàng	Định giá đơn theo kiểu chỉ-đọc để xem trước, và định giá rồi chụp lại nó lúc thanh toán

Kịch bản cốt lõi: thu ngân dựng một giỏ ba dòng. Luồng bán hàng gọi xem trước giá đơn hàng, thao tác này định giá lại đơn đang có theo kiểu chỉ-đọc và trả về ảnh chụp định giá - mỗi dòng kèm giá, thuế và sổ cái theo bên, cộng tổng đơn - mà không lưu gì cả. Khách nhìn thấy số mình sẽ trả. Đến lúc thanh toán, đơn được định giá lại bằng chính bộ máy đó và ảnh chụp được lưu kèm đơn. Nếu một dòng có biến thể chưa có fare set kích hoạt, lý do từ chối thật từ thượng nguồn được phơi ra thay vì một lỗi chung chung.

4. User Stories

#	Là một	Tôi muốn	Để
01	thu ngân	định giá cả giỏ trong một lệnh và nhận tổng theo dòng lẫn theo đơn	không bao giờ phải tự cộng tổng
02	khách hàng	được cho thấy số mình sẽ trả trước khi cam kết	không bất ngờ lúc thanh toán
03	chủ merchant	mỗi đơn giữ một bản ghi tự chứa về cách từng dòng đã được định giá	bảo vệ được con số rất lâu sau khi quy tắc đã đổi
04	chủ merchant	thấy rõ ai gánh khoản nào	việc đọc thuế và ghi sổ không phải tính lại từ đầu
05	luồng bán hàng	xem trước là chỉ-đọc	việc trưng giá không bao giờ làm thay đổi đơn
06	luồng bán hàng	một dòng bị từ chối hiện đúng lý do thật	thu ngân biết phải sửa gì

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

#	Yêu cầu	Trạng thái	URD ref
FR-001	Định giá giỏ hàng không trạng thái, từ 1 đến 100 dòng: không lưu đơn và không thay đổi tồn kho.	✅	URD-SIM-001
FR-002	Kết quả định giá trả về đủ số liệu để đối chiếu tay. • Theo từng dòng: giá gốc và đơn giá, fare đã chọn cùng các quy tắc đã áp, các khoản thuế đã áp, subtotal / discount / tax / total. • Theo đơn hàng: tổng đơn và một mốc thời gian tính. • Thuế đã gộp trong giá và thuế cộng thêm được xử lý đúng theo từng loại.	✅	URD-SIM-002 · URD-SIM-004
FR-003	Một id dòng do bên gọi cấp được trả lại nguyên vẹn và dùng làm khóa kết quả, để ánh xạ dòng không nhập nhằng.	✅	URD-SIM-003
FR-004	Ảnh chụp định giá gồm một ảnh chụp cho đơn và một ảnh chụp cho từng dòng. • Ảnh chụp mang mọi quyết định đã áp: giá, thuế, giảm giá, phí. • Mỗi quyết định được sao chép tại thời điểm tính, không tham chiếu ngược về cấu hình gốc. • Ảnh chụp bất biến sau khi đã tính.	🔶	URD-SIM-005 · URD-SIM-006
FR-005	Tổng trong ảnh chụp tách theo bên chịu. • Theo từng dòng: số tiền người mua phải trả, cùng sổ cái theo từng bên. • Theo đơn hàng: subtotal, số tiền người mua phải trả, sổ cái theo từng bên, và nghĩa vụ của người bán.	✅	URD-SIM-007
FR-006	Một lần mô phỏng khai báo một hướng giao dịch (mua / bán) và một tiền tệ đơn (ISO 4217, mặc định VND).	✅	URD-SIM-008
FR-007	Xem trước giá của một đơn đang có là thao tác chỉ-đọc. • Đơn được định giá lại và trả về ảnh chụp định giá. • Trạng thái và dữ liệu đã lưu của đơn không đổi. • Định giá một giỏ rỗng bị từ chối.	🔶	URD-SIM-009 · URD-SIM-010
FR-008	Lúc thanh toán, đơn được định giá bằng bộ máy định giá và ảnh chụp được lưu kèm đơn. • Ảnh chụp đơn và các ảnh chụp dòng được lưu cùng đơn. • Thuế lưu theo từng dòng lấy từ các quyết định thuế trong ảnh chụp.	🔶	URD-SIM-011 · URD-SIM-012
FR-009	Mỗi dòng mang theo một ngữ cảnh định giá để quy tắc fare đánh giá. • Số lượng và thời điểm tính. • Ngày, giờ, thứ trong tuần. • Các id biến thể cùng xuất hiện trong giỏ. • Một khung dịch vụ được suy ra từ thời điểm tính.	✅	URD-SIM-013
FR-010	Mô phỏng chạy dưới một bộ ràng buộc cố định. • Một từ chối từ thượng nguồn (ví dụ: biến thể không có fare set đang kích hoạt) được phơi ra với trạng thái và lý do thật, không nuốt lỗi. • Mô phỏng yêu cầu xác thực và giới hạn trong merchant của chính người dùng. • Mọi phép tính tiền dùng độ chính xác 4 chữ số thập phân.	🔶	URD-SIM-014 · URD-SIM-015

5.1 Tiêu chí nghiệm thu

• Gọi mô phỏng định giá với 1 đến 100 dòng → mỗi dòng nhận đủ kết quả; không đơn nào được tạo, tồn kho không đổi.
• Định giá một giỏ có một sản phẩm chịu thuế đã gộp và một sản phẩm chịu thuế cộng thêm → thuế đã gộp nằm sẵn trong giá và không làm tăng tổng; thuế cộng thêm được cộng lên trên; kết quả trả đủ giá gốc, đơn giá, fare đã chọn, thuế đã áp, subtotal/discount/tax/total theo dòng, cùng tổng đơn và mốc thời gian tính.
• Gửi hai dòng cùng một biến thể nhưng saleOrderItemId khác nhau → kết quả trả về hai mục tách biệt, khóa đúng theo id đã gửi.
• Gọi mô phỏng định giá → nhận một ảnh chụp đơn cộng N ảnh chụp dòng; mỗi dòng mang một quyết định giá và các quyết định thuế của nó, mỗi quyết định tự chứa nhãn, cơ sở, giá trị và khoản tại thời điểm tính.
• Đổi tên một loại thuế rồi mở lại đơn cũ → ảnh chụp vẫn hiển thị đúng nhãn và số tiền của lúc bán.
• Xem một ảnh chụp dòng → thấy số tiền người mua phải trả và sổ cái theo bên (mua/bán/nền tảng/nhà cung cấp/nhà nước); xem ảnh chụp đơn → thấy subtotal, tiền người mua trả, sổ cái theo bên và nghĩa vụ người bán cuộn đúng từ các dòng lên.
• Gọi mô phỏng không truyền currency → mặc định VND; truyền direction PURCHASE → ảnh chụp phản ánh đúng hướng giao dịch đã khai.
• Gọi xem trước giá cho một đơn 3 dòng đang có → nhận ảnh chụp định giá, đơn không đổi trạng thái, không có gì được lưu; gọi xem trước hoặc mô phỏng cho giỏ 0 dòng → bị từ chối.
• Thanh toán một đơn hợp lệ → đơn được định giá và ảnh chụp được lưu kèm đơn; xem thuế đã lưu theo dòng sau thanh toán → thấy đúng các quyết định thuế của ảnh chụp.
• Định giá một dòng có cấu hình mua kèm → ngữ cảnh mang đúng id biến thể dẫn dắt của chính dòng đó để quy tắc fare đánh giá; định giá một dòng có khai serviceTimeFrom/serviceTimeTo → ngữ cảnh trả về đúng giờ dịch vụ, ngày, thứ và thời lượng suy ra từ khoảng thời gian đã khai.
• Định giá một biến thể không có fare set nào được kích hoạt → nhận lỗi thật nói rõ lý do thay vì lỗi chung chung; gọi mô phỏng khi chưa đăng nhập hoặc thiếu header merchant → bị từ chối.
• Định giá một dòng cân ký 1,235 kg → số lượng vào phép tính đúng 1,2350, không bị làm tròn thành 1,24.

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

Khía cạnh	Yêu cầu
Không trạng thái	Mô phỏng và xem trước là phép đọc thuần - không lưu đơn, không đổi trạng thái, không tác động tồn kho
Bất biến	Một ảnh chụp định giá là bất biến sau khi đã tính (URD-CON-004); một chỉnh sửa sinh ra ảnh chụp mới, không bao giờ sửa ảnh chụp cũ
Tự chứa	Mỗi quyết định đã áp sao chép nhãn, cơ sở, giá trị và khoản tại thời điểm tính, để hiển thị đúng kể cả sau khi quy tắc nguồn đổi
Đa thuê & phân quyền	Mô phỏng yêu cầu xác thực và giới hạn công việc trong merchant của chính người dùng; kiểm soát bởi quyền mô phỏng định giá
Độ chính xác	Mọi phép tính tiền và số lượng dùng độ chính xác 4 chữ số thập phân, khớp với cột dữ liệu numeric(15,4) (C-04); thuế đã gộp không bao giờ làm tăng tổng
i18n	Nhãn fare và thuế hướng người dùng là song ngữ

7. UX & Luồng

Bề mặt chính: xem trước giá hướng khách trong client bán hàng (tổng theo dòng và theo đơn), và - sau thanh toán - ảnh chụp định giá đính vào đơn cùng các dòng của nó, phục vụ kiểm toán, khai thuế và đọc sổ.

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

Khái niệm	Vai trò
Ảnh chụp định giá đơn	Ảnh chụp cấp đơn: hướng giao dịch, tiền tệ, các quyết định phạm vi đơn, và tổng cuộn lên (subtotal, tiền người mua trả, sổ cái theo bên, nghĩa vụ người bán)
Ảnh chụp định giá dòng	Ảnh chụp một dòng: số lượng, ngữ cảnh đã trộn, các quyết định đã áp của nó, và tổng (tiền người mua trả + sổ cái theo bên)
Quyết định đã áp	Một mục giá / thuế / giảm giá / phí tự chứa - nhãn, cơ sở, giá trị, khoản, bên gánh, tính đã-gộp, độ ưu tiên, tính lũy tiến - sao chép tại thời điểm tính

Chỉ mang tính khái niệm - schema ảnh chụp đầy đủ và các bất biến nằm trong mô hình miền định giá. Ảnh chụp được thiết kế để các bên gọi ở bán hàng lưu lại trên đơn và các dòng của nó.

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

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	FARE · TAX Bộ máy fare & thuế	Mô phỏng dẫn dắt việc chọn fare và tính thuế; đặc tả tại PRD-FARE-001.
02	Đơn hàng	Xem trước định giá lại một đơn đang có; thanh toán lưu ảnh chụp.
03	Nguyên thủy định giá chung	Độ chính xác tiền chung, hình dạng ảnh chụp thuế, và giới hạn theo merchant.

Giả định

#	Giả định	Sai thì sao
01	Mỗi biến thể được định giá đều có một fare set kích hoạt (tự tạo khi tạo biến thể); thiếu fare set là một từ chối từ thượng nguồn và được phơi ra đúng như vậy.	Một biến thể không có fare set kích hoạt sẽ không định giá được; nếu lỗi đó không phơi ra đúng lý do, thu ngân chỉ thấy một lỗi chung chung và không biết phải sửa gì.
02	Bộ tính giảm giá và khuyến mãi chưa được đấu nối (URD-PROMO-006); ảnh chụp chừa sẵn nhưng chưa điền quyết định giảm giá và phí.	Một khuyến mãi đã cấu hình xong sẽ không tự động xuất hiện trong ảnh chụp cho tới khi bộ tính được nối vào luồng mô phỏng.
03	Các bên gọi ở bán hàng sở hữu mọi việc lưu và đổi trạng thái; bộ máy định giá giữ không trạng thái.	Nếu bộ máy định giá tự lưu hoặc tự đổi trạng thái đơn, ranh giới không trạng thái bị phá vỡ và xem trước không còn là phép đọc thuần nữa.

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

Khía cạnh	Kế hoạch
Phase	P2 - xem danh mục feature URD, bên cạnh COST
Rollout	Mọi merchant; không feature flag
Di trú	Không - mô phỏng và xem trước là phép đọc không trạng thái trên bộ máy fare/thuế đang có
Tiêu chí ra mắt	Mô phỏng trả về ảnh chụp đơn cộng ảnh chụp theo dòng, bất biến, kèm sổ cái theo bên; thuế đã gộp và thuế cộng thêm tính đúng; xem trước là chỉ-đọc và từ chối giỏ rỗng; thanh toán lưu ảnh chụp kèm đơn; từ chối từ thượng nguồn phơi ra trạng thái thật; mọi phép tính đúng 4 chữ số thập phân
Giám sát	Độ trễ và tỉ lệ lỗi của mô phỏng, số lần từ chối từ thượng nguồn (ví dụ: thiếu fare set)

Tham chiếu

• URD: Định giá - SIM · FARE · TAX
• PRD cùng nhóm: Bộ máy định giá Fare & Thuế · Khuyến mãi, phương thức & quy tắc phân khúc
• Module: Định giá - URD
• Kỹ thuật: @nx/pricing · mô hình miền
• Bên tiêu thụ: Đơn hàng / Bán hàng

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

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Một ảnh chụp có thể lệch khỏi quy tắc nó trích, nếu quy tắc đổi về sau	Mỗi quyết định đã áp sao chép nhãn, cơ sở, giá trị và khoản tại thời điểm tính - ảnh chụp tự chứa
02	Thuế đã gộp bị cộng nhầm vào tổng	Thuế đã gộp được tính ngược ra từ giá và không bao giờ làm tăng tổng (C-03)
03	Lẫn lộn dòng khi ánh xạ kết quả ngược về	Id dòng do bên gọi cấp được trả lại và dùng làm khóa kết quả
04	Một biến thể không có fare set kích hoạt lỗi mờ ám	Trạng thái và lý do thật từ thượng nguồn được lan truyền thay vì một lỗi chung chung
05	Đường định giá dùng lúc thanh toán chưa khớp đặc tả này ở ba điểm: độ chính xác thập phân, thuế tính theo đơn vị, và việc phân biệt bên chịu khoản thuế	Đã ghi thành hạng mục nội bộ; đường thanh toán sẽ dùng chung một cài đặt với mô phỏng
06	Thuế cấp đơn hàng chưa được cộng vào ảnh chụp	Đã ghi thành hạng mục nội bộ; ảnh chụp đơn hiện chỉ mang các quyết định cấp dòng

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

#	Câu hỏi	Trả lời
01	Xem trước một giá có làm thay đổi đơn không?	Không. Xem trước là một phép đọc thuần. Nó định giá lại đơn đang có và trả về ảnh chụp định giá, không lưu gì, không đổi trạng thái, không chạm tồn kho.
02	Ảnh chụp định giá là gì và để làm gì?	Đó là kết quả định giá được đóng băng tại thời điểm tính: một ảnh chụp cho đơn, một ảnh chụp cho mỗi dòng, mỗi quyết định giá và thuế đều tự chứa, kèm sổ cái ghi rõ bên nào gánh khoản nào. Nó vừa dùng để hiển thị ngay cho khách, vừa được lưu trên đơn để về sau kiểm toán và khai thuế.
03	Một ảnh chụp có còn đọc đúng nếu tôi đổi tên một loại thuế sau này không?	Có. Mỗi quyết định đã áp sao chép nhãn, cơ sở, giá trị và khoản của nó ngay tại thời điểm tính, nên hóa đơn cũ không bị ảnh hưởng bởi các lần sửa quy tắc về sau.
04	Vì sao tiền lại tính tới 4 chữ số thập phân?	Vì cột dữ liệu tiền và số lượng là numeric(15,4). Bán hàng cân ký cần đúng 1,2350 kg chứ không phải 1,24 kg; làm tròn sớm là sai tiền thật trên từng đơn.
05	Khuyến mãi có được áp ở đây không?	Chưa. Bộ tính giảm giá chưa được đấu nối vào luồng tính (URD-PROMO-006). Ảnh chụp đã chừa sẵn ô quyết định giảm giá và phí cho lúc nó được đấu nối.