# 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

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