购物车API后端

Laburen MCP - Model Context Protocol Backend

API REST de productos y carritos de compra deployado en Cloudflare Workers con D1 Database.

🚀 Stack Tecnológico

• Runtime: Cloudflare Workers
• Lenguaje: TypeScript
• Base de datos: D1 (SQLite)
• Validaciones: Zod
• Herramientas: Wrangler CLI

📁 Estructura del Proyecto

laburen-mcp/
├── src/
│   ├── db/              # Capa de acceso a datos
│   │   ├── client.ts    # Cliente D1
│   │   ├── products.repo.ts
│   │   └── carts.repo.ts
│   ├── services/        # Lógica de negocio
│   │   └── cart.service.ts
│   ├── routes/          # Handlers HTTP + validaciones
│   │   ├── products.routes.ts
│   │   └── carts.routes.ts
│   ├── utils/           # Utilidades
│   │   ├── errors.ts    # Sistema de errores
│   │   └── logger.ts    # Logging estructurado
│   ├── env.d.ts         # Tipos de ambiente
│   └── index.ts         # Entry point + router
├── migrations/          # Migraciones SQL
│   ├── 0001_init.sql
│   └── 0002_import_products.sql
└── wrangler.jsonc       # Configuración Cloudflare

🛠️ Setup Local

1. Instalar dependencias

npm install

2. Crear y poblar base de datos local

# Aplicar migración de schema
wrangler d1 execute laburen-mcp-db --local --file=migrations/0001_init.sql

# Importar 100 productos
wrangler d1 execute laburen-mcp-db --local --file=migrations/0002_import_products.sql

3. Iniciar servidor de desarrollo

npm run dev

El servidor estará disponible en http://127.0.0.1:8787

📡 Endpoints

Productos

GET /products

Lista todos los productos con búsqueda opcional.

Query params:

• q (opcional): Término de búsqueda

Ejemplo:

curl http://127.0.0.1:8787/products
curl http://127.0.0.1:8787/products?q=camiseta

GET /products/:id

Obtiene un producto por ID.

Ejemplo:

curl http://127.0.0.1:8787/products/1

Carritos

POST /carts

Crea un nuevo carrito vacío.

Respuesta:

{
  "id": "uuid-v4",
  "created_at": "2026-01-23T...",
  "updated_at": "2026-01-23T..."
}

Ejemplo:

curl -X POST http://127.0.0.1:8787/carts

GET /carts/:id

Obtiene un carrito con sus items y total.

Respuesta:

{
  "id": "uuid",
  "created_at": "...",
  "updated_at": "...",
  "items": [
    {
      "id": 1,
      "product_id": 5,
      "product_name": "Producto X",
      "price": 1500,
      "qty": 2,
      "subtotal": 3000
    }
  ],
  "total": 3000
}

Ejemplo:

curl http://127.0.0.1:8787/carts/{cart-id}

POST /carts/:id/items

Agrega items al carrito con validación de stock.

Body:

{
  "product_id": 1,
  "quantity": 2
}

Validaciones:

• Product ID debe existir
• Quantity debe ser positiva
• Stock suficiente (validación acumulativa)

Ejemplo:

curl -X POST http://127.0.0.1:8787/carts/{cart-id}/items \
  -H "Content-Type: application/json" \
  -d '{"product_id": 1, "quantity": 2}'

POST /carts/items (Query Params)

Agrega items usando query params (compatible con Laburen).

Query Params:

• cart_id (UUID)
• product_id (número)
• quantity (número)

Ejemplo:

curl -X POST "http://127.0.0.1:8787/carts/items?cart_id={cart-id}&product_id=1&quantity=2"

PATCH /carts/items (Query Params)

Actualiza la cantidad de un producto en el carrito.

Query Params:

• cart_id (UUID)
• product_id (número)
• quantity (número - nueva cantidad total)

Validaciones:

• Product debe existir en el carrito
• Quantity debe ser positiva
• Stock suficiente

Ejemplo:

