---
id: EPIC-MCH-014
type: Epic
title: "MCH-014: Gestion de Clientes"
code: MCH-014
status: Completado
phase: 4
priority: P1
created_at: 2026-01-06
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 21
dependencies:
  blocks: []
  depends_on: []
---

# MCH-014: Gestion de Clientes

## Metadata
- **Codigo:** MCH-014
- **Fase:** 4 - Pedidos y Clientes
- **Prioridad:** P1
- **Estado:** Completado
- **Story Points:** 21
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-07

## Descripcion

Sistema completo de gestion de clientes: registro, historial de compras, saldo de fiado, comunicacion via WhatsApp, y segmentacion basica.

## Objetivos

1. CRUD de clientes
2. Historial de compras por cliente
3. Integracion con sistema de fiados
4. Comunicacion via WhatsApp
5. Segmentacion basica (frecuencia, monto)

## Alcance

### Incluido
- Registro de clientes (nombre, telefono, direccion)
- Historial de compras
- Saldo de fiado integrado
- Envio de mensajes WhatsApp
- Tags/etiquetas para segmentacion
- Notas por cliente

### Excluido
- CRM avanzado
- Campanas de marketing automatizadas
- Programas de lealtad (fase posterior)

## Modelo de Datos

### Tablas (schema: customers)

**customers**
- id, tenant_id, name, phone
- email (opcional), address
- credit_enabled, credit_limit, balance
- tags (JSONB), notes, status
- first_purchase_at, last_purchase_at
- total_purchases, total_spent

**customer_purchases** (vista agregada)
- Derivado de sales por customer_id

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /customers | Listar clientes |
| GET | /customers/:id | Obtener cliente |
| POST | /customers | Crear cliente |
| PUT | /customers/:id | Actualizar cliente |
| DELETE | /customers/:id | Eliminar cliente |
| GET | /customers/:id/purchases | Historial compras |
| GET | /customers/:id/credit | Estado de fiado |
| POST | /customers/:id/message | Enviar WhatsApp |
| GET | /customers/segments | Segmentos |

## Flujos de Usuario

### Registrar Cliente Nuevo
```
1. Durante venta, empleado pregunta nombre
2. Ingresa telefono (obligatorio para fiado)
3. Cliente creado con datos basicos
4. Opcionalmente: direccion para entregas
```

### Ver Historial de Cliente
```
1. Dueno busca cliente por nombre/telefono
2. Abre ficha del cliente
3. Ve:
   - Datos de contacto
   - Total comprado historico
   - Ultimas 10 compras
   - Saldo de fiado
   - Notas
```

### Enviar Mensaje WhatsApp
```
1. Dueno abre ficha de cliente
2. Click en "Enviar WhatsApp"
3. Selecciona template o escribe mensaje
4. Mensaje enviado via WhatsApp Service
```

### Segmentar Clientes
```
1. Dueno abre lista de clientes
2. Filtra por:
   - Con/sin fiado
   - Frecuencia (semanal, mensual, ocasional)
   - Monto (alto, medio, bajo)
3. Puede asignar tags personalizados
```

## UI Components

### CustomerList
- Tabla con: nombre, telefono, total, fiado
- Busqueda por nombre/telefono
- Filtros por tags, estado

### CustomerForm
- Campos: nombre, telefono, email, direccion
- Toggle credito + limite
- Tags
- Notas

### CustomerDetail
- Info de contacto
- Metricas: total, # compras, promedio
- Historial de compras
- Historial de fiado
- Boton WhatsApp

### CreditHistory
- Lista de movimientos
- Grafica de saldo en el tiempo
- Botones: registrar abono, enviar recordatorio

## Segmentacion

### Por Frecuencia
| Segmento | Criterio |
|----------|----------|
| Frecuente | >= 4 compras/mes |
| Regular | 2-3 compras/mes |
| Ocasional | 1 compra/mes |
| Inactivo | 0 compras en 30 dias |

### Por Valor
| Segmento | Criterio |
|----------|----------|
| Alto valor | >= $2000/mes |
| Medio | $500-$2000/mes |
| Bajo | < $500/mes |

### Tags Personalizados
- Ejemplos: "vecino", "oficina", "escuela", "mayoreo"

