---
id: EPIC-MCH-008
type: Epic
title: "MCH-008: Sistema de Fiados"
code: MCH-008
status: Completado
phase: 2
priority: P1
created_at: 2026-01-10
updated_at: 2026-01-10
story_points: 13
simco_version: "4.0.1"
dependencies:
  blocks: ["MCH-017"]
  depends_on: ["MCH-002", "MCH-004", "MCH-014"]
---

# MCH-008: Sistema de Fiados

## Metadata
- **Codigo:** MCH-008
- **Fase:** 2 - Inteligencia
- **Prioridad:** P1
- **Estado:** Completado
- **Story Points:** 13
- **Fecha completado:** 2026-01-10

## Descripcion

Sistema de credito informal ("fiados") tradicional en Mexico: permite a clientes frecuentes comprar a credito con limites personalizados, recordatorios automaticos de pago, y registro de abonos.

## Objetivos

1. Cuentas de credito por cliente
2. Limites de credito configurables
3. Registro de compras a credito
4. Registro de abonos/pagos
5. Recordatorios automaticos via WhatsApp
6. Reporte de cartera

## Alcance

### Incluido
- Habilitar credito por cliente
- Limite de credito configurable
- Ventas a credito desde POS
- Abonos parciales o totales
- Historial de movimientos
- Recordatorios via WhatsApp
- Bloqueo automatico por limite

### Excluido
- Intereses por mora
- Scoring crediticio
- Reportes a buro de credito
- Contratos formales

## Modelo de Datos

### Tablas (schema: customers)

**credit_accounts**
- id, customer_id, credit_limit
- current_balance, status (active/blocked/closed)
- created_at, last_payment_at

**credit_transactions**
- id, credit_account_id, type (charge/payment)
- amount, sale_id (si es cargo), notes
- created_at, created_by

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /customers/:id/credit | Estado de cuenta |
| POST | /customers/:id/credit/enable | Habilitar credito |
| PUT | /customers/:id/credit/limit | Ajustar limite |
| POST | /customers/:id/credit/payment | Registrar abono |
| GET | /customers/:id/credit/history | Historial |
| GET | /credit/portfolio | Cartera total |
| GET | /credit/overdue | Clientes con adeudo |

## Flujos de Usuario

### Habilitar Credito
```
1. Dueno abre ficha del cliente
2. Activa "Habilitar fiado"
3. Define limite (ej: $500)
4. Cliente puede comprar a credito
```

### Venta a Credito
```
1. Empleado crea venta en POS
2. Selecciona cliente con credito
3. Elige "Fiado" como pago
4. Sistema verifica:
   - Credito habilitado
   - Saldo + venta <= limite
5. Si OK: registra venta
6. Actualiza saldo del cliente
```

### Registrar Abono
```
1. Cliente llega a pagar
2. Dueno abre cuenta del cliente
3. Registra abono (monto)
4. Sistema actualiza saldo
5. Genera recibo de pago
```

### Recordatorio Automatico
```
1. Cron diario revisa cuentas
2. Identifica clientes con saldo > X dias
3. Envia WhatsApp:
   "Hola [nombre], tienes un saldo de $X
   en [negocio]. Pasa a ponerte al corriente!"
4. Registra envio de recordatorio
```

## UI Components

### CreditHistory
- Lista de movimientos (cargos/abonos)
- Saldo actual
- Grafica de historial
- Filtros por fecha

### CreditDashboard
- Total cartera
- Clientes con adeudo
- Promedio de dias de pago
- Alertas de limite

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL credit | Completado | `08-customers.sql` |
| fiados.module | En progreso | `modules/fiados/` |
| CreditHistory.tsx | En progreso | `components/customers/` |
| WhatsApp reminder | Pendiente | `whatsapp-service/` |

## Dependencias

### Depende de
- MCH-002 (Auth)
- MCH-004 (POS)
- MCH-014 (Clientes)

### Bloquea a
- MCH-017 (Notificaciones)

## Criterios de Aceptacion

- [x] Credito se habilita/deshabilita por cliente
- [x] Limite de credito funciona
- [x] Ventas a credito descuentan del disponible
- [x] Abonos se registran correctamente
- [x] Recordatorios se envian via WhatsApp
- [x] Reporte de cartera funciona

## Configuracion por Tenant

```typescript
{
  fiados: {
    enabled: true,
    default_limit: 500,
    max_limit: 5000,
    reminder_days: [7, 14, 30],
    auto_block_days: 60
  }
}
```

---

## Historias de Usuario

### MCH-US-070: Habilitar Credito Cliente
**Story Points:** 2

Como **dueno de changarrito**
Quiero **habilitar fiados para clientes de confianza con limites personalizados**
Para **ofrecer credito informal a clientes frecuentes sin perder control del riesgo**

