michangarrito/docs/01-epicas/MCH-025-widgets-atajos.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-025	Epic	MCH-025: Widgets y Atajos	MCH-025	Completado	6	P2	2026-01-10	2026-01-17	4.0.1	21	blocks depends_on

MCH-025: Widgets y Atajos

Metadata

• Codigo: MCH-025
• Fase: 6 - Crecimiento
• Prioridad: P2
• Estado: Completado
• Fecha estimada: Sprint 7
• Story Points: 21

Descripcion

Widgets para pantalla de inicio (Android/iOS) y atajos rapidos: ver ventas del dia, acceso rapido al POS, alertas de stock, y notificaciones importantes sin abrir la app.

Objetivos

1. Widget de ventas del dia
2. Widget de alertas
3. Atajos rapidos (Quick Actions)
4. Deep linking
5. Actualizacion en tiempo real

Alcance

Incluido

• Widget pequeno (ventas hoy)
• Widget mediano (ventas + alertas)
• Quick Actions iOS (3D Touch / Long Press)
• App Shortcuts Android
• Deep links a secciones

Excluido

• Widget interactivo completo
• Widgets para Apple Watch
• Widgets para tablets

Widgets

Widget Pequeno (2x1)

┌─────────────────────┐
│  💰 Ventas Hoy     │
│     $3,450         │
│     23 ventas      │
└─────────────────────┘

Widget Mediano (4x2)

┌─────────────────────────────────────┐
│  MiChangarrito                      │
├─────────────────────────────────────┤
│  💰 Ventas: $3,450  |  📦 Stock: 3  │
│  🛒 Pedidos: 2      |  💳 Fiados: 5 │
├─────────────────────────────────────┤
│  [Abrir POS]  [Ver Pedidos]         │
└─────────────────────────────────────┘

Widget Grande (4x4) - Solo Android

┌─────────────────────────────────────┐
│  MiChangarrito Dashboard            │
├─────────────────────────────────────┤
│                                     │
│  Ventas Hoy: $3,450 (+15%)         │
│  ████████████░░░ 23 transacciones  │
│                                     │
│  Alertas:                          │
│  ⚠️ Coca-Cola: 5 unidades          │
│  ⚠️ Pan Bimbo: 3 unidades          │
│  💰 5 fiados pendientes            │
│                                     │
│  [POS] [Productos] [Pedidos]       │
└─────────────────────────────────────┘

Quick Actions / App Shortcuts

iOS (Long Press en icono)

┌─────────────────────┐
│ 🛒 Nueva Venta     │
│ 📦 Ver Inventario  │
│ 📊 Ventas de Hoy   │
│ ➕ Agregar Producto │
└─────────────────────┘

Android (Long Press en icono)

┌─────────────────────┐
│ Nueva Venta        │
│ Escanear Producto  │
│ Ver Pedidos        │
│ Mi Saldo de Tokens │
└─────────────────────┘

Deep Links

Accion	Deep Link
Abrir POS	michangarrito://pos
Nueva venta	michangarrito://pos/new
Ver producto	michangarrito://products/:id
Ver pedido	michangarrito://orders/:id
Dashboard	michangarrito://dashboard
Escanear	michangarrito://scan

Implementacion Tecnica

iOS Widgets (WidgetKit)

struct SalesWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "SalesWidget",
            provider: SalesProvider()
        ) { entry in
            SalesWidgetView(entry: entry)
        }
        .configurationDisplayName("Ventas del Día")
        .description("Ve tus ventas en tiempo real")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}

Android Widgets (Glance / AppWidget)

class SalesWidget : GlanceAppWidget() {
    override suspend fun provideGlance(
        context: Context,
        id: GlanceId
    ) {
        provideContent {
            SalesWidgetContent(getSalesData())
        }
    }
}

React Native Bridge

• expo-widgets (si disponible)
• react-native-widget-extension
• Codigo nativo para cada plataforma

Actualizacion de Datos

Estrategia

1. Widget se actualiza cada 15 minutos (sistema)
2. Push notification trigger refresh
3. Background fetch cuando app esta activa
4. Datos cacheados localmente

API para Widgets

// Endpoint liviano para widgets
GET /api/widget/summary

Response:
{
  "sales_today": 3450,
  "transactions_count": 23,
  "pending_orders": 2,
  "low_stock_count": 3,
  "pending_credits": 5,
  "updated_at": "2026-01-07T15:30:00Z"
}

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
iOS Widget	Pendiente	ios/MiChangarritoWidget/ (codigo nativo)
Android Widget	Pendiente	android/app/src/widget/ (codigo nativo)
Quick Actions	Pendiente	Configuracion nativa
Deep linking	Completado	mobile/src/services/deepLinking.ts
Widget API	Completado	backend/src/modules/widgets/widgets.controller.ts

Dependencias

Depende de

• App movil base
• MCH-021 (Dashboard - datos)
• Push notifications configuradas

Bloquea a

• Ninguno

Criterios de Aceptacion

• Widget pequeno funciona iOS (pendiente codigo nativo Swift)
• Widget pequeno funciona Android (pendiente codigo nativo Kotlin)
• Widget mediano funciona (pendiente codigo nativo)
• Quick Actions funcionan (pendiente codigo nativo)
• Deep links abren seccion correcta
• Datos se actualizan regularmente (Widget API implementada)

Configuracion de Usuario

// Preferencias de widget
{
  widget: {
    show_sales: true,
    show_orders: true,
    show_stock_alerts: true,
    show_credits: true,
    refresh_interval: 15 // minutos
  }
}

Limitaciones por Plataforma

Feature	iOS	Android
Widget pequeno	Si	Si
Widget mediano	Si	Si
Widget grande	No	Si
Interactivo	Limitado	Si
Background refresh	15 min min	Configurable

---

Ultima actualizacion: 2026-01-17