ofertaweb.cl/PLANIFICACION.md

🚀 PLANIFICACIÓN - OFERTAWEB.CL

Sistema E-Commerce Multi-Canal con Gestión de Despacho

Fecha: Diciembre 2025
Versión: 1.0

---

📁 ESTRUCTURA DEL PROYECTO

ofertaweb.cl/
├── backend/              # API REST (Node.js + Express + PostgreSQL)
├── frontend/             # Tienda web para clientes (React/Vue)
└── administracion/       # Panel administrativo (React/Vue)

---

🎯 OBJETIVOS DEL SISTEMA

Funcionalidades Core

1. ✅ Catálogo de productos con categorías
2. ✅ Carrito de compras y proceso de checkout
3. ✅ Gestión de órdenes y despacho (tracking completo)
4. ✅ Panel administrativo completo
5. ✅ Sistema de stock unificado en tiempo real

Integraciones Externas

1. 🔗 MercadoLibre - Publicación automática (precio +10%)
2. 🔗 Instagram Shopping - Sincronización de catálogo
3. 🔗 BlueExpress - Cálculo de envío en tiempo real
4. 🔗 Pasarela de Pagos - Webpay/Transbank (por definir)

---

🗄️ ARQUITECTURA DE BASE DE DATOS

Módulo: Usuarios y Autenticación

users
├── id (PK)
├── email (unique)
├── password_hash
├── nombre
├── apellido
├── telefono
├── role (enum: 'cliente', 'admin', 'repartidor')
├── is_active
├── created_at
└── updated_at

user_addresses
├── id (PK)
├── user_id (FK → users)
├── direccion
├── comuna
├── ciudad
├── region
├── codigo_postal
├── referencia
├── is_default
└── created_at

Módulo: Catálogo de Productos

categories
├── id (PK)
├── nombre
├── slug
├── descripcion
├── parent_id (FK → categories, nullable)
├── orden
└── is_active

products
├── id (PK)
├── sku (unique)
├── nombre
├── descripcion
├── precio_base
├── peso_gramos
├── alto_cm
├── ancho_cm
├── largo_cm
├── category_id (FK → categories)
├── is_active
├── created_at
└── updated_at

product_images
├── id (PK)
├── product_id (FK → products)
├── url
├── alt_text
├── orden
└── is_primary

Módulo: Multi-Canal

channels
├── id (PK)
├── nombre (enum: 'tienda', 'mercadolibre', 'instagram')
├── slug
├── config (jsonb) -- credenciales, tokens
├── is_active
└── updated_at

channel_products
├── id (PK)
├── product_id (FK → products)
├── channel_id (FK → channels)
├── external_id (ID en plataforma externa)
├── precio_ajustado (precio_base * factor)
├── precio_factor (ej: 1.10 para ML)
├── estado (enum: 'publicado', 'pausado', 'agotado')
├── last_sync_at
└── sync_errors (jsonb)

channel_sync_logs
├── id (PK)
├── channel_id (FK → channels)
├── product_id (FK → products, nullable)
├── tipo (enum: 'stock', 'precio', 'publicacion')
├── status (enum: 'success', 'error')
├── mensaje
└── created_at

Módulo: Inventario (Stock Unificado)

inventory
├── id (PK)
├── product_id (FK → products, unique)
├── stock_actual
├── stock_minimo
├── stock_reservado
└── updated_at

inventory_movements
├── id (PK)
├── product_id (FK → products)
├── tipo (enum: 'entrada', 'salida', 'ajuste', 'reserva', 'liberacion')
├── cantidad
├── cantidad_anterior
├── cantidad_nueva
├── referencia (ej: order_id, ajuste manual)
├── notas
├── created_by (FK → users)
└── created_at

Módulo: Carrito de Compras

carts
├── id (PK)
├── user_id (FK → users, nullable para invitados)
├── session_id (para invitados)
├── expires_at
└── created_at

cart_items
├── id (PK)
├── cart_id (FK → carts)
├── product_id (FK → products)
├── cantidad
├── precio_unitario (precio al momento de agregar)
└── created_at

Módulo: Órdenes de Compra

