From c659f1c623d883c8a09cd266dfcc165f14950f8e Mon Sep 17 00:00:00 2001 From: rckrdmrd Date: Sat, 17 Jan 2026 04:40:45 -0600 Subject: [PATCH] =?UTF-8?q?[MCH-DOC-VAL]=20docs:=20Estandarizar=20=C3=A9pi?= =?UTF-8?q?cas=20MCH-016=20a=20MCH-027=20con=20HU=20formales?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/01-epicas/MCH-016-entregas-domicilio.md | 156 +++++++++++- docs/01-epicas/MCH-017-notificaciones.md | 181 ++++++++++++- .../01-epicas/MCH-018-planes-suscripciones.md | 169 ++++++++++++- docs/01-epicas/MCH-019-tienda-tokens.md | 173 ++++++++++++- docs/01-epicas/MCH-020-pagos-suscripcion.md | 177 ++++++++++++- docs/01-epicas/MCH-021-dashboard-web.md | 214 ++++++++++++++-- docs/01-epicas/MCH-022-modo-offline.md | 172 ++++++++++++- docs/01-epicas/MCH-023-programa-referidos.md | 170 ++++++++++++- docs/01-epicas/MCH-024-codi-spei.md | 152 ++++++++++- docs/01-epicas/MCH-025-widgets-atajos.md | 162 +++++++++++- docs/01-epicas/MCH-026-multi-idioma-latam.md | 203 ++++++++++++++- docs/01-epicas/MCH-027-integracion-sat.md | 237 +++++++++++++++++- 12 files changed, 2110 insertions(+), 56 deletions(-) diff --git a/docs/01-epicas/MCH-016-entregas-domicilio.md b/docs/01-epicas/MCH-016-entregas-domicilio.md index 4c9043d39..7f7f83f32 100644 --- a/docs/01-epicas/MCH-016-entregas-domicilio.md +++ b/docs/01-epicas/MCH-016-entregas-domicilio.md @@ -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 diff --git a/docs/01-epicas/MCH-017-notificaciones.md b/docs/01-epicas/MCH-017-notificaciones.md index 3590b5bee..a5c09dcd2 100644 --- a/docs/01-epicas/MCH-017-notificaciones.md +++ b/docs/01-epicas/MCH-017-notificaciones.md @@ -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 diff --git a/docs/01-epicas/MCH-018-planes-suscripciones.md b/docs/01-epicas/MCH-018-planes-suscripciones.md index 9a150bee6..82412b004 100644 --- a/docs/01-epicas/MCH-018-planes-suscripciones.md +++ b/docs/01-epicas/MCH-018-planes-suscripciones.md @@ -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 diff --git a/docs/01-epicas/MCH-019-tienda-tokens.md b/docs/01-epicas/MCH-019-tienda-tokens.md index b243c4801..38b7371f6 100644 --- a/docs/01-epicas/MCH-019-tienda-tokens.md +++ b/docs/01-epicas/MCH-019-tienda-tokens.md @@ -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 diff --git a/docs/01-epicas/MCH-020-pagos-suscripcion.md b/docs/01-epicas/MCH-020-pagos-suscripcion.md index 1156a281f..a35f6edc7 100644 --- a/docs/01-epicas/MCH-020-pagos-suscripcion.md +++ b/docs/01-epicas/MCH-020-pagos-suscripcion.md @@ -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 diff --git a/docs/01-epicas/MCH-021-dashboard-web.md b/docs/01-epicas/MCH-021-dashboard-web.md index 0850ce69c..a70bbc17d 100644 --- a/docs/01-epicas/MCH-021-dashboard-web.md +++ b/docs/01-epicas/MCH-021-dashboard-web.md @@ -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 diff --git a/docs/01-epicas/MCH-022-modo-offline.md b/docs/01-epicas/MCH-022-modo-offline.md index 226e5efbc..9eee142a3 100644 --- a/docs/01-epicas/MCH-022-modo-offline.md +++ b/docs/01-epicas/MCH-022-modo-offline.md @@ -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 diff --git a/docs/01-epicas/MCH-023-programa-referidos.md b/docs/01-epicas/MCH-023-programa-referidos.md index 770165e30..8ab10ff3e 100644 --- a/docs/01-epicas/MCH-023-programa-referidos.md +++ b/docs/01-epicas/MCH-023-programa-referidos.md @@ -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 diff --git a/docs/01-epicas/MCH-024-codi-spei.md b/docs/01-epicas/MCH-024-codi-spei.md index 58162f4d7..d79c5424a 100644 --- a/docs/01-epicas/MCH-024-codi-spei.md +++ b/docs/01-epicas/MCH-024-codi-spei.md @@ -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 diff --git a/docs/01-epicas/MCH-025-widgets-atajos.md b/docs/01-epicas/MCH-025-widgets-atajos.md index 585eefd2a..f2f1e498b 100644 --- a/docs/01-epicas/MCH-025-widgets-atajos.md +++ b/docs/01-epicas/MCH-025-widgets-atajos.md @@ -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 diff --git a/docs/01-epicas/MCH-026-multi-idioma-latam.md b/docs/01-epicas/MCH-026-multi-idioma-latam.md index d872d3042..32bf05055 100644 --- a/docs/01-epicas/MCH-026-multi-idioma-latam.md +++ b/docs/01-epicas/MCH-026-multi-idioma-latam.md @@ -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 diff --git a/docs/01-epicas/MCH-027-integracion-sat.md b/docs/01-epicas/MCH-027-integracion-sat.md index 1eb6e8315..9978562e3 100644 --- a/docs/01-epicas/MCH-027-integracion-sat.md +++ b/docs/01-epicas/MCH-027-integracion-sat.md @@ -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