rckrdmrd/michangarrito
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
michangarrito/docs/01-epicas/MCH-008-sistema-fiados.md
rckrdmrd 184d21d6ce [MCH-DOC-VAL] docs: Estandarizar épicas MCH-006 a MCH-010 con HU formales 
Épicas actualizadas con formato SIMCO 4.0.1:
- MCH-006: Onboarding Inteligente (4 HU, 13 SP)
- MCH-007: Templates y Catálogos (4 HU, 8 SP)
- MCH-008: Sistema de Fiados (5 HU, 13 SP)
- MCH-009: Predicción Inventario (5 HU, 13 SP)
- MCH-010: MCP Server (7 HU, 21 SP)

Cambios aplicados:
- Agregado story_points en frontmatter y metadata
- Sección "Historias de Usuario" con formato Como/Quiero/Para
- Criterios de Aceptación con formato [CA-XXX-N]
- Tareas con formato [MCH-TT-XXX-NN]
- Tabla resumen de Story Points

IDs asignados: MCH-US-050 a MCH-US-096

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-17 04:28:53 -06:00

318 lines
8.8 KiB
Markdown
Raw Permalink Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink