Diseño de Sistemas: Plataforma E-Commerce

// Flexible product schema supporting varied attributes
interface Product {
  id: string;
  sellerId: string;
  title: string;
  slug: string;
  description: string;
  category: CategoryPath; // e.g., ["Electronics", "Phones", "Smartphones"]
  brand: string;
  basePrice: number;
  currency: string;
  images: ProductImage[];
  variants: ProductVariant[];
  attributes: Record<string, string | number | boolean>;
  status: "DRAFT" | "ACTIVE" | "ARCHIVED";
  createdAt: Date;
  updatedAt: Date;
}

interface ProductVariant {
  sku: string;
  attributes: Record<string, string>; // e.g., { color: "Red", size: "M" }
  price: number;
  inventoryCount: number;
  weight: number;
  dimensions: { length: number; width: number; height: number };
}

type CategoryPath = string[];
// Stored as: "Electronics > Phones > Smartphones"
// Enables efficient queries: find all products under "Electronics"

interface CartItem {
  productId: string;
  variantSku: string;
  quantity: number;
  priceAtAdd: number;
  addedAt: Date;
}

interface ShoppingCart {
  userId: string;
  items: CartItem[];
  updatedAt: Date;
  expiresAt: Date;
}

class CartService {
  private redis: RedisClient;

  async addItem(userId: string, item: CartItem): Promise<ShoppingCart> {
    const cartKey = `cart:${userId}`;

    const available = await inventoryService.checkAvailability(
      item.variantSku,
      item.quantity
    );
    if (!available) throw new Error("Item out of stock");

    const cart = await this.getCart(userId);

    const existingIndex = cart.items.findIndex(
      (i) => i.variantSku === item.variantSku
    );
    if (existingIndex >= 0) {
      cart.items[existingIndex].quantity += item.quantity;
    } else {
      cart.items.push(item);
    }

    cart.updatedAt = new Date();
    cart.expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);

    await this.redis.setex(cartKey, 7 * 86400, JSON.stringify(cart));
    return cart;
  }
}

class InventoryService {
  async reserveInventory(
    items: { sku: string; quantity: number }[],
    orderId: string,
    ttlMinutes: number = 15
  ): Promise<boolean> {
    const client = await db.pool.connect();
    try {
      await client.query("BEGIN");

      for (const item of items) {
        const result = await client.query(
          `UPDATE inventory
           SET available_count = available_count - $1,
               reserved_count = reserved_count + $1
           WHERE sku = $2
             AND available_count >= $1
           RETURNING available_count`,
          [item.quantity, item.sku]
        );

        if (result.rowCount === 0) {
          await client.query("ROLLBACK");
          await this.releaseReservation(orderId);
          return false;
        }

        await client.query(
          `INSERT INTO inventory_reservations (order_id, sku, quantity, expires_at)
           VALUES ($1, $2, $3, NOW() + INTERVAL '$4 minutes')`,
          [orderId, item.sku, item.quantity, ttlMinutes]
        );
      }

      await client.query("COMMIT");
      return true;
    } catch (error) {
      await client.query("ROLLBACK");
      throw error;
    } finally {
      client.release();
    }
  }

  async releaseExpiredReservations(): Promise<void> {
    const expired = await db.query(
      `SELECT * FROM inventory_reservations WHERE expires_at < NOW()`
    );

    for (const reservation of expired.rows) {
      await db.query(
        `UPDATE inventory
         SET available_count = available_count + $1,
             reserved_count = reserved_count - $1
         WHERE sku = $2`,
        [reservation.quantity, reservation.sku]
      );
      await db.query(
        `DELETE FROM inventory_reservations WHERE id = $1`,
        [reservation.id]
      );
    }
  }
}

enum OrderStatus {
  CREATED = "CREATED",
  PAYMENT_PENDING = "PAYMENT_PENDING",
  PAYMENT_CONFIRMED = "PAYMENT_CONFIRMED",
  PREPARING = "PREPARING",
  SHIPPED = "SHIPPED",
  DELIVERED = "DELIVERED",
  CANCELLED = "CANCELLED",
  REFUNDED = "REFUNDED",
}

async function handleOrderCreated(order: Order): Promise<void> {
  // 1. Validate order
  await validateOrder(order);

  // 2. Reserve inventory
  const reserved = await inventoryService.reserveInventory(
    order.items.map((i) => ({ sku: i.sku, quantity: i.quantity })),
    order.id
  );
  if (!reserved) {
    await updateOrderStatus(order.id, OrderStatus.CANCELLED, "Out of stock");
    await notifyCustomer(order.customerId, "order_cancelled_stock");
    return;
  }

  // 3. Process payment
  await updateOrderStatus(order.id, OrderStatus.PAYMENT_PENDING);
  const paymentResult = await paymentService.charge(order);

  if (!paymentResult.success) {
    await inventoryService.releaseReservation(order.id);
    await updateOrderStatus(order.id, OrderStatus.CANCELLED, "Payment failed");
    return;
  }

  // 4. Confirm order
  await updateOrderStatus(order.id, OrderStatus.PAYMENT_CONFIRMED);
  await inventoryService.confirmReservation(order.id);

  // 5. Send to fulfillment
  await fulfillmentService.createShipment(order);
  await notifyCustomer(order.customerId, "order_confirmed");
}