Files
ofertaweb.cl/PLANIFICACION.md
cesar 2a88b4a71b Initial commit: Estructura backend y frontend con estándar VPS
- Backend migrado a estructura VPS (src/ subfolder)
- Frontend con estructura Vite + React 19 + Tailwind
- Configuración PostgreSQL con Pool
- API service con interceptores JWT
- Ambos servidores funcionando (backend:3001, frontend:5173)
2025-12-09 00:35:46 -03:00

850 lines
23 KiB
Markdown

# 🚀 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