# Módulo E-commerce integrado al ERP (estilo Jack Center)

**Referencia UX:** [farmaciajackcenter.com.py](https://farmaciajackcenter.com.py/) — header con búsqueda, categorías, destacados, novedades, carrito lateral, cambio de moneda.

**Stack actual (sin cambiar):** PHP 8 + MySQL + sesiones ERP + API JSON.

**Ya existente en tu proyecto (reutilizar):**
- Tablas `pedidos_web`, `pedidos_web_items`, `clientes_unificados`, `reservas_stock_web`
- Stock depósito Departamento (id 1647), ventas ERP, panel `gestionar_pedidos_web.php`
- API `ec_tienda_api.php?r=*` / `api_ecommerce/*`
- Opcional: storefront Next.js `pharma-tienda/` (Vercel)

Este documento define la **versión 2**: tienda **dentro del hosting PHP** (sin depender de Vercel), WhatsApp + transferencia/efectivo, catálogo enriquecido.

---

## 1. Arquitectura recomendada

```
┌─────────────────────────────────────────────────────────────┐
│  TIENDA PÚBLICA (PHP + JS)                                   │
│  /ecomerce/tienda/  → index, catálogo, carrito, checkout    │
└───────────────────────────┬─────────────────────────────────┘
                            │ AJAX / fetch
┌───────────────────────────▼─────────────────────────────────┐
│  API REST  /ecomerce/api_tienda/v1/                          │
│  catálogo | carrito | pedidos | checkout | whatsapp          │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  NÚCLEO ERP (existente)                                      │
│  productos | stock_deposito | ventas | clientes_unificados   │
│  funciones_ecommerce*.php | pedidos_web                      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  ADMIN ERP (sesión + permisos)                               │
│  admin_tienda_productos.php | categorias | banners | dash   │
└─────────────────────────────────────────────────────────────┘
```

**Por qué PHP en `/ecomerce/tienda/`:** ya tenés hosting en `distribuidorapharma.com.py/ecomerce`; evita el conflicto DNS con Vercel y el “Index of /”.

---

## 2. Estructura de carpetas (nuevo)

```
mayo copia/
├── MIGRACION_ECOMMERCE_V2_CATALOGO.sql
├── funciones_tienda_publica.php      # catálogo web, banners, WhatsApp
├── api_tienda/
│   ├── _bootstrap.php                # CORS, JSON, rate limit opcional
│   └── v1/
│       ├── catalogo.php              # GET categorías, productos, búsqueda
│       ├── producto.php              # GET ficha
│       ├── carrito.php               # GET/POST/DELETE sesión carrito
│       ├── pedido.php                # POST crear pedido
│       ├── checkout.php              # POST confirmar + método pago
│       └── config.php                # monedas, banners, métodos pago
├── tienda/                           # Frontend público (Jack-style)
│   ├── index.php
│   ├── catalogo.php
│   ├── producto.php
│   ├── carrito.php
│   ├── checkout.php
│   ├── assets/
│   │   ├── css/tienda.css
│   │   └── js/carrito.js
│   └── components/
│       ├── header.php
│       ├── footer.php
│       └── product-card.php
├── admin_tienda/
│   ├── dashboard_tienda.php
│   ├── categorias_web.php
│   ├── productos_web.php
│   ├── banners_web.php
│   └── pedidos_web.php             # redirect o embed gestionar_pedidos_web
└── (existente) gestionar_pedidos_web.php, api_ecommerce/, ...
```

---

## 3. Modelo de datos (nuevo + existente)

### Tablas nuevas (ver `MIGRACION_ECOMMERCE_V2_CATALOGO.sql`)

| Tabla | Uso |
|-------|-----|
| `ec_categorias` | Suplementos, cosméticos, etc. (árbol opcional `parent_id`) |
| `ec_producto_web` | Overlay ERP `productos`: slug, descripción HTML, visible, destacado, novedad |
| `ec_producto_categorias` | N:N producto ↔ categoría |
| `ec_producto_imagenes` | URLs o rutas `/uploads/tienda/` |
| `ec_banners` | Hero promocional (imagen, link, orden, vigencia) |
| `ec_metodos_pago` | transferencia, efectivo, whatsapp, bancard (futuro) |
| `ec_sucursales` | Multi-sucursal futuro (CDE, CDEste, etc.) |

### Tablas existentes (extender)

| Tabla | Campos nuevos |
|-------|----------------|
| `pedidos_web` | `metodo_pago`, `moneda_display` (PYG/USD/BRL), `sucursal_id`, `whatsapp_enviado`, `direccion_entrega` |
| `productos` | (sin duplicar) precio desde ERP; USD vía tasa del día |

### Relación con ERP

- **Stock:** `stock_deposito` depósito canal (1647) — ya implementado.
- **Venta:** `ecommerce_confirmar_pedido_pagado()` → `ventas` — ya implementado.
- **Cliente:** `clientes_unificados` — ya implementado.

---

## 4. API REST — `api_tienda/v1/`

Base: `https://distribuidorapharma.com.py/ecomerce/api_tienda/v1/`

Auth tienda pública: sin API Key en lectura catálogo; **POST pedido** puede usar token sesión o clave opcional `TIENDA_API_PUBLIC_KEY`.

### Catálogo

| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | `config.php` | Monedas, tasa USD/BRL, banners activos, métodos pago |
| GET | `catalogo.php` | `?categoria=&q=&page=&orden=` lista + filtros |
| GET | `producto.php` | `?id=` o `?slug=` ficha completa |
| GET | `categorias.php` | Árbol de categorías |

**Respuesta producto (ejemplo):**
```json
{
  "ok": true,
  "data": {
    "id": 12,
    "nombre": "Whey Protein",
    "slug": "whey-protein-12",
    "precios": { "pyg": 350000, "usd": 52.23, "brl": 0 },
    "stock": { "disponible": 24 },
    "imagenes": ["/uploads/tienda/12/principal.jpg"],
    "categorias": ["Suplementos"],
    "descripcion_html": "<p>...</p>"
  }
}
```

### Carrito (sesión PHP o localStorage + sync)

| Método | Ruta | Body |
|--------|------|------|
| GET | `carrito.php` | Estado carrito sesión |
| POST | `carrito.php` | `{ "action": "add", "producto_id": 1, "cantidad": 2 }` |
| POST | `carrito.php` | `{ "action": "update", "items": [...] }` |
| DELETE | `carrito.php` | `{ "producto_id": 1 }` |

### Pedido y checkout

| Método | Ruta | Body |
|--------|------|------|
| POST | `pedido.php` | Cliente + items + `moneda` (PYG/USD) |
| POST | `checkout.php` | `{ "uuid", "metodo_pago": "whatsapp\|transferencia\|efectivo" }` |

**WhatsApp:** respuesta incluye `whatsapp_url` con texto prearmado del pedido.

**Transferencia / efectivo:** estado `pendiente_pago` → operador confirma en `gestionar_pedidos_web.php`.

### Admin (ERP session cookie o API Key admin)

| Método | Ruta | Auth |
|--------|------|------|
| CRUD | `admin/categorias.php` | Sesión ERP |
| CRUD | `admin/productos-web.php` | Sesión ERP |
| CRUD | `admin/banners.php` | Sesión ERP |
| GET | `admin/dashboard.php` | KPIs pedidos, stock bajo |

*(Los CRUD admin pueden ser solo PHP server-rendered en `admin_tienda/` sin REST, más rápido en tu stack.)*

---

## 5. Flujos de negocio

### Compra con WhatsApp

1. Cliente arma carrito (AJAX).
2. Checkout: nombre, teléfono, dirección, método **WhatsApp**.
3. `POST pedido.php` → crea `pedidos_web` + reserva stock.
4. `POST checkout.php` → genera link `https://wa.me/5959XXXX?text=Pedido%20...`.
5. Operador recibe mensaje → confirma pago manual en panel → `confirmar_pago` → venta ERP.

### Transferencia / efectivo

- Igual, estado `pendiente_pago`, sin pasarela.
- Panel: botón “Confirmar pago” (ya existe).

### Pagos online (futuro)

- `ec_metodos_pago.codigo = bancard` → reutilizar `checkout.php` + `api_ecommerce/checkout.php` existente.

---

## 6. Frontend (Jack Center — componentes)

| Sección | Implementación |
|---------|----------------|
| Header | Logo, buscador, selector PYG/USD, icono carrito con contador |
| Nav categorías | Tabs desde `ec_categorias` |
| Hero | Carrusel `ec_banners` |
| Destacados | `ec_producto_web.destacado = 1` |
| Novedades | Orden por `productos.fecha_creacion` o flag `novedad` |
| Grid productos | Cards con imagen, precio dual, badge stock |
| Carrito lateral | Drawer AJAX |
| Footer | Horario, entregas, ubicación (configurable) |

Archivos ejemplo en `/tienda/` (generados en este sprint).

---

## 7. Panel administrativo ERP

| Módulo | Permiso sugerido |
|--------|------------------|
| Dashboard tienda | `admin_tienda` |
| Categorías web | `admin_tienda` |
| Productos web (visibilidad, fotos, SEO) | `admin_tienda` |
| Banners | `admin_tienda` |
| Pedidos | `gestionar_pedidos_web` (existente) |

Registrar en `modulos_sistema.php`.

---

## 8. Multi-moneda y sucursales

| Moneda | Implementación |
|--------|----------------|
| PYG (Gs) | Base ERP + `tasas` |
| USD | `precio_brl` o campo USD + tasa `real_a_gs` inversa |
| BRL | Ya en canal headless Bancard/MP |

| Sucursal | `ec_sucursales` + `pedidos_web.sucursal_id` + stock por depósito |

---

## 9. Roadmap de implementación

| Fase | Entregable | Días est. |
|------|------------|-----------|
| **F1** | SQL V2 + categorías + imágenes + banners | 2 |
| **F2** | API v1 catálogo + carrito sesión | 3 |
| **F3** | Tienda pública `/tienda/` (UX Jack) | 4 |
| **F4** | Checkout WhatsApp + transferencia/efectivo | 2 |
| **F5** | Admin CRUD + dashboard | 3 |
| **F6** | Unificar con `pedidos_web` + panel existente | 1 |

**Total estimado:** 15 días hábiles (1 dev).

---

## 10. Coexistencia con pharma-tienda (Next.js)

| Canal | URL | Uso |
|-------|-----|-----|
| Tienda PHP | `distribuidorapharma.com.py/ecomerce/tienda/` | Principal Paraguay, WhatsApp |
| Next.js | `tienda.distribuidorapharma.com.py` | Opcional BRL/Bancard internacional |

Ambos consumen la misma API y tablas `pedidos_web`.

---

## 11. Próximo paso técnico inmediato

1. Ejecutar `MIGRACION_ECOMMERCE_V2_CATALOGO.sql`
2. Subir carpeta `tienda/` y `api_tienda/` al hosting
3. Probar `tienda/index.php` y `api_tienda/v1/config.php`