feat: Implement Phase 6 Shopping and Checkout

- 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.
2026-09-03 23:45:01 +05:30
parent 5643d89236
commit ad9287b804
33 changed files with 187 additions and 10 deletions
@@ -0,0 +1,76 @@
+# 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.