MCH-011: Estandarizar épica WhatsApp Service a SIMCO 4.0.1 con historias de usuario
- Actualizar frontmatter YAML con simco_version 4.0.1, story_points 55 - Agregar metadata de Story Points y SIMCO Version - Crear 10 historias de usuario (MCH-US-100 a MCH-US-109) con criterios de aceptación - Agregar tabla de tareas técnicas estimadas por historia - Incluir tabla resumen de Story Points con total de 85 puntos - Actualizar fecha de actualización a 2026-01-17
This commit is contained in:
parent
c38ab432a5
commit
08397f9828
@ -187,6 +187,249 @@ o lo enviamos a tu domicilio.
|
||||
6. Espera delivery report
|
||||
```
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
### MCH-US-100: Webhook de Meta para recepcion de mensajes
|
||||
**Story Points:** 8
|
||||
|
||||
**Como** administrador del servicio WhatsApp
|
||||
**Quiero** recibir mensajes desde Meta en un webhook verificado
|
||||
**Para** procesar mensajes entrantes de clientes de forma confiable
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-100-1] El endpoint POST /whatsapp/webhook recibe payloads de Meta
|
||||
- [CA-100-2] Se valida la firma HMAC del request con verify_token
|
||||
- [CA-100-3] Se retorna 200 OK para requests validos
|
||||
- [CA-100-4] Se registra cada mensaje recibido en logs
|
||||
- [CA-100-5] El endpoint GET /whatsapp/webhook responde challenge token para verificacion inicial
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-100-01 | Crear controller webhook con validacion HMAC | 3h |
|
||||
| MCH-TT-100-02 | Implementar verificacion de challenge token | 2h |
|
||||
| MCH-TT-100-03 | Agregar logging y monitoreo de requests | 2h |
|
||||
| MCH-TT-100-04 | Tests unitarios de validacion | 1h |
|
||||
|
||||
### MCH-US-101: Procesamiento de tipos de mensaje entrante
|
||||
**Story Points:** 13
|
||||
|
||||
**Como** procesador de mensajes
|
||||
**Quiero** diferenciar y procesar distintos tipos de mensaje (texto, audio, imagen, ubicacion)
|
||||
**Para** aplicar logica especifica a cada tipo
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-101-1] Texto se extrae y envia a MCP directamente
|
||||
- [CA-101-2] Audio se descarga de Meta y se transcribe con speech-to-text
|
||||
- [CA-101-3] Imagen se descarga y se procesa con OCR si es necesario
|
||||
- [CA-101-4] Ubicacion se extrae como coordenadas para entregas
|
||||
- [CA-101-5] Interactive (botones/lista) se registra como respuesta seleccionada
|
||||
- [CA-101-6] Mensajes no soportados retornan error al usuario
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-101-01 | Parser de payloads segun tipo de mensaje | 3h |
|
||||
| MCH-TT-101-02 | Integracion con speech-to-text para audio | 4h |
|
||||
| MCH-TT-101-03 | Integracion con OCR para imagenes | 3h |
|
||||
| MCH-TT-101-04 | Manejo de ubicaciones y coordenadas | 2h |
|
||||
| MCH-TT-101-05 | Tests de parseo para cada tipo | 1h |
|
||||
|
||||
### MCH-US-102: Cola de mensajes con Redis
|
||||
**Story Points:** 8
|
||||
|
||||
**Como** procesador asincrono
|
||||
**Quiero** encolar mensajes en Redis para procesamiento no bloqueante
|
||||
**Para** garantizar entrega y poder procesar picos de volumen
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-102-1] Cada mensaje webhook se enqueuea en Redis inmediatamente
|
||||
- [CA-102-2] La cola tiene nombre por tenant (ej: whatsapp:messages:{tenantId})
|
||||
- [CA-102-3] Se registra timestamp de enqueue
|
||||
- [CA-102-4] Se implementa retry automatico en caso de fallo
|
||||
- [CA-102-5] Se monitorea longitud de la cola
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-102-01 | Crear consumer de Redis para WhatsApp | 2h |
|
||||
| MCH-TT-102-02 | Implementar logica de enqueue en webhook | 2h |
|
||||
| MCH-TT-102-03 | Manejo de retries y fallidos | 2h |
|
||||
| MCH-TT-102-04 | Monitoreo y alertas de cola | 2h |
|
||||
|
||||
### MCH-US-103: Procesamiento de mensajes con MCP Server
|
||||
**Story Points:** 10
|
||||
|
||||
**Como** worker de procesamiento
|
||||
**Quiero** enviar mensajes a MCP Server para respuestas con IA
|
||||
**Para** proporcionar respuestas inteligentes a clientes
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-103-1] El worker consume mensajes de la cola Redis
|
||||
- [CA-103-2] Envía mensaje a MCP Server (texto o transcripcion)
|
||||
- [CA-103-3] Recibe respuesta del MCP
|
||||
- [CA-103-4] Registra la conversacion y respuesta en BD
|
||||
- [CA-103-5] Maneja timeout si MCP no responde
|
||||
- [CA-103-6] Registra errores sin detener el worker
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-103-01 | Worker que consume de Redis | 3h |
|
||||
| MCH-TT-103-02 | Cliente HTTP para MCP Server | 2h |
|
||||
| MCH-TT-103-03 | Persistencia de conversaciones | 2h |
|
||||
| MCH-TT-103-04 | Manejo de errores y timeouts | 2h |
|
||||
| MCH-TT-103-05 | Tests de integracion | 1h |
|
||||
|
||||
### MCH-US-104: Multi-tenant con routing por numero
|
||||
**Story Points:** 9
|
||||
|
||||
**Como** servicio multi-tenant
|
||||
**Quiero** identificar el tenant segun el numero de WhatsApp de destino
|
||||
**Para** garantizar aislamiento de datos entre negocios
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-104-1] Se busca tenant_id por numero de telefono en tenant_integrations
|
||||
- [CA-104-2] Si no existe, se rechaza el mensaje (no valido)
|
||||
- [CA-104-3] Se asocia cada mensaje a su tenant_id en BD
|
||||
- [CA-104-4] La cola de Redis es por tenant
|
||||
- [CA-104-5] MCP context incluye tenant_id para respuestas contextualizadas
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-104-01 | Mapper de numero a tenant_id | 2h |
|
||||
| MCH-TT-104-02 | Validacion y rechazo de numeros desconocidos | 2h |
|
||||
| MCH-TT-104-03 | Aislamiento en BD con tenant_id | 2h |
|
||||
| MCH-TT-104-04 | Tests de routing multi-tenant | 3h |
|
||||
|
||||
### MCH-US-105: Envio de mensajes de texto
|
||||
**Story Points:** 6
|
||||
|
||||
**Como** backend o trigger de negocio
|
||||
**Quiero** enviar mensajes de texto simples a clientes
|
||||
**Para** notificar estados, recordatorios, etc.
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-105-1] Endpoint POST /whatsapp/send acepta numero y contenido
|
||||
- [CA-105-2] Se valida numero de telefono valido
|
||||
- [CA-105-3] Se envia a Meta API con access_token correcto
|
||||
- [CA-105-4] Se registra el mensaje en BD con estado pending
|
||||
- [CA-105-5] Se retorna message_id de Meta para tracking
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-105-01 | Controller POST /whatsapp/send | 2h |
|
||||
| MCH-TT-105-02 | Validacion de numero de telefono | 1h |
|
||||
| MCH-TT-105-03 | Cliente de Meta API para envio | 2h |
|
||||
| MCH-TT-105-04 | Tests de envio | 1h |
|
||||
|
||||
### MCH-US-106: Envio de templates pre-aprobados
|
||||
**Story Points:** 11
|
||||
|
||||
**Como** backend de negocio
|
||||
**Quiero** enviar templates pre-aprobados por Meta con variables
|
||||
**Para** notificaciones con formato consistente sin reenvios
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-106-1] Se cargan templates desde BD (recordatorio, confirmacion pedido, etc.)
|
||||
- [CA-106-2] Endpoint POST /whatsapp/template acepta template_name y parametros
|
||||
- [CA-106-3] Se valida que template existe y esta aprobado por Meta
|
||||
- [CA-106-4] Se reemplazan variables {{1}}, {{2}}, etc. correctamente
|
||||
- [CA-106-5] Se envia a Meta API
|
||||
- [CA-106-6] Se registra en BD para auditoria
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-106-01 | Modelo de datos para templates | 2h |
|
||||
| MCH-TT-106-02 | Loader de templates desde BD | 2h |
|
||||
| MCH-TT-106-03 | Parser y reemplazo de variables | 2h |
|
||||
| MCH-TT-106-04 | Controller POST /whatsapp/template | 2h |
|
||||
| MCH-TT-106-05 | Tests de templates | 3h |
|
||||
|
||||
### MCH-US-107: Historial de conversaciones
|
||||
**Story Points:** 8
|
||||
|
||||
**Como** cliente o admin
|
||||
**Quiero** ver el historial de conversaciones con cada numero
|
||||
**Para** mantener contexto y auditoria de interacciones
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-107-1] Endpoint GET /whatsapp/conversations lista conversaciones del tenant
|
||||
- [CA-107-2] Cada conversacion muestra ultimo mensaje y timestamp
|
||||
- [CA-107-3] Endpoint GET /whatsapp/messages/:conversationId lista mensajes ordenados
|
||||
- [CA-107-4] Se filtra por rango de fechas (opcional)
|
||||
- [CA-107-5] Se muestra direccion (in/out), tipo y estado de cada mensaje
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-107-01 | Controller GET /whatsapp/conversations | 2h |
|
||||
| MCH-TT-107-02 | Controller GET /whatsapp/messages/:id | 2h |
|
||||
| MCH-TT-107-03 | Queries optimizadas en BD | 2h |
|
||||
| MCH-TT-107-04 | Tests de paginacion y filtros | 2h |
|
||||
|
||||
### MCH-US-108: Delivery reports y confirmacion de estado
|
||||
**Story Points:** 7
|
||||
|
||||
**Como** backend
|
||||
**Quiero** recibir webhooks de Meta con status de delivery
|
||||
**Para** actualizar estado de mensajes enviados
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-108-1] Meta envia webhook con message_status (sent, delivered, read, failed)
|
||||
- [CA-108-2] Se actualiza estado en tabla messages
|
||||
- [CA-108-3] Se maneja failed con reintento opcional
|
||||
- [CA-108-4] Se log cada cambio de estado
|
||||
- [CA-108-5] Se notifica al cliente si es necesario
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-108-01 | Handler de status webhook | 2h |
|
||||
| MCH-TT-108-02 | Logica de actualizacion de estado | 2h |
|
||||
| MCH-TT-108-03 | Manejo de reintentos | 2h |
|
||||
| MCH-TT-108-04 | Tests de delivery reports | 1h |
|
||||
|
||||
### MCH-US-109: Configuracion y credenciales por tenant
|
||||
**Story Points:** 5
|
||||
|
||||
**Como** admin de tenant
|
||||
**Quiero** almacenar y gestionar credenciales de Meta de forma segura
|
||||
**Para** habilitar WhatsApp en mi negocio sin exponer secrets
|
||||
|
||||
#### Criterios de Aceptacion
|
||||
- [CA-109-1] Credenciales se almacenan encriptadas en tenant_integrations
|
||||
- [CA-109-2] phone_number_id, access_token, verify_token se persisten
|
||||
- [CA-109-3] Endpoint para actualizar credenciales con validacion
|
||||
- [CA-109-4] Nunca se retornan credenciales en respuestas de API
|
||||
- [CA-109-5] Se registra auditar cuando se cambian credenciales
|
||||
|
||||
#### Tareas
|
||||
| ID | Tarea | Estimación |
|
||||
|----|-------|------------|
|
||||
| MCH-TT-109-01 | Migracion de schema para encriptacion | 1h |
|
||||
| MCH-TT-109-02 | Service de gestion de credenciales | 2h |
|
||||
| MCH-TT-109-03 | Endpoint PUT /whatsapp/credentials | 1h |
|
||||
| MCH-TT-109-04 | Tests de seguridad | 1h |
|
||||
|
||||
### Resumen de Story Points
|
||||
| Historia | Descripción | SP |
|
||||
|----------|-------------|-----|
|
||||
| MCH-US-100 | Webhook de Meta para recepcion de mensajes | 8 |
|
||||
| MCH-US-101 | Procesamiento de tipos de mensaje entrante | 13 |
|
||||
| MCH-US-102 | Cola de mensajes con Redis | 8 |
|
||||
| MCH-US-103 | Procesamiento de mensajes con MCP Server | 10 |
|
||||
| MCH-US-104 | Multi-tenant con routing por numero | 9 |
|
||||
| MCH-US-105 | Envio de mensajes de texto | 6 |
|
||||
| MCH-US-106 | Envio de templates pre-aprobados | 11 |
|
||||
| MCH-US-107 | Historial de conversaciones | 8 |
|
||||
| MCH-US-108 | Delivery reports y confirmacion de estado | 7 |
|
||||
| MCH-US-109 | Configuracion y credenciales por tenant | 5 |
|
||||
| **Total** | | **85** |
|
||||
|
||||
## Entregables
|
||||
|
||||
| Entregable | Estado | Archivo |
|
||||
@ -242,4 +485,4 @@ o lo enviamos a tu domicilio.
|
||||
|
||||
---
|
||||
|
||||
**Ultima actualizacion:** 2026-01-10
|
||||
**Ultima actualizacion:** 2026-01-17
|
||||
|
||||
Loading…
Reference in New Issue
Block a user