rckrdmrd/michangarrito
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[MCH-DOC-VAL] docs: Estandarizar épicas MCH-016 a MCH-027 con HU formales

Browse Source 
TAREA-001: Estandarización de épicas al formato SIMCO 4.0.1

Cambios aplicados a las 12 épicas:
- Frontmatter: simco_version="4.0.1", story_points, updated_at=2026-01-17
- Metadata: Agregado **Story Points:** N
- Nueva sección "## Historias de Usuario" antes de Entregables
- Cada HU: Como/Quiero/Para, Story Points, Criterios [CA-XXX-N], Tareas [MCH-TT-XXX-NN]
- Tabla resumen de Story Points al final de cada épica

Épicas estandarizadas:
- MCH-016: Entregas a Domicilio (5 HUs, 34 SP)
- MCH-017: Notificaciones (6 HUs, 34 SP)
- MCH-018: Planes y Suscripciones (6 HUs, 21 SP)
- MCH-019: Tienda de Tokens (6 HUs, 21 SP)
- MCH-020: Pagos de Suscripción (6 HUs, 34 SP)
- MCH-021: Dashboard Web (6 HUs, 21 SP)
- MCH-022: Modo Offline (6 HUs, 21 SP)
- MCH-023: Programa de Referidos (6 HUs, 21 SP)
- MCH-024: CoDi y SPEI (5 HUs, 21 SP)
- MCH-025: Widgets y Atajos (6 HUs, 21 SP)
- MCH-026: Multi-idioma LATAM (7 HUs, 34 SP)
- MCH-027: Integración SAT (8 HUs, 55 SP)

Rango de IDs utilizados: MCH-US-150 a MCH-US-269

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
rckrdmrd 2026-01-17 04:40:45 -06:00
parent 08397f9828
commit c659f1c623
12 changed files with 2110 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
docs/01-epicas/MCH-016-entregas-domicilio.md
View File

@ -7,8 +7,9 @@ status: Pendiente
phase: 4
priority: P2
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:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 10-11
- **Story Points:** 34
## Descripcion
@ -158,6 +160,154 @@ Bot: "Perfecto! Envio a Col. Centro = $25
- Boton "En camino"
- Boton "Entregado" + foto
## Historias de Usuario
### MCH-US-150: Gestion de Zonas de Cobertura
**Story Points:** 8
**Como** dueno de negocio
**Quiero** definir zonas de cobertura por radio o poligono
**Para** controlar las areas donde ofrezco servicio de entrega a domicilio
#### Criterios de Aceptacion
- [CA-150-1] El sistema permite crear zonas por radio (km desde punto central)
- [CA-150-2] El sistema permite crear zonas por poligono (lista de colonias)
- [CA-150-3] Cada zona tiene nombre, tipo, coordenadas y estado activo/inactivo
- [CA-150-4] Las zonas se visualizan en un mapa interactivo
- [CA-150-5] Se pueden editar y eliminar zonas existentes
- [CA-150-6] El sistema valida que no existan zonas con el mismo nombre
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-150-01 | Crear tabla delivery_zones con campos requeridos | 2h |
| MCH-TT-150-02 | Implementar DeliveryZonesService con CRUD | 4h |
| MCH-TT-150-03 | Crear endpoints REST para zonas | 3h |
| MCH-TT-150-04 | Desarrollar componente DeliveryZonesMap | 6h |
| MCH-TT-150-05 | Implementar edicion visual de poligonos | 4h |
| MCH-TT-150-06 | Agregar validaciones y tests | 3h |
---
### MCH-US-151: Configuracion de Costos de Envio
**Story Points:** 5
**Como** dueno de negocio
**Quiero** configurar tarifas de envio por zona
**Para** cobrar el costo adecuado segun la distancia de entrega
#### Criterios de Aceptacion
- [CA-151-1] Cada zona tiene un costo de envio configurable
- [CA-151-2] Se puede definir un pedido minimo por zona
- [CA-151-3] Se puede configurar tiempo estimado de entrega por zona
- [CA-151-4] El bot muestra el costo de envio al cliente antes de confirmar
- [CA-151-5] El costo de envio se suma correctamente al total del pedido
- [CA-151-6] Se valida que la direccion este dentro de una zona activa
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-151-01 | Agregar campos delivery_fee, min_order, estimated_time a zonas | 1h |
| MCH-TT-151-02 | Implementar endpoint check-coverage | 3h |
| MCH-TT-151-03 | Integrar calculo de costo en flujo de pedido | 4h |
| MCH-TT-151-04 | Actualizar UI para configurar tarifas | 3h |
| MCH-TT-151-05 | Agregar validacion de pedido minimo | 2h |
---
### MCH-US-152: Asignacion de Repartidores
**Story Points:** 8
**Como** dueno o empleado del negocio
**Quiero** asignar pedidos a repartidores disponibles
**Para** gestionar las entregas de manera organizada
#### Criterios de Aceptacion
- [CA-152-1] Se pueden ver pedidos pendientes de asignar en dashboard
- [CA-152-2] Se muestra lista de repartidores disponibles (rol delivery)
- [CA-152-3] Al asignar, el sistema crea registro en tabla deliveries
- [CA-152-4] El repartidor recibe notificacion de asignacion
- [CA-152-5] El cliente recibe notificacion de que su pedido fue asignado
- [CA-152-6] Se puede reasignar un pedido a otro repartidor
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-152-01 | Crear tabla deliveries con campos requeridos | 2h |
| MCH-TT-152-02 | Implementar DeliveriesService | 4h |
| MCH-TT-152-03 | Crear endpoint assign-delivery | 3h |
| MCH-TT-152-04 | Desarrollar componente DeliveryAssignment | 5h |
| MCH-TT-152-05 | Implementar notificaciones a repartidor | 3h |
| MCH-TT-152-06 | Implementar notificaciones a cliente | 2h |
| MCH-TT-152-07 | Agregar logica de reasignacion | 2h |
---
### MCH-US-153: Tracking de Estado de Entrega
**Story Points:** 8
**Como** repartidor
**Quiero** actualizar el estado de mis entregas asignadas
**Para** mantener informados al negocio y al cliente sobre el progreso
#### Criterios de Aceptacion
- [CA-153-1] El repartidor ve lista de entregas asignadas en app movil
- [CA-153-2] Puede marcar entrega como "En camino" con timestamp
- [CA-153-3] Puede marcar entrega como "Entregado" con timestamp
- [CA-153-4] Los estados validos son: asignado, en_camino, entregado
- [CA-153-5] El cliente recibe notificacion en cada cambio de estado
- [CA-153-6] El dashboard muestra estado actual de todas las entregas
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-153-01 | Implementar endpoint update-status | 3h |
| MCH-TT-153-02 | Desarrollar pantalla mobile DeliveryTracking | 6h |
| MCH-TT-153-03 | Implementar logica de transicion de estados | 2h |
| MCH-TT-153-04 | Agregar timestamps pickup_at y delivered_at | 1h |
| MCH-TT-153-05 | Implementar notificaciones push al cliente | 4h |
| MCH-TT-153-06 | Actualizar dashboard con estados en tiempo real | 3h |
---
### MCH-US-154: Confirmacion de Entrega con Evidencia
**Story Points:** 5
**Como** repartidor
**Quiero** confirmar la entrega con foto o firma opcional
**Para** tener evidencia de que el pedido fue entregado correctamente
#### Criterios de Aceptacion
- [CA-154-1] El repartidor puede tomar foto de la entrega
- [CA-154-2] El repartidor puede capturar firma del cliente (opcional)
- [CA-154-3] La foto/firma se almacena y vincula a la entrega
- [CA-154-4] El dueno puede ver la evidencia en el historial
- [CA-154-5] El cliente recibe mensaje de confirmacion con resumen
- [CA-154-6] El sistema registra hora exacta de confirmacion
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-154-01 | Implementar endpoint confirm-delivery | 2h |
| MCH-TT-154-02 | Agregar upload de foto a storage | 3h |
| MCH-TT-154-03 | Implementar captura de firma en mobile | 4h |
| MCH-TT-154-04 | Guardar URLs de evidencia en deliveries | 1h |
| MCH-TT-154-05 | Mostrar evidencia en historial del dashboard | 3h |
| MCH-TT-154-06 | Enviar confirmacion al cliente via WhatsApp | 2h |
---
### Resumen de Story Points
| Historia | Descripcion | SP |
|----------|-------------|---:|
| MCH-US-150 | Gestion de Zonas de Cobertura | 8 |
| MCH-US-151 | Configuracion de Costos de Envio | 5 |
| MCH-US-152 | Asignacion de Repartidores | 8 |
| MCH-US-153 | Tracking de Estado de Entrega | 8 |
| MCH-US-154 | Confirmacion de Entrega con Evidencia | 5 |
| **TOTAL** | | **34** |
## Entregables
| Entregable | Estado | Archivo |
@ -194,4 +344,4 @@ Bot: "Perfecto! Envio a Col. Centro = $25
---
**Ultima actualizacion:** 2026-01-07
**Ultima actualizacion:** 2026-01-17

181
docs/01-epicas/MCH-017-notificaciones.md
View File