## Historias de Usuario

### MCH-US-130: Registrar cliente nuevo
**Story Points:** 3

**Como** empleado de ventas
**Quiero** crear un cliente rapidamente durante una venta
**Para** registrar contactos y poder consultar su historial en futuras transacciones

#### Criterios de Aceptación
- [CA-130-1] El formulario solicita nombre (requerido) y telefono (requerido)
- [CA-130-2] Email y direccion son opcionales
- [CA-130-3] El cliente se crea exitosamente y se muestra en el listado
- [CA-130-4] Se valida que no exista otro cliente con el mismo telefono

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-130-01 | Crear modelo Customer en backend | 2h |
| MCH-TT-130-02 | Implementar endpoint POST /customers | 3h |
| MCH-TT-130-03 | Crear componente CustomerForm.tsx | 4h |
| MCH-TT-130-04 | Validar duplicados por telefono | 2h |

---

### MCH-US-131: Ver historial de compras de cliente
**Story Points:** 3

**Como** dueno de tienda
**Quiero** consultar todas las compras historicas de un cliente
**Para** entender su comportamiento de compra y patrones

#### Criterios de Aceptación
- [CA-131-1] El historial muestra todas las compras del cliente
- [CA-131-2] Se muestran fecha, monto, productos y metodo de pago
- [CA-131-3] El historial esta ordenado por fecha descendente
- [CA-131-4] Se muestra total historico y cantidad de compras

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-131-01 | Crear vista customer_purchases en BD | 2h |
| MCH-TT-131-02 | Implementar endpoint GET /customers/:id/purchases | 3h |
| MCH-TT-131-03 | Crear componente CustomerPurchaseHistory.tsx | 4h |
| MCH-TT-131-04 | Agregar metricas: total, promedio, frecuencia | 2h |

---

### MCH-US-132: Gestionar saldo de fiado
**Story Points:** 4

**Como** dueno de tienda
**Quiero** ver y actualizar el saldo de fiado de un cliente
**Para** controlar credito y cobros pendientes

#### Criterios de Aceptación
- [CA-132-1] Se muestra el limite de credito y saldo actual
- [CA-132-2] Se puede registrar un abono manualmente
- [CA-132-3] Se muestra historial de movimientos de fiado
- [CA-132-4] Se previene exceder el limite de credito en ventas
- [CA-132-5] Se calcula saldo automaticamente desde sales

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-132-01 | Extender tabla customers con campos credit | 2h |
| MCH-TT-132-02 | Crear tabla credit_movements | 2h |
| MCH-TT-132-03 | Implementar logica de validacion de credito | 4h |
| MCH-TT-132-04 | Crear componente CreditHistory.tsx | 4h |
| MCH-TT-132-05 | Endpoint para registrar abono | 3h |

---

### MCH-US-133: Enviar mensaje WhatsApp a cliente
**Story Points:** 3

**Como** dueno de tienda
**Quiero** enviar mensajes WhatsApp a mis clientes
**Para** comunicarme sobre pedidos, recordatorios y cobros

#### Criterios de Aceptación
- [CA-133-1] Existe boton "Enviar WhatsApp" en ficha de cliente
- [CA-133-2] Se puede escribir un mensaje personalizado
- [CA-133-3] Se puede seleccionar un template predefinido
- [CA-133-4] El mensaje se envia al numero de cliente almacenado
- [CA-133-5] Se registra el envio en el historial del cliente

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-133-01 | Configurar servicio WhatsApp API | 3h |
| MCH-TT-133-02 | Crear tabla message_log para audit | 2h |
| MCH-TT-133-03 | Implementar endpoint POST /customers/:id/message | 3h |
| MCH-TT-133-04 | Crear componente WhatsAppSender.tsx | 4h |
| MCH-TT-133-05 | Crear templates predefinidos | 2h |

---

### MCH-US-134: Segmentar clientes por frecuencia
**Story Points:** 4

**Como** dueno de tienda
**Quiero** segmentar mis clientes por frecuencia de compra
**Para** identificar clientes frecuentes e inactivos

