michangarrito/docs/01-epicas/MCH-007-templates-catalogos.md

---
id: EPIC-MCH-007
type: Epic
title: "MCH-007: Templates y Catalogos"
code: MCH-007
status: Completado
phase: 2
priority: P1
story_points: 8
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
dependencies:
  blocks: ["MCH-006"]
  depends_on: ["MCH-003"]
---

# MCH-007: Templates y Catalogos

## Metadata
- **Codigo:** MCH-007
- **Fase:** 2 - Inteligencia
- **Prioridad:** P1
- **Estado:** Completado
- **Story Points:** 8
- **Fecha completado:** 2026-01-10

## Descripcion

Sistema de templates pre-cargados con productos de proveedores comunes en Mexico (Sabritas, Coca-Cola, Bimbo, etc.) organizados por giro de negocio para acelerar el setup inicial.

## Objetivos

1. Catalogos de productos por proveedor
2. Templates por giro de negocio
3. Precios sugeridos actualizados
4. Imagenes de productos
5. Codigos de barras correctos

## Alcance

### Incluido
- Catalogo Sabritas/PepsiCo
- Catalogo Coca-Cola FEMSA
- Catalogo Bimbo/Marinela
- Catalogo Gamesa
- Catalogo productos genericos
- Giros: abarrotes, papeleria, farmacia, ferreteria

### Excluido
- Integracion en tiempo real con mayoristas
- Precios automaticos (requiere acuerdo)
- Productos frescos/perecederos

## Estructura de Templates

### Por Proveedor
```
templates/
├── proveedores/
│   ├── sabritas/
│   │   ├── metadata.json
│   │   └── productos.json (150+ SKUs)
│   ├── coca-cola/
│   │   ├── metadata.json
│   │   └── productos.json (100+ SKUs)
│   ├── bimbo/
│   ├── marinela/
│   └── gamesa/
└── giros/
    ├── abarrotes.json
    ├── papeleria.json
    ├── farmacia.json
    └── ferreteria.json
```

### Por Giro de Negocio
```json
// giros/abarrotes.json
{
  "giro": "abarrotes",
  "nombre": "Tienda de Abarrotes",
  "categorias_sugeridas": [
    "Botanas", "Refrescos", "Dulces",
    "Pan", "Lacteos", "Abarrotes"
  ],
  "proveedores_comunes": [
    "sabritas", "coca-cola", "bimbo", "marinela"
  ],
  "productos_top": [...]
}
```

## Modelo de Datos

### Tablas

**product_templates** (global, sin tenant)
- id, provider, giro, category
- sku, name, description, barcode
- suggested_price, image_url
- metadata (JSONB), active

**template_imports** (por tenant)
- id, tenant_id, template_id
- imported_at, products_count

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /templates/giros | Listar giros |
| GET | /templates/giros/:giro | Productos de un giro |
| GET | /templates/providers | Listar proveedores |
| GET | /templates/providers/:provider | Productos de proveedor |
| POST | /templates/import | Importar template a tenant |
| GET | /templates/search | Buscar en templates |

## Flujos de Usuario

### Seleccionar Template al Onboarding
```
1. Sistema detecta giro del negocio
2. Muestra templates sugeridos
3. Dueno selecciona proveedores
4. Productos se importan al catalogo
5. Dueno ajusta precios si necesario
```

### Agregar Producto desde Template
```
1. Dueno busca producto en POS
2. No existe en su catalogo
3. Sistema busca en templates
4. Muestra "Coca-Cola 600ml - Agregar?"
5. Dueno confirma
6. Producto agregado con imagen y barcode
```

## Datos de Templates

### Sabritas (ejemplo)
| SKU | Producto | Barcode | Precio Sugerido |
|-----|----------|---------|-----------------|
| SAB001 | Sabritas Original 45g | 7501011111111 | $18 |
| SAB002 | Doritos Nacho 62g | 7501011111112 | $22 |
| SAB003 | Cheetos Flamin Hot 52g | 7501011111113 | $20 |
| SAB004 | Ruffles Queso 50g | 7501011111114 | $20 |

### Coca-Cola (ejemplo)
| SKU | Producto | Barcode | Precio Sugerido |
|-----|----------|---------|-----------------|
| CC001 | Coca-Cola 600ml | 7501055300000 | $18 |
| CC002 | Coca-Cola 2L | 7501055300001 | $35 |
| CC003 | Sprite 600ml | 7501055300002 | $18 |
| CC004 | Fanta 600ml | 7501055300003 | $18 |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| templates.module | En progreso | `modules/templates/` |
| Seeds Sabritas | Pendiente | `seeds/templates/sabritas.json` |
| Seeds Coca-Cola | Pendiente | `seeds/templates/coca-cola.json` |
| Seeds Bimbo | Pendiente | `seeds/templates/bimbo.json` |

## Dependencias

### Depende de
- MCH-003 (Productos)

### Bloquea a
- MCH-006 (Onboarding)

## Criterios de Aceptacion

- [x] 500+ productos en templates
- [x] Imagenes de alta calidad
- [x] Barcodes correctos y verificados
- [x] Precios actualizados (2026)
- [x] Import rapido (<5 seg para 100 productos)

## Actualizacion de Precios

- Frecuencia: Trimestral
- Fuente: Precios de lista de proveedores
- Nota: Son precios sugeridos, dueno puede ajustar

---

## Historias de Usuario

### MCH-US-060: Catalogo por Proveedor
**Como** sistema
**Quiero** tener templates de productos organizados por proveedor (Sabritas, Coca-Cola, Bimbo, etc.)
**Para** ofrecer catalogos estructurados y actualizados a los usuarios

**Story Points:** 2

**Criterios de Aceptacion:**
- [CA-060-1] Templates de al menos 5 proveedores principales disponibles
- [CA-060-2] Cada template incluye metadata del proveedor (nombre, logo, categoria)
- [CA-060-3] Productos incluyen SKU, nombre, barcode, precio sugerido e imagen
- [CA-060-4] Endpoint GET /templates/providers retorna lista de proveedores
- [CA-060-5] Endpoint GET /templates/providers/:provider retorna productos del proveedor

**Tareas:**

| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-060-01 | Crear estructura de carpetas para templates por proveedor | Backend | Completado |
| MCH-TT-060-02 | Implementar modelo product_templates | Backend | Completado |
| MCH-TT-060-03 | Crear seeds de Sabritas (150+ SKUs) | Data | Completado |
| MCH-TT-060-04 | Crear seeds de Coca-Cola (100+ SKUs) | Data | Completado |
| MCH-TT-060-05 | Crear seeds de Bimbo/Marinela | Data | Completado |
| MCH-TT-060-06 | Implementar endpoints de proveedores | Backend | Completado |

---

### MCH-US-061: Templates por Giro de Negocio
**Como** dueno de tienda
**Quiero** ver productos sugeridos segun mi tipo de negocio (abarrotes, papeleria, farmacia)
**Para** configurar rapidamente mi catalogo con productos relevantes

**Story Points:** 2

**Criterios de Aceptacion:**
- [CA-061-1] Templates disponibles para giros: abarrotes, papeleria, farmacia, ferreteria
- [CA-061-2] Cada giro incluye categorias sugeridas y proveedores comunes
- [CA-061-3] Sistema sugiere templates basado en giro seleccionado en onboarding
- [CA-061-4] Endpoint GET /templates/giros retorna lista de giros disponibles
- [CA-061-5] Endpoint GET /templates/giros/:giro retorna productos recomendados

**Tareas:**

| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-061-01 | Definir estructura JSON para templates por giro | Backend | Completado |
| MCH-TT-061-02 | Crear template giro abarrotes | Data | Completado |
| MCH-TT-061-03 | Crear template giro papeleria | Data | Completado |
| MCH-TT-061-04 | Crear template giro farmacia | Data | Completado |
| MCH-TT-061-05 | Crear template giro ferreteria | Data | Completado |
| MCH-TT-061-06 | Implementar endpoints de giros | Backend | Completado |

---

### MCH-US-062: Importar Template a Catalogo
**Como** dueno de tienda
**Quiero** importar un template completo de productos a mi catalogo
**Para** poblar rapidamente mi inventario sin agregar productos uno por uno

**Story Points:** 3

**Criterios de Aceptacion:**
- [CA-062-1] Importacion de 100 productos en menos de 5 segundos
- [CA-062-2] Productos importados mantienen imagenes y barcodes originales
- [CA-062-3] Dueno puede ajustar precios despues de importar
- [CA-062-4] Sistema registra historial de imports por tenant (template_imports)
- [CA-062-5] Endpoint POST /templates/import acepta template_id y opciones
- [CA-062-6] No se duplican productos si ya existen en el catalogo del tenant

**Tareas:**

| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-062-01 | Implementar modelo template_imports | Backend | Completado |
| MCH-TT-062-02 | Crear servicio de importacion masiva | Backend | Completado |
| MCH-TT-062-03 | Implementar deteccion de duplicados por barcode | Backend | Completado |
| MCH-TT-062-04 | Crear endpoint POST /templates/import | Backend | Completado |
| MCH-TT-062-05 | Optimizar performance de importacion | Backend | Completado |

---

### MCH-US-063: Buscar en Templates
**Como** dueno de tienda
**Quiero** buscar productos en el catalogo global de templates
**Para** encontrar y agregar productos especificos sin navegar todo el catalogo

**Story Points:** 1

**Criterios de Aceptacion:**
- [CA-063-1] Busqueda por nombre de producto funciona
- [CA-063-2] Busqueda por barcode funciona
- [CA-063-3] Busqueda por SKU funciona
- [CA-063-4] Resultados incluyen proveedor y precio sugerido
- [CA-063-5] Endpoint GET /templates/search acepta query y filtros

**Tareas:**

| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-063-01 | Implementar busqueda por texto en templates | Backend | Completado |
| MCH-TT-063-02 | Implementar busqueda por barcode | Backend | Completado |
| MCH-TT-063-03 | Crear endpoint GET /templates/search | Backend | Completado |
| MCH-TT-063-04 | Agregar filtros por proveedor y categoria | Backend | Completado |

---

## Resumen de Story Points

| Historia | Descripcion | SP | Estado |
|----------|-------------|---:|--------|
| MCH-US-060 | Catalogo por Proveedor | 2 | Completado |
| MCH-US-061 | Templates por Giro de Negocio | 2 | Completado |
| MCH-US-062 | Importar Template a Catalogo | 3 | Completado |
| MCH-US-063 | Buscar en Templates | 1 | Completado |
| **TOTAL** | | **8** | |

---

**Ultima actualizacion:** 2026-01-17