curl -X PATCH "http://127.0.0.1:8787/carts/items?cart_id={cart-id}&product_id=1&quantity=5"

DELETE /carts/items (Query Params)

Elimina un producto del carrito completamente.

Query Params:

• cart_id (UUID)
• product_id (número)

Ejemplo:

curl -X DELETE "http://127.0.0.1:8787/carts/items?cart_id={cart-id}&product_id=1"

🧪 Testing

Probar endpoints manualmente:

# Listar productos
curl http://127.0.0.1:8787/products

# Crear carrito
CART_ID=$(curl -X POST http://127.0.0.1:8787/carts | jq -r '.id')

# Agregar items
curl -X POST "http://127.0.0.1:8787/carts/items?cart_id=$CART_ID&product_id=1&quantity=2"
curl -X POST "http://127.0.0.1:8787/carts/items?cart_id=$CART_ID&product_id=5&quantity=1"

# Ver carrito
curl http://127.0.0.1:8787/carts/$CART_ID

# Actualizar cantidad
curl -X PATCH "http://127.0.0.1:8787/carts/items?cart_id=$CART_ID&product_id=1&quantity=5"

# Eliminar producto
curl -X DELETE "http://127.0.0.1:8787/carts/items?cart_id=$CART_ID&product_id=5"

# Ver carrito final
curl http://127.0.0.1:8787/carts/$CART_ID

🚢 Deploy a Producción

1. Login en Cloudflare

wrangler login

2. Aplicar migraciones en producción

# Schema
wrangler d1 migrations apply laburen-mcp-db

# Productos (ya generado en migrations/)
wrangler d1 execute laburen-mcp-db --file=migrations/0002_import_products.sql

3. Deploy

npm run deploy

El MCP estará disponible en: https://laburen-mcp.{tu-subdominio}.workers.dev

🔧 Scripts Útiles

# Desarrollo local
npm run dev

# Deploy a producción
npm run deploy

# Regenerar tipos de Cloudflare
npm run cf-typegen

📝 Manejo de Errores

Todos los errores devuelven JSON con formato:

{
  "error": "Mensaje descriptivo",
  "code": "ERROR_CODE"
}

Códigos comunes:

• NOT_FOUND (404): Recurso no existe
• VALIDATION_ERROR (400): Input inválido
• INSUFFICIENT_STOCK (400): Stock insuficiente
• INTERNAL_ERROR (500): Error interno

🏗️ Arquitectura

• index.ts: Router simple basado en path matching
• Repositories: Acceso directo a D1 con SQL
• Services: Validaciones de negocio (ej: stock)
• Routes: Validación Zod + transformación HTTP
• Utils: Errores y logging centralizados

Sin ORMs pesados, sin frameworks frontend, código limpio y directo.

📊 Base de Datos

Schema

products

• id (INTEGER PRIMARY KEY)
• name (TEXT NOT NULL)
• description (TEXT)
• price (REAL NOT NULL)
• stock (INTEGER NOT NULL)

carts

• id (TEXT PRIMARY KEY - UUID)
• created_at (TEXT NOT NULL - ISO 8601)
• updated_at (TEXT NOT NULL - ISO 8601)

cart_items

• id (INTEGER PRIMARY KEY)
• cart_id (TEXT FK → carts)
• product_id (INTEGER FK → products)
• qty (INTEGER NOT NULL)

📦 Entregables del Challenge

✅ 1. Agente Desplegado

• Canal: WhatsApp
• Integración: Chatwoot Agent Bot → Laburen Platform
• Estado: ✓ Funcional y respondiendo

✅ 2. Repositorio GitHub

• Código completo del MCP Backend
• Base de datos con 100 productos
• Endpoints REST validados
• Deploy en Cloudflare Workers

✅ 3. Documentación Técnica

📄 Documentos en /docs:

• resumen-tecnico.md - Endpoints + Diagrama de Flujo (Entregable oficial)
• arquitectura-agente.md - Arquitectura detallada
• diagrama-flujo.md - Flujos de interacción
• guia-instalacion.md - Setup completo

🎯 Criterios del Challenge