michangarrito/docs/01-epicas/MCH-014-gestion-clientes.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-014	Epic	MCH-014: Gestion de Clientes	MCH-014	Completado	4	P1	2026-01-06	2026-01-10	3.8.0	blocks depends_on

MCH-014: Gestion de Clientes

Metadata

• Codigo: MCH-014
• Fase: 4 - Pedidos y Clientes
• Prioridad: P1
• Estado: Completado
• 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"

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

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

Metricas Calculadas

// 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-07