PRD: Pricing simulation & order pricing preview

Module	Pricing	PRD ID	PRD-SIM-001
Status	Ready to dev	FEAT	SIM · BANA-1434
Epic	—	Plane	BANA-1550
Date	2026-06-15	Version	v1.0
Packages	@nx/pricing · @nx/sale	URD	SIM
Surface	Backend
Owner	Phát Nguyễn

What pricing simulation & order pricing preview are

Once the cashier has built the basket, the sale flow prices the whole basket in one call, up to 100 lines, and no order is persisted and no stock is touched. What comes back is a pricing snapshot: one snapshot for the order, plus one snapshot for each line. Each snapshot carries every decision applied to that line - which price, which taxes, which discounts, which fees - and each decision is copied at compute time, so renaming or deactivating a rule later leaves an old receipt reading exactly as it did on the day of sale.

The snapshot also records who bears what: how much the buyer pays, how much the seller absorbs, and which portions belong to the government, the platform, or a supplier. Readers take the figure straight from it instead of re-adding it. Before checkout, the customer is shown the price through a read-only action: the order is re-priced and the snapshot is returned, and the order's status does not change. At checkout the order is priced by that same engine, and the snapshot is persisted alongside the order for later audit, tax declaration, and dispute resolution.

Why a simulation surface is needed

The fare and tax engine decides the winning fare per variant and computes compound taxes. It answers "what is this one variant's price right now". But the sale flow needs to price a whole basket at once, show that price to a customer before any order is committed, and later keep an auditable record of exactly how each line was priced.

Without a simulation surface the sale flow would have to call the fare and tax primitives line by line, re-assemble order totals itself, and re-implement the inclusive/exclusive tax rules. Worse, there would be no immutable, self-contained record of the pricing decision to attach to the order for tax declaration, ledger, and dispute resolution. A merchant also cannot show a trustworthy "this is what you will pay" figure if pricing is only computed at the moment of commit.

This increment closes that gap with a stateless pricing engine that returns a pricing snapshot, plus the read-only preview the sale flow consumes - with no order persistence, no status change, and no stock side effects.

One example, start to finish

Step	What happens	Result
A cashier builds a basket of three lines	The sale flow calls the order-pricing preview	The order is re-priced read-only, returning a pricing snapshot - each line with price, taxes, per-party ledger - plus the order total, with nothing persisted
The customer sees the price before paying	Checkout happens	The order is re-priced by that same engine and the snapshot is persisted alongside it
A line's variant has no active fare set	The line is priced	The real upstream rejection reason is surfaced, rather than a generic failure

The easiest thing to get wrong

A preview persists nothing, even when it returns exactly what checkout would

The order-pricing preview and the pricing simulation are pure reads. They always price FROM SCRATCH and return a fresh snapshot - never reading back a previously persisted snapshot, and never writing anything to the order. Only checkout actually persists a snapshot alongside the order.

1. Goals & Non-Goals

Goals

• A stateless basket-pricing engine (1-100 lines) that never persists an order or touches stock.
• An immutable pricing snapshot - an order snapshot plus one line snapshot each - carrying every applied decision self-contained, so historical rendering survives later rule edits.
• A per-party ledger (buyer / seller / platform / supplier / government) on the snapshot so readers consume totals directly instead of re-aggregating.
• A read-only order-pricing preview the sale flow calls to show a price before checkout.
• At checkout, the order is priced by that same engine and its snapshot is persisted alongside the order.

Non-Goals

• Order persistence, status changes, invoice issuance, or stock mutation - the preview is read-only; persistence stays in the sale callers.
• Applying promotions / discounts in the pipeline - the discount calculator is not yet wired (URD-PROMO-006); the snapshot reserves discount and fee decision slots but does not yet populate them.
• Multi-currency conversion - a line carries a currency code, but the engine does not convert (URD-CON).
• The fare-selection and tax-computation rules themselves - specified in PRD-FARE-001.

2. Success Metrics

Metric	Target / signal
No side effects	A preview or simulation never persists an order, changes status, or mutates stock
Total integrity	order total = Σ line totals holds at 4-decimal precision; inclusive taxes never increase the total
Auditability	Every applied decision in the snapshot renders correctly even after its source rule is renamed or deactivated
Line traceability	Every priced line maps back to its request line by the caller-supplied id
Honest rejection	A line rejected upstream surfaces its real reason, not a generic failure

3. Personas & Scenarios

Persona	Goal in this feature
Cashier	See a trustworthy basket price before committing the order
Customer	Be shown what they will pay, line by line, ahead of checkout
Owner / Manager	Trust that each order keeps an auditable record of how it was priced
Sale flow	Price an order read-only for preview, and price then snapshot it at checkout

Core scenario: a cashier builds a basket of three lines. The sale flow calls the order-pricing preview, which re-prices the existing order read-only and returns the pricing snapshot - each line carrying its price, taxes, and per-party ledger, plus the order total - with nothing persisted. The customer sees what they will pay. At checkout the order is re-priced by that same engine and the snapshot is persisted alongside it. If a line's variant has no active fare set, the real upstream rejection reason is surfaced rather than a generic failure.

4. User Stories

#	As a	I want	So that
01	cashier	to price the whole basket in one call and get per-line and order totals	I never assemble totals by hand
02	customer	to be shown what I will pay before I commit	there are no surprises at checkout
03	owner	every order to keep a self-contained record of how each line was priced	I can defend a figure long after the rule changed
04	owner	to see clearly who bears each amount	tax and ledger reads need no re-computation
05	sale flow	the preview to be read-only	showing a price never mutates the order
06	sale flow	a rejected line to surface its real reason	the cashier knows what to fix

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Stateless basket pricing of 1 to 100 lines: no order is persisted and no stock is mutated.	✅	URD-SIM-001
FR-002	The pricing result returns enough figures to reconcile by hand. • Per line: base and unit price, the selected fare plus the rules it applied, the taxes applied, subtotal / discount / tax / total. • Per order: order totals and a compute timestamp. • Inclusive and exclusive taxes are each treated correctly.	✅	URD-SIM-002 · URD-SIM-004
FR-003	A caller-supplied line id is echoed back untouched and used as the result key, so lines map back unambiguously.	✅	URD-SIM-003
FR-004	The pricing snapshot is one snapshot for the order plus one per line. • A snapshot carries every applied decision: price, tax, discount, fee. • Each decision is copied at compute time rather than referencing the source configuration. • A snapshot is immutable once computed.	🔶	URD-SIM-005 · URD-SIM-006
FR-005	Snapshot totals are split by the party that bears them. • Per line: the buyer-payable amount plus a per-party ledger. • Per order: subtotal, buyer-payable, per-party ledger, and seller liability.	✅	URD-SIM-007
FR-006	A simulation declares a transaction direction (sale / purchase) and one order currency (ISO 4217, default VND).	✅	URD-SIM-008
FR-007	Previewing the price of an existing order is a read-only action. • The order is re-priced and the pricing snapshot is returned. • The order's status and stored data are unchanged. • Pricing an empty cart is refused.	🔶	URD-SIM-009 · URD-SIM-010
FR-008	At checkout the order is priced by the pricing engine and the snapshot is persisted alongside it. • The order snapshot and its line snapshots are stored with the order. • The per-line taxes persisted come from the snapshot's tax decisions.	🔶	URD-SIM-011 · URD-SIM-012
FR-009	Every line carries a pricing context for fare rules to evaluate. • Quantity and compute time. • Date, time of day, and day of week. • The variant ids co-occurring in the basket. • A service window derived from the compute time.	✅	URD-SIM-013
FR-010	The simulation runs under one fixed set of constraints. • An upstream rejection (for example, a variant with no active fare set) surfaces with its real status and reason rather than being swallowed. • The simulation requires authentication and is confined to the user's own merchant. • All money math is precise to 4 decimals.	🔶	URD-SIM-014 · URD-SIM-015

5.1 Acceptance Criteria

• Call the pricing simulation with 1 to 100 lines → every line returns a full result; no order is created, stock is unchanged.
• Price a basket with one inclusive-tax product and one exclusive-tax product → the inclusive tax is already embedded in the price and does not add to the total; the exclusive tax adds on top; the result returns base price, unit price, selected fare, applied taxes, and per-line subtotal/discount/tax/total, plus order totals and a compute timestamp.
• Submit two lines for the same variant with different saleOrderItemId values → the result returns two separate entries, correctly keyed by the supplied ids.
• Call the pricing simulation → get back one order snapshot plus N line snapshots; each line carries one price decision and its own tax decisions, each self-contained with label, base, value, and amount at compute time.
• Rename a tax type, then reopen an old order → the snapshot still shows the label and amount as of the day of sale.
• Look at a line snapshot → see the buyer-payable amount and a per-party ledger (buyer/seller/platform/supplier/government); look at the order snapshot → see subtotal, buyer-payable, per-party ledger, and seller liability rolled up correctly from the lines.
• Call the simulation without a currency → defaults to VND; pass direction PURCHASE → the snapshot reflects the declared direction.
• Call the price preview for an existing 3-line order → get the pricing snapshot, with the order's status unchanged and nothing persisted; call the preview or a simulation with an empty cart → refused.
• Check out a valid order → the order is priced and the snapshot is persisted alongside it; look at the persisted per-line taxes after checkout → see exactly the snapshot's tax decisions.
• Price a line with a buy-with configuration → the context carries that line's own lead variant id for fare rules to evaluate; price a line with serviceTimeFrom/serviceTimeTo set → the context returns the correct service time, date, day of week, and duration derived from that window.
• Price a variant with no active fare set → get a real error stating the reason instead of a generic failure; call a simulation without authentication or without the merchant header → refused.
• Price a weighed line of 1.235 kg → the quantity enters the calculation as exactly 1.2350, not rounded to 1.24.

6. Non-Functional Requirements

Area	Requirement
Statelessness	Simulation and preview are pure reads - no order persistence, status change, or stock side effect
Immutability	A pricing snapshot is immutable once computed (URD-CON-004); a correction computes a new snapshot, never edits the old one
Self-containment	Each applied decision copies its label, base, value, and amount at compute time, so it renders correctly even after the source rule changes
Tenancy & authz	The simulation requires authentication and confines work to the user's own merchant; gated by a pricing-simulate permission
Precision	All money and quantity math uses 4-decimal precision, matching the numeric(15,4) data columns (C-04); inclusive taxes never increase the total
i18n	User-facing fare and tax labels are bilingual

7. UX & Flows

Key surfaces: the customer-facing price preview in the sale client (per-line and order totals), and - behind checkout - the pricing snapshot attached to the order and its items for audit, tax declaration, and ledger reads.

8. Data & Domain

Concept	Role
Order pricing snapshot	Order-level snapshot: direction, currency, order-scope decisions, and rolled-up totals (subtotal, buyer-payable, per-party ledger, seller liability)
Line pricing snapshot	One line's snapshot: quantity, merged context, its applied decisions, and totals (buyer-payable + per-party ledger)
Applied decision	A self-contained price / tax / discount / fee entry - label, base, value, amount, bearer, inclusivity, priority, compounding - copied at compute time

Conceptual only - the full snapshot schema and invariants live in the pricing domain model. The snapshot is designed to be persisted on the order and its items by the sale callers.

9. Dependencies & Assumptions

Depends on

#	Feature	Dependency
01	FARE · TAX Fare & tax engine	The simulation drives fare selection and tax computation; specified in PRD-FARE-001.
02	Sale orders	The preview re-prices an existing order; checkout persists the snapshot.
03	Shared pricing primitives	Common money precision, tax-snapshot shape, and merchant scoping.

Assumptions

#	Assumption	If wrong
01	Each priced variant has an activated fare set (auto-created on variant creation); a missing fare set is an upstream rejection, surfaced as such.	A variant with no activated fare set cannot be priced; if that failure is not surfaced with its real reason, the cashier only sees a generic error and does not know what to fix.
02	The discount/promotion calculator is not yet wired (URD-PROMO-006); the snapshot reserves but does not populate discount and fee decisions.	A fully configured promotion will not automatically show up in the snapshot until the calculator is wired into the simulation pipeline.
03	The sale callers own all persistence and status changes; the pricing engine stays stateless.	If the pricing engine persisted or changed order status itself, the stateless boundary would break and the preview would no longer be a pure read.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P2 - see URD feature catalog, alongside COST
Rollout	All merchants; no feature flag
Migration	None - simulation and preview are stateless reads over the existing fare/tax engine
Launch criteria	The simulation returns an immutable order + per-line snapshot with a per-party ledger; inclusive and exclusive taxes compute correctly; the preview is read-only and refuses an empty cart; checkout persists the snapshot with the order; upstream rejections surface their real status; all math is exact to 4 decimals
Monitoring	Simulation latency and error rate, upstream-rejection counts (e.g. missing fare set)

References

• URD: Pricing - SIM · FARE · TAX
• Sibling PRDs: Fare & Tax Pricing Engine · Promotions, methods & segment rules
• Module: Pricing - URD
• Developer: @nx/pricing · domain model
• Consumer: Orders / Sale

Risks & Open Questions

#	Risk / question	Mitigation / status
01	A snapshot could drift from the rule it cited if the rule later changes	Each applied decision copies label, base, value, and amount at compute time - the snapshot is self-contained
02	Inclusive taxes mis-counted into the total	Inclusive taxes are back-calculated from the price and never increase the total (C-03)
03	Lines confused when matching the response back	The caller-supplied line id is echoed and used as the result key
04	A variant without an active fare set fails opaquely	The real upstream status and reason is propagated instead of a generic failure
05	The pricing path used at checkout does not yet match this specification on three points: decimal precision, per-unit tax, and distinguishing which party bears a tax	Tracked as internal work items; the checkout path will share one implementation with the simulation
06	Order-level taxes are not yet added to the snapshot	Tracked as an internal work item; the order snapshot currently carries line-level decisions only

FAQ

#	Question	Answer
01	Does previewing a price change the order?	No. The preview is a pure read. It re-prices an existing order and returns the pricing snapshot without persisting anything, changing status, or touching stock.
02	What is the pricing snapshot, and what is it for?	It is the pricing result frozen at compute time: one snapshot for the order, one for each line, every price and tax decision self-contained, with a ledger recording which party bears which amount. It serves both the immediate display to the customer and the record persisted on the order for later audit and tax declaration.
03	Will a snapshot still read correctly if I rename a tax later?	Yes. Each applied decision copies its label, base, value, and amount at compute time, so an old receipt is unaffected by later rule edits.
04	Why is money computed to 4 decimals?	Because the money and quantity columns are numeric(15,4). Selling by weight needs exactly 1.2350 kg, not 1.24 kg; rounding early is real money lost or gained on every order.
05	Are promotions applied here?	Not yet. The discount calculator is not wired into the pipeline (URD-PROMO-006). The snapshot already reserves discount and fee decision slots for when it is.