# MCH-025: Widgets y Atajos

## Metadata
- **Codigo:** MCH-025
- **Fase:** 6 - Crecimiento
- **Prioridad:** P2
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 16

## 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"
}
```

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| iOS Widget | Pendiente | `ios/MiChangarritoWidget/` |
| Android Widget | Pendiente | `android/app/src/widget/` |
| Quick Actions | Pendiente | Configuracion nativa |
| Deep linking | Pendiente | `mobile/navigation/` |
| Widget API | Pendiente | `backend/controllers/widget.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
- [ ] Widget pequeno funciona Android
- [ ] Widget mediano funciona
- [ ] Quick Actions funcionan
- [ ] Deep links abren seccion correcta
- [ ] Datos se actualizan regularmente

## 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-07