Add PaymentAttempt, InventoryReservation, and Fulfillment models for Order Management Epic (#124)

Author: AshrafAbir

docs/ORDER_MANAGEMENT_IMPLEMENTATION.md

@@ -0,0 +1,100 @@
+-- AlterEnum for PaymentGateway
+ALTER TYPE "PaymentGateway" ADD VALUE 'BKASH';
+ALTER TYPE "PaymentGateway" ADD VALUE 'NAGAD';
+
+-- CreateEnum for PaymentAttemptStatus
+CREATE TYPE "PaymentAttemptStatus" AS ENUM ('PENDING', 'SUCCEEDED', 'FAILED', 'REFUNDED', 'PARTIALLY_REFUNDED');
+
+-- CreateEnum for ReservationStatus
+CREATE TYPE "ReservationStatus" AS ENUM ('PENDING', 'CONFIRMED', 'EXPIRED', 'RELEASED');
+
+-- CreateEnum for FulfillmentStatus
+CREATE TYPE "FulfillmentStatus" AS ENUM ('PENDING', 'PROCESSING', 'SHIPPED', 'IN_TRANSIT', 'OUT_FOR_DELIVERY', 'DELIVERED', 'FAILED', 'RETURNED', 'CANCELLED');
+
+-- AlterTable Order - Add new columns
+ALTER TABLE "Order" ADD COLUMN "correlationId" TEXT;
+ALTER TABLE "Order" ADD COLUMN "refundableBalance" DOUBLE PRECISION;
+
+-- CreateIndex for Order
+CREATE INDEX "Order_storeId_customerEmail_idx" ON "Order"("storeId", "customerEmail");
+
+-- CreateTable PaymentAttempt
+CREATE TABLE "PaymentAttempt" (
+    "id" TEXT NOT NULL,
+    "orderId" TEXT NOT NULL,
+    "provider" "PaymentGateway" NOT NULL,
+    "status" "PaymentAttemptStatus" NOT NULL DEFAULT 'PENDING',
+    "amount" DOUBLE PRECISION NOT NULL,
+    "currency" TEXT NOT NULL DEFAULT 'BDT',
+    "stripePaymentIntentId" TEXT,
+    "bkashPaymentId" TEXT,
+    "nagadPaymentId" TEXT,
+    "metadata" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "PaymentAttempt_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable InventoryReservation
+CREATE TABLE "InventoryReservation" (
+    "id" TEXT NOT NULL,
+    "orderId" TEXT,
+    "productId" TEXT NOT NULL,
+    "variantId" TEXT,
+    "quantity" INTEGER NOT NULL,
+    "status" "ReservationStatus" NOT NULL DEFAULT 'PENDING',
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "reservedBy" TEXT,
+    "releasedAt" TIMESTAMP(3),
+    "releaseReason" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "InventoryReservation_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable Fulfillment
+CREATE TABLE "Fulfillment" (
+    "id" TEXT NOT NULL,
+    "orderId" TEXT NOT NULL,
+    "trackingNumber" TEXT,
+    "trackingUrl" TEXT,
+    "carrier" TEXT,
+    "status" "FulfillmentStatus" NOT NULL DEFAULT 'PENDING',
+    "items" TEXT,
+    "shippedAt" TIMESTAMP(3),
+    "deliveredAt" TIMESTAMP(3),
+    "notes" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Fulfillment_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex for PaymentAttempt
+CREATE UNIQUE INDEX "PaymentAttempt_stripePaymentIntentId_key" ON "PaymentAttempt"("stripePaymentIntentId");
+CREATE UNIQUE INDEX "PaymentAttempt_bkashPaymentId_key" ON "PaymentAttempt"("bkashPaymentId");
+CREATE UNIQUE INDEX "PaymentAttempt_nagadPaymentId_key" ON "PaymentAttempt"("nagadPaymentId");
+CREATE INDEX "PaymentAttempt_orderId_status_idx" ON "PaymentAttempt"("orderId", "status");
+CREATE INDEX "PaymentAttempt_stripePaymentIntentId_idx" ON "PaymentAttempt"("stripePaymentIntentId");
+
+-- CreateIndex for InventoryReservation
+CREATE INDEX "InventoryReservation_orderId_idx" ON "InventoryReservation"("orderId");
+CREATE INDEX "InventoryReservation_productId_variantId_status_idx" ON "InventoryReservation"("productId", "variantId", "status");
+CREATE INDEX "InventoryReservation_expiresAt_status_idx" ON "InventoryReservation"("expiresAt", "status");
+
+-- CreateIndex for Fulfillment
+CREATE INDEX "Fulfillment_orderId_status_idx" ON "Fulfillment"("orderId", "status");
+CREATE INDEX "Fulfillment_trackingNumber_idx" ON "Fulfillment"("trackingNumber");
+
+-- AddForeignKey
+ALTER TABLE "PaymentAttempt" ADD CONSTRAINT "PaymentAttempt_orderId_fkey" FOREIGN KEY ("orderId") REFERENCES "Order"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "InventoryReservation" ADD CONSTRAINT "InventoryReservation_orderId_fkey" FOREIGN KEY ("orderId") REFERENCES "Order"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+ALTER TABLE "InventoryReservation" ADD CONSTRAINT "InventoryReservation_productId_fkey" FOREIGN KEY ("productId") REFERENCES "Product"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "InventoryReservation" ADD CONSTRAINT "InventoryReservation_variantId_fkey" FOREIGN KEY ("variantId") REFERENCES "ProductVariant"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+ALTER TABLE "Fulfillment" ADD CONSTRAINT "Fulfillment_orderId_fkey" FOREIGN KEY ("orderId") REFERENCES "Order"("id") ON DELETE CASCADE ON UPDATE CASCADE;

docs/complete-implementations/ORDERS_PAGE_AUTO_REFRESH_FIX.md

@@ -236,6 +236,8 @@ enum PaymentMethod {
 enum PaymentGateway {
   STRIPE
   SSLCOMMERZ
+  BKASH
+  NAGAD
   MANUAL
 }
 
@@ -508,6 +510,7 @@ model Product {
   attributes  ProductAttributeValue[]
   reviews     Review[]
   inventoryLogs InventoryLog[] @relation("InventoryLogs")
+  inventoryReservations InventoryReservation[]
   
   createdAt   DateTime      @default(now())
   updatedAt   DateTime      @updatedAt
@@ -547,6 +550,7 @@ model ProductVariant {
   
   orderItems OrderItem[]
   inventoryLogs InventoryLog[] @relation("VariantInventoryLogs")
+  inventoryReservations InventoryReservation[]
   
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -777,7 +781,14 @@ model Order {
   
   ipAddress   String?
   
-  items    OrderItem[]
+  // Observability and financial tracking
+  correlationId     String?
+  refundableBalance Float?
+  
+  items             OrderItem[]
+  paymentAttempts   PaymentAttempt[]
+  inventoryReservations InventoryReservation[]
+  fulfillments      Fulfillment[]
   
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -788,6 +799,7 @@ model Order {
   @@index([storeId, customerId])
   @@index([storeId, status])
   @@index([storeId, createdAt])
+  @@index([storeId, customerEmail]) // Search by email for guest orders
   // Note: Removed @@index([orderNumber]) to prevent cross-tenant queries
   // Note: Removed @@index([paymentStatus]) to prevent cross-tenant queries
   @@index([storeId, customerId, createdAt]) // Customer order history (tenant-isolated)
@@ -823,6 +835,122 @@ model OrderItem {
   @@index([productId])
 }
 
+// Payment attempt tracking for financial integrity
+enum PaymentAttemptStatus {
+  PENDING
+  SUCCEEDED
+  FAILED
+  REFUNDED
+  PARTIALLY_REFUNDED
+}
+
+model PaymentAttempt {
+  id        String   @id @default(cuid())
+  orderId   String
+  order     Order    @relation(fields: [orderId], references: [id], onDelete: Cascade)
+  
+  provider  PaymentGateway
+  status    PaymentAttemptStatus @default(PENDING)
+  
+  amount    Float // Amount in smallest currency unit (e.g., paisa for BDT)
+  currency  String @default("BDT")
+  
+  // External payment gateway IDs for idempotency and reconciliation
+  stripePaymentIntentId String? @unique
+  bkashPaymentId        String? @unique
+  nagadPaymentId        String? @unique
+  
+  // Metadata for debugging and audit trail
+  metadata  String? // JSON object with error codes, refund reasons, etc.
+  
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  
+  @@index([orderId, status])
+  @@index([stripePaymentIntentId])
+}
+
+// Inventory reservation for oversell prevention
+enum ReservationStatus {
+  PENDING
+  CONFIRMED
+  EXPIRED
+  RELEASED
+}
+
+model InventoryReservation {
+  id        String   @id @default(cuid())
+  orderId   String?
+  order     Order?   @relation(fields: [orderId], references: [id], onDelete: SetNull)
+  
+  productId String
+  product   Product  @relation(fields: [productId], references: [id], onDelete: Cascade)
+  
+  variantId String?
+  variant   ProductVariant? @relation(fields: [variantId], references: [id], onDelete: SetNull)
+  
+  quantity  Int
+  status    ReservationStatus @default(PENDING)
+  
+  // 15-minute hold for checkout completion
+  expiresAt DateTime
+  
+  // Tracking
+  reservedBy String? // User ID who created the reservation
+  releasedAt DateTime?
+  releaseReason String? // "expired", "order_completed", "order_cancelled", "manual"
+  
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  
+  @@index([orderId])
+  @@index([productId, variantId, status])
+  @@index([expiresAt, status]) // For cleanup job
+}
+
+// Fulfillment tracking for shipments
+enum FulfillmentStatus {
+  PENDING
+  PROCESSING
+  SHIPPED
+  IN_TRANSIT
+  OUT_FOR_DELIVERY
+  DELIVERED
+  FAILED
+  RETURNED
+  CANCELLED
+}
+
+model Fulfillment {
+  id        String   @id @default(cuid())
+  orderId   String
+  order     Order    @relation(fields: [orderId], references: [id], onDelete: Cascade)
+  
+  // Tracking information
+  trackingNumber String?
+  trackingUrl    String?
+  carrier        String? // "Pathao", "Steadfast", "DHL", "Manual", etc.
+  
+  status    FulfillmentStatus @default(PENDING)
+  
+  // Items included in this fulfillment (JSON array of {orderItemId, quantity})
+  // Supports partial shipments
+  items     String? // JSON: [{orderItemId: "xxx", quantity: 2}]
+  
+  // Timestamps
+  shippedAt   DateTime?
+  deliveredAt DateTime?
+  
+  // Notes
+  notes       String?
+  
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  
+  @@index([orderId, status])
+  @@index([trackingNumber])
+}
+
 // Webhook configuration for external integrations
 model Webhook {
   id        String   @id @default(cuid())

prisma/migrations/20251213000000_add_payment_attempt_inventory_reservation_fulfillment/migration.sql

@@ -37,6 +37,7 @@ try {
   // when the migration is not failed and prevents noisy errors in the build log.
   const knownMigrations = [
     '20251205014330_add_discount_codes_and_webhooks',
+    '20251213000000_add_payment_attempt_inventory_reservation_fulfillment',
   ];
 
   console.log('\n🧹 Checking known migration statuses before attempting resolves...');

prisma/schema.prisma

@@ -0,0 +1,105 @@
+/**
+ * Fulfillment Status Update API Route
+ * 
+ * Handles updating fulfillment status (e.g., SHIPPED, DELIVERED).
+ * Auto-updates order status based on fulfillment status.
+ * 
+ * @module app/api/fulfillments/[fulfillmentId]/route
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getServerSession } from 'next-auth/next';
+import { authOptions } from '@/lib/auth';
+import { OrderService } from '@/lib/services/order.service';
+import { prisma } from '@/lib/prisma';
+import { FulfillmentStatus } from '@prisma/client';
+import { z } from 'zod';
+
+export const dynamic = 'force-dynamic';
+
+type RouteContext = {
+  params: Promise<{ fulfillmentId: string }>;
+};
+
+/**
+ * Fulfillment update schema
+ */
+const UpdateFulfillmentSchema = z.object({
+  storeId: z.string().cuid(),
+  status: z.nativeEnum(FulfillmentStatus),
+});
+
+/**
+ * PATCH /api/fulfillments/[fulfillmentId]
+ * 
+ * Update fulfillment status
+ * 
+ * @returns 200 - Fulfillment updated successfully
+ * @returns 401 - Unauthorized
+ * @returns 400 - Bad Request
+ * @returns 404 - Fulfillment not found
+ * @returns 500 - Internal Server Error
+ */
+export async function PATCH(request: NextRequest, context: RouteContext) {
+  try {
+    const session = await getServerSession(authOptions);
+    if (!session?.user) {
+      return NextResponse.json({ error: 'Authentication required' }, { status: 401 });
+    }
+
+    const params = await context.params;
+    const body = await request.json();
+
+    const validationResult = UpdateFulfillmentSchema.safeParse(body);
+    if (!validationResult.success) {
+      return NextResponse.json(
+        {
+          error: 'Invalid request data',
+          details: validationResult.error.flatten().fieldErrors,
+        },
+        { status: 400 }
+      );
+    }
+
+    const { storeId, status } = validationResult.data;
+
+    // Verify user has access to this store
+    const store = await prisma.store.findFirst({
+      where: {
+        id: storeId,
+        OR: [
+          { organization: { memberships: { some: { userId: session.user.id } } } },
+          { staff: { some: { userId: session.user.id, isActive: true } } },
+        ],
+      },
+    });
+
+    if (!store) {
+      return NextResponse.json(
+        { error: 'Access denied. You do not have access to this store.' },
+        { status: 403 }
+      );
+    }
+
+    // Update fulfillment status
+    const orderService = OrderService.getInstance();
+    const fulfillment = await orderService.updateFulfillmentStatus({
+      fulfillmentId: params.fulfillmentId,
+      storeId,
+      status,
+    });
+
+    return NextResponse.json({
+      data: fulfillment,
+      message: 'Fulfillment status updated successfully',
+    });
+  } catch (error) {
+    console.error('Error updating fulfillment:', error);
+
+    if (error instanceof Error && error.message.includes('not found')) {
+      return NextResponse.json({ error: error.message }, { status: 404 });
+    }
+
+    return NextResponse.json({ error: 'Failed to update fulfillment' }, { status: 500 });
+  }
+}