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

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-014	Epic	MCH-014: Gestion de Clientes	MCH-014	Completado	4	P1	2026-01-06	2026-01-17	4.0.1	21	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

• 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-17