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.

app/services/inventory/inventory.service.js

@@ -36,9 +36,9 @@ async function selectWarehouse(variantId, quantity, transaction) {
   throw fault("Insufficient available stock", "INSUFFICIENT_STOCK", 409);
 }
 
-async function reserveStock({ reservationKey, warehouseId, variantId, quantity, referenceType, referenceId, userId, expiresAt, requestId }) {
+async function reserveStock({ reservationKey, warehouseId, variantId, quantity, referenceType, referenceId, userId, expiresAt, requestId, transaction: externalTransaction }) {
   assertQuantity(quantity); if (!reservationKey) throw fault("reservationKey is required", "INVALID_RESERVATION");
-  return db.sequelize.transaction(async transaction => {
+  const execute = async transaction => {
     const existing = await db.InventoryReservation.findOne({ where: { reservation_key: reservationKey }, transaction, lock: transaction.LOCK.UPDATE });
     if (existing) return { reservation: existing, idempotent: true };
     const variant = await db.ProductVariant.findOne({ where: { id: variantId, status: "ACTIVE" }, transaction });
@@ -55,11 +55,12 @@ async function reserveStock({ reservationKey, warehouseId, variantId, quantity,
     const reservation = await db.InventoryReservation.create({ id: crypto.randomUUID(), reservation_key: reservationKey, warehouse_id: selected.warehouse.id, variant_id: variantId, quantity, reference_type: referenceType, reference_id: referenceId, user_id: userId, expires_at: expiresAt || new Date(Date.now() + ttlMinutes() * 60000) }, { transaction });
     await ledger({ event_id: `reserve:${reservationKey}`, warehouse_id: selected.warehouse.id, variant_id: variantId, type: "RESERVATION", reserved_delta: quantity, reference_type: "INVENTORY_RESERVATION", reference_id: reservation.id, request_id: requestId }, transaction);
     return { reservation, idempotent: false };
-  });
+  };
+  return externalTransaction ? execute(externalTransaction) : db.sequelize.transaction(execute);
 }
 
-async function finishReservation(reservationKey, status, requestId) {
-  return db.sequelize.transaction(async transaction => {
+async function finishReservation(reservationKey, status, requestId, externalTransaction) {
+  const execute = async transaction => {
     const reservation = await db.InventoryReservation.findOne({ where: { reservation_key: reservationKey }, transaction, lock: transaction.LOCK.UPDATE });
     if (!reservation) throw fault("Reservation not found", "RESERVATION_NOT_FOUND", 404);
     if (reservation.status === status) return { reservation, idempotent: true };
@@ -72,11 +73,12 @@ async function finishReservation(reservationKey, status, requestId) {
     await reservation.update({ status, released_at: consume ? null : new Date(), consumed_at: consume ? new Date() : null }, { transaction });
     await ledger({ event_id: `${status.toLowerCase()}:${reservationKey}`, warehouse_id: reservation.warehouse_id, variant_id: reservation.variant_id, type: consume ? "RESERVATION_CONSUME" : "RESERVATION_RELEASE", quantity_delta: consume ? -reservation.quantity : 0, reserved_delta: -reservation.quantity, reference_type: "INVENTORY_RESERVATION", reference_id: reservation.id, request_id: requestId }, transaction);
     return { reservation, idempotent: false };
-  });
+  };
+  return externalTransaction ? execute(externalTransaction) : db.sequelize.transaction(execute);
 }
 
-const releaseReservation = args => finishReservation(args.reservationKey, args.expired ? "EXPIRED" : "RELEASED", args.requestId);
-const consumeReservation = args => finishReservation(args.reservationKey, "CONSUMED", args.requestId);
+const releaseReservation = args => finishReservation(args.reservationKey, args.expired ? "EXPIRED" : "RELEASED", args.requestId, args.transaction);
+const consumeReservation = args => finishReservation(args.reservationKey, "CONSUMED", args.requestId, args.transaction);
 
 async function transferStock({ eventId, sourceWarehouseId, destinationWarehouseId, variantId, quantity, actorUserId, requestId }) {
   assertQuantity(quantity); if (sourceWarehouseId === destinationWarehouseId) throw fault("Warehouses must differ", "INVALID_TRANSFER");