@ -6,9 +6,10 @@ code: MCH-017
status: Pendiente
phase: 4
priority: P1
story_points: 34
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"
dependencies:
blocks: []
depends_on: []
@ -21,6 +22,7 @@ dependencies:
- **Fase:** 4 - Pedidos y Clientes
- **Prioridad:** P1
- **Estado:** Pendiente
- **Story Points:** 34
- **Fecha estimada:** Sprint 8-9
## Descripcion
@ -156,6 +158,179 @@ un saldo pendiente de ${{balance}} en {{business_name}}.
¿Cuando podrias pasar a liquidar?
```
## Historias de Usuario
### MCH-US-160: Push Notifications con Firebase FCM
**Story Points:** 8
**Como** dueno de changarrito
**Quiero** recibir notificaciones push en mi dispositivo movil
**Para** enterarme inmediatamente de eventos importantes del negocio sin tener que revisar la app constantemente
#### Criterios de Aceptacion
- [CA-160-1] El sistema soporta push notifications en iOS y Android via Firebase Cloud Messaging
- [CA-160-2] Los tokens de dispositivo se registran automaticamente al iniciar sesion
- [CA-160-3] Las notificaciones muestran titulo, cuerpo e icono del negocio
- [CA-160-4] Al tocar la notificacion, la app abre la pantalla relevante (pedido, venta, etc.)
- [CA-160-5] Las notificaciones se envian correctamente cuando la app esta en background o cerrada
- [CA-160-6] Los tokens invalidos se desactivan automaticamente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-160-01 | Configurar proyecto Firebase y obtener credenciales | 2h |
| MCH-TT-160-02 | Implementar FirebaseProvider en backend | 4h |
| MCH-TT-160-03 | Crear endpoint POST /notifications/register-device | 2h |
| MCH-TT-160-04 | Implementar device_tokens repository y service | 3h |
| MCH-TT-160-05 | Integrar Firebase SDK en app movil (iOS/Android) | 4h |
| MCH-TT-160-06 | Implementar deep linking desde notificaciones | 3h |
| MCH-TT-160-07 | Crear tests unitarios y de integracion | 2h |
---
### MCH-US-161: Notificaciones WhatsApp
**Story Points:** 5
**Como** dueno de changarrito
**Quiero** enviar notificaciones a mis clientes via WhatsApp
**Para** comunicarme con ellos en el canal que mas usan y asegurar que reciban mis mensajes
#### Criterios de Aceptacion
- [CA-161-1] El sistema envia notificaciones WhatsApp usando la integracion de MCH-011
- [CA-161-2] Las notificaciones usan templates aprobados por WhatsApp Business API
- [CA-161-3] El sistema registra el estado de entrega (sent/delivered/read/failed)
- [CA-161-4] Los errores de envio se manejan con reintentos automaticos (max 3)
- [CA-161-5] El sistema respeta el rate limit de la API de WhatsApp
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-161-01 | Integrar con WhatsApp Service de MCH-011 | 3h |
| MCH-TT-161-02 | Implementar mapeo de templates a mensajes WhatsApp | 2h |
| MCH-TT-161-03 | Crear sistema de reintentos con backoff exponencial | 2h |
| MCH-TT-161-04 | Implementar webhook para callbacks de estado | 2h |
| MCH-TT-161-05 | Crear tests de integracion con WhatsApp Service | 2h |
---
### MCH-US-162: SMS Fallback con Twilio
**Story Points:** 5
**Como** sistema de notificaciones
**Quiero** enviar SMS como canal de respaldo cuando falla WhatsApp
**Para** garantizar que los mensajes criticos lleguen al destinatario
#### Criterios de Aceptacion
- [CA-162-1] El sistema detecta cuando WhatsApp falla despues de reintentos
- [CA-162-2] Los SMS se envian automaticamente como fallback para mensajes criticos
- [CA-162-3] Twilio se integra correctamente con credenciales seguras
- [CA-162-4] El costo de SMS se registra para facturacion
- [CA-162-5] Los mensajes SMS respetan el limite de 160 caracteres o se dividen correctamente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-162-01 | Configurar cuenta Twilio y obtener credenciales | 1h |
| MCH-TT-162-02 | Implementar TwilioProvider en backend | 3h |
| MCH-TT-162-03 | Crear logica de fallback WhatsApp -> SMS | 2h |
| MCH-TT-162-04 | Implementar registro de costos por SMS enviado | 2h |
| MCH-TT-162-05 | Crear tests unitarios y de integracion | 2h |
---
### MCH-US-163: Preferencias de Notificacion por Usuario
**Story Points:** 5
**Como** usuario de la aplicacion
**Quiero** configurar mis preferencias de notificacion por canal
**Para** recibir solo las notificaciones que me interesan en los horarios que prefiero
#### Criterios de Aceptacion
- [CA-163-1] El usuario puede habilitar/deshabilitar cada canal (push, WhatsApp, SMS)
- [CA-163-2] El usuario puede configurar "horas tranquilas" donde no recibe notificaciones
- [CA-163-3] El sistema respeta las preferencias antes de enviar cualquier notificacion
- [CA-163-4] Las notificaciones programadas durante horas tranquilas se posponen automaticamente
- [CA-163-5] Existe una pantalla de configuracion accesible desde el perfil
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-163-01 | Crear tabla notification_preferences y migracion | 1h |
| MCH-TT-163-02 | Implementar NotificationPreferencesService | 2h |
| MCH-TT-163-03 | Crear endpoints GET/PUT /notifications/preferences | 2h |
| MCH-TT-163-04 | Implementar logica de quiet hours en NotificationService | 2h |
| MCH-TT-163-05 | Crear UI de preferencias en frontend | 4h |
| MCH-TT-163-06 | Crear tests unitarios | 2h |
---
### MCH-US-164: Templates de Notificacion Personalizables
**Story Points:** 5
**Como** administrador del sistema
**Quiero** gestionar templates de notificacion por tipo y canal
**Para** mantener consistencia en los mensajes y permitir personalizacion por tenant
#### Criterios de Aceptacion
- [CA-164-1] Existen templates predefinidos para todos los eventos del sistema
- [CA-164-2] Los templates soportan variables dinamicas ({{order_id}}, {{customer_name}}, etc.)
- [CA-164-3] Cada tenant puede personalizar los templates manteniendo las variables requeridas
- [CA-164-4] El sistema valida que las variables requeridas esten presentes al guardar
- [CA-164-5] Los templates se cachean para mejor rendimiento
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-164-01 | Crear tabla notification_templates y migracion | 1h |
| MCH-TT-164-02 | Implementar NotificationTemplateService con interpolacion | 3h |
| MCH-TT-164-03 | Crear seed de templates predefinidos | 2h |
| MCH-TT-164-04 | Implementar validacion de variables requeridas | 2h |
| MCH-TT-164-05 | Agregar cache Redis para templates | 2h |
| MCH-TT-164-06 | Crear tests unitarios | 2h |
---
### MCH-US-165: Historial de Notificaciones
**Story Points:** 6
**Como** usuario de la aplicacion
**Quiero** ver el historial de notificaciones recibidas
**Para** revisar mensajes anteriores y no perder informacion importante
#### Criterios de Aceptacion
- [CA-165-1] El usuario puede ver lista paginada de sus notificaciones
- [CA-165-2] Las notificaciones muestran estado (leida/no leida)
- [CA-165-3] El usuario puede marcar notificaciones como leidas individual o masivamente
- [CA-165-4] El historial se filtra por tipo, canal y rango de fechas
- [CA-165-5] Las notificaciones antiguas (>30 dias) se archivan automaticamente
- [CA-165-6] Existe badge con contador de no leidas en la UI
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-165-01 | Crear tabla notifications y migracion | 1h |
| MCH-TT-165-02 | Implementar NotificationsRepository con paginacion | 2h |
| MCH-TT-165-03 | Crear endpoint GET /notifications con filtros | 2h |
| MCH-TT-165-04 | Crear endpoint PUT /notifications/:id/read | 1h |
| MCH-TT-165-05 | Implementar job de archivado automatico | 2h |
| MCH-TT-165-06 | Crear pantalla de historial en frontend | 4h |
| MCH-TT-165-07 | Implementar badge de notificaciones no leidas | 2h |
| MCH-TT-165-08 | Crear tests unitarios y de integracion | 2h |
---
### Resumen de Historias de Usuario
| ID | Titulo | Story Points | Estado |
|----|--------|--------------|--------|
| MCH-US-160 | Push Notifications con Firebase FCM | 8 | Pendiente |
| MCH-US-161 | Notificaciones WhatsApp | 5 | Pendiente |
| MCH-US-162 | SMS Fallback con Twilio | 5 | Pendiente |
| MCH-US-163 | Preferencias de Notificacion por Usuario | 5 | Pendiente |
| MCH-US-164 | Templates de Notificacion Personalizables | 5 | Pendiente |
| MCH-US-165 | Historial de Notificaciones | 6 | Pendiente |
| **Total** | | **34** | |
## Entregables
| Entregable | Estado | Archivo |
@ -210,4 +385,4 @@ un saldo pendiente de ${{balance}} en {{business_name}}.
---
**Ultima actualizacion:** 2026-01-07
**Ultima actualizacion:** 2026-01-17

169
docs/01-epicas/MCH-018-planes-suscripciones.md
View File

@ -6,9 +6,10 @@ code: MCH-018
status: Completado
phase: 5
priority: P0
story_points: 21
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"
dependencies:
blocks: []
depends_on: []
@ -21,6 +22,7 @@ dependencies:
- **Fase:** 5 - Monetizacion
- **Prioridad:** P0
- **Estado:** Completado
- **Story Points:** 21
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-07
@ -179,6 +181,167 @@ const subscription = await stripe.subscriptions.create({
- `invoice.payment_succeeded`
- `invoice.payment_failed`
## Historias de Usuario
### MCH-US-170: Catalogo de Planes de Suscripcion
**Story Points:** 3
**Como** visitante o usuario registrado
**Quiero** ver el catalogo de planes disponibles con sus caracteristicas y precios
**Para** tomar una decision informada sobre cual plan contratar
#### Criterios de Aceptacion
- [CA-170-1] Se muestran los planes Changarrito ($99/mes) y Tiendita ($199/mes)
- [CA-170-2] Cada plan muestra claramente sus caracteristicas incluidas y excluidas
- [CA-170-3] Se indica el periodo de prueba gratuito de 14 dias
- [CA-170-4] Existe boton de CTA para iniciar suscripcion en cada plan
- [CA-170-5] La comparativa entre planes es clara y visual
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-170-01 | Crear componente PlanCard con features | 2h |
| MCH-TT-170-02 | Implementar pagina Plans.tsx con comparativa | 3h |
| MCH-TT-170-03 | Integrar endpoint GET /subscriptions/plans | 1h |
| MCH-TT-170-04 | Agregar tests unitarios de componentes | 2h |
---
### MCH-US-171: Proceso de Suscripcion con Trial
**Story Points:** 5
**Como** usuario nuevo
**Quiero** suscribirme a un plan con un periodo de prueba gratuito
**Para** probar el sistema antes de comprometerme con el pago
#### Criterios de Aceptacion
- [CA-171-1] El usuario puede seleccionar un plan y registrar metodo de pago via Stripe
- [CA-171-2] Se crea suscripcion en estado "trialing" con 14 dias de trial
- [CA-171-3] El usuario tiene acceso completo a features del plan durante el trial
- [CA-171-4] Se notifica por email la activacion del trial y fecha de primer cobro
- [CA-171-5] El tenant se configura con los limites del plan seleccionado
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-171-01 | Implementar flujo de checkout con Stripe Elements | 4h |
| MCH-TT-171-02 | Crear endpoint POST /subscriptions/subscribe | 3h |
| MCH-TT-171-03 | Configurar trial_period_days en Stripe | 1h |
| MCH-TT-171-04 | Implementar notificaciones email de trial | 2h |
| MCH-TT-171-05 | Tests de integracion del flujo completo | 2h |
---
### MCH-US-172: Facturacion Recurrente Automatica
**Story Points:** 5
**Como** suscriptor activo
**Quiero** que mi pago mensual se procese automaticamente
**Para** mantener mi suscripcion activa sin intervencion manual
#### Criterios de Aceptacion
- [CA-172-1] Stripe cobra automaticamente al terminar el trial o periodo actual
- [CA-172-2] Se genera invoice y se almacena en tabla invoices
- [CA-172-3] El webhook invoice.payment_succeeded actualiza estado a "active"
- [CA-172-4] El webhook invoice.payment_failed marca como "past_due" con grace period
- [CA-172-5] Se envia email de confirmacion de pago con link al recibo
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-172-01 | Implementar handler webhook invoice.payment_succeeded | 2h |
| MCH-TT-172-02 | Implementar handler webhook invoice.payment_failed | 2h |
| MCH-TT-172-03 | Crear servicio de sincronizacion de invoices | 3h |
| MCH-TT-172-04 | Implementar emails transaccionales de facturacion | 2h |
| MCH-TT-172-05 | Configurar retry policy para pagos fallidos | 1h |
---
### MCH-US-173: Upgrade y Downgrade de Plan
**Story Points:** 3
**Como** suscriptor del plan Changarrito
**Quiero** poder cambiar a plan Tiendita (o viceversa)
**Para** ajustar mi suscripcion a las necesidades de mi negocio
#### Criterios de Aceptacion
- [CA-173-1] El usuario puede solicitar cambio de plan desde su dashboard
- [CA-173-2] Se calcula y muestra el prorateo antes de confirmar
- [CA-173-3] En upgrade: se cobra diferencia y activan features inmediatamente
- [CA-173-4] En downgrade: se ajusta al siguiente ciclo de facturacion
- [CA-173-5] Los limites del tenant se actualizan segun nuevo plan
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-173-01 | Implementar endpoint PUT /subscriptions/change-plan | 3h |
| MCH-TT-173-02 | Calcular prorateo con Stripe proration_behavior | 2h |
| MCH-TT-173-03 | Crear UI de cambio de plan con preview de costos | 2h |
| MCH-TT-173-04 | Actualizar limites de tenant post-cambio | 1h |
---
### MCH-US-174: Cancelacion y Pausas de Suscripcion
**Story Points:** 3
**Como** suscriptor
**Quiero** poder cancelar o pausar mi suscripcion
**Para** gestionar el ciclo de vida segun mis circunstancias
#### Criterios de Aceptacion
- [CA-174-1] El usuario puede solicitar cancelacion con confirmacion requerida
- [CA-174-2] La cancelacion es efectiva al final del periodo pagado
- [CA-174-3] Los datos se preservan 30 dias despues de cancelar
- [CA-174-4] El usuario puede reanudar suscripcion cancelada antes de perder datos
- [CA-174-5] Se puede pausar temporalmente con estado "paused"
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-174-01 | Implementar endpoint POST /subscriptions/cancel | 2h |
| MCH-TT-174-02 | Implementar endpoint POST /subscriptions/resume | 2h |
| MCH-TT-174-03 | Crear UI de cancelacion con encuesta de salida | 2h |
| MCH-TT-174-04 | Implementar job de limpieza de datos post-30 dias | 2h |
| MCH-TT-174-05 | Manejar webhook customer.subscription.deleted | 1h |
---
### MCH-US-175: Historial de Facturacion
**Story Points:** 2
**Como** suscriptor
**Quiero** ver mi historial de facturas y descargar recibos
**Para** tener control de mis gastos y documentacion fiscal
#### Criterios de Aceptacion
- [CA-175-1] Se muestra lista de invoices con fecha, monto y estado
- [CA-175-2] Cada invoice tiene link para descargar PDF desde Stripe
- [CA-175-3] Se pueden filtrar invoices por rango de fechas
- [CA-175-4] Se muestra informacion de la suscripcion actual y proximo cobro
- [CA-175-5] El historial es accesible desde pagina Billing.tsx
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-175-01 | Implementar endpoint GET /subscriptions/invoices | 2h |
| MCH-TT-175-02 | Crear pagina Billing.tsx con historial | 3h |
| MCH-TT-175-03 | Integrar descarga de PDF via Stripe invoice URL | 1h |
| MCH-TT-175-04 | Agregar filtros y paginacion al historial | 2h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Estado |
|----|----------|--------------|--------|
| MCH-US-170 | Catalogo de Planes de Suscripcion | 3 | Completado |
| MCH-US-171 | Proceso de Suscripcion con Trial | 5 | Completado |
| MCH-US-172 | Facturacion Recurrente Automatica | 5 | Completado |
| MCH-US-173 | Upgrade y Downgrade de Plan | 3 | En Progreso |
| MCH-US-174 | Cancelacion y Pausas de Suscripcion | 3 | Completado |
| MCH-US-175 | Historial de Facturacion | 2 | Pendiente |
| **TOTAL** | | **21** | |
## Entregables
| Entregable | Estado | Archivo |
@ -238,4 +401,4 @@ const subscription = await stripe.subscriptions.create({
---
**Ultima actualizacion:** 2026-01-07
**Ultima actualizacion:** 2026-01-17

173
docs/01-epicas/MCH-019-tienda-tokens.md
View File

@ -7,8 +7,9 @@ status: Pendiente
phase: 5
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: 21
dependencies:
blocks: []
depends_on: []
@ -22,6 +23,7 @@ dependencies:
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 11-12
- **Story Points:** 21
## Descripcion
@ -165,6 +167,171 @@ Recarga para seguir usando el asistente IA.
- Saldo actual
- CTA comprar
## Historias de Usuario
### MCH-US-180: Catalogo de Paquetes de Tokens
**Story Points:** 3
**Como** usuario de MiChangarrito
**Quiero** ver los paquetes de tokens disponibles con sus precios y beneficios
**Para** elegir el que mejor se adapte a mis necesidades de uso de IA
#### Criterios de Aceptacion
- [CA-180-1] El catalogo muestra los 4 paquetes definidos (Basico, Popular, Pro, Ultra)
- [CA-180-2] Cada paquete muestra cantidad de tokens, precio y precio por token
- [CA-180-3] El paquete "Popular" se destaca visualmente como recomendado
- [CA-180-4] Los precios se muestran en la moneda local del tenant
- [CA-180-5] Solo se muestran paquetes activos (active = true)
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-180-01 | Crear endpoint GET /tokens/packages | 2h |
| MCH-TT-180-02 | Implementar TokenPackageCard component | 2h |
| MCH-TT-180-03 | Crear TokenShop grid layout | 2h |
| MCH-TT-180-04 | Agregar seed de paquetes de tokens | 1h |
---
### MCH-US-181: Compra de Tokens con Tarjeta
**Story Points:** 5
**Como** usuario de MiChangarrito
**Quiero** comprar tokens usando mi tarjeta de credito o debito
**Para** tener acceso inmediato a funciones de IA sin salir de la aplicacion
#### Criterios de Aceptacion
- [CA-181-1] El usuario puede seleccionar un paquete y proceder al pago
- [CA-181-2] La integracion con Stripe procesa el pago de forma segura
- [CA-181-3] Los tokens se acreditan inmediatamente tras pago exitoso
- [CA-181-4] Se genera registro en token_purchases con stripe_payment_id
- [CA-181-5] El usuario recibe confirmacion visual y notificacion del acreditamiento
- [CA-181-6] En caso de error, se muestra mensaje claro y se registra el fallo
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-181-01 | Crear endpoint POST /tokens/purchase | 3h |
| MCH-TT-181-02 | Implementar integracion Stripe Checkout | 4h |
| MCH-TT-181-03 | Crear webhook para confirmar pagos | 3h |
| MCH-TT-181-04 | Implementar UI de checkout con Stripe Elements | 3h |
| MCH-TT-181-05 | Crear pantalla de confirmacion de compra | 2h |
---
### MCH-US-182: Compra de Tokens en OXXO
**Story Points:** 3
**Como** usuario de MiChangarrito sin tarjeta bancaria
**Quiero** generar un voucher para pagar en OXXO
**Para** poder comprar tokens usando efectivo
#### Criterios de Aceptacion
- [CA-182-1] El usuario puede seleccionar OXXO como metodo de pago
- [CA-182-2] Se genera voucher con codigo de barras y monto a pagar
- [CA-182-3] El voucher incluye fecha de vencimiento (72 horas)
- [CA-182-4] Los tokens se acreditan automaticamente al confirmar pago via webhook
- [CA-182-5] El usuario puede ver el estado de vouchers pendientes
- [CA-182-6] Se envia notificacion cuando el pago es confirmado
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-182-01 | Implementar Stripe OXXO payment method | 3h |
| MCH-TT-182-02 | Crear componente de voucher descargable | 2h |
| MCH-TT-182-03 | Configurar webhook para pagos OXXO | 2h |
| MCH-TT-182-04 | Implementar listado de vouchers pendientes | 2h |
---
### MCH-US-183: Visualizacion de Saldo y Consumo
**Story Points:** 3
**Como** usuario de MiChangarrito
**Quiero** ver mi saldo de tokens actual y el consumo reciente
**Para** saber cuantos tokens me quedan y planificar mis compras
#### Criterios de Aceptacion
- [CA-183-1] El saldo se muestra en el header de la aplicacion (TokenBalance)
- [CA-183-2] El saldo se actualiza en tiempo real tras cada operacion
- [CA-183-3] Al hacer click en el saldo, se muestra detalle con consumo reciente
- [CA-183-4] Se muestra estimacion de consultas restantes basado en promedio
- [CA-183-5] El componente es responsive y se adapta a movil
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-183-01 | Crear endpoint GET /tokens/balance | 2h |
| MCH-TT-183-02 | Implementar TokenBalance component en header | 2h |
| MCH-TT-183-03 | Crear cache de balance con Redis | 2h |
| MCH-TT-183-04 | Implementar actualizacion en tiempo real (WebSocket) | 3h |
---
### MCH-US-184: Historial de Consumo de Tokens
**Story Points:** 3
**Como** usuario de MiChangarrito
**Quiero** ver el historial detallado de consumo de tokens por operacion
**Para** entender como uso mis tokens y optimizar mi consumo
#### Criterios de Aceptacion
- [CA-184-1] El historial muestra fecha, tipo de operacion y tokens consumidos
- [CA-184-2] Se puede filtrar por rango de fechas y tipo de operacion
- [CA-184-3] Se muestra grafica de consumo por dia/semana/mes
- [CA-184-4] El historial incluye paginacion para grandes volumenes
- [CA-184-5] Se puede exportar el historial a CSV
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-184-01 | Crear endpoint GET /tokens/usage con filtros | 2h |
| MCH-TT-184-02 | Crear endpoint GET /tokens/usage/summary | 2h |
| MCH-TT-184-03 | Implementar TokenUsageHistory component | 3h |
| MCH-TT-184-04 | Agregar grafica de consumo con Recharts | 2h |
| MCH-TT-184-05 | Implementar exportacion a CSV | 1h |
---
### MCH-US-185: Alertas de Saldo Bajo
**Story Points:** 4
**Como** usuario de MiChangarrito
**Quiero** recibir alertas cuando mi saldo de tokens este bajo
**Para** recargar a tiempo y no quedarme sin acceso a funciones de IA
#### Criterios de Aceptacion
- [CA-185-1] Se envia alerta cuando el saldo llega al umbral configurado (default 100)
- [CA-185-2] Se envia alerta critica cuando el saldo llega a 20 tokens
- [CA-185-3] Las alertas se envian por los canales configurados (push, WhatsApp)
- [CA-185-4] El usuario puede configurar sus umbrales y canales preferidos
- [CA-185-5] No se envian alertas duplicadas en menos de 24 horas
- [CA-185-6] La alerta incluye CTA directo a la tienda de tokens
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-185-01 | Implementar servicio de monitoreo de saldo | 3h |
| MCH-TT-185-02 | Crear job de verificacion de umbrales | 2h |
| MCH-TT-185-03 | Integrar con sistema de notificaciones push | 2h |
| MCH-TT-185-04 | Integrar con WhatsApp Business API | 3h |
| MCH-TT-185-05 | Crear UI de configuracion de alertas | 2h |
| MCH-TT-185-06 | Implementar control de alertas duplicadas | 1h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Prioridad |
|----|----------|--------------|-----------|
| MCH-US-180 | Catalogo de Paquetes de Tokens | 3 | Alta |
| MCH-US-181 | Compra de Tokens con Tarjeta | 5 | Alta |
| MCH-US-182 | Compra de Tokens en OXXO | 3 | Alta |
| MCH-US-183 | Visualizacion de Saldo y Consumo | 3 | Alta |
| MCH-US-184 | Historial de Consumo de Tokens | 3 | Media |
| MCH-US-185 | Alertas de Saldo Bajo | 4 | Media |
| **Total** | | **21** | |
## Entregables
| Entregable | Estado | Archivo |
@ -207,4 +374,4 @@ Recarga para seguir usando el asistente IA.
---
**Ultima actualizacion:** 2026-01-07
**Ultima actualizacion:** 2026-01-17

177
docs/01-epicas/MCH-020-pagos-suscripcion.md
View File

@ -6,9 +6,10 @@ code: MCH-020
status: Completado
phase: 5
priority: P0
story_points: 34
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"
dependencies:
blocks: []
depends_on: []
@ -21,6 +22,7 @@ dependencies:
- **Fase:** 5 - Monetizacion
- **Prioridad:** P0
- **Estado:** Completado
- **Story Points:** 34
- **Fecha completado:** 2026-01-10
## Descripcion
@ -201,6 +203,175 @@ en 3 dias si no actualizas tu pago.
- Estado y fecha
- Descargar recibo
## Historias de Usuario
### MCH-US-190: Pagos con Tarjeta via Stripe Checkout
**Story Points:** 8
**Como** propietario de negocio
**Quiero** pagar mi suscripcion o tokens con tarjeta de credito/debito
**Para** activar mi plan de manera inmediata y segura
#### Criterios de Aceptacion
- [CA-190-1] El sistema redirige a Stripe Checkout al seleccionar pago con tarjeta
- [CA-190-2] Se soportan tarjetas Visa, Mastercard y American Express
- [CA-190-3] La confirmacion del pago es inmediata tras procesamiento exitoso
- [CA-190-4] El usuario recibe recibo por email automaticamente
- [CA-190-5] La suscripcion/tokens se activan inmediatamente tras pago exitoso
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-190-01 | Configurar Stripe Checkout Session en backend | 4h |
| MCH-TT-190-02 | Implementar stripe-checkout.service.ts | 6h |
| MCH-TT-190-03 | Crear endpoint POST /payments/create-checkout | 3h |
| MCH-TT-190-04 | Integrar Stripe.js en frontend | 4h |
| MCH-TT-190-05 | Implementar flujo de redireccion y confirmacion | 3h |
| MCH-TT-190-06 | Configurar webhook para eventos de pago | 4h |
---
### MCH-US-191: Pagos en OXXO con Voucher
**Story Points:** 5
**Como** propietario de negocio sin tarjeta bancaria
**Quiero** generar un voucher para pagar en OXXO
**Para** poder adquirir mi suscripcion usando efectivo
#### Criterios de Aceptacion
- [CA-191-1] Se genera referencia OXXO con codigo de barras valido
- [CA-191-2] El voucher muestra monto, referencia y fecha de vencimiento (3 dias)
- [CA-191-3] El usuario puede compartir el voucher via imagen o PDF
- [CA-191-4] El sistema procesa webhook de confirmacion de OXXO (24-72h)
- [CA-191-5] La suscripcion/tokens se activan automaticamente tras confirmacion
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-191-01 | Implementar oxxo.service.ts con Stripe OXXO Pay | 4h |
| MCH-TT-191-02 | Crear endpoint POST /payments/create-oxxo | 2h |
| MCH-TT-191-03 | Disenar componente OXXOVoucher con codigo de barras | 4h |
| MCH-TT-191-04 | Implementar funcionalidad de compartir voucher | 2h |
| MCH-TT-191-05 | Configurar webhook para confirmacion OXXO | 3h |
| MCH-TT-191-06 | Implementar notificacion push al confirmar pago | 2h |
---
### MCH-US-192: In-App Purchase para iOS
**Story Points:** 8
**Como** usuario de la app iOS
**Quiero** comprar suscripciones o tokens desde la app
**Para** no tener que salir de la aplicacion para pagar
#### Criterios de Aceptacion
- [CA-192-1] Los productos estan configurados en App Store Connect
- [CA-192-2] StoreKit muestra la hoja de compra nativa de Apple
- [CA-192-3] El usuario puede confirmar con Face ID/Touch ID
- [CA-192-4] El backend valida el receipt con Apple Server
- [CA-192-5] Las suscripciones se renuevan automaticamente via Apple
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-192-01 | Configurar productos en App Store Connect | 2h |
| MCH-TT-192-02 | Implementar StoreKit 2 en app iOS (React Native) | 6h |
| MCH-TT-192-03 | Implementar apple-iap.service.ts en backend | 5h |
| MCH-TT-192-04 | Crear endpoint POST /payments/verify-iap | 3h |
| MCH-TT-192-05 | Configurar Server Notifications de Apple | 3h |
| MCH-TT-192-06 | Implementar validacion de receipts con Apple API | 4h |
---
### MCH-US-193: In-App Purchase para Android
**Story Points:** 6
**Como** usuario de la app Android
**Quiero** comprar suscripciones o tokens desde la app
**Para** usar el metodo de pago configurado en Google Play
#### Criterios de Aceptacion
- [CA-193-1] Los productos estan configurados en Google Play Console
- [CA-193-2] Google Play Billing muestra la UI nativa de compra
- [CA-193-3] El backend valida la compra con Google Play API
- [CA-193-4] Las suscripciones se renuevan automaticamente via Google
- [CA-193-5] Se manejan correctamente los estados de compra pendiente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-193-01 | Configurar productos en Google Play Console | 2h |
| MCH-TT-193-02 | Implementar Google Play Billing Library en app | 5h |
| MCH-TT-193-03 | Implementar google-billing.service.ts en backend | 4h |
| MCH-TT-193-04 | Crear endpoint para validacion de compras Google | 3h |
| MCH-TT-193-05 | Configurar Real-time Developer Notifications | 3h |
| MCH-TT-193-06 | Manejar estados de compra pendiente (PENDING) | 2h |
---
### MCH-US-194: Manejo de Pagos Fallidos con Reintentos
**Story Points:** 5
**Como** sistema
**Quiero** reintentar automaticamente pagos fallidos
**Para** maximizar la retencion de suscriptores y reducir churn involuntario
#### Criterios de Aceptacion
- [CA-194-1] Se ejecutan reintentos en dias 1, 3, 5 y 7 tras fallo inicial
- [CA-194-2] Se envia notificacion push y email en cada intento fallido
- [CA-194-3] El dia 7 se envia alerta de suspension inminente
- [CA-194-4] El dia 10 se suspende el servicio si no hay pago exitoso
- [CA-194-5] El usuario puede actualizar metodo de pago en cualquier momento
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-194-01 | Implementar job de reintentos programados (cron) | 4h |
| MCH-TT-194-02 | Crear templates de notificaciones de pago fallido | 2h |
| MCH-TT-194-03 | Implementar logica de suspension de servicio | 3h |
| MCH-TT-194-04 | Crear pantalla de actualizacion de metodo de pago | 4h |
| MCH-TT-194-05 | Implementar webhook para invoice.payment_failed | 2h |
| MCH-TT-194-06 | Agregar metricas de dunning para analytics | 2h |
---
### MCH-US-195: Gestion de Metodos de Pago Guardados
**Story Points:** 3
**Como** propietario de negocio
**Quiero** guardar y gestionar mis metodos de pago
**Para** facilitar pagos futuros sin reingresar datos
#### Criterios de Aceptacion
- [CA-195-1] El usuario puede guardar tarjetas de forma segura (tokenizadas)
- [CA-195-2] Se muestra lista de metodos guardados con ultimos 4 digitos
- [CA-195-3] El usuario puede seleccionar un metodo de pago por defecto
- [CA-195-4] El usuario puede eliminar metodos de pago guardados
- [CA-195-5] Los datos de tarjeta nunca se almacenan en nuestros servidores
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-195-01 | Implementar tabla payment_methods en base de datos | 2h |
| MCH-TT-195-02 | Crear endpoints CRUD para metodos de pago | 3h |
| MCH-TT-195-03 | Integrar Stripe SetupIntent para guardar tarjetas | 3h |
| MCH-TT-195-04 | Disenar componente PaymentMethodSelector | 3h |
| MCH-TT-195-05 | Implementar pantalla de gestion de metodos de pago | 3h |
---
### Resumen de Historias de Usuario
| ID | Historia | SP | Prioridad |
|----|----------|----|-----------|
| MCH-US-190 | Pagos con Tarjeta via Stripe Checkout | 8 | P0 |
| MCH-US-191 | Pagos en OXXO con Voucher | 5 | P0 |
| MCH-US-192 | In-App Purchase para iOS | 8 | P0 |
| MCH-US-193 | In-App Purchase para Android | 6 | P0 |
| MCH-US-194 | Manejo de Pagos Fallidos con Reintentos | 5 | P1 |
| MCH-US-195 | Gestion de Metodos de Pago Guardados | 3 | P1 |
| **Total** | | **34** | |
## Entregables
| Entregable | Estado | Archivo |
@ -251,4 +422,4 @@ en 3 dias si no actualizas tu pago.
---
**Ultima actualizacion:** 2026-01-10
**Ultima actualizacion:** 2026-01-17

214
docs/01-epicas/MCH-021-dashboard-web.md
View File

@ -7,8 +7,9 @@ status: Completado
phase: 5
priority: P1
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: 21
dependencies:
blocks: []
depends_on: []
@ -22,6 +23,7 @@ dependencies:
- **Prioridad:** P1
- **Estado:** Completado
- **Fecha completado:** 2026-01-10
- **Story Points:** 21
## Descripcion
@ -135,6 +137,192 @@ Dashboard web completo para duenos de negocio: metricas de ventas, graficas, rep
- Efectivo vs Tarjeta vs Fiado
- Porcentaje de cada uno
## Historias de Usuario
### MCH-US-200: KPIs en Tiempo Real
**Story Points:** 5
**Como** dueno de negocio
**Quiero** visualizar metricas clave de ventas en tiempo real (ventas del dia, transacciones, ticket promedio)
**Para** monitorear el rendimiento de mi negocio de un vistazo
#### Criterios de Aceptacion
- [CA-200-1] El dashboard muestra ventas totales del dia actualizadas
- [CA-200-2] Se muestra el numero de transacciones realizadas
- [CA-200-3] El ticket promedio se calcula correctamente
- [CA-200-4] Se muestra comparativo porcentual vs dia anterior
- [CA-200-5] Los KPIs se refrescan automaticamente cada 5 minutos
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-200-01 | Implementar endpoint /analytics/dashboard | 4h |
| MCH-TT-200-02 | Crear componente KPICard reutilizable | 3h |
| MCH-TT-200-03 | Integrar KPIs en Dashboard page | 2h |
| MCH-TT-200-04 | Implementar auto-refresh con polling | 2h |
| MCH-TT-200-05 | Pruebas unitarias de calculos | 2h |
---
### MCH-US-201: Graficas Interactivas
**Story Points:** 5
**Como** dueno de negocio
**Quiero** ver graficas interactivas de ventas por dia/hora y productos mas vendidos
**Para** identificar tendencias y tomar decisiones informadas
#### Criterios de Aceptacion
- [CA-201-1] Grafica de ventas por dia muestra ultimos 7 dias
- [CA-201-2] Grafica de ventas por hora identifica horas pico
- [CA-201-3] Grafica de top productos muestra top 5 por ingresos
- [CA-201-4] Grafica de metodos de pago muestra distribucion
- [CA-201-5] Las graficas tienen tooltips interactivos al hover
- [CA-201-6] Se puede cambiar el periodo de visualizacion
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-201-01 | Implementar endpoint /analytics/sales-by-day | 3h |
| MCH-TT-201-02 | Implementar endpoint /analytics/sales-by-hour | 3h |
| MCH-TT-201-03 | Implementar endpoint /analytics/top-products | 2h |
| MCH-TT-201-04 | Crear componente SalesChart con Recharts | 4h |
| MCH-TT-201-05 | Crear componente TopProductsList | 2h |
| MCH-TT-201-06 | Integrar selector de periodo | 2h |
---
### MCH-US-202: Reportes Exportables
**Story Points:** 3
**Como** dueno de negocio
**Quiero** exportar reportes de ventas y corte de caja en PDF y Excel
**Para** mantener registros fisicos y compartir con mi contador
#### Criterios de Aceptacion
- [CA-202-1] Se puede exportar corte de caja diario a PDF
- [CA-202-2] Se puede exportar ventas del periodo a Excel
- [CA-202-3] El PDF incluye logo del negocio y fecha
- [CA-202-4] El Excel mantiene formato de tabla con totales
- [CA-202-5] Los reportes se descargan automaticamente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-202-01 | Implementar servicio de generacion PDF (jsPDF) | 4h |
| MCH-TT-202-02 | Implementar servicio de generacion Excel (SheetJS) | 3h |
| MCH-TT-202-03 | Crear endpoint /reports/export | 2h |
| MCH-TT-202-04 | Crear botones de exportacion en UI | 1h |
| MCH-TT-202-05 | Disenar template de reporte PDF | 2h |
---
### MCH-US-203: Configuracion del Negocio
**Story Points:** 3
**Como** dueno de negocio
**Quiero** configurar los datos de mi negocio y metodos de pago aceptados
**Para** personalizar la plataforma a mis necesidades
#### Criterios de Aceptacion
- [CA-203-1] Se pueden editar nombre, direccion y telefono del negocio
- [CA-203-2] Se puede subir logo del negocio
- [CA-203-3] Se pueden activar/desactivar metodos de pago
- [CA-203-4] Se puede configurar horario de operacion
- [CA-203-5] Los cambios se guardan y aplican inmediatamente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-203-01 | Crear pagina de configuracion del negocio | 3h |
| MCH-TT-203-02 | Implementar upload de logo | 2h |
| MCH-TT-203-03 | Crear formulario de metodos de pago | 2h |
| MCH-TT-203-04 | Implementar endpoints de configuracion | 3h |
| MCH-TT-203-05 | Validaciones y feedback de guardado | 1h |
---
### MCH-US-204: Gestion de Usuarios y Roles
**Story Points:** 3
**Como** dueno de negocio
**Quiero** administrar usuarios y asignar roles a mis empleados
**Para** controlar quien tiene acceso a que funcionalidades
#### Criterios de Aceptacion
- [CA-204-1] Se pueden crear nuevos usuarios empleados
- [CA-204-2] Se pueden asignar roles (admin, cajero, inventario)
- [CA-204-3] Se pueden desactivar usuarios sin eliminarlos
- [CA-204-4] Se muestra lista de usuarios con su rol y estado
- [CA-204-5] Solo el dueno puede gestionar usuarios
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-204-01 | Crear pagina de gestion de usuarios | 3h |
| MCH-TT-204-02 | Implementar CRUD de usuarios en backend | 4h |
| MCH-TT-204-03 | Crear sistema de roles y permisos | 3h |
| MCH-TT-204-04 | Implementar formulario de creacion/edicion | 2h |
| MCH-TT-204-05 | Agregar validaciones de permisos | 2h |
---
### MCH-US-205: Panel de Alertas
**Story Points:** 2
**Como** dueno de negocio
**Quiero** ver alertas de stock bajo, fiados pendientes y pedidos nuevos
**Para** actuar rapidamente ante situaciones que requieren atencion
#### Criterios de Aceptacion
- [CA-205-1] Se muestran alertas de productos con stock bajo
- [CA-205-2] Se muestran fiados pendientes por cobrar
- [CA-205-3] Se notifican pedidos nuevos de clientes
- [CA-205-4] Las alertas muestran cantidad de items
- [CA-205-5] Se puede hacer click para ver detalle
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-205-01 | Crear componente AlertsPanel | 2h |
| MCH-TT-205-02 | Implementar endpoint de alertas consolidadas | 3h |
| MCH-TT-205-03 | Integrar panel en dashboard | 1h |
| MCH-TT-205-04 | Agregar navegacion a detalle de alerta | 2h |
| MCH-TT-205-05 | Estilos y animaciones de alertas | 1h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Estado |
|----|----------|--------------|--------|
| MCH-US-200 | KPIs en Tiempo Real | 5 | Completado |
| MCH-US-201 | Graficas Interactivas | 5 | Completado |
| MCH-US-202 | Reportes Exportables | 3 | Completado |
| MCH-US-203 | Configuracion del Negocio | 3 | Completado |
| MCH-US-204 | Gestion de Usuarios y Roles | 3 | Completado |
| MCH-US-205 | Panel de Alertas | 2 | Completado |
| **Total** | | **21** | |
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Dashboard.tsx | Completado | `pages/Dashboard.tsx` |
| analytics.module | En progreso | `modules/analytics/` |
| KPICard.tsx | Completado | `components/dashboard/` |
| SalesChart.tsx | En progreso | `components/dashboard/` |
| Reports export | Pendiente | `services/reports.service.ts` |
## Dependencias
### Depende de
- MCH-004 (Sales data)
- MCH-003 (Products data)
- MCH-014 (Customers data)
### Bloquea a
- Ninguno
## Endpoints API (Existentes)
| Metodo | Endpoint | Descripcion |
@ -175,26 +363,6 @@ Dashboard web completo para duenos de negocio: metricas de ventas, graficas, rep
- Fiados pendientes
- Pedidos nuevos
## Entregables
| Entregable | Estado | Archivo |
|------------|--------|---------|
| Dashboard.tsx | Completado | `pages/Dashboard.tsx` |
| analytics.module | En progreso | `modules/analytics/` |
| KPICard.tsx | Completado | `components/dashboard/` |
| SalesChart.tsx | En progreso | `components/dashboard/` |
| Reports export | Pendiente | `services/reports.service.ts` |
## Dependencias
### Depende de
- MCH-004 (Sales data)
- MCH-003 (Products data)
- MCH-014 (Customers data)
### Bloquea a
- Ninguno
## Criterios de Aceptacion
- [x] Dashboard muestra KPIs correctos
@ -213,4 +381,4 @@ Dashboard web completo para duenos de negocio: metricas de ventas, graficas, rep
---
**Ultima actualizacion:** 2026-01-10
**Ultima actualizacion:** 2026-01-17

172
docs/01-epicas/MCH-022-modo-offline.md
View File

@ -7,8 +7,9 @@ status: Completado
phase: 6
priority: P1
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: 21
dependencies:
blocks: []
depends_on: []
@ -22,6 +23,7 @@ dependencies:
- **Prioridad:** P1
- **Estado:** Completado
- **Fecha completado:** 2026-01-10
- **Story Points:** 21
## Descripcion
@ -179,6 +181,170 @@ if (local.updated_at > server.updated_at) {
- **Sync:** Custom sync engine o WatermelonDB
- **Network:** NetInfo para detectar conexion
## Historias de Usuario
### MCH-US-210: Base de Datos Local SQLite
**Story Points:** 5
**Como** desarrollador de la app movil
**Quiero** configurar SQLite como base de datos local
**Para** almacenar datos que permitan el funcionamiento offline de la aplicacion
#### Criterios de Aceptacion
- [CA-210-1] SQLite esta configurado e inicializado correctamente en la app movil
- [CA-210-2] Esquema de tablas locales replica las tablas necesarias del servidor (products, categories, customers, sales)
- [CA-210-3] Tablas adicionales sync_queue y sync_status estan creadas
- [CA-210-4] Migraciones de esquema funcionan correctamente
- [CA-210-5] Tests unitarios validan operaciones CRUD basicas
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-210-01 | Instalar y configurar react-native-sqlite-storage o expo-sqlite | 2h |
| MCH-TT-210-02 | Crear esquema de tablas locales (products, categories, customers, sales) | 3h |
| MCH-TT-210-03 | Crear tablas sync_queue y sync_status | 2h |
| MCH-TT-210-04 | Implementar sistema de migraciones de esquema | 3h |
| MCH-TT-210-05 | Escribir tests unitarios para operaciones CRUD | 2h |
---
### MCH-US-211: Sincronizacion Bidireccional
**Story Points:** 5
**Como** dueno de changarrito
**Quiero** que mis datos se sincronicen automaticamente entre la app y el servidor
**Para** tener informacion actualizada en todos mis dispositivos
#### Criterios de Aceptacion
- [CA-211-1] Productos y categorias se descargan del servidor al iniciar la app
- [CA-211-2] Productos se actualizan cada 5 minutos cuando hay conexion
- [CA-211-3] Clientes se sincronizan bidireccionalmente cada 15 minutos
- [CA-211-4] Inventario se actualiza desde el servidor cada 30 minutos
- [CA-211-5] Configuraciones se descargan al iniciar
- [CA-211-6] El sync engine maneja errores de red graciosamente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-211-01 | Disenar e implementar sync engine base | 4h |
| MCH-TT-211-02 | Implementar sync de productos (Server → Local) | 3h |
| MCH-TT-211-03 | Implementar sync de categorias (Server → Local) | 2h |
| MCH-TT-211-04 | Implementar sync bidireccional de clientes | 3h |
| MCH-TT-211-05 | Implementar sync de inventario y configuraciones | 2h |
| MCH-TT-211-06 | Configurar timers y frecuencias de sincronizacion | 2h |
---
### MCH-US-212: Ventas sin Conexion
**Story Points:** 3
**Como** empleado de changarrito
**Quiero** poder registrar ventas aunque no haya internet
**Para** no perder ventas cuando la conexion falle
#### Criterios de Aceptacion
- [CA-212-1] Ventas en efectivo se pueden realizar sin conexion a internet
- [CA-212-2] Venta se guarda localmente en SQLite con estado "pending_sync"
- [CA-212-3] UI muestra confirmacion clara "Venta guardada offline"
- [CA-212-4] Stock local se actualiza inmediatamente despues de la venta
- [CA-212-5] Venta aparece en historial local con indicador de pendiente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-212-01 | Modificar flujo de venta para detectar modo offline | 2h |
| MCH-TT-212-02 | Implementar guardado local de ventas en SQLite | 3h |
| MCH-TT-212-03 | Actualizar UI para mostrar estado offline de venta | 2h |
| MCH-TT-212-04 | Implementar actualizacion de stock local | 2h |
---
### MCH-US-213: Cola de Operaciones Offline
**Story Points:** 3
**Como** sistema de sincronizacion
**Quiero** una cola que almacene operaciones realizadas offline
**Para** procesarlas ordenadamente cuando se recupere la conexion
#### Criterios de Aceptacion
- [CA-213-1] Operaciones offline se encolan en tabla sync_queue
- [CA-213-2] Cola procesa operaciones en orden FIFO cuando hay conexion
- [CA-213-3] Operaciones fallidas se reintentan hasta 3 veces
- [CA-213-4] Estado de cada operacion se actualiza (pending, syncing, synced, failed)
- [CA-213-5] IDs locales se actualizan con IDs del servidor tras sync exitoso
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-213-01 | Implementar servicio de cola de operaciones | 3h |
| MCH-TT-213-02 | Implementar procesador de cola con reintentos | 3h |
| MCH-TT-213-03 | Implementar actualizacion de IDs locales post-sync | 2h |
| MCH-TT-213-04 | Agregar logging y metricas de operaciones | 1h |
---
### MCH-US-214: Resolucion de Conflictos
**Story Points:** 3
**Como** sistema de sincronizacion
**Quiero** resolver automaticamente conflictos entre datos locales y remotos
**Para** mantener la integridad de datos sin intervencion manual
#### Criterios de Aceptacion
- [CA-214-1] Conflictos se resuelven usando estrategia Last Write Wins basada en updated_at
- [CA-214-2] Campos no conflictivos se fusionan (merge)
- [CA-214-3] Ventas offline con productos eliminados se manejan correctamente
- [CA-214-4] Stock negativo genera alerta al dueno para ajuste manual
- [CA-214-5] Conflictos resueltos se registran en log para auditoria
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-214-01 | Implementar comparador de timestamps para Last Write Wins | 2h |
| MCH-TT-214-02 | Implementar logica de merge para campos no conflictivos | 3h |
| MCH-TT-214-03 | Manejar caso de producto eliminado en servidor | 2h |
| MCH-TT-214-04 | Implementar alertas para stock negativo | 2h |
| MCH-TT-214-05 | Agregar registro de conflictos resueltos | 1h |
---
### MCH-US-215: Indicador de Estado de Conexion
**Story Points:** 2
**Como** usuario de la app
**Quiero** ver claramente si estoy online u offline
**Para** saber si mis cambios se estan sincronizando
#### Criterios de Aceptacion
- [CA-215-1] Icono en header muestra estado: verde (online), amarillo (sync pendiente), rojo (offline)
- [CA-215-2] Banner aparece cuando se detecta modo offline
- [CA-215-3] Modal de progreso muestra estado de sincronizacion por tabla
- [CA-215-4] Errores de sync se muestran claramente al usuario
- [CA-215-5] Transiciones de estado son suaves y no intrusivas
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-215-01 | Implementar ConnectionIndicator con iconos de estado | 2h |
| MCH-TT-215-02 | Implementar OfflineBanner con mensaje contextual | 2h |
| MCH-TT-215-03 | Implementar SyncProgress modal con progreso por tabla | 3h |
| MCH-TT-215-04 | Integrar NetInfo para deteccion de conexion | 1h |
| MCH-TT-215-05 | Agregar animaciones y transiciones de estado | 1h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Estado |
|----|----------|--------------|--------|
| MCH-US-210 | Base de Datos Local SQLite | 5 | Completado |
| MCH-US-211 | Sincronizacion Bidireccional | 5 | Completado |
| MCH-US-212 | Ventas sin Conexion | 3 | Completado |
| MCH-US-213 | Cola de Operaciones Offline | 3 | Completado |
| MCH-US-214 | Resolucion de Conflictos | 3 | Completado |
| MCH-US-215 | Indicador de Estado de Conexion | 2 | Completado |
| **Total** | | **21** | |
## Entregables
| Entregable | Estado | Archivo |
@ -220,4 +386,4 @@ if (local.updated_at > server.updated_at) {
---
**Ultima actualizacion:** 2026-01-10
**Ultima actualizacion:** 2026-01-17

170
docs/01-epicas/MCH-023-programa-referidos.md
View File

@ -6,9 +6,10 @@ code: MCH-023
status: Pendiente
phase: 6
priority: P2
story_points: 21
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"
dependencies:
blocks: []
depends_on: []
@ -21,6 +22,7 @@ dependencies:
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Completado
- **Story Points:** 21
- **Fecha completado:** 2026-01-10
## Descripcion
@ -182,6 +184,168 @@ async function processSubscriptionPayment(tenant, payment) {
}
```
## Historias de Usuario
### MCH-US-220: Codigo de Referido Unico
**Story Points:** 3
**Como** propietario de tienda
**Quiero** tener un codigo de referido unico y personalizable
**Para** compartirlo facilmente con mis contactos y que sea memorable
#### Criterios de Aceptacion
- [CA-220-1] El sistema genera automaticamente un codigo unico al crear la tienda
- [CA-220-2] El codigo tiene formato MCH-XXXXX por defecto
- [CA-220-3] El usuario puede personalizar su codigo (ej: TIENDAJUAN) si esta disponible
- [CA-220-4] El codigo es case-insensitive para facilitar ingreso
- [CA-220-5] El sistema valida que el codigo no contenga palabras ofensivas
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-220-01 | Crear tabla referral_codes en DDL | 2h |
| MCH-TT-220-02 | Implementar servicio de generacion de codigos | 3h |
| MCH-TT-220-03 | Endpoint GET /referrals/my-code | 1h |
| MCH-TT-220-04 | Endpoint POST /referrals/generate-code con personalizacion | 2h |
| MCH-TT-220-05 | Validacion de codigos ofensivos (blacklist) | 1h |
---
### MCH-US-221: Link Compartible con Codigo Embebido
**Story Points:** 2
**Como** propietario de tienda
**Quiero** obtener un link compartible con mi codigo de referido
**Para** enviarlo por WhatsApp, redes sociales o email sin friccion
#### Criterios de Aceptacion
- [CA-221-1] El link tiene formato michangarrito.com/r/{CODIGO}
- [CA-221-2] El boton "Copiar" copia el link al portapapeles
- [CA-221-3] El boton "Compartir WhatsApp" abre WhatsApp con mensaje predefinido
- [CA-221-4] El link es valido mientras el codigo este activo
- [CA-221-5] Al acceder al link, el registro pre-llena el campo de codigo
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-221-01 | Implementar ruta /r/{codigo} en frontend | 2h |
| MCH-TT-221-02 | Componente ShareReferralCard con botones | 2h |
| MCH-TT-221-03 | Integracion con Web Share API | 1h |
| MCH-TT-221-04 | Pre-llenado de codigo en formulario de registro | 1h |
---
### MCH-US-222: Beneficio al Referido (50% Descuento)
**Story Points:** 5
**Como** nuevo usuario registrado con codigo de referido
**Quiero** recibir automaticamente un 50% de descuento en mi primer mes
**Para** probar la plataforma a menor costo
#### Criterios de Aceptacion
- [CA-222-1] Al registrarse con codigo valido, se aplica 50% de descuento
- [CA-222-2] El descuento aplica solo al primer mes de suscripcion
- [CA-222-3] El usuario ve claramente el descuento aplicado en checkout
- [CA-222-4] Si el codigo es invalido/expirado, se muestra mensaje de error
- [CA-222-5] El descuento se registra en el historial de pagos
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-222-01 | Endpoint POST /referrals/apply-code en registro | 2h |
| MCH-TT-222-02 | Logica de validacion de codigo (activo, no expirado) | 2h |
| MCH-TT-222-03 | Integracion con modulo de suscripciones para descuento | 4h |
| MCH-TT-222-04 | UI de confirmacion de descuento en checkout | 2h |
| MCH-TT-222-05 | Tests de integracion de flujo completo | 2h |
---
### MCH-US-223: Recompensa al Referidor (1 Mes Gratis)
**Story Points:** 5
**Como** usuario que refirio a un nuevo cliente
**Quiero** recibir 1 mes gratis de suscripcion cuando mi referido pague
**Para** ser recompensado por ayudar al crecimiento de la plataforma
#### Criterios de Aceptacion
- [CA-223-1] Al pagar el referido su primer mes, se acredita 1 mes gratis al referidor
- [CA-223-2] Los meses gratis son acumulables (multiples referidos)
- [CA-223-3] Los meses gratis se usan automaticamente en el siguiente ciclo de pago
- [CA-223-4] El referidor recibe notificacion cuando gana el mes gratis
- [CA-223-5] Los meses gratis tienen vigencia de 12 meses
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-223-01 | Crear tabla referral_rewards en DDL | 2h |
| MCH-TT-223-02 | Trigger al confirmar pago de referido | 3h |
| MCH-TT-223-03 | Logica de acreditacion de meses gratis | 2h |
| MCH-TT-223-04 | Integracion con processSubscriptionPayment | 4h |
| MCH-TT-223-05 | Endpoint GET /referrals/rewards | 1h |
---
### MCH-US-224: Tracking de Conversiones
**Story Points:** 3
**Como** sistema
**Quiero** rastrear el estado de cada referido (pending/converted/expired)
**Para** gestionar correctamente las recompensas y metricas
#### Criterios de Aceptacion
- [CA-224-1] Estado inicial es "pending" al registrarse con codigo
- [CA-224-2] Cambia a "converted" cuando referido paga primer mes
- [CA-224-3] Cambia a "expired" si no paga en 30 dias
- [CA-224-4] Estado "rewarded" se marca cuando referidor recibe beneficio
- [CA-224-5] Job programado verifica expiraciones diariamente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-224-01 | Crear tabla referrals con estados | 2h |
| MCH-TT-224-02 | Implementar maquina de estados de referido | 3h |
| MCH-TT-224-03 | Cron job para marcar expirados | 2h |
| MCH-TT-224-04 | Logs de auditoria de cambios de estado | 1h |
---
### MCH-US-225: Dashboard de Referidos
**Story Points:** 3
**Como** propietario de tienda
**Quiero** ver un dashboard con mis estadisticas de referidos
**Para** conocer el impacto de mis invitaciones y meses acumulados
#### Criterios de Aceptacion
- [CA-225-1] Muestra total de invitados (todos los registrados)
- [CA-225-2] Muestra convertidos (que pagaron)
- [CA-225-3] Muestra meses ganados y meses disponibles
- [CA-225-4] Lista de referidos con nombre, fecha y estado
- [CA-225-5] Opcion de filtrar por estado (pending/converted/expired)
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-225-01 | Endpoint GET /referrals/stats | 2h |
| MCH-TT-225-02 | Endpoint GET /referrals/list con filtros | 2h |
| MCH-TT-225-03 | Componente ReferralStats | 2h |
| MCH-TT-225-04 | Componente ReferralList con tabla | 3h |
| MCH-TT-225-05 | Pagina Referrals.tsx integrando componentes | 2h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Prioridad |
|----|----------|--------------|-----------|
| MCH-US-220 | Codigo de Referido Unico | 3 | Alta |
| MCH-US-221 | Link Compartible | 2 | Alta |
| MCH-US-222 | Beneficio al Referido (50%) | 5 | Alta |
| MCH-US-223 | Recompensa al Referidor (1 mes) | 5 | Alta |
| MCH-US-224 | Tracking de Conversiones | 3 | Media |
| MCH-US-225 | Dashboard de Referidos | 3 | Media |
| **Total** | | **21** | |
## Entregables
| Entregable | Estado | Archivo |
@ -226,4 +390,4 @@ async function processSubscriptionPayment(tenant, payment) {
---
**Ultima actualizacion:** 2026-01-10
**Ultima actualizacion:** 2026-01-17

152
docs/01-epicas/MCH-024-codi-spei.md
View File

@ -7,8 +7,9 @@ status: Pendiente
phase: 6
priority: P2
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: 21
dependencies:
blocks: []
depends_on: []
@ -21,6 +22,7 @@ dependencies:
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Completado (Base)
- **Story Points:** 21
- **Fecha completado:** 2026-01-10
- **Nota:** Requiere integracion con proveedor (STP/Arcus/Conekta)
@ -159,6 +161,150 @@ Integracion con CoDi (Cobro Digital) de Banxico y SPEI para pagos instantaneos s
- Boton copiar
- Nombre del beneficiario
## Historias de Usuario
### MCH-US-230: Generacion de QR CoDi
**Story Points:** 5
**Como** operador de punto de venta
**Quiero** generar un codigo QR CoDi con el monto de la venta
**Para** que el cliente pueda pagar instantaneamente sin comisiones desde su app bancaria
#### Criterios de Aceptacion
- [CA-230-1] El sistema genera un QR CoDi valido con el monto exacto de la venta
- [CA-230-2] El QR incluye la referencia unica de la transaccion
- [CA-230-3] El QR tiene una vigencia configurable (default 5 minutos)
- [CA-230-4] El QR es compatible con las apps bancarias que soportan CoDi
- [CA-230-5] Se muestra mensaje de error claro si la generacion falla
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-230-01 | Implementar codi.service.ts con metodo generateQR | 4h |
| MCH-TT-230-02 | Crear endpoint POST /codi/generate-qr | 2h |
| MCH-TT-230-03 | Integrar con SDK/API del proveedor CoDi | 4h |
| MCH-TT-230-04 | Crear tabla codi_transactions en BD | 2h |
| MCH-TT-230-05 | Agregar tests unitarios para generacion QR | 2h |
---
### MCH-US-231: Confirmacion de Pago CoDi
**Story Points:** 5
**Como** sistema de MiChangarrito
**Quiero** recibir y procesar el webhook de confirmacion de Banxico
**Para** actualizar automaticamente el estado de la venta cuando el pago sea exitoso
#### Criterios de Aceptacion
- [CA-231-1] El webhook recibe notificaciones de Banxico en tiempo real
- [CA-231-2] El sistema valida la autenticidad del webhook (firma/token)
- [CA-231-3] La venta se marca como pagada automaticamente al confirmar
- [CA-231-4] Se envia notificacion push al POS cuando el pago se confirma
- [CA-231-5] Se registra timestamp de confirmacion en codi_transactions
- [CA-231-6] Manejo de reintentos para webhooks duplicados (idempotencia)
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-231-01 | Implementar endpoint POST /codi/webhook | 3h |
| MCH-TT-231-02 | Validar firma/autenticacion del webhook | 2h |
| MCH-TT-231-03 | Actualizar estado de venta en BD | 2h |
| MCH-TT-231-04 | Implementar notificacion push al POS | 3h |
| MCH-TT-231-05 | Agregar manejo de idempotencia | 2h |
| MCH-TT-231-06 | Tests de integracion para webhook | 2h |
---
### MCH-US-232: CLABE Virtual por Tenant
**Story Points:** 4
**Como** tenant de MiChangarrito
**Quiero** tener una CLABE virtual unica asignada a mi negocio
**Para** recibir pagos SPEI directamente y que se concilien automaticamente
#### Criterios de Aceptacion
- [CA-232-1] Se genera CLABE virtual unica al activar SPEI para el tenant
- [CA-232-2] La CLABE se almacena en tabla virtual_accounts
- [CA-232-3] El tenant puede ver su CLABE en el dashboard
- [CA-232-4] La CLABE incluye nombre del beneficiario correcto
- [CA-232-5] Se puede copiar la CLABE con un click
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-232-01 | Crear tabla virtual_accounts en BD | 1h |
| MCH-TT-232-02 | Integrar con proveedor (STP/Arcus) para generar CLABE | 4h |
| MCH-TT-232-03 | Implementar endpoint GET /spei/clabe | 2h |
| MCH-TT-232-04 | Crear componente CLABEDisplay en frontend | 2h |
| MCH-TT-232-05 | Tests de integracion con proveedor | 2h |
---
### MCH-US-233: Recepcion y Conciliacion de SPEI
**Story Points:** 4
**Como** sistema de MiChangarrito
**Quiero** recibir notificaciones de pagos SPEI entrantes
**Para** conciliar automaticamente los pagos con las ventas pendientes
#### Criterios de Aceptacion
- [CA-233-1] El webhook recibe notificaciones de SPEI entrantes
- [CA-233-2] Se registra la transaccion en spei_transactions
- [CA-233-3] El sistema intenta conciliar automaticamente con ventas pendientes
- [CA-233-4] Si no hay match, se registra como pago no conciliado
- [CA-233-5] Se notifica al tenant cuando recibe un pago SPEI
- [CA-233-6] Se puede ver historial de transacciones SPEI recibidas
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-233-01 | Crear tabla spei_transactions en BD | 1h |
| MCH-TT-233-02 | Implementar endpoint POST /spei/webhook | 3h |
| MCH-TT-233-03 | Implementar logica de conciliacion automatica | 4h |
| MCH-TT-233-04 | Implementar endpoint GET /spei/transactions | 2h |
| MCH-TT-233-05 | Agregar notificacion al tenant | 2h |
| MCH-TT-233-06 | Tests de conciliacion | 2h |
---
### MCH-US-234: UI de Pago CoDi
**Story Points:** 3
**Como** operador de punto de venta
**Quiero** una pantalla clara que muestre el QR CoDi con timer
**Para** guiar al cliente durante el proceso de pago y saber cuando se confirma
#### Criterios de Aceptacion
- [CA-234-1] Boton "Pagar con CoDi" visible en opciones de pago
- [CA-234-2] QR se muestra grande y claro con monto visible
- [CA-234-3] Timer de cuenta regresiva muestra tiempo restante
- [CA-234-4] Instrucciones claras para el cliente
- [CA-234-5] Indicador visual cuando el pago esta siendo procesado
- [CA-234-6] Confirmacion visual cuando el pago es exitoso
- [CA-234-7] Boton para regenerar QR si expira
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-234-01 | Crear componente CoDiPaymentOption | 2h |
| MCH-TT-234-02 | Crear componente QRCodeDisplay con timer | 3h |
| MCH-TT-234-03 | Integrar con WebSocket para confirmacion en tiempo real | 3h |
| MCH-TT-234-04 | Agregar animaciones de estado (esperando, confirmado) | 2h |
| MCH-TT-234-05 | Tests de componentes UI | 2h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Prioridad |
|----|----------|--------------|-----------|
| MCH-US-230 | Generacion de QR CoDi | 5 | Alta |
| MCH-US-231 | Confirmacion de Pago CoDi | 5 | Alta |
| MCH-US-232 | CLABE Virtual por Tenant | 4 | Media |
| MCH-US-233 | Recepcion y Conciliacion de SPEI | 4 | Media |
| MCH-US-234 | UI de Pago CoDi | 3 | Alta |
| **Total** | | **21** | |
## Entregables
| Entregable | Estado | Archivo |
@ -225,4 +371,4 @@ Integracion con CoDi (Cobro Digital) de Banxico y SPEI para pagos instantaneos s
---
**Ultima actualizacion:** 2026-01-07
**Ultima actualizacion:** 2026-01-17

162
docs/01-epicas/MCH-025-widgets-atajos.md
View File

@ -7,8 +7,9 @@ status: Pendiente
phase: 6
priority: P2
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: 21
dependencies:
blocks: []
depends_on: []
@ -22,6 +23,7 @@ dependencies:
- **Prioridad:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 16
- **Story Points:** 21
## Descripcion
@ -187,6 +189,160 @@ Response:
}
```
## Historias de Usuario
### MCH-US-240: Widget Pequeno de Ventas
**Story Points:** 3
**Como** tendero con smartphone
**Quiero** ver mis ventas del dia en un widget pequeno en la pantalla de inicio
**Para** monitorear rapidamente mis ingresos sin abrir la aplicacion
#### Criterios de Aceptacion
- [CA-240-1] El widget muestra el total de ventas del dia en pesos mexicanos
- [CA-240-2] El widget muestra el numero de transacciones realizadas
- [CA-240-3] El widget se actualiza automaticamente cada 15 minutos
- [CA-240-4] Al tocar el widget se abre la seccion de ventas en la app
- [CA-240-5] El widget funciona en iOS (WidgetKit) y Android (Glance)
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-240-01 | Implementar SalesWidget con WidgetKit en iOS | 4h |
| MCH-TT-240-02 | Implementar SalesWidget con Glance en Android | 4h |
| MCH-TT-240-03 | Crear endpoint GET /api/widget/summary | 2h |
| MCH-TT-240-04 | Implementar cache local para datos offline | 2h |
| MCH-TT-240-05 | Configurar actualizacion periodica (15 min) | 1h |
### MCH-US-241: Widget Mediano con Alertas
**Story Points:** 5
**Como** tendero
**Quiero** ver un resumen completo de mi negocio en un widget mediano
**Para** estar al tanto de ventas, stock bajo, pedidos pendientes y fiados de un vistazo
#### Criterios de Aceptacion
- [CA-241-1] El widget muestra ventas del dia, alertas de stock, pedidos y fiados
- [CA-241-2] Los indicadores usan iconos claros y colores diferenciados
- [CA-241-3] Incluye botones de acceso rapido a POS y Pedidos
- [CA-241-4] El widget se adapta al tema claro/oscuro del dispositivo
- [CA-241-5] Los datos criticos (stock bajo) se destacan visualmente
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-241-01 | Disenar layout del widget mediano (4x2) | 2h |
| MCH-TT-241-02 | Implementar widget mediano iOS con WidgetKit | 5h |
| MCH-TT-241-03 | Implementar widget mediano Android con Glance | 5h |
| MCH-TT-241-04 | Agregar campos adicionales al endpoint /api/widget/summary | 2h |
| MCH-TT-241-05 | Implementar soporte para tema claro/oscuro | 2h |
| MCH-TT-241-06 | Configurar deep links para botones del widget | 2h |
### MCH-US-242: Widget Grande Android
**Story Points:** 4
**Como** tendero con dispositivo Android
**Quiero** un widget grande tipo dashboard en mi pantalla de inicio
**Para** tener visibilidad completa de metricas y alertas sin entrar a la app
#### Criterios de Aceptacion
- [CA-242-1] El widget muestra ventas con comparativa porcentual vs dia anterior
- [CA-242-2] Incluye barra de progreso visual de transacciones
- [CA-242-3] Lista las 3 alertas mas importantes (stock bajo, fiados)
- [CA-242-4] Tiene botones de acceso directo a POS, Productos y Pedidos
- [CA-242-5] Solo disponible en Android (limitacion de iOS)
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-242-01 | Disenar layout del widget grande (4x4) | 2h |
| MCH-TT-242-02 | Implementar widget grande Android con Glance | 6h |
| MCH-TT-242-03 | Crear logica de comparativa de ventas (% vs ayer) | 2h |
| MCH-TT-242-04 | Implementar lista de alertas prioritarias | 2h |
| MCH-TT-242-05 | Configurar interactividad de botones | 2h |
### MCH-US-243: Quick Actions iOS
**Story Points:** 3
**Como** usuario de iPhone
**Quiero** acceder a funciones clave con un long press en el icono de la app
**Para** realizar acciones rapidas sin navegar por la aplicacion
#### Criterios de Aceptacion
- [CA-243-1] Long press muestra 4 acciones: Nueva Venta, Ver Inventario, Ventas de Hoy, Agregar Producto
- [CA-243-2] Cada accion tiene un icono representativo
- [CA-243-3] Las acciones abren directamente la seccion correspondiente
- [CA-243-4] Funciona con 3D Touch en dispositivos compatibles
- [CA-243-5] Las acciones se actualizan segun el contexto del usuario
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-243-01 | Configurar UIApplicationShortcutItem en Info.plist | 1h |
| MCH-TT-243-02 | Implementar handler de Quick Actions en AppDelegate | 3h |
| MCH-TT-243-03 | Configurar iconos SF Symbols para cada accion | 1h |
| MCH-TT-243-04 | Integrar con sistema de navegacion React Native | 2h |
| MCH-TT-243-05 | Pruebas en dispositivos con y sin 3D Touch | 1h |
### MCH-US-244: App Shortcuts Android
**Story Points:** 3
**Como** usuario de Android
**Quiero** acceder a funciones clave con un long press en el icono de la app
**Para** realizar acciones rapidas como nueva venta o escanear producto
#### Criterios de Aceptacion
- [CA-244-1] Long press muestra 4 acciones: Nueva Venta, Escanear Producto, Ver Pedidos, Mi Saldo de Tokens
- [CA-244-2] Los shortcuts son estaticos y dinamicos segun el estado del negocio
- [CA-244-3] Cada shortcut tiene icono y etiqueta descriptiva
- [CA-244-4] Los shortcuts funcionan en Android 7.1+ (API 25+)
- [CA-244-5] Los shortcuts pinneables pueden agregarse a la pantalla de inicio
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-244-01 | Configurar static shortcuts en shortcuts.xml | 2h |
| MCH-TT-244-02 | Implementar dynamic shortcuts con ShortcutManager | 3h |
| MCH-TT-244-03 | Crear iconos adaptativos para cada shortcut | 1h |
| MCH-TT-244-04 | Implementar handler de shortcuts en MainActivity | 2h |
| MCH-TT-244-05 | Integrar con navegacion React Native | 2h |
### MCH-US-245: Deep Linking
**Story Points:** 3
**Como** desarrollador del sistema
**Quiero** implementar deep linking con URL scheme personalizado
**Para** permitir navegacion directa a cualquier seccion desde widgets y shortcuts
#### Criterios de Aceptacion
- [CA-245-1] URL scheme `michangarrito://` registrado en ambas plataformas
- [CA-245-2] Rutas soportadas: /pos, /pos/new, /products/:id, /orders/:id, /dashboard, /scan
- [CA-245-3] Los deep links funcionan desde widgets, shortcuts y enlaces externos
- [CA-245-4] Manejo de deep links con app cerrada (cold start)
- [CA-245-5] Fallback a pantalla principal si la ruta no existe
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-245-01 | Configurar URL scheme en iOS (Info.plist) | 1h |
| MCH-TT-245-02 | Configurar URL scheme en Android (AndroidManifest.xml) | 1h |
| MCH-TT-245-03 | Implementar DeepLinkingService en React Native | 3h |
| MCH-TT-245-04 | Integrar con React Navigation para rutas dinamicas | 2h |
| MCH-TT-245-05 | Implementar manejo de cold start con deep link | 2h |
| MCH-TT-245-06 | Pruebas de deep linking end-to-end | 2h |
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Prioridad |
|----|----------|--------------|-----------|
| MCH-US-240 | Widget Pequeno de Ventas | 3 | Alta |
| MCH-US-241 | Widget Mediano con Alertas | 5 | Alta |
| MCH-US-242 | Widget Grande Android | 4 | Media |
| MCH-US-243 | Quick Actions iOS | 3 | Media |
| MCH-US-244 | App Shortcuts Android | 3 | Media |
| MCH-US-245 | Deep Linking | 3 | Alta |
| **Total** | | **21** | |
## Entregables
| Entregable | Estado | Archivo |
@ -243,4 +399,4 @@ Response:
---
**Ultima actualizacion:** 2026-01-07
**Ultima actualizacion:** 2026-01-17