orders
├── id (PK)
├── order_number (unique, ej: ORD-20251205-0001)
├── user_id (FK → users)
├── channel_id (FK → channels) -- origen de la venta
├── estado (enum: 'pendiente_pago', 'pagada', 'preparando', 'enviada', 'entregada', 'cancelada')
├── subtotal
├── descuento
├── costo_envio
├── total
├── notas_cliente
├── created_at
└── updated_at

order_items
├── id (PK)
├── order_id (FK → orders)
├── product_id (FK → products)
├── cantidad
├── precio_unitario
├── subtotal
└── created_at

Módulo: Pagos

payments
├── id (PK)
├── order_id (FK → orders)
├── metodo (enum: 'webpay', 'transferencia', 'mercadopago', 'efectivo')
├── estado (enum: 'pendiente', 'aprobado', 'rechazado', 'reembolsado')
├── monto
├── transaction_id (ID de la pasarela)
├── response_data (jsonb)
├── paid_at
└── created_at

payment_transactions
├── id (PK)
├── payment_id (FK → payments)
├── tipo (enum: 'authorization', 'capture', 'refund')
├── status
├── request_data (jsonb)
├── response_data (jsonb)
└── created_at

Módulo: Despacho y Envíos

shipments
├── id (PK)
├── order_id (FK → orders, unique)
├── tracking_number
├── courier (enum: 'bluexpress', 'chilexpress', 'starken', 'retiro')
├── estado (enum: 'pendiente', 'preparando', 'en_transito', 'en_reparto', 'entregado', 'fallido')
├── direccion_id (FK → user_addresses)
├── costo_calculado
├── peso_total
├── dimensiones (jsonb)
├── fecha_estimada_entrega
├── fecha_entrega_real
├── repartidor_id (FK → users, nullable)
├── notas_despacho
├── comprobante_url (foto/firma)
└── created_at

shipment_tracking
├── id (PK)
├── shipment_id (FK → shipments)
├── estado
├── ubicacion
├── descripcion
├── created_by (FK → users, nullable)
└── created_at

shipping_quotes
├── id (PK)
├── order_id (FK → orders, nullable)
├── courier
├── servicio (ej: 'express', 'normal')
├── origen_comuna
├── destino_comuna
├── peso_gramos
├── costo
├── dias_estimados
├── response_data (jsonb)
├── expires_at
└── created_at

Módulo: Configuración del Sistema

settings
├── id (PK)
├── key (unique, ej: 'ml_client_id', 'instagram_token')
├── value (text)
├── tipo (enum: 'string', 'number', 'boolean', 'json')
├── descripcion
├── is_secret (boolean)
└── updated_at

---

🏗️ BACKEND - ESTRUCTURA DE ARCHIVOS

