397 lines
11 KiB
Markdown
397 lines
11 KiB
Markdown
---
|
|
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
|