203
docs/01-epicas/MCH-026-multi-idioma-latam.md
View File

@ -7,8 +7,9 @@ status: Pendiente
phase: 7
priority: P3
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: 34
dependencies:
blocks: []
depends_on: []
@ -21,6 +22,7 @@ dependencies:
- **Fase:** 7 - Expansion (Futuro)
- **Prioridad:** P3
- **Estado:** Completado (Base)
- **Story Points:** 34
- **Fecha completado:** 2026-01-10
## Descripcion
@ -212,6 +214,201 @@ const formatCurrency = (amount: number, locale: string) => {
4. Usuario puede cambiar en settings
```
## Historias de Usuario
### MCH-US-250: Setup i18n
**Story Points:** 8
**Como** desarrollador
**Quiero** configurar react-i18next en las aplicaciones web y mobile
**Para** tener la infraestructura base de internacionalizacion lista
#### Criterios de Aceptacion
- [CA-250-1] react-i18next instalado y configurado en app web
- [CA-250-2] react-i18next instalado y configurado en app mobile
- [CA-250-3] Estructura de carpetas locales/ creada con archivos base
- [CA-250-4] Hook useTranslation funciona en componentes de prueba
- [CA-250-5] Cambio de idioma dinamico funciona sin recargar app
- [CA-250-6] Fallback a es-MX cuando traduccion no existe
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-250-01 | Instalar dependencias i18n en web | 1h |
| MCH-TT-250-02 | Configurar i18next provider en web | 2h |
| MCH-TT-250-03 | Instalar dependencias i18n en mobile | 1h |
| MCH-TT-250-04 | Configurar i18next provider en mobile | 2h |
| MCH-TT-250-05 | Crear estructura de carpetas locales/ | 1h |
| MCH-TT-250-06 | Implementar language detector | 2h |
| MCH-TT-250-07 | Crear componente LanguageSwitcher | 2h |
| MCH-TT-250-08 | Tests de integracion i18n | 2h |
---
### MCH-US-251: Traducciones es-MX
**Story Points:** 5
**Como** usuario mexicano
**Quiero** ver la aplicacion en espanol de Mexico
**Para** entender perfectamente la terminologia local (changarro, fiado, etc.)
#### Criterios de Aceptacion
- [CA-251-1] Archivo locales/es-MX/common.json completo
- [CA-251-2] Archivo locales/es-MX/pos.json completo
- [CA-251-3] Archivo locales/es-MX/products.json completo
- [CA-251-4] Archivo locales/es-MX/errors.json completo
- [CA-251-5] Terminologia mexicana validada (changarro, fiado)
- [CA-251-6] 100% de strings de UI traducidos
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-251-01 | Extraer todas las strings de la app | 3h |
| MCH-TT-251-02 | Crear common.json es-MX | 2h |
| MCH-TT-251-03 | Crear pos.json es-MX | 2h |
| MCH-TT-251-04 | Crear products.json es-MX | 2h |
| MCH-TT-251-05 | Crear errors.json es-MX | 1h |
| MCH-TT-251-06 | Validar terminologia con usuarios mexicanos | 2h |
---
### MCH-US-252: Traducciones es-CO
**Story Points:** 3
**Como** usuario colombiano
**Quiero** ver la aplicacion en espanol de Colombia
**Para** sentirme identificado con la terminologia local
#### Criterios de Aceptacion
- [CA-252-1] Archivos locales/es-CO/ completos
- [CA-252-2] Terminologia colombiana aplicada
- [CA-252-3] Formato de moneda COP configurado
- [CA-252-4] 100% de strings traducidos
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-252-01 | Copiar base es-MX a es-CO | 0.5h |
| MCH-TT-252-02 | Adaptar terminologia colombiana | 2h |
| MCH-TT-252-03 | Validar con usuarios colombianos | 2h |
| MCH-TT-252-04 | Configurar formato moneda COP | 1h |
---
### MCH-US-253: Traducciones es-AR
**Story Points:** 3
**Como** usuario argentino
**Quiero** ver la aplicacion en espanol de Argentina
**Para** usar terminologia familiar (almacen, cuenta, vos)
#### Criterios de Aceptacion
- [CA-253-1] Archivos locales/es-AR/ completos
- [CA-253-2] Terminologia argentina aplicada (almacen en vez de tienda)
- [CA-253-3] Formato de moneda ARS configurado
- [CA-253-4] 100% de strings traducidos
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-253-01 | Copiar base es-MX a es-AR | 0.5h |
| MCH-TT-253-02 | Adaptar terminologia argentina | 2h |
| MCH-TT-253-03 | Validar con usuarios argentinos | 2h |
| MCH-TT-253-04 | Configurar formato moneda ARS | 1h |
---
### MCH-US-254: Traducciones pt-BR
**Story Points:** 5
**Como** usuario brasileno
**Quiero** ver la aplicacion en portugues de Brasil
**Para** usar la app en mi idioma nativo
#### Criterios de Aceptacion
- [CA-254-1] Archivos locales/pt-BR/ completos
- [CA-254-2] Traducciones profesionales al portugues brasileno
- [CA-254-3] Terminologia comercial brasilena (loja, dinheiro)
- [CA-254-4] Formato de moneda BRL (R$) configurado
- [CA-254-5] 100% de strings traducidos
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-254-01 | Copiar estructura de es-MX a pt-BR | 0.5h |
| MCH-TT-254-02 | Contratar servicio traduccion profesional | 1h |
| MCH-TT-254-03 | Aplicar traducciones profesionales | 3h |
| MCH-TT-254-04 | Validar con usuarios brasilenos | 3h |
| MCH-TT-254-05 | Configurar formato moneda BRL | 1h |
---
### MCH-US-255: Localizacion de Monedas y Formatos
**Story Points:** 5
**Como** usuario de cualquier pais LATAM
**Quiero** ver precios y fechas en el formato de mi pais
**Para** entender rapidamente los valores sin hacer conversiones mentales
#### Criterios de Aceptacion
- [CA-255-1] MXN formateado como $1,234.56
- [CA-255-2] COP formateado como $1.234,56
- [CA-255-3] ARS formateado como $1.234,56
- [CA-255-4] BRL formateado como R$ 1.234,56
- [CA-255-5] Fechas formateadas como DD/MM/YYYY para todos
- [CA-255-6] Utility formatCurrency funciona con todos los locales
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-255-01 | Crear utils/currency.ts con Intl.NumberFormat | 2h |
| MCH-TT-255-02 | Crear utils/date.ts con formateo local | 2h |
| MCH-TT-255-03 | Integrar formatters en componentes POS | 3h |
| MCH-TT-255-04 | Integrar formatters en reportes | 2h |
| MCH-TT-255-05 | Tests unitarios de formatters | 2h |
---
### MCH-US-256: Deteccion Automatica de Region
**Story Points:** 5
**Como** usuario nuevo
**Quiero** que la app detecte automaticamente mi pais
**Para** no tener que configurar manualmente el idioma y moneda
#### Criterios de Aceptacion
- [CA-256-1] Deteccion de pais por IP al registrarse
- [CA-256-2] Asignacion automatica de locale segun pais detectado
- [CA-256-3] Usuario puede cambiar locale en configuracion
- [CA-256-4] Preferencia de locale persistida en base de datos
- [CA-256-5] Fallback a es-MX si pais no soportado
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-256-01 | Integrar servicio geolocalizacion IP | 3h |
| MCH-TT-256-02 | Implementar logica deteccion en registro | 2h |
| MCH-TT-256-03 | Agregar campo locale a modelo tenant | 1h |
| MCH-TT-256-04 | Agregar campo locale a modelo user | 1h |
| MCH-TT-256-05 | Crear pantalla configuracion de idioma | 3h |
| MCH-TT-256-06 | Endpoint PUT /settings/locale | 2h |
| MCH-TT-256-07 | Tests de integracion | 2h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Prioridad |
|----|----------|--------------|-----------|
| MCH-US-250 | Setup i18n | 8 | Alta |
| MCH-US-251 | Traducciones es-MX | 5 | Alta |
| MCH-US-252 | Traducciones es-CO | 3 | Media |
| MCH-US-253 | Traducciones es-AR | 3 | Media |
| MCH-US-254 | Traducciones pt-BR | 5 | Media |
| MCH-US-255 | Localizacion de Monedas y Formatos | 5 | Alta |
| MCH-US-256 | Deteccion Automatica de Region | 5 | Media |
| **Total** | | **34** | |
## Entregables
| Entregable | Estado | Archivo |
@ -255,4 +452,4 @@ const formatCurrency = (amount: number, locale: string) => {
---
**Ultima actualizacion:** 2026-01-07
**Ultima actualizacion:** 2026-01-17

237
docs/01-epicas/MCH-027-integracion-sat.md
View File

@ -6,9 +6,10 @@ code: MCH-027
status: Pendiente
phase: 7
priority: P3
story_points: 55
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"
dependencies:
blocks: []
depends_on: []
@ -21,6 +22,7 @@ dependencies:
- **Fase:** 7 - Expansion (Futuro)
- **Prioridad:** P3
- **Estado:** Completado
- **Story Points:** 55
- **Fecha estimada:** Sprint 19+
## Descripcion
@ -201,6 +203,235 @@ const invoice = await facturapi.invoices.create({
- Datos fiscales
- Botones: descargar, enviar
## Historias de Usuario
### MCH-US-260: Emision de CFDI de Ingreso
**Story Points:** 8
**Como** dueno de negocio
**Quiero** emitir facturas electronicas (CFDI de Ingreso) cuando un cliente lo solicite
**Para** cumplir con las obligaciones fiscales y dar al cliente su comprobante oficial
#### Criterios de Aceptacion
- [CA-260-1] El sistema genera un CFDI valido con estructura XML conforme al esquema SAT vigente
- [CA-260-2] El CFDI incluye todos los datos fiscales requeridos: RFC, razon social, regimen fiscal, uso CFDI
- [CA-260-3] Los productos facturados incluyen clave de producto/servicio SAT y clave de unidad
- [CA-260-4] El timbrado se realiza exitosamente con el PAC configurado
- [CA-260-5] El UUID (folio fiscal) se almacena correctamente en la base de datos
- [CA-260-6] El estatus de la factura se actualiza a "Timbrada" tras el proceso exitoso
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-260-01 | Implementar entity Invoice con todos los campos SAT | 3h |
| MCH-TT-260-02 | Crear servicio de construccion de XML CFDI | 4h |
| MCH-TT-260-03 | Implementar validaciones de datos fiscales | 2h |
| MCH-TT-260-04 | Integrar con servicio de timbrado PAC | 4h |
| MCH-TT-260-05 | Crear endpoint POST /invoices | 2h |
| MCH-TT-260-06 | Implementar tests unitarios y de integracion | 3h |
---
### MCH-US-261: Emision de CFDI de Egreso
**Story Points:** 5
**Como** dueno de negocio
**Quiero** emitir notas de credito (CFDI de Egreso) cuando haya devoluciones o descuentos
**Para** reflejar correctamente las operaciones fiscales y mantener la contabilidad al dia
#### Criterios de Aceptacion
- [CA-261-1] El CFDI de Egreso referencia correctamente al CFDI de Ingreso original (UUID)
- [CA-261-2] El tipo de relacion SAT se especifica correctamente (01-Nota de credito)
- [CA-261-3] Los montos del egreso corresponden a la devolucion o descuento aplicado
- [CA-261-4] El sistema valida que el CFDI original exista y este vigente
- [CA-261-5] El egreso se timbra correctamente con el PAC
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-261-01 | Extender modelo Invoice para tipo Egreso | 2h |
| MCH-TT-261-02 | Implementar logica de relacion entre CFDIs | 3h |
| MCH-TT-261-03 | Crear validaciones especificas para egresos | 2h |
| MCH-TT-261-04 | Ajustar servicio de timbrado para egresos | 2h |
| MCH-TT-261-05 | Implementar tests para flujo de egreso | 2h |
---
### MCH-US-262: Integracion con PAC
**Story Points:** 8
**Como** sistema
**Quiero** conectarme con un Proveedor Autorizado de Certificacion (PAC)
**Para** timbrar los CFDIs y obtener el sello digital del SAT
#### Criterios de Aceptacion
- [CA-262-1] El sistema soporta al menos un PAC (Facturapi como principal)
- [CA-262-2] Las credenciales del PAC se almacenan encriptadas por tenant
- [CA-262-3] El sistema maneja errores de timbrado con mensajes claros
- [CA-262-4] Se implementa retry automatico ante fallas temporales del PAC
- [CA-262-5] Los tiempos de respuesta del PAC se registran para monitoreo
- [CA-262-6] El sistema puede funcionar en modo sandbox para pruebas
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-262-01 | Crear interfaz abstracta PacProvider | 2h |
| MCH-TT-262-02 | Implementar FacturapiProvider | 4h |
| MCH-TT-262-03 | Configurar manejo de credenciales encriptadas | 3h |
| MCH-TT-262-04 | Implementar circuit breaker y retry logic | 3h |
| MCH-TT-262-05 | Crear modo sandbox/pruebas | 2h |
| MCH-TT-262-06 | Implementar logging y metricas de PAC | 2h |
---
### MCH-US-263: Generacion de PDF de Factura
**Story Points:** 5
**Como** cliente
**Quiero** recibir mi factura en formato PDF legible
**Para** tener un comprobante imprimible y facil de leer
#### Criterios de Aceptacion
- [CA-263-1] El PDF incluye todos los datos fiscales del emisor y receptor
- [CA-263-2] Se muestra el desglose de productos con claves SAT
- [CA-263-3] El PDF incluye codigo QR con URL de verificacion SAT
- [CA-263-4] Se muestra la cadena original y sello digital
- [CA-263-5] El diseno es profesional y cumple con requisitos SAT
- [CA-263-6] El PDF se genera en menos de 3 segundos
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-263-01 | Disenar template de factura PDF | 3h |
| MCH-TT-263-02 | Implementar servicio de generacion PDF | 4h |
| MCH-TT-263-03 | Integrar generacion de codigo QR | 2h |
| MCH-TT-263-04 | Crear endpoint GET /invoices/:id/pdf | 1h |
| MCH-TT-263-05 | Optimizar rendimiento de generacion | 2h |
---
### MCH-US-264: Envio Automatico por Email
**Story Points:** 5
**Como** cliente
**Quiero** recibir mi factura automaticamente por email
**Para** tenerla disponible sin tener que solicitarla nuevamente
#### Criterios de Aceptacion
- [CA-264-1] El email incluye el XML como adjunto
- [CA-264-2] El email incluye el PDF como adjunto
- [CA-264-3] El asunto del email identifica claramente la factura (serie, folio)
- [CA-264-4] El cuerpo del email incluye resumen de la factura
- [CA-264-5] Se registra el envio exitoso en la base de datos
- [CA-264-6] El sistema permite reenviar la factura bajo demanda
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-264-01 | Disenar template de email para factura | 2h |
| MCH-TT-264-02 | Implementar servicio de envio con adjuntos | 3h |
| MCH-TT-264-03 | Crear endpoint POST /invoices/:id/send | 1h |
| MCH-TT-264-04 | Implementar cola de envios para alto volumen | 3h |
| MCH-TT-264-05 | Registrar tracking de envios | 2h |
---
### MCH-US-265: Cancelacion de Facturas
**Story Points:** 8
**Como** dueno de negocio
**Quiero** cancelar facturas emitidas por error o devolucion
**Para** mantener mi contabilidad correcta ante el SAT
#### Criterios de Aceptacion
- [CA-265-1] La cancelacion se envia al SAT a traves del PAC
- [CA-265-2] Se requiere motivo de cancelacion segun catalogo SAT
- [CA-265-3] Para facturas >$1000, se gestiona el proceso de aceptacion del receptor
- [CA-265-4] El estatus de cancelacion se actualiza correctamente (En proceso, Cancelada)
- [CA-265-5] Se genera acuse de cancelacion cuando aplica
- [CA-265-6] El sistema consulta periodicamente el estatus de cancelaciones pendientes
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-265-01 | Implementar endpoint POST /invoices/:id/cancel | 2h |
| MCH-TT-265-02 | Integrar API de cancelacion del PAC | 4h |
| MCH-TT-265-03 | Implementar flujo de aceptacion de receptor | 4h |
| MCH-TT-265-04 | Crear job de consulta de estatus de cancelaciones | 3h |
| MCH-TT-265-05 | Implementar notificaciones de cambio de estatus | 2h |
| MCH-TT-265-06 | Crear tests para flujos de cancelacion | 3h |
---
### MCH-US-266: Solicitud de Factura via WhatsApp
**Story Points:** 8
**Como** cliente
**Quiero** solicitar mi factura a traves de WhatsApp
**Para** obtenerla de forma rapida y conversacional sin llamar al negocio
#### Criterios de Aceptacion
- [CA-266-1] El bot reconoce la intencion de solicitar factura
- [CA-266-2] El bot solicita los datos fiscales requeridos de forma conversacional
- [CA-266-3] El sistema valida el RFC en formato y estructura
- [CA-266-4] El bot confirma los datos antes de generar la factura
- [CA-266-5] La factura se genera y se notifica al cliente el envio por email
- [CA-266-6] El bot maneja errores de forma amigable (RFC invalido, ticket no encontrado)
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-266-01 | Disenar flujo conversacional de facturacion | 3h |
| MCH-TT-266-02 | Implementar intent de solicitud de factura | 2h |
| MCH-TT-266-03 | Crear colectores de datos fiscales | 4h |
| MCH-TT-266-04 | Integrar validacion de RFC | 2h |
| MCH-TT-266-05 | Conectar con servicio de facturacion | 3h |
| MCH-TT-266-06 | Implementar manejo de errores conversacional | 2h |
---
### MCH-US-267: Reportes Fiscales Mensuales
**Story Points:** 8
**Como** contador del negocio
**Quiero** generar reportes mensuales de facturas emitidas
**Para** facilitar la declaracion de impuestos y conciliacion fiscal
#### Criterios de Aceptacion
- [CA-267-1] El reporte incluye todas las facturas del periodo (ingresos y egresos)
- [CA-267-2] Se muestra desglose de IVA trasladado y retenido
- [CA-267-3] El reporte se puede exportar en formato Excel y PDF
- [CA-267-4] Se incluye totales por tipo de comprobante
- [CA-267-5] El reporte incluye facturas canceladas marcadas como tal
- [CA-267-6] Se puede filtrar por serie, estatus y tipo de CFDI
#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-267-01 | Disenar estructura del reporte fiscal | 2h |
| MCH-TT-267-02 | Implementar consultas agregadas de facturas | 4h |
| MCH-TT-267-03 | Crear endpoint GET /invoices/report | 2h |
| MCH-TT-267-04 | Implementar exportacion a Excel | 3h |
| MCH-TT-267-05 | Implementar exportacion a PDF | 2h |
| MCH-TT-267-06 | Crear UI de reportes fiscales | 4h |
| MCH-TT-267-07 | Implementar filtros y parametros del reporte | 2h |
---
### Resumen de Historias de Usuario
| ID | Historia | Story Points | Prioridad |
|----|----------|--------------|-----------|
| MCH-US-260 | Emision de CFDI de Ingreso | 8 | Alta |
| MCH-US-261 | Emision de CFDI de Egreso | 5 | Alta |
| MCH-US-262 | Integracion con PAC | 8 | Alta |
| MCH-US-263 | Generacion de PDF de Factura | 5 | Alta |
| MCH-US-264 | Envio Automatico por Email | 5 | Media |
| MCH-US-265 | Cancelacion de Facturas | 8 | Alta |
| MCH-US-266 | Solicitud de Factura via WhatsApp | 8 | Media |
| MCH-US-267 | Reportes Fiscales Mensuales | 8 | Media |
| **Total** | | **55** | |
## Entregables
| Entregable | Estado | Archivo |
@ -262,4 +493,4 @@ const invoice = await facturapi.invoices.create({
---
**Ultima actualizacion:** 2026-01-10
**Ultima actualizacion:** 2026-01-17