backend/
├── index.js                    # Punto de entrada
├── package.json
├── .env                        # Variables de entorno
├── .env.example
│
├── config/
│   ├── db.js                   # Conexión PostgreSQL
│   ├── constants.js            # Constantes del sistema
│   └── multer.js               # Configuración de uploads
│
├── middleware/
│   ├── auth.js                 # Verificación JWT
│   ├── roleCheck.js            # Control de roles
│   ├── errorHandler.js         # Manejo centralizado de errores
│   └── validation.js           # Validación de datos (Joi)
│
├── models/
│   ├── User.js
│   ├── Product.js
│   ├── Category.js
│   ├── Order.js
│   ├── Shipment.js
│   ├── Channel.js
│   └── Inventory.js
│
├── controllers/
│   ├── authController.js       # Login, registro, recuperar contraseña
│   ├── productController.js    # CRUD productos
│   ├── categoryController.js   # CRUD categorías
│   ├── cartController.js       # Gestión del carrito
│   ├── orderController.js      # Gestión de órdenes
│   ├── shipmentController.js   # Gestión de despachos
│   ├── inventoryController.js  # Control de stock
│   ├── channelController.js    # Multi-canal
│   └── paymentController.js    # Procesamiento de pagos
│
├── routes/
│   ├── authRoutes.js
│   ├── productRoutes.js
│   ├── categoryRoutes.js
│   ├── cartRoutes.js
│   ├── orderRoutes.js
│   ├── shipmentRoutes.js
│   ├── inventoryRoutes.js
│   ├── channelRoutes.js
│   └── paymentRoutes.js
│
├── services/
│   ├── stockService.js         # Lógica de sincronización de stock
│   ├── pricingService.js       # Cálculo de precios por canal
│   ├── mercadolibreService.js  # Integración MercadoLibre API
│   ├── instagramService.js     # Integración Instagram/Facebook API
│   ├── blueexpressService.js   # Integración BlueExpress API
│   ├── paymentService.js       # Integración pasarela de pagos
│   ├── emailService.js         # Envío de emails (Nodemailer)
│   └── uploadService.js        # Manejo de imágenes (Multer + Sharp)
│
├── utils/
│   ├── validators.js           # Validadores personalizados
│   ├── helpers.js              # Funciones auxiliares
│   └── logger.js               # Sistema de logs
│
├── jobs/
│   ├── syncStockJob.js         # Cron: sincronizar stock cada X minutos
│   ├── syncPricesJob.js        # Cron: actualizar precios en canales
│   └── cleanCartsJob.js        # Cron: limpiar carritos expirados
│
├── migrations/
│   ├── 001_create_users.sql
│   ├── 002_create_products.sql
│   ├── 003_create_channels.sql
│   ├── 004_create_inventory.sql
│   ├── 005_create_orders.sql
│   ├── 006_create_shipments.sql
│   └── ...
│
├── public/
│   └── uploads/
│       └── products/           # Imágenes de productos
│
└── tests/
    ├── auth.test.js
    ├── products.test.js
    └── ...

---

🌐 FRONTEND - TIENDA (Clientes)

Tecnologías sugeridas

• Framework: React + Vite (o Next.js para SEO)
• Estado: Redux Toolkit / Zustand
• UI: TailwindCSS + Headless UI
• HTTP: Axios
• Routing: React Router

Páginas principales

frontend/
├── public/
├── src/
│   ├── components/
│   │   ├── layout/
│   │   │   ├── Header.jsx
│   │   │   ├── Footer.jsx
│   │   │   └── Navbar.jsx
│   │   ├── product/
│   │   │   ├── ProductCard.jsx
│   │   │   ├── ProductDetail.jsx
│   │   │   └── ProductGallery.jsx
│   │   ├── cart/
│   │   │   ├── CartDrawer.jsx
│   │   │   ├── CartItem.jsx
│   │   │   └── CartSummary.jsx
│   │   └── checkout/
│   │       ├── CheckoutForm.jsx
│   │       ├── AddressForm.jsx
│   │       └── PaymentForm.jsx
│   │
│   ├── pages/
│   │   ├── Home.jsx              # Página principal
│   │   ├── Products.jsx          # Catálogo con filtros
│   │   ├── ProductDetail.jsx     # Detalle de producto
│   │   ├── Cart.jsx              # Carrito completo
│   │   ├── Checkout.jsx          # Proceso de compra
│   │   ├── OrderConfirmation.jsx # Confirmación de orden
│   │   ├── TrackOrder.jsx        # Seguimiento de pedido
│   │   ├── Profile.jsx           # Perfil del usuario
│   │   ├── Orders.jsx            # Historial de órdenes
│   │   └── Login.jsx             # Login/Registro
│   │
│   ├── services/
│   │   ├── api.js                # Configuración Axios
│   │   ├── productService.js
│   │   ├── cartService.js
│   │   ├── orderService.js
│   │   └── authService.js
│   │
│   ├── store/                    # Redux/Zustand
│   │   ├── cartSlice.js
│   │   ├── authSlice.js
│   │   └── store.js
│   │
│   ├── utils/
│   │   ├── formatters.js
│   │   └── validators.js
│   │
│   ├── App.jsx
│   └── main.jsx
│
└── package.json

---

🎛️ ADMINISTRACIÓN - Panel Admin

Tecnologías sugeridas

• Framework: React + Vite
• UI Admin: React Admin / Ant Design / Material UI
• Gráficos: Chart.js / Recharts
• Tablas: TanStack Table

Módulos principales

administracion/
├── src/
│   ├── components/
│   │   ├── layout/
│   │   │   ├── AdminLayout.jsx
│   │   │   ├── Sidebar.jsx
│   │   │   └── TopBar.jsx
│   │   ├── dashboard/
│   │   │   ├── StatsCard.jsx
│   │   │   ├── SalesChart.jsx
│   │   │   └── RecentOrders.jsx
│   │   └── ...
│   │
│   ├── pages/
│   │   ├── Dashboard.jsx         # Estadísticas generales
│   │   │
│   │   ├── products/
│   │   │   ├── ProductList.jsx   # Listado de productos
│   │   │   ├── ProductForm.jsx   # Crear/Editar producto
│   │   │   └── ProductStock.jsx  # Control de inventario
│   │   │
│   │   ├── categories/
│   │   │   ├── CategoryList.jsx
│   │   │   └── CategoryForm.jsx
│   │   │
│   │   ├── orders/
│   │   │   ├── OrderList.jsx     # Todas las órdenes
│   │   │   ├── OrderDetail.jsx   # Detalle de orden
│   │   │   └── OrderStatus.jsx   # Cambiar estados
│   │   │
│   │   ├── shipments/
│   │   │   ├── ShipmentList.jsx  # Panel de despachos
│   │   │   ├── ShipmentMap.jsx   # Mapa de repartos
│   │   │   └── ShipmentForm.jsx  # Asignar repartidor
│   │   │
│   │   ├── channels/
│   │   │   ├── ChannelList.jsx   # Canales activos
│   │   │   ├── ChannelSync.jsx   # Sincronización manual
│   │   │   └── SyncLogs.jsx      # Historial de sync
│   │   │
│   │   ├── inventory/
│   │   │   ├── StockList.jsx     # Stock por producto
│   │   │   ├── StockMovements.jsx # Historial de movimientos
│   │   │   └── StockAdjust.jsx   # Ajuste manual
│   │   │
│   │   ├── settings/
│   │   │   ├── GeneralSettings.jsx
│   │   │   ├── ChannelSettings.jsx # Config APIs
│   │   │   ├── ShippingSettings.jsx
│   │   │   └── PaymentSettings.jsx
│   │   │
│   │   └── reports/
│   │       ├── SalesReport.jsx
│   │       ├── StockReport.jsx
│   │       └── ShipmentReport.jsx
│   │
│   ├── services/
│   │   └── (igual que frontend)
│   │
│   └── App.jsx
│
└── package.json

---

🔌 INTEGRACIONES - APIs Externas

1. MercadoLibre API

Documentación: https://developers.mercadolibre.cl

Flujo de integración:

1. Autenticación OAuth 2.0
2. Publicar producto con precio ajustado (+10%)
3. Webhook para notificaciones de ventas
4. Sincronización de stock automática
5. Actualización de precios

Endpoints clave:

• POST /items - Publicar producto
• PUT /items/:id - Actualizar producto
• PUT /items/:id/stock - Actualizar stock
• GET /orders/search - Buscar órdenes

2. Instagram Shopping (Facebook Graph API)

Documentación: https://developers.facebook.com/docs/commerce-platform

Flujo de integración:

1. Crear cuenta empresarial de Instagram
2. Vincular catálogo de productos
3. Sincronizar productos como publicaciones comprables
4. Webhook para interacciones

Endpoints clave:

• POST /catalog - Crear catálogo
• POST /products - Agregar productos
• PATCH /products/:id - Actualizar producto

3. BlueExpress API

Documentación: Contacto directo con BlueExpress

Flujo de integración:

1. Credenciales API (solicitar a BlueExpress)
2. Cotizar envío según destino y peso
3. Generar orden de envío
4. Obtener tracking number
5. Webhook para estados de envío

Funciones:

• Cotización automática en checkout
• Generación de etiquetas
• Tracking en tiempo real

4. Pasarela de Pagos - Webpay Plus (Transbank)

Documentación: https://www.transbankdevelopers.cl

Flujo de integración:

1. Obtener credenciales (ambiente de prueba/producción)
2. Crear transacción en checkout
3. Redireccionar a Webpay
4. Confirmar transacción con callback
5. Guardar comprobante

Alternativas:

• Flow (más simple)
• Mercado Pago (ya integrado si usas ML)
• Khipu (transferencias)

---

📋 VARIABLES DE ENTORNO (.env)

# Server
NODE_ENV=development
PORT=3000

# Database
DBTYPE=postgres
DBHOST=localhost
DBPORT=5432
DBNAME=ofertaweb
DBUSER=postgres
DBPASS=tu_password

# JWT
JWT_SECRET=tu_secreto_super_seguro
JWT_EXPIRES_IN=7d

# URLs
FRONTEND_URL=http://localhost:5173
ADMIN_URL=http://localhost:5174
API_URL=http://localhost:3000

# MercadoLibre
ML_CLIENT_ID=tu_client_id
ML_CLIENT_SECRET=tu_client_secret
ML_REDIRECT_URI=http://localhost:3000/api/channels/mercadolibre/callback
ML_PRICE_FACTOR=1.10

# Instagram/Facebook
FB_APP_ID=tu_app_id
FB_APP_SECRET=tu_app_secret
FB_ACCESS_TOKEN=tu_access_token

# BlueExpress
BLUEX_API_KEY=tu_api_key
BLUEX_API_SECRET=tu_api_secret
BLUEX_ORIGIN_COMMUNE=santiago

# Transbank/Webpay
TRANSBANK_COMMERCE_CODE=tu_codigo_comercio
TRANSBANK_API_KEY=tu_api_key
TRANSBANK_ENVIRONMENT=integration

# Email (Nodemailer)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=tu_email@gmail.com
SMTP_PASS=tu_password

# Uploads
MAX_FILE_SIZE=5242880
ALLOWED_IMAGE_TYPES=image/jpeg,image/png,image/webp

---

🚦 HOJA DE RUTA - FASES DE DESARROLLO

FASE 1: Fundamentos del Backend (Semana 1-2)

• Configurar estructura de carpetas
• Instalar dependencias necesarias
• Crear esquema de base de datos
• Ejecutar migraciones
• Implementar modelos básicos
• Sistema de autenticación (JWT)
• Middleware de autenticación y roles

FASE 2: Módulo de Productos (Semana 2-3)

• CRUD de categorías
• CRUD de productos
• Sistema de imágenes múltiples
• Validaciones
• Filtros y búsqueda
• Paginación

FASE 3: Sistema de Stock Multi-Canal (Semana 3-4)

• Modelo de inventario unificado
• Servicio de sincronización de stock
• Tabla de canales
• Relación producto-canal
• Reglas de precios por canal
• Logs de sincronización

FASE 4: Carrito y Órdenes (Semana 4-5)

• Carrito de compras (usuarios + invitados)
• Creación de órdenes
• Cálculo de totales
• Reserva temporal de stock
• Estados de órdenes
• Historial de órdenes del usuario

FASE 5: Integración MercadoLibre (Semana 5-6)

• OAuth 2.0 authentication
• Publicar producto en ML
• Actualizar precio (+10%)
• Sincronizar stock
• Webhook de ventas ML
• Importar órdenes de ML

FASE 6: Integración Instagram Shopping (Semana 6-7)

• Configurar Facebook Business
• Crear catálogo de productos
• Sincronizar productos
• Actualizar stock en tiempo real
• Webhook de interacciones

FASE 7: Sistema de Envíos (BlueExpress) (Semana 7-8)

• Integración API BlueExpress
• Cotización automática en checkout
• Generación de orden de envío
• Obtener tracking number
• Actualización de estados
• Webhook de tracking

FASE 8: Pasarela de Pagos (Semana 8-9)

• Integración Webpay Plus
• Crear transacción
• Callback de confirmación
• Validar pago
• Actualizar estado de orden
• Envío de comprobante por email

FASE 9: Sistema de Despacho (Semana 9-10)

• Modelo de shipments
• Estados de despacho
• Asignación de repartidor
• Tracking interno
• Comprobante de entrega
• Notificaciones al cliente

FASE 10: Frontend Tienda (Semana 10-12)

• Setup del proyecto React
• Componentes de layout
• Página de inicio
• Catálogo de productos
• Detalle de producto
• Carrito de compras
• Proceso de checkout
• Integración con pasarela
• Seguimiento de pedido
• Perfil de usuario

FASE 11: Panel de Administración (Semana 12-14)

• Setup del proyecto admin
• Dashboard con estadísticas
• CRUD de productos
• Gestión de categorías
• Control de inventario
• Gestión de órdenes
• Panel de despachos
• Sincronización de canales
• Configuración del sistema
• Reportes

FASE 12: Testing y Optimización (Semana 14-15)

• Tests unitarios (backend)
• Tests de integración
• Optimización de queries
• Manejo de errores
• Logs del sistema
• Seguridad (sanitización, rate limiting)
• Documentación de API (Swagger)

FASE 13: Deploy y Producción (Semana 15-16)

• Configurar servidor (VPS/AWS/Heroku)
• Deploy del backend
• Deploy del frontend
• Deploy del admin
• Configurar dominio y SSL
• Credenciales de producción (ML, IG, Transbank)
• Backups automáticos
• Monitoreo

---

📦 DEPENDENCIAS PRINCIPALES

Backend (package.json)

{
  "dependencies": {
    "express": "^5.2.1",
    "pg": "^8.16.3",
    "dotenv": "^17.2.3",
    "cors": "^2.8.5",
    "bcryptjs": "^2.4.3",
    "jsonwebtoken": "^9.0.2",
    "joi": "^17.11.0",
    "multer": "^1.4.5-lts.1",
    "sharp": "^0.33.1",
    "axios": "^1.6.2",
    "node-cron": "^3.0.3",
    "nodemailer": "^6.9.7",
    "mercadolibre": "^0.0.13",
    "winston": "^3.11.0"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "supertest": "^6.3.3",
    "nodemon": "^3.0.2"
  }
}

Frontend/Admin (package.json)

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.20.1",
    "axios": "^1.6.2",
    "zustand": "^4.4.7",
    "tailwindcss": "^3.3.6",
    "@headlessui/react": "^1.7.17",
    "react-hook-form": "^7.48.2",
    "react-hot-toast": "^2.4.1",
    "chart.js": "^4.4.1",
    "react-chartjs-2": "^5.2.0"
  },
  "devDependencies": {
    "vite": "^5.0.8",
    "@vitejs/plugin-react": "^4.2.1"
  }
}

---

🎯 MÉTRICAS DE ÉXITO

KPIs Técnicos

• Tiempo de respuesta API < 200ms
• Disponibilidad del sistema > 99%
• Sincronización de stock en < 5 minutos
• Tasa de error en integraciones < 1%

KPIs de Negocio

• Conversión de carrito a orden > 10%
• Tiempo promedio de despacho < 48h
• Satisfacción del cliente > 4.5/5
• Ventas multi-canal > 30% del total

---

📞 PREGUNTAS PENDIENTES

1. ✅ Pasarela de pagos: ¿Webpay Plus, Flow, Mercado Pago o Khipu?
2. ✅ Cuenta MercadoLibre: ¿Ya tienes cuenta de desarrollador?
3. ✅ Instagram Business: ¿Cuenta empresarial configurada?
4. ✅ BlueExpress: ¿Contrato existente o explorar Chilexpress/Starken?
5. ❓ Hosting: ¿Dónde desplegar? (AWS, Heroku, VPS propio, Vercel)
6. ❓ Email: ¿Qué servicio de email? (Gmail, SendGrid, AWS SES)

---

📝 NOTAS ADICIONALES

• El sistema debe ser escalable para agregar más canales en el futuro
• Considerar cache (Redis) para mejorar performance
• Implementar rate limiting en APIs
• Sistema de logs robusto para debugging
• Webhooks para mantener sincronización en tiempo real
• Cron jobs como respaldo de sincronización

---

Última actualización: Diciembre 5, 2025
Estado: Planificación inicial