rckrdmrd
928eb795e6
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8 - Cambios en backend y frontend Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
198 lines
4.5 KiB
Markdown
198 lines
4.5 KiB
Markdown
# 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
|