#### Criterios de Aceptación
- [CA-134-1] Se calculan 4 segmentos: Frecuente (>=4/mes), Regular (2-3/mes), Ocasional (1/mes), Inactivo (0/30d)
- [CA-134-2] Se puede filtrar el listado de clientes por segmento
- [CA-134-3] El calculo se actualiza diariamente
- [CA-134-4] Se muestra el segmento en la ficha del cliente

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-134-01 | Crear función de calculo de frecuencia | 2h |
| MCH-TT-134-02 | Agregar columnas frequency_segment a customers | 1h |
| MCH-TT-134-03 | Crear job batch para actualizar diariamente | 3h |
| MCH-TT-134-04 | Implementar filtro en GET /customers | 2h |
| MCH-TT-134-05 | Mostrar segmento en UI | 2h |

---

### MCH-US-135: Asignar tags y notas a cliente
**Story Points:** 2

**Como** dueno de tienda
**Quiero** agregar tags personalizados (vecino, oficina, mayoreo) y notas a clientes
**Para** categorizar y recordar detalles importantes

#### Criterios de Aceptación
- [CA-135-1] Se puede asignar multiples tags a un cliente
- [CA-135-2] Se pueden crear tags personalizados
- [CA-135-3] Se puede escribir y editar notas
- [CA-135-4] Los tags aparecen en el listado y detalle del cliente
- [CA-135-5] Se puede filtrar por tags

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-135-01 | Agregar columnas tags (JSONB) y notes a customers | 1h |
| MCH-TT-135-02 | Crear CRUD para tags | 2h |
| MCH-TT-135-03 | Agregar inputs de tags/notas en CustomerForm | 2h |
| MCH-TT-135-04 | Implementar filtro por tags | 2h |

---

### MCH-US-136: Segmentar clientes por valor de compra
**Story Points:** 2

**Como** dueno de tienda
**Quiero** segmentar mis clientes por valor total de compra
**Para** identificar clientes de alto valor e inactivos

#### Criterios de Aceptación
- [CA-136-1] Se calculan 3 segmentos: Alto (>=2000/mes), Medio (500-2000/mes), Bajo (<500/mes)
- [CA-136-2] Se puede filtrar el listado por segmento de valor
- [CA-136-3] El calculo se actualiza diariamente
- [CA-136-4] Se muestra el segmento en la ficha del cliente

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-136-01 | Crear función de calculo de valor | 2h |
| MCH-TT-136-02 | Agregar columna value_segment a customers | 1h |
| MCH-TT-136-03 | Actualizar job batch | 1h |
| MCH-TT-136-04 | Mostrar en UI y filtro | 2h |

---

### Resumen de Story Points
| Historia | Descripción | SP |
|----------|-------------|-----|
| MCH-US-130 | Registrar cliente nuevo | 3 |
| MCH-US-131 | Ver historial de compras | 3 |
| MCH-US-132 | Gestionar saldo de fiado | 4 |
| MCH-US-133 | Enviar mensaje WhatsApp | 3 |
| MCH-US-134 | Segmentar por frecuencia | 4 |
| MCH-US-135 | Asignar tags y notas | 2 |
| MCH-US-136 | Segmentar por valor | 2 |
| **Total** | | **21** |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL customers | Completado | `08-customers.sql` |
| customers.module | Completado | `modules/customers/` |
| Customers.tsx | Completado | `pages/Customers.tsx` |
| CustomerList.tsx | Completado | `components/customers/` |
| CustomerForm.tsx | Completado | `components/customers/` |

## Dependencias

### Depende de
- MCH-002 (Auth)
- MCH-004 (Sales - para historial)

### Bloquea a
- MCH-008 (Fiados)
- MCH-013 (Chat cliente)
- MCH-015 (Pedidos WhatsApp)

## Criterios de Aceptacion

- [x] CRUD de clientes funciona
- [x] Historial de compras se muestra
- [x] Fiado integrado correctamente
- [x] Busqueda por nombre/telefono
- [x] Tags funcionan
- [x] Boton WhatsApp envia mensaje

## Metricas Calculadas

```typescript
// Se actualizan en cada venta
customer.total_purchases++
customer.total_spent += sale.total
customer.last_purchase_at = new Date()

// Calculo de segmento (batch job diario)
customer.frequency_segment = calculateFrequency(customer)
customer.value_segment = calculateValue(customer)
```

---

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