michangarrito/docs/01-epicas/MCH-008-sistema-fiados.md

id	type	title	code	status	phase	priority	created_at	updated_at	story_points	simco_version	dependencies
EPIC-MCH-008	Epic	MCH-008: Sistema de Fiados	MCH-008	Completado	2	P1	2026-01-10	2026-01-10	13	4.0.1	blocks depends_on MCH-017 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

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

Configuracion por Tenant

{
  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