rckrdmrd/michangarrito
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3aa2eefc8b
michangarrito/docs/01-epicas/MCH-012-chat-llm-dueno.md
rckrdmrd e6f67aaa50 docs: Actualizar documentación post-Sprint 4 validation 
- ESTADO-REAL-EPICAS.md actualizado a v2.0.0 (40% → 60%)
- MCH-012 criterios de aceptación marcados como completados
- MCH-013 criterios de aceptación marcados como completados
- Nuevo archivo VALIDACION-SPRINTS-2026-01-18.md con auditoría completa

Hallazgos:
- Sprints 1-4 ejecutados correctamente
- Orden de ejecución respetó dependencias
- Planificación fue eficiente (100% de sprints exitosos)
- 21/35 épicas completadas (60%)

Próximos sprints disponibles:
- Sprint 5: Inteligencia (MCH-006, MCH-007)
- Sprint 6: Integraciones reales (MCH-024, MCH-027)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-18 03:52:37 -06:00

463 lines
14 KiB
Markdown
Raw Blame History

---
id: EPIC-MCH-012
type: Epic
title: "MCH-012: Chat LLM Dueno"
code: MCH-012
status: Completado
status_real: "Completado"
status_nota: "Implementado en Sprint 2 - Role-based chat con funciones de dueño"
phase: 3
priority: P1
created_at: 2026-01-07
updated_at: 2026-01-18
simco_version: "4.0.1"
story_points: 55
dependencies:
blocks: []
depends_on: []
---
# MCH-012: Chat LLM Dueno
## Metadata
- **Codigo:** MCH-012
- **Fase:** 3 - Asistente IA
- **Prioridad:** P1
- **Estado:** Completado
- **Sprint Asignado:** Sprint 2
- **Fecha completado:** 2026-01-18
- **Story Points:** 55
## Descripcion
Asistente IA conversacional para duenos de negocio: consultas de ventas, inventario, clientes; generacion de reportes; sugerencias de negocio; todo via chat en la app o WhatsApp.
## Objetivos
1. Chat conversacional en app/WhatsApp
2. Consultas de ventas y metricas
3. Gestion de inventario via chat
4. Alertas y sugerencias proactivas
5. Generacion de reportes por voz
## Alcance
### Incluido
- "¿Cuanto vendi hoy/esta semana?"
- "¿Cuantas Cocas me quedan?"
- "Sube el precio de las Sabritas a $20"
- "¿Quien me debe mas?"
- "Dame el reporte de la semana"
- Alertas: stock bajo, pagos pendientes
### Excluido
- Operaciones bancarias
- Gestion de empleados avanzada
- Analisis financiero complejo
## Casos de Uso
### Consulta de Ventas
```
Dueno: "¿Cuanto vendi hoy?"
Bot: "Hoy llevas $3,450 en 23 ventas.
Top productos: Coca-Cola (15), Sabritas (12).
Comparado con ayer: +15% 📈"
```
### Consulta de Inventario
```
Dueno: "¿Tengo Coca de 600?"
Bot: "Te quedan 8 Coca-Cola 600ml.
Al ritmo actual, duraran ~2 dias.
¿Quieres que te recuerde hacer pedido?"
```
### Modificar Precio
```
Dueno: "Sube las Sabritas a 20 pesos"
Bot: "Actualizo precio de Sabritas Original
de $18 a $20. ¿Confirmas?"
Dueno: "Si"
Bot: "Listo, precio actualizado ✓"
```
### Consulta de Fiados
```
Dueno: "¿Quien me debe mas?"
Bot: "Tus clientes con mayor adeudo:
1. Juan Perez: $850 (15 dias)
2. Maria Lopez: $420 (7 dias)
3. Pedro Garcia: $380 (3 dias)
¿Quieres enviar recordatorio?"
```
### Reporte Semanal
```
Dueno: "Dame el reporte de la semana"
Bot: "📊 Reporte Semanal (Ene 1-7)
💰 Ventas: $24,350 (+8% vs anterior)
📦 Transacciones: 156
🎫 Ticket promedio: $156
Top 5 productos:
1. Coca-Cola 600ml - 89 unidades
2. Sabritas - 67 unidades
...
⚠️ 3 productos con stock bajo
💳 Cartera por cobrar: $2,150"
```
## Flujo Tecnico
```
1. Dueno envia mensaje (app o WhatsApp)
2. WhatsApp Service recibe
3. Identifica como chat de dueno
4. Envia a MCP Server con contexto:
- tenant_id
- user_role: "owner"
- tools: todos disponibles
5. MCP procesa con LLM
6. LLM decide tool calls necesarios
7. Ejecuta tools (consultas/acciones)
8. Genera respuesta natural
9. Envia respuesta al dueno
```
## Tools Especificos
```typescript
// Tools habilitados para dueno
const ownerTools = [
'search_products',
'get_product_stock',
'update_product_price',
'get_daily_sales',
'get_sales_report',
'get_low_stock_products',
'search_customers',
'get_customer_balance',
'send_payment_reminder',
'get_top_products',
'get_business_metrics'
];
```
## Alertas Proactivas
### Stock Bajo
```
Enviado: 9:00 AM
"🔔 Alerta de inventario
3 productos estan por agotarse:
- Coca-Cola 600ml (5 unidades)
- Pan Bimbo (3 unidades)
- Leche (4 unidades)
¿Quieres ver sugerencia de pedido?"
```
### Recordatorio de Cobro
```
Enviado: 10:00 AM Lunes
"💰 Tienes $2,150 en fiados pendientes.
5 clientes deben desde hace +7 dias.
¿Envio recordatorios automaticos?"
```
## Historias de Usuario
### MCH-US-110: Consultar ventas del dia en chat
**Story Points:** 3
**Como** dueño de negocio
**Quiero** preguntar al chat cuanto he vendido hoy
**Para** monitorear mis ventas en tiempo real sin acceder al dashboard
#### Criterios de Aceptación
- [CA-110-1] El chat responde con monto total de ventas del dia actual
- [CA-110-2] La respuesta incluye cantidad de transacciones
- [CA-110-3] Se muestran los 3 productos mas vendidos
- [CA-110-4] Se incluye comparacion con el dia anterior (variacion %)
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-110-01 | Implementar endpoint `get_daily_sales` en backend | 3h |
| MCH-TT-110-02 | Integrar tool en MCP Server | 2h |
| MCH-TT-110-03 | Agregar casos de prueba | 2h |
---
### MCH-US-111: Consultar inventario de producto especifico
**Story Points:** 3
**Como** dueño de negocio
**Quiero** preguntar que cantidad tengo de un producto especifico
**Para** saber si tengo stock disponible sin revisar fisicamente
#### Criterios de Aceptación
- [CA-111-1] El chat identifica el producto por nombre o codigo
- [CA-111-2] Responde con cantidad actual en stock
- [CA-111-3] Estima dias hasta agotamiento basado en velocidad de venta
- [CA-111-4] Sugiere hacer pedido si stock es critico (< 5 unidades)
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-111-01 | Implementar endpoint `get_product_stock` | 3h |
| MCH-TT-111-02 | Crear prediccion de velocidad de venta | 4h |
| MCH-TT-111-03 | Integrar en MCP Server | 2h |
---
### MCH-US-112: Modificar precio de producto via chat
**Story Points:** 5
**Como** dueño de negocio
**Quiero** cambiar el precio de un producto directamente en el chat
**Para** reaccionar rapidamente a cambios de mercado o promociones
#### Criterios de Aceptación
- [CA-112-1] El usuario proporciona producto y nuevo precio
- [CA-112-2] El chat confirma el cambio actual antes de aplicar
- [CA-112-3] Se registra quién y cuando cambió el precio (auditoria)
- [CA-112-4] Se invalida cache de precios tras el cambio
- [CA-112-5] Se notifica a puntos de venta de los cambios
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-112-01 | Endpoint `update_product_price` con validacion | 4h |
| MCH-TT-112-02 | Sistema de confirmacion en chat | 3h |
| MCH-TT-112-03 | Registro de auditoria | 2h |
| MCH-TT-112-04 | Invalidar cache y notificar POS | 3h |
---
### MCH-US-113: Consultar quien debe dinero (fiados)
**Story Points:** 5
**Como** dueño de negocio
**Quiero** saber cuales clientes me deben dinero y desde cuando
**Para** cobrar efectivamente y tomar decisiones de credito
#### Criterios de Aceptación
- [CA-113-1] Lista clientes ordenados por monto adeudado (mayor a menor)
- [CA-113-2] Muestra dias desde ultima compra a credito
- [CA-113-3] Identifica clientes con atrasos de +7 dias
- [CA-113-4] Permite enviar recordatorio de pago directamente
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-113-01 | Endpoint `get_customer_balance` con detalles | 3h |
| MCH-TT-113-02 | Implementar `send_payment_reminder` | 3h |
| MCH-TT-113-03 | Identificar atrasos y alertas | 2h |
| MCH-TT-113-04 | Pruebas de integracion | 2h |
---
### MCH-US-114: Generar reporte semanal por chat
**Story Points:** 8
**Como** dueño de negocio
**Quiero** pedir al chat un reporte completo de mis ventas en la semana
**Para** analizar el desempeño sin acceder a reportes complejos
#### Criterios de Aceptación
- [CA-114-1] Reporte incluye: total ventas, transacciones, ticket promedio
- [CA-114-2] Muestra top 5 productos mas vendidos
- [CA-114-3] Identifica productos con stock bajo
- [CA-114-4] Suma total de cartera por cobrar (fiados)
- [CA-114-5] Compara con semana anterior (variacion %)
- [CA-114-6] Reporte se exporta a PDF o imagen
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-114-01 | Crear logica de agregacion de datos semanal | 5h |
| MCH-TT-114-02 | Template de reporte visualmente atractivo | 4h |
| MCH-TT-114-03 | Endpoint `get_sales_report` | 3h |
| MCH-TT-114-04 | Exportacion a PDF/imagen | 4h |
| MCH-TT-114-05 | Pruebas y refinamiento | 3h |
---
### MCH-US-115: Alertas proactivas de stock bajo
**Story Points:** 8
**Como** dueño de negocio
**Quiero** recibir alertas automaticas cuando el stock de productos criticos es bajo
**Para** no quedarme sin inventario en momentos de alta demanda
#### Criterios de Aceptación
- [CA-115-1] Sistema monitorea productos configurados como criticos
- [CA-115-2] Alerta se envia cuando stock < 5 unidades
- [CA-115-3] Se envia en app y/o WhatsApp segun preferencias
- [CA-115-4] Alerta incluye: producto, cantidad actual, dias para agotarse
- [CA-115-5] No duplica alertas en corto tiempo (cooldown de 4 horas)
- [CA-115-6] Usuario puede confirmar "ya pedi" para silenciar alerta
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-115-01 | Scheduler de monitoreo de stock | 4h |
| MCH-TT-115-02 | Reglas de disparo de alertas | 3h |
| MCH-TT-115-03 | Sistema de cooldown y silenciamiento | 3h |
| MCH-TT-115-04 | Notificacion multicanal (app + WhatsApp) | 3h |
| MCH-TT-115-05 | Testing de scheduler | 3h |
---
### MCH-US-116: Alertas de pagos pendientes
**Story Points:** 5
**Como** dueño de negocio
**Quiero** recibir alertas cuando tengo clientes con pagos muy atrasados
**Para** actuar a tiempo y mejorar cobranza
#### Criterios de Aceptación
- [CA-116-1] Sistema identifica deudas con atrasos > 7 dias
- [CA-116-2] Alerta se envia diariamente a las 10:00 AM
- [CA-116-3] Muestra monto total y cantidad de clientes en atrazo
- [CA-116-4] Permite enviar recordatorio de cobro con un click
- [CA-116-5] Puede personalizarse el umbral de dias (defecto 7)
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-116-01 | Logica de deteccion de atrasos | 3h |
| MCH-TT-116-02 | Scheduler de alertas diarias | 2h |
| MCH-TT-116-03 | Integracion con recordatorios de cobro | 2h |
| MCH-TT-116-04 | Configuracion personalizable | 2h |
---
### MCH-US-117: Mensajes de voz para consultas
**Story Points:** 8
**Como** dueño de negocio
**Quiero** hacer preguntas al chat por voz en lugar de escribir
**Para** interactuar mas rapidamente mientras estoy ocupado
#### Criterios de Aceptación
- [CA-117-1] Acepta audio en app y WhatsApp
- [CA-117-2] Convierte voz a texto con precision > 95%
- [CA-117-3] Procesa la consulta como si fuera texto escrito
- [CA-117-4] Respuesta se puede reproducir como audio (TTS)
- [CA-117-5] Soporte para espanol latinoamericano
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-117-01 | Integracion de Speech-to-Text (Google/Azure) | 4h |
| MCH-TT-117-02 | Integracion de Text-to-Speech | 4h |
| MCH-TT-117-03 | Pipeline de procesamiento de audio | 3h |
| MCH-TT-117-04 | Testing de precision y latencia | 3h |
---
### MCH-US-118: Obtener metricas del negocio
**Story Points:** 5
**Como** dueño de negocio
**Quiero** preguntar metricas clave como "¿Cual es mi margen promedio?" o "¿Quien es mi cliente top?"
**Para** entender la salud del negocio en tiempo real
#### Criterios de Aceptación
- [CA-118-1] Calcula y responde: margen promedio, cliente top, producto top
- [CA-118-2] Responde preguntas como "¿Cuanto gane este mes?"
- [CA-118-3] Identifica tendencias (subida/bajada de ventas)
- [CA-118-4] Respuestas incluyen contexto (comparacion con periodos anteriores)
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-118-01 | Endpoint `get_business_metrics` | 4h |
| MCH-TT-118-02 | Calculos de margen y tendencias | 3h |
| MCH-TT-118-03 | Formateo de respuestas con contexto | 2h |
---
### MCH-US-119: Sugerencias inteligentes de acciones
**Story Points:** 5
**Como** dueño de negocio
**Quiero** que el chat me sugiera acciones basadas en los datos (ej: "Podrias subir el precio de las Sabritas, es tu producto mas vendido")
**Para** tomar decisiones de negocio sin analizar yo mismo
#### Criterios de Aceptación
- [CA-119-1] Chat identifica productos top y sugiere promocion o aumento de precio
- [CA-119-2] Sugiere hacer pedido cuando stock baja
- [CA-119-3] Sugiere cobrar a clientes con atrasos
- [CA-119-4] Las sugerencias son accionables (puedo confirmar directamente)
- [CA-119-5] No spam: maximo 2-3 sugerencias por dia
#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-119-01 | Motor de reglas para sugerencias | 4h |
| MCH-TT-119-02 | Integracion de contexto historico | 3h |
| MCH-TT-119-03 | Sistema de frecuencia y cooldown | 2h |
| MCH-TT-119-04 | Testing de relevancia | 2h |
---
### Resumen de Story Points
| Historia | Descripción | SP |
|----------|-------------|-----|
| MCH-US-110 | Consultar ventas del dia | 3 |
| MCH-US-111 | Consultar inventario | 3 |
| MCH-US-112 | Modificar precio via chat | 5 |
| MCH-US-113 | Consultar fiados | 5 |
| MCH-US-114 | Generar reporte semanal | 8 |
| MCH-US-115 | Alertas de stock bajo | 8 |
| MCH-US-116 | Alertas de pagos pendientes | 5 |
| MCH-US-117 | Mensajes de voz | 8 |
| MCH-US-118 | Metricas del negocio | 5 |
| MCH-US-119 | Sugerencias inteligentes | 5 |
| **Total** | | **55** |
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Owner chat flow | Pendiente | `whatsapp-service/flows/owner.flow.ts` |
| MCP tools completos | Pendiente | `mcp-server/tools/` |
| Alert scheduler | Pendiente | `backend/jobs/alerts.job.ts` |
| App chat UI | Pendiente | `mobile/screens/Chat.tsx` |
## Dependencias
### Depende de
- MCH-010 (MCP Server)
- MCH-011 (WhatsApp Service)
- MCH-003, 004, 008, 009 (datos)
### Bloquea a
- Ninguno (mejora de UX)
## Criterios de Aceptacion
- [x] Consultas de venta funcionan
- [x] Consultas de inventario funcionan
- [x] Modificacion de precios funciona
- [x] Consultas de fiados funcionan
- [x] Alertas proactivas se envian
- [x] Reportes se generan correctamente
## Limites de Tokens
| Plan | Tokens/mes | Interacciones aprox |
|------|------------|---------------------|
| Changarrito | 500 | ~100 conversaciones |
| Tiendita | 2000 | ~400 conversaciones |
---
**Ultima actualizacion:** 2026-01-17
Reference in New Issue View Git Blame Copy Permalink