ofertaweb.cl/backend/README.md

# OfertaWeb Backend

Backend API para tienda web multi-canal con integración a MercadoLibre, Instagram Shopping y BlueExpress.

## 📁 Estructura del Proyecto

```
backend/
├── server.js                 # Punto de entrada del servidor
├── package.json              # Dependencias y scripts
├── .env                      # Variables de entorno
├── .gitignore               # Archivos ignorados por git
├── src/                     # Código fuente
│   ├── config/              # Configuraciones (DB, etc)
│   ├── controllers/         # Controladores de rutas
│   ├── middlewares/         # Middlewares (auth, validation, etc)
│   ├── models/              # Modelos de datos
│   ├── routes/              # Definición de rutas
│   ├── services/            # Lógica de negocio
│   └── utils/               # Utilidades (logger, helpers)
├── migrations/              # Migraciones de base de datos
├── scripts/                 # Scripts de utilidad
├── public/                  # Archivos públicos
│   └── uploads/            # Imágenes subidas
├── logs/                    # Logs del servidor
└── tests/                   # Tests unitarios e integración
```

## 🚀 Inicio Rápido

### Requisitos Previos
- Node.js >= 18.x
- PostgreSQL >= 12
- npm o yarn

### Instalación

1. **Instalar dependencias:**
```bash
npm install
```

2. **Configurar variables de entorno:**
```bash
cp .env.example .env
# Editar .env con tus credenciales
```

3. **Ejecutar migraciones:**
```bash
psql -U postgres -d ofertaweb -f migrations/001_schema_completo.sql
psql -U postgres -d ofertaweb -f migrations/002_initial_data.sql
psql -U postgres -d ofertaweb -f migrations/003_create_admin_user.sql
psql -U postgres -d ofertaweb -f migrations/004_add_codigo_to_categories.sql
```

4. **Iniciar servidor:**
```bash
# Desarrollo
npm run dev

# Producción
npm start
```

El servidor estará disponible en `http://localhost:3001`

## 📋 Variables de Entorno

```env
# Puerto del servidor
PORT=3001

# Entorno
NODE_ENV=development

# Base de datos
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ofertaweb
DB_USER=ofertaweb_user
DB_PASSWORD=tu_password

# JWT
JWT_SECRET=tu_clave_secreta
JWT_EXPIRES_IN=7d

# CORS
FRONTEND_URL=http://localhost:5173
ADMIN_URL=http://localhost:5174
```

## 🛣️ API Endpoints

### Autenticación
- `POST /api/auth/login` - Iniciar sesión
- `POST /api/auth/register` - Registrar usuario
- `GET /api/auth/me` - Obtener usuario actual

### Productos
- `GET /api/products` - Listar productos
- `GET /api/products/:id` - Obtener producto
- `POST /api/products` - Crear producto (admin)
- `PUT /api/products/:id` - Actualizar producto (admin)
- `DELETE /api/products/:id` - Eliminar producto (admin)

### Categorías
- `GET /api/categories` - Listar categorías
- `GET /api/categories/tree` - Árbol de categorías
- `POST /api/categories` - Crear categoría (admin)
- `PUT /api/categories/:id` - Actualizar categoría (admin)

### Inventario
- `GET /api/inventory/:productId` - Ver inventario
- `POST /api/inventory/adjust` - Ajustar stock (admin)
- `GET /api/inventory/movements/:productId` - Historial de movimientos

### Órdenes
- `GET /api/orders` - Listar órdenes
- `GET /api/orders/:id` - Detalle de orden
- `POST /api/orders` - Crear orden
- `PATCH /api/orders/:id/status` - Actualizar estado (admin)

### Carrito
- `GET /api/cart` - Ver carrito
- `POST /api/cart/items` - Agregar producto
- `PUT /api/cart/items/:productId` - Actualizar cantidad
- `DELETE /api/cart/items/:productId` - Eliminar del carrito

### Uploads
- `POST /api/upload/product/:productId` - Subir imagen de producto
- `DELETE /api/upload/image/:imageId` - Eliminar imagen

## 🗄️ Base de Datos

### Módulos
1. **Usuarios y Autenticación** - users, user_addresses
2. **Catálogo** - categories, products, product_images
3. **Multi-Canal** - channels, channel_products
4. **Inventario** - inventory, inventory_movements
5. **Carrito** - carts, cart_items
6. **Órdenes** - orders, order_items, order_status_history
7. **Pagos** - payments
8. **Envíos** - shipments

## 🔧 Scripts Disponibles

```bash
# Desarrollo con auto-reload
npm run dev

# Iniciar en producción
npm start

# Ejecutar tests
npm test

# Generar hash de contraseña
node scripts/generate_password_hash.js
```

## 📝 Logs

Los logs se almacenan en la carpeta `logs/`:
- `error.log` - Solo errores
- `combined.log` - Todos los logs

## 🔐 Seguridad

- Autenticación mediante JWT
- Contraseñas hasheadas con bcrypt
- Validación de datos con Joi
- Protección CORS configurada
- Rate limiting implementado
- SQL injection prevention con prepared statements

## 🚧 Desarrollo

### Agregar nueva ruta

1. Crear controlador en `src/controllers/`
2. Crear modelo en `src/models/` (si aplica)
3. Definir ruta en `src/routes/`
4. Registrar en `server.js`

### Ejemplo:
```javascript
// src/controllers/ejemploController.js
const db = require('../config/db');

exports.getEjemplo = async (req, res) => {
  const result = await db.query('SELECT * FROM tabla');
  res.json(result.rows);
};

// src/routes/ejemploRoutes.js
const router = require('express').Router();
const controller = require('../controllers/ejemploController');

router.get('/', controller.getEjemplo);

module.exports = router;

// server.js
const ejemploRoutes = require('./src/routes/ejemploRoutes');
app.use('/api/ejemplo', ejemploRoutes);
```

## 📦 Dependencias Principales

- **express** - Framework web
- **pg** - Cliente PostgreSQL
- **jsonwebtoken** - Autenticación JWT
- **bcryptjs** - Hash de contraseñas
- **multer** - Upload de archivos
- **winston** - Sistema de logs
- **joi** - Validación de datos
- **cors** - Configuración CORS

## 🤝 Contribuir

1. Crear rama feature: `git checkout -b feature/nueva-funcionalidad`
2. Hacer cambios y commit: `git commit -m 'Agregar nueva funcionalidad'`
3. Push a la rama: `git push origin feature/nueva-funcionalidad`
4. Crear Pull Request

## 📄 Licencia

ISC