#### Criterios de Aceptacion
- [CA-070-1] El dueno puede activar/desactivar credito desde la ficha del cliente
- [CA-070-2] Se puede definir un limite de credito entre $100 y el maximo configurado por tenant
- [CA-070-3] El sistema muestra el limite disponible y saldo actual
- [CA-070-4] Solo el rol dueno puede habilitar creditos

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-070-01 | Endpoint POST /customers/:id/credit/enable | 2h |
| MCH-TT-070-02 | Endpoint PUT /customers/:id/credit/limit | 2h |
| MCH-TT-070-03 | UI toggle y campo limite en CustomerDetail | 3h |
| MCH-TT-070-04 | Validaciones de permisos y limites | 2h |

---

### MCH-US-071: Venta a Credito
**Story Points:** 3

Como **empleado de changarrito**
Quiero **registrar ventas a fiado desde el POS seleccionando el cliente**
Para **agilizar la venta a credito sin procesos adicionales**

#### Criterios de Aceptacion
- [CA-071-1] En el POS aparece opcion "Fiado" solo si el cliente tiene credito habilitado
- [CA-071-2] El sistema valida que saldo + venta no exceda el limite
- [CA-071-3] Si excede limite, muestra mensaje y bloquea la operacion
- [CA-071-4] La venta actualiza automaticamente el saldo del cliente
- [CA-071-5] Se genera registro en credit_transactions tipo "charge"

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-071-01 | Logica de validacion de credito en SalesService | 3h |
| MCH-TT-071-02 | Integracion metodo pago "Fiado" en POS | 3h |
| MCH-TT-071-03 | Actualizacion automatica de saldo | 2h |
| MCH-TT-071-04 | Tests de flujo de venta a credito | 2h |

---

### MCH-US-072: Registrar Abono
**Story Points:** 2

Como **dueno de changarrito**
Quiero **registrar pagos parciales o totales de clientes con fiado**
Para **mantener actualizado el saldo y generar comprobantes de pago**

#### Criterios de Aceptacion
- [CA-072-1] Se puede registrar abono desde la ficha del cliente
- [CA-072-2] El monto del abono no puede exceder el saldo pendiente
- [CA-072-3] El sistema actualiza el saldo inmediatamente
- [CA-072-4] Se genera recibo de pago imprimible
- [CA-072-5] El abono queda registrado en credit_transactions tipo "payment"

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-072-01 | Endpoint POST /customers/:id/credit/payment | 2h |
| MCH-TT-072-02 | UI formulario de abono con validaciones | 3h |
| MCH-TT-072-03 | Generacion de recibo de pago | 2h |
| MCH-TT-072-04 | Actualizacion de last_payment_at | 1h |

---

### MCH-US-073: Recordatorios WhatsApp
**Story Points:** 3

Como **sistema**
Quiero **enviar recordatorios de pago automaticos via WhatsApp a clientes con saldo pendiente**
Para **reducir la cartera vencida sin intervencion manual del dueno**

#### Criterios de Aceptacion
- [CA-073-1] El cron diario identifica clientes con saldo > X dias sin pago
- [CA-073-2] Se envia mensaje WhatsApp personalizado con nombre, saldo y negocio
- [CA-073-3] Los dias de recordatorio son configurables por tenant (ej: 7, 14, 30)
- [CA-073-4] Se registra cada envio de recordatorio en el sistema
- [CA-073-5] No se envian mas de 1 recordatorio por semana al mismo cliente

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-073-01 | CronJob de revision de cuentas vencidas | 3h |
| MCH-TT-073-02 | Integracion con WhatsApp Service | 4h |
| MCH-TT-073-03 | Templates de mensajes configurables | 2h |
| MCH-TT-073-04 | Registro y control de envios | 2h |

---

### MCH-US-074: Reporte Cartera
**Story Points:** 3

Como **dueno de changarrito**
Quiero **ver el estado consolidado de todos los fiados pendientes**
Para **tomar decisiones sobre creditos y priorizar cobranza**

#### Criterios de Aceptacion
- [CA-074-1] Dashboard muestra total de cartera (suma de saldos pendientes)
- [CA-074-2] Lista de clientes ordenada por saldo descendente
- [CA-074-3] Indicador de dias desde ultimo pago por cliente
- [CA-074-4] Filtros por rango de fechas y estado (activo/bloqueado)
- [CA-074-5] Exportable a PDF/Excel

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-074-01 | Endpoint GET /credit/portfolio con agregaciones | 3h |
| MCH-TT-074-02 | Endpoint GET /credit/overdue con filtros | 2h |
| MCH-TT-074-03 | Componente CreditDashboard | 4h |
| MCH-TT-074-04 | Exportacion PDF/Excel | 3h |

---

## Resumen de Story Points

| Historia | Titulo | SP |
|----------|--------|---:|
| MCH-US-070 | Habilitar Credito Cliente | 2 |
| MCH-US-071 | Venta a Credito | 3 |
| MCH-US-072 | Registrar Abono | 2 |
| MCH-US-073 | Recordatorios WhatsApp | 3 |
| MCH-US-074 | Reporte Cartera | 3 |
| **TOTAL** | | **13** |

---

**Ultima actualizacion:** 2026-01-10