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

---
id: EPIC-MCH-025
type: Epic
title: "MCH-025: Widgets y Atajos"
code: MCH-025
status: Completado
phase: 6
priority: P2
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 21
dependencies:
  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)
```swift
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)
```kotlin
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
```typescript
// 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)
- [x] Deep links abren seccion correcta
- [x] Datos se actualizan regularmente (Widget API implementada)

## Configuracion de Usuario

```typescript
// 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