From adab7aea24e311e6a735d3e6a91fe119ec1aa4e6 Mon Sep 17 00:00:00 2001 From: rckrdmrd Date: Sat, 17 Jan 2026 04:31:01 -0600 Subject: [PATCH] =?UTF-8?q?MCH-015:=20Estandarizar=20=C3=A9pica=20Pedidos?= =?UTF-8?q?=20via=20WhatsApp=20seg=C3=BAn=20SIMCO=204.0.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/01-epicas/MCH-011-whatsapp-service.md | 16 +- docs/01-epicas/MCH-012-chat-llm-dueno.md | 260 ++++++++++++++++++++- docs/01-epicas/MCH-013-chat-llm-cliente.md | 173 +++++++++++++- docs/01-epicas/MCH-014-gestion-clientes.md | 189 ++++++++++++++- docs/01-epicas/MCH-015-pedidos-whatsapp.md | 246 ++++++++++++++++++- 5 files changed, 870 insertions(+), 14 deletions(-) diff --git a/docs/01-epicas/MCH-011-whatsapp-service.md b/docs/01-epicas/MCH-011-whatsapp-service.md index 00cfd9b1d..a041784de 100644 --- a/docs/01-epicas/MCH-011-whatsapp-service.md +++ b/docs/01-epicas/MCH-011-whatsapp-service.md @@ -7,11 +7,15 @@ status: Completado phase: 3 priority: P0 created_at: 2026-01-10 -updated_at: 2026-01-10 -simco_version: "3.8.0" +updated_at: 2026-01-17 +simco_version: "4.0.1" +story_points: 55 dependencies: blocks: [] - depends_on: [] + depends_on: + - MCH-001 + - MCH-002 + - MCH-010 --- # MCH-011: WhatsApp Service @@ -22,6 +26,8 @@ dependencies: - **Prioridad:** P0 - **Estado:** Completado - **Fecha completado:** 2026-01-10 +- **Story Points:** 55 +- **SIMCO Version:** 4.0.1 ## Descripcion @@ -44,12 +50,16 @@ Servicio de integracion con WhatsApp Business API de Meta. Permite a los negocio - Procesamiento via MCP Server - Webhooks verificados - Cola de mensajes (Redis) +- Multi-tenant con routing por numero +- Manejo de diferentes tipos de mensaje +- Procesamiento asincrono con workers ### Excluido - WhatsApp Web (no oficial) - Grupos de WhatsApp - Estados/historias - Llamadas de voz/video +- Integracion con redes sociales adicionales ## Arquitectura diff --git a/docs/01-epicas/MCH-012-chat-llm-dueno.md b/docs/01-epicas/MCH-012-chat-llm-dueno.md index 9fc00a93c..8a9d23e05 100644 --- a/docs/01-epicas/MCH-012-chat-llm-dueno.md +++ b/docs/01-epicas/MCH-012-chat-llm-dueno.md @@ -7,8 +7,9 @@ status: Pendiente phase: 3 priority: P1 created_at: 2026-01-07 -updated_at: 2026-01-10 -simco_version: "3.8.0" +updated_at: 2026-01-17 +simco_version: "4.0.1" +story_points: 47 dependencies: blocks: [] depends_on: [] @@ -22,6 +23,7 @@ dependencies: - **Prioridad:** P1 - **Estado:** Pendiente - **Fecha estimada:** Sprint 7-8 +- **Story Points:** 47 ## Descripcion @@ -163,6 +165,260 @@ Enviado: 10:00 AM Lunes ¿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 | diff --git a/docs/01-epicas/MCH-013-chat-llm-cliente.md b/docs/01-epicas/MCH-013-chat-llm-cliente.md index 7765d3efe..c885e17ea 100644 --- a/docs/01-epicas/MCH-013-chat-llm-cliente.md +++ b/docs/01-epicas/MCH-013-chat-llm-cliente.md @@ -7,8 +7,9 @@ status: Pendiente phase: 3 priority: P1 created_at: 2026-01-07 -updated_at: 2026-01-10 -simco_version: "3.8.0" +updated_at: 2026-01-17 +simco_version: "4.0.1" +story_points: 34 dependencies: blocks: [] depends_on: [] @@ -22,6 +23,7 @@ dependencies: - **Prioridad:** P1 - **Estado:** Pendiente - **Fecha estimada:** Sprint 8-9 +- **Story Points:** 34 ## Descripcion @@ -183,6 +185,171 @@ const customerTools = [ - Rate limit: 20 mensajes/hora por cliente - Tokens: descontados de cuota del tenant +## Historias de Usuario + +### MCH-US-120: Consultar Precios de Productos + +**Story Points:** 5 + +**Como** cliente del negocio +**Quiero** consultar el precio de un producto específico via chat +**Para** conocer cuánto cuesta antes de hacer mi pedido + +#### Criterios de Aceptación +- [CA-120-1] El cliente puede enviar mensaje como "¿Cuánto cuesta la Coca?" +- [CA-120-2] El bot responde con todos los tamaños disponibles y sus precios +- [CA-120-3] La información mostrada coincide con la base de datos actual +- [CA-120-4] Solo se muestran productos disponibles en el catálogo + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-120-01 | Crear endpoint `get_product_price` en MCP Server | 3h | +| MCH-TT-120-02 | Implementar intent recognition para CONSULTA_PRECIO | 2h | +| MCH-TT-120-03 | Diseñar prompt para formatear respuesta de precios | 2h | +| MCH-TT-120-04 | Testing de consultas de precio comunes | 2h | + +--- + +### MCH-US-121: Consultar Disponibilidad de Productos + +**Story Points:** 5 + +**Como** cliente del negocio +**Quiero** verificar si un producto está disponible en el inventario +**Para** saber si puedo pedirlo en este momento + +#### Criterios de Aceptación +- [CA-121-1] El cliente puede preguntar "¿Tienen pan Bimbo?" +- [CA-121-2] El bot responde con estado de disponibilidad (✓ disponible / ✗ agotado) +- [CA-121-3] Se muestran opciones alternativas si el producto no está disponible +- [CA-121-4] La información se obtiene en tiempo real del inventario + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-121-01 | Crear endpoint `check_availability` en MCP Server | 3h | +| MCH-TT-121-02 | Conectar con servicio de inventario | 3h | +| MCH-TT-121-03 | Implementar lógica de sugerencias de productos similares | 3h | +| MCH-TT-121-04 | Testing de disponibilidad en tiempo real | 2h | + +--- + +### MCH-US-122: Crear Pedido Via Chat + +**Story Points:** 8 + +**Como** cliente del negocio +**Quiero** hacer un pedido directamente desde el chat +**Para** obtener mis productos sin necesidad de ir personalmente + +#### Criterios de Aceptación +- [CA-122-1] El cliente puede decir "Quiero 2 Cocas de 600 y unas Sabritas" +- [CA-122-2] El bot resume el pedido con total a pagar +- [CA-122-3] El cliente puede confirmar, agregar más o cancelar +- [CA-122-4] El pedido se guarda en la base de datos con estado "confirmado_por_chat" +- [CA-122-5] El cliente recibe número de pedido y hora estimada de entrega + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-122-01 | Crear flujo de carrito en memoria durante chat | 4h | +| MCH-TT-122-02 | Implementar endpoint `create_order` con validación | 5h | +| MCH-TT-122-03 | Crear intent recognition para HACER_PEDIDO | 3h | +| MCH-TT-122-04 | Integrar con servicio de órdenes del backend | 4h | +| MCH-TT-122-05 | Testing end-to-end de flujo completo de pedido | 3h | + +--- + +### MCH-US-123: Consultar Saldo de Fiado + +**Story Points:** 5 + +**Como** cliente con crédito en el negocio +**Quiero** verificar mi saldo de deuda actual +**Para** saber cuánto debo y poder organizar mi pago + +#### Criterios de Aceptación +- [CA-123-1] El cliente puede preguntar "¿Cuánto debo?" +- [CA-123-2] El bot responde con saldo actual y último movimiento +- [CA-123-3] Solo se muestra el saldo del cliente autenticado +- [CA-123-4] Se protege la privacidad: no se muestra info de otros clientes + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-123-01 | Crear endpoint `get_my_balance` con autenticación | 3h | +| MCH-TT-123-02 | Implementar reconocimiento de intent CONSULTA_SALDO | 2h | +| MCH-TT-123-03 | Formatear respuesta con movimientos recientes | 2h | +| MCH-TT-123-04 | Testing de seguridad (aislamiento por cliente) | 2h | + +--- + +### MCH-US-124: Consultar Información del Negocio + +**Story Points:** 4 + +**Como** cliente potencial o existente +**Quiero** obtener información del negocio (horarios, ubicación, promociones) +**Para** saber cuándo puedo ir, dónde está y qué ofertas tienen + +#### Criterios de Aceptación +- [CA-124-1] El cliente puede preguntar "¿A qué hora abren?" +- [CA-124-2] El cliente puede preguntar "¿Dónde están?" +- [CA-124-3] El cliente puede preguntar "¿Qué promociones tienen?" +- [CA-124-4] El bot responde con información del negocio desde configuración tenant +- [CA-124-5] Se muestran horarios, ubicación, contacto y promociones activas + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-124-01 | Crear endpoint `get_business_info` | 2h | +| MCH-TT-124-02 | Crear endpoint `get_promotions` | 2h | +| MCH-TT-124-03 | Implementar intents HORARIOS, UBICACION, PROMOCIONES | 2h | +| MCH-TT-124-04 | Testing de información personalizada por tenant | 1h | + +--- + +### MCH-US-125: Limitación de Permisos por Rol (Cliente vs Dueño) + +**Story Points:** 7 + +**Como** arquitecto del sistema +**Quiero** que los clientes solo accedan a tools permitidas en el MCP Server +**Para** proteger información sensible del negocio y evitar acceso no autorizado + +#### Criterios de Aceptación +- [CA-125-1] Los clientes pueden usar: search_products, get_product_price, check_availability, create_order, get_my_balance, get_business_info, get_promotions +- [CA-125-2] Los clientes NO pueden usar: update_product_price, get_sales_report, send_payment_reminder, delete_products, modify_business_settings +- [CA-125-3] El sistema valida el rol del usuario en cada llamada a tool +- [CA-125-4] Se registran intentos de acceso no autorizado en logs +- [CA-125-5] Los dueños mantienen acceso a todas las tools + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-125-01 | Implementar sistema de permisos por rol en MCP Server | 5h | +| MCH-TT-125-02 | Crear lista blanca de tools para clientes | 2h | +| MCH-TT-125-03 | Implementar validación de permisos antes de ejecutar tool | 4h | +| MCH-TT-125-04 | Agregar logging de intentos de acceso no autorizado | 2h | +| MCH-TT-125-05 | Testing de seguridad (intentos de escalación de privilegios) | 3h | + +--- + +### Resumen de Story Points + +| Historia | Descripción | SP | +|----------|-------------|-----| +| MCH-US-120 | Consultar Precios de Productos | 5 | +| MCH-US-121 | Consultar Disponibilidad de Productos | 5 | +| MCH-US-122 | Crear Pedido Via Chat | 8 | +| MCH-US-123 | Consultar Saldo de Fiado | 5 | +| MCH-US-124 | Consultar Información del Negocio | 4 | +| MCH-US-125 | Limitación de Permisos por Rol | 7 | +| **Total** | | **34** | + +--- + ## Entregables | Entregable | Estado | Archivo | @@ -228,4 +395,4 @@ const customerTools = [ --- -**Ultima actualizacion:** 2026-01-07 +**Ultima actualizacion:** 2026-01-17 diff --git a/docs/01-epicas/MCH-014-gestion-clientes.md b/docs/01-epicas/MCH-014-gestion-clientes.md index e0f24dc86..8ae95b409 100644 --- a/docs/01-epicas/MCH-014-gestion-clientes.md +++ b/docs/01-epicas/MCH-014-gestion-clientes.md @@ -7,8 +7,9 @@ status: Completado phase: 4 priority: P1 created_at: 2026-01-06 -updated_at: 2026-01-10 -simco_version: "3.8.0" +updated_at: 2026-01-17 +simco_version: "4.0.1" +story_points: 21 dependencies: blocks: [] depends_on: [] @@ -21,6 +22,7 @@ dependencies: - **Fase:** 4 - Pedidos y Clientes - **Prioridad:** P1 - **Estado:** Completado +- **Story Points:** 21 - **Fecha inicio:** 2026-01-06 - **Fecha fin:** 2026-01-07 @@ -165,6 +167,187 @@ Sistema completo de gestion de clientes: registro, historial de compras, saldo d ### Tags Personalizados - Ejemplos: "vecino", "oficina", "escuela", "mayoreo" +## Historias de Usuario + +### MCH-US-130: Registrar cliente nuevo +**Story Points:** 3 + +**Como** empleado de ventas +**Quiero** crear un cliente rapidamente durante una venta +**Para** registrar contactos y poder consultar su historial en futuras transacciones + +#### Criterios de Aceptación +- [CA-130-1] El formulario solicita nombre (requerido) y telefono (requerido) +- [CA-130-2] Email y direccion son opcionales +- [CA-130-3] El cliente se crea exitosamente y se muestra en el listado +- [CA-130-4] Se valida que no exista otro cliente con el mismo telefono + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-130-01 | Crear modelo Customer en backend | 2h | +| MCH-TT-130-02 | Implementar endpoint POST /customers | 3h | +| MCH-TT-130-03 | Crear componente CustomerForm.tsx | 4h | +| MCH-TT-130-04 | Validar duplicados por telefono | 2h | + +--- + +### MCH-US-131: Ver historial de compras de cliente +**Story Points:** 3 + +**Como** dueno de tienda +**Quiero** consultar todas las compras historicas de un cliente +**Para** entender su comportamiento de compra y patrones + +#### Criterios de Aceptación +- [CA-131-1] El historial muestra todas las compras del cliente +- [CA-131-2] Se muestran fecha, monto, productos y metodo de pago +- [CA-131-3] El historial esta ordenado por fecha descendente +- [CA-131-4] Se muestra total historico y cantidad de compras + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-131-01 | Crear vista customer_purchases en BD | 2h | +| MCH-TT-131-02 | Implementar endpoint GET /customers/:id/purchases | 3h | +| MCH-TT-131-03 | Crear componente CustomerPurchaseHistory.tsx | 4h | +| MCH-TT-131-04 | Agregar metricas: total, promedio, frecuencia | 2h | + +--- + +### MCH-US-132: Gestionar saldo de fiado +**Story Points:** 4 + +**Como** dueno de tienda +**Quiero** ver y actualizar el saldo de fiado de un cliente +**Para** controlar credito y cobros pendientes + +#### Criterios de Aceptación +- [CA-132-1] Se muestra el limite de credito y saldo actual +- [CA-132-2] Se puede registrar un abono manualmente +- [CA-132-3] Se muestra historial de movimientos de fiado +- [CA-132-4] Se previene exceder el limite de credito en ventas +- [CA-132-5] Se calcula saldo automaticamente desde sales + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-132-01 | Extender tabla customers con campos credit | 2h | +| MCH-TT-132-02 | Crear tabla credit_movements | 2h | +| MCH-TT-132-03 | Implementar logica de validacion de credito | 4h | +| MCH-TT-132-04 | Crear componente CreditHistory.tsx | 4h | +| MCH-TT-132-05 | Endpoint para registrar abono | 3h | + +--- + +### MCH-US-133: Enviar mensaje WhatsApp a cliente +**Story Points:** 3 + +**Como** dueno de tienda +**Quiero** enviar mensajes WhatsApp a mis clientes +**Para** comunicarme sobre pedidos, recordatorios y cobros + +#### Criterios de Aceptación +- [CA-133-1] Existe boton "Enviar WhatsApp" en ficha de cliente +- [CA-133-2] Se puede escribir un mensaje personalizado +- [CA-133-3] Se puede seleccionar un template predefinido +- [CA-133-4] El mensaje se envia al numero de cliente almacenado +- [CA-133-5] Se registra el envio en el historial del cliente + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-133-01 | Configurar servicio WhatsApp API | 3h | +| MCH-TT-133-02 | Crear tabla message_log para audit | 2h | +| MCH-TT-133-03 | Implementar endpoint POST /customers/:id/message | 3h | +| MCH-TT-133-04 | Crear componente WhatsAppSender.tsx | 4h | +| MCH-TT-133-05 | Crear templates predefinidos | 2h | + +--- + +### MCH-US-134: Segmentar clientes por frecuencia +**Story Points:** 4 + +**Como** dueno de tienda +**Quiero** segmentar mis clientes por frecuencia de compra +**Para** identificar clientes frecuentes e inactivos + +#### Criterios de Aceptación +- [CA-134-1] Se calculan 4 segmentos: Frecuente (>=4/mes), Regular (2-3/mes), Ocasional (1/mes), Inactivo (0/30d) +- [CA-134-2] Se puede filtrar el listado de clientes por segmento +- [CA-134-3] El calculo se actualiza diariamente +- [CA-134-4] Se muestra el segmento en la ficha del cliente + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-134-01 | Crear función de calculo de frecuencia | 2h | +| MCH-TT-134-02 | Agregar columnas frequency_segment a customers | 1h | +| MCH-TT-134-03 | Crear job batch para actualizar diariamente | 3h | +| MCH-TT-134-04 | Implementar filtro en GET /customers | 2h | +| MCH-TT-134-05 | Mostrar segmento en UI | 2h | + +--- + +### MCH-US-135: Asignar tags y notas a cliente +**Story Points:** 2 + +**Como** dueno de tienda +**Quiero** agregar tags personalizados (vecino, oficina, mayoreo) y notas a clientes +**Para** categorizar y recordar detalles importantes + +#### Criterios de Aceptación +- [CA-135-1] Se puede asignar multiples tags a un cliente +- [CA-135-2] Se pueden crear tags personalizados +- [CA-135-3] Se puede escribir y editar notas +- [CA-135-4] Los tags aparecen en el listado y detalle del cliente +- [CA-135-5] Se puede filtrar por tags + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-135-01 | Agregar columnas tags (JSONB) y notes a customers | 1h | +| MCH-TT-135-02 | Crear CRUD para tags | 2h | +| MCH-TT-135-03 | Agregar inputs de tags/notas en CustomerForm | 2h | +| MCH-TT-135-04 | Implementar filtro por tags | 2h | + +--- + +### MCH-US-136: Segmentar clientes por valor de compra +**Story Points:** 2 + +**Como** dueno de tienda +**Quiero** segmentar mis clientes por valor total de compra +**Para** identificar clientes de alto valor e inactivos + +#### Criterios de Aceptación +- [CA-136-1] Se calculan 3 segmentos: Alto (>=2000/mes), Medio (500-2000/mes), Bajo (<500/mes) +- [CA-136-2] Se puede filtrar el listado por segmento de valor +- [CA-136-3] El calculo se actualiza diariamente +- [CA-136-4] Se muestra el segmento en la ficha del cliente + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-136-01 | Crear función de calculo de valor | 2h | +| MCH-TT-136-02 | Agregar columna value_segment a customers | 1h | +| MCH-TT-136-03 | Actualizar job batch | 1h | +| MCH-TT-136-04 | Mostrar en UI y filtro | 2h | + +--- + +### Resumen de Story Points +| Historia | Descripción | SP | +|----------|-------------|-----| +| MCH-US-130 | Registrar cliente nuevo | 3 | +| MCH-US-131 | Ver historial de compras | 3 | +| MCH-US-132 | Gestionar saldo de fiado | 4 | +| MCH-US-133 | Enviar mensaje WhatsApp | 3 | +| MCH-US-134 | Segmentar por frecuencia | 4 | +| MCH-US-135 | Asignar tags y notas | 2 | +| MCH-US-136 | Segmentar por valor | 2 | +| **Total** | | **21** | + ## Entregables | Entregable | Estado | Archivo | @@ -210,4 +393,4 @@ customer.value_segment = calculateValue(customer) --- -**Ultima actualizacion:** 2026-01-07 +**Ultima actualizacion:** 2026-01-17 diff --git a/docs/01-epicas/MCH-015-pedidos-whatsapp.md b/docs/01-epicas/MCH-015-pedidos-whatsapp.md index 61f8855dd..75c4f81ab 100644 --- a/docs/01-epicas/MCH-015-pedidos-whatsapp.md +++ b/docs/01-epicas/MCH-015-pedidos-whatsapp.md @@ -7,8 +7,9 @@ status: Pendiente phase: 4 priority: P1 created_at: 2026-01-07 -updated_at: 2026-01-10 -simco_version: "3.8.0" +updated_at: 2026-01-17 +simco_version: "4.0.1" +story_points: 55 dependencies: blocks: [] depends_on: [] @@ -21,6 +22,7 @@ dependencies: - **Fase:** 4 - Pedidos y Clientes - **Prioridad:** P1 - **Estado:** Pendiente +- **Story Points:** 55 - **Fecha estimada:** Sprint 9-10 ## Descripcion @@ -162,6 +164,244 @@ pending ──► confirmed ──► preparing ──► ready ──► delive - Sonido distintivo - Accion rapida: Aceptar/Rechazar +## Historias de Usuario + +### MCH-US-140: Cliente solicita pedido via WhatsApp +**Story Points:** 8 + +**Como** cliente +**Quiero** hacer un pedido conversando naturalmente con el bot +**Para** comprar productos sin usar una interfaz tradicional + +#### Criterios de Aceptación +- [CA-140-1] El bot entiende solicitudes de compra en lenguaje natural +- [CA-140-2] El bot construye un carrito conversacional +- [CA-140-3] El cliente puede agregar/quitar items +- [CA-140-4] Se muestra el total antes de confirmar + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-140-01 | Implementar NLU para interpretación de pedidos | 5h | +| MCH-TT-140-02 | Crear carrito conversacional | 5h | +| MCH-TT-140-03 | Integrar con inventario de productos | 3h | + +--- + +### MCH-US-141: Cliente confirma pedido +**Story Points:** 5 + +**Como** cliente +**Quiero** confirmar mi pedido con un clic +**Para** asegurar que mi compra se procese + +#### Criterios de Aceptación +- [CA-141-1] Botón de confirmación claramente visible +- [CA-141-2] Resumen final antes de confirmar +- [CA-141-3] Opción para cancelar/modificar +- [CA-141-4] Mensaje de éxito con número de pedido + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-141-01 | UI de confirmación de pedido | 4h | +| MCH-TT-141-02 | Validación y persistencia en BD | 3h | + +--- + +### MCH-US-142: Negocio recibe notificación de nuevo pedido +**Story Points:** 8 + +**Como** dueño del negocio +**Quiero** recibir notificación inmediata cuando llega un pedido +**Para** comenzar a prepararlo rápidamente + +#### Criterios de Aceptación +- [CA-142-1] Notificación push instantánea +- [CA-142-2] También envía WhatsApp al dueño +- [CA-142-3] Incluye detalles del cliente y items +- [CA-142-4] Sonido distintivo para alertar +- [CA-142-5] Enlace directo para ver pedido completo + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-142-01 | Servicio de notificaciones push | 5h | +| MCH-TT-142-02 | Integración de envío WhatsApp | 4h | +| MCH-TT-142-03 | Configuración de sonidos | 2h | + +--- + +### MCH-US-143: Negocio acepta o rechaza pedido +**Story Points:** 5 + +**Como** dueño del negocio +**Quiero** aceptar o rechazar un pedido rápidamente +**Para** confirmar si puedo prepararlo o si hay algún problema + +#### Criterios de Aceptación +- [CA-143-1] Botones de Aceptar/Rechazar en notificación +- [CA-143-2] Campo opcional de motivo de rechazo +- [CA-143-3] Cliente recibe confirmación inmediata +- [CA-143-4] Pedido se marca como confirmado o cancelado + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-143-01 | Endpoints de aceptación/rechazo | 3h | +| MCH-TT-143-02 | Lógica de cambio de estado | 3h | +| MCH-TT-143-03 | Notificación al cliente | 2h | + +--- + +### MCH-US-144: Cliente ve estado de su pedido en tiempo real +**Story Points:** 8 + +**Como** cliente +**Quiero** ver el estado actual de mi pedido +**Para** saber cuándo estará listo + +#### Criterios de Aceptación +- [CA-144-1] Estado visible en el chat +- [CA-144-2] Actualizaciones en tiempo real (WebSocket) +- [CA-144-3] Muestra tiempo estimado de entrega +- [CA-144-4] Estados: recibido, preparando, listo, entregado +- [CA-144-5] Notificación cada vez que cambia el estado + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-144-01 | Máquina de estados para pedidos | 4h | +| MCH-TT-144-02 | WebSocket para actualizaciones en vivo | 5h | +| MCH-TT-144-03 | Interfaz visual de timeline | 4h | + +--- + +### MCH-US-145: Negocio actualiza estado del pedido +**Story Points:** 5 + +**Como** dueño del negocio +**Quiero** marcar el estado del pedido (preparando, listo, entregado) +**Para** mantener al cliente informado + +#### Criterios de Aceptación +- [CA-145-1] Cambio de estado desde dashboard o WhatsApp +- [CA-145-2] Transiciones válidas según máquina de estados +- [CA-145-3] Historial de cambios guardado +- [CA-145-4] Cliente notificado automáticamente + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-145-01 | UI en dashboard para cambiar estado | 3h | +| MCH-TT-145-02 | Servicio de auditoría de cambios | 3h | +| MCH-TT-145-03 | Validación de transiciones | 2h | + +--- + +### MCH-US-146: Historial de pedidos del cliente +**Story Points:** 5 + +**Como** cliente +**Quiero** ver mis pedidos anteriores +**Para** reordenar fácilmente los mismos productos + +#### Criterios de Aceptación +- [CA-146-1] Lista de todos los pedidos históricos +- [CA-146-2] Filtros por fecha/estado +- [CA-146-3] Opción para repetir un pedido anterior +- [CA-146-4] Detalles de cada pedido disponibles + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-146-01 | API de historial de pedidos | 3h | +| MCH-TT-146-02 | Interfaz de cliente en chat | 3h | +| MCH-TT-146-03 | Función de "repetir pedido" | 2h | + +--- + +### MCH-US-147: Cliente cancela pedido +**Story Points:** 3 + +**Como** cliente +**Quiero** cancelar mi pedido si cambio de opinión +**Para** no pagar por algo que no quiero + +#### Criterios de Aceptación +- [CA-147-1] Opción de cancelación disponible antes de "listo" +- [CA-147-2] Confirmación antes de cancelar +- [CA-147-3] Dueño notificado de la cancelación +- [CA-147-4] Pedido marcado como cancelado en historial + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-147-01 | Endpoint de cancelación | 2h | +| MCH-TT-147-02 | Validaciones de estado | 1h | +| MCH-TT-147-03 | Notificación al negocio | 1h | + +--- + +### MCH-US-148: Dashboard de pedidos del negocio +**Story Points:** 8 + +**Como** dueño del negocio +**Quiero** un dashboard con todos mis pedidos +**Para** gestionar el flujo de trabajo eficientemente + +#### Criterios de Aceptación +- [CA-148-1] Vista de tabla con pedidos del día +- [CA-148-2] Filtros por estado (pendiente, preparando, listo) +- [CA-148-3] Acciones rápidas: aceptar, marcar listo, cancelar +- [CA-148-4] Sonido/alert para nuevos pedidos +- [CA-148-5] Información del cliente con teléfono + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-148-01 | Componente OrderList | 4h | +| MCH-TT-148-02 | Filtros y búsqueda | 3h | +| MCH-TT-148-03 | Acciones rápidas en UI | 3h | + +--- + +### MCH-US-149: Historial de estados del pedido +**Story Points:** 3 + +**Como** usuario (cliente o dueño) +**Quiero** ver el historial completo de cambios en un pedido +**Para** verificar cuándo se hizo cada acción + +#### Criterios de Aceptación +- [CA-149-1] Timeline de cambios de estado +- [CA-149-2] Muestra quién hizo el cambio y cuándo +- [CA-149-3] Notas adicionales si existen +- [CA-149-4] Accesible desde detalles del pedido + +#### Tareas +| ID | Tarea | Estimación | +|----|-------|------------| +| MCH-TT-149-01 | API de historial de estados | 2h | +| MCH-TT-149-02 | Componente visual de timeline | 2h | + +--- + +### Resumen de Story Points +| Historia | Descripción | SP | +|----------|-------------|-----| +| MCH-US-140 | Cliente solicita pedido via WhatsApp | 8 | +| MCH-US-141 | Cliente confirma pedido | 5 | +| MCH-US-142 | Negocio recibe notificación | 8 | +| MCH-US-143 | Negocio acepta o rechaza | 5 | +| MCH-US-144 | Cliente ve estado en tiempo real | 8 | +| MCH-US-145 | Negocio actualiza estado | 5 | +| MCH-US-146 | Historial de pedidos cliente | 5 | +| MCH-US-147 | Cliente cancela pedido | 3 | +| MCH-US-148 | Dashboard de pedidos negocio | 8 | +| MCH-US-149 | Historial de estados pedido | 3 | +| **Total** | | **55** | + ## Entregables | Entregable | Estado | Archivo | @@ -209,4 +449,4 @@ pending ──► confirmed ──► preparing ──► ready ──► delive --- -**Ultima actualizacion:** 2026-01-07 +**Ultima actualizacion:** 2026-01-17