Sathira Sri Sathara
ad9287b804
- Introduced authenticated shopping state and atomic checkout process without creating orders or payments. - Reused existing components from previous phases including identities, addresses, catalogues, pricing, and inventory. - Developed cart architecture to support one active cart per user with unique items per variant. - Implemented dynamic cart pricing with various precedence rules for promotions and coupons. - Created a wishlist feature that exposes only visible active products without reserving inventory. - Integrated inventory validation to ensure availability of items before adding to cart. - Developed a checkout architecture that locks the cart, revalidates pricing and shipping, and reserves inventory. - Added shipping zones, methods, and rates with configurable options for international shipping and duty/tax boundaries. - Implemented checkout snapshots to capture immutable checkout details. - Introduced idempotency for checkout requests to prevent duplicate processing. - Added functionality for coupon integration and business checkout validation. - Established permissions for managing shipping zones, methods, and rates. - Created comprehensive unit tests covering various aspects of the shopping and checkout processes. - Added cron job for handling checkout expiry reconciliation. - Created migration script to set up new database tables and constraints for carts, checkout sessions, and shipping.
3.9 KiB
ZUMRI Phase 6 Shopping and Checkout
Objective
Add authenticated shopping state and an atomic, priced, inventory-reserved checkout handoff without creating orders or payments.
Existing Components Reused
Phase 3 identities/addresses/business accounts, Phase 4 catalogue, Phase 5 pricing/inventory/promotions, Phase 1 permissions, Phase 2 audit, Sequelize, Zod, and cron bootstrap.
Cart Architecture
One ACTIVE cart per identity; items are unique per variant and owner-scoped. Guest carts were intentionally omitted. Version increments detect state changes and checkout locks mutation.
Cart Pricing
Cart items are dynamically requoted with retail/business/volume/promotion/coupon precedence. DECIMAL strings use BigInt-scaled arithmetic.
Wishlist
Unique owner/product entries expose only visible active products and never reserve inventory.
Inventory Validation
Adding and projecting items checks authoritative aggregate availability. Unavailable items remain explainable.
Reservation Integration
Cart does not reserve. Checkout extends the Phase 5 service with external transaction composition and reserves sorted variants all-or-nothing.
Shipping Zones
Normalized country/province/district records provide deterministic destination matching, including international zones.
Shipping Methods
Configurable methods include delivery estimates and tracking capability.
Shipping Rates
Scheduled DECIMAL rates support currency, subtotal bands, and configurable free-shipping thresholds.
International Shipping
Only configured zones are eligible; unsupported destinations fail explicitly.
Duty/Tax Boundary
Zones declare NONE, ESTIMATED, PAYABLE_ON_DELIVERY, INCLUDED, or UNKNOWN. No customs amount is fabricated. Tax remains zero without authoritative configuration.
Checkout Architecture
A user-scoped transaction locks the cart, revalidates catalogue/pricing/shipping, reserves inventory, writes snapshots, and locks the cart.
Checkout Snapshots
Immutable checkout items capture product/variant/SKU, price, discount, total, currency, and pricing source. Owned address and shipping selections are copied as JSON.
Checkout Totals
Merchandise subtotal minus discounts plus shipping plus configured tax/duty equals grand total. Client totals are prohibited.
Idempotency
Unique (userId, idempotencyKey) plus SHA-256 request fingerprint returns the same session or rejects changed payloads.
Checkout Expiry
A no-overlap minute reconciliation processes 100 sessions, locks each session, releases reservations idempotently, marks EXPIRED, and restores its cart.
Coupon Integration
Cart coupons are provisional and revalidated at checkout. Authoritative redemption remains Phase 7.
Business Checkout
The shared flow revalidates approved ACTIVE business context, MOQ, customer/tier price, and volume tier. Credit is untouched.
Permissions
Shipping zone/method/rate read/manage permissions protect all administration.
Audit
Cart, wishlist, checkout, expiry/cancellation, and shipping configuration use stable Phase 2 activity types without full addresses or carts.
Database Changes
Forward-only migration 20260903060000 creates nine Phase 6 tables and required uniqueness/status-expiry indexes.
Tests
Phase 6 unit tests cover decimal totals, strict client-total rejection, quantity validation, deterministic fingerprints, safe address snapshots, and shipping permission denial. Existing suites remain green.
Remaining Known Issues
Real InnoDB concurrent checkout, migration, and multi-instance cron behavior require staging. Shipping weight bands, authoritative tax/duty, and coupon redemption are intentionally deferred.
Phase 7 Prerequisites
Run legacy table/address/currency/reservation prechecks, migrate staging, seed zones/methods/rates and permissions, and prove concurrent final-stock and duplicate-idempotency behavior with real MySQL connections.