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.
77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
# 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.
|