# 🚀 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 ```sql 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 ```sql 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 ```sql 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) ```sql 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 ```sql 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 ```sql 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 ```sql 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 ```sql 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 ```sql 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) ```bash # 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) - [x] 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) ```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) ```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