checklist/frontend/PWA-UPDATE-GUIDE.md

# Sistema de Actualización PWA - AYUTEC

## 🚀 Características

- ✅ **Detección automática** de nuevas versiones
- ✅ **Modal de actualización** grande y visible
- ✅ **Service Worker** con estrategia Network-First
- ✅ **Cache inteligente** para funcionamiento offline
- ✅ **Actualización forzada** al usuario cuando hay nueva versión

## 📱 Instalación como PWA

### En Android/iOS:
1. Abre la app en Chrome/Safari
2. Toca el menú (⋮) 
3. Selecciona "Agregar a pantalla de inicio"
4. Confirma la instalación

### En Desktop:
1. Abre la app en Chrome/Edge
2. Haz clic en el ícono de instalación (➕) en la barra de direcciones
3. Confirma "Instalar"

## 🔄 Proceso de Actualización

### Para el Usuario:
1. Cuando hay una actualización, aparece automáticamente un **modal grande**
2. El modal muestra: "¡Nueva Actualización!"
3. Botón grande: **"🚀 ACTUALIZAR AHORA"**
4. Al presionar, la app se recarga con la nueva versión

### Para el Desarrollador:

#### Opción 1: Script Automático (Recomendado)
```powershell
cd frontend
.\update-version.ps1
```
Este script:
- Incrementa automáticamente la versión patch (1.0.87 → 1.0.88)
- Actualiza `package.json`
- Actualiza `public/service-worker.js`

#### Opción 2: Manual
1. **Actualizar `package.json`:**
   ```json
   "version": "1.0.88"  // Incrementar número
   ```

2. **Actualizar `public/service-worker.js`:**
   ```javascript
   const CACHE_NAME = 'ayutec-v1.0.88';  // Mismo número
   ```

3. **Hacer build y deploy:**
   ```powershell
   npm run build
   docker build -t tu-registry/checklist-frontend:latest .
   docker push tu-registry/checklist-frontend:latest
   ```

## 🔧 Cómo Funciona

### 1. Service Worker
- Registrado en `App.jsx`
- Cache con nombre versionado: `ayutec-v1.0.87`
- Estrategia: **Network First, Cache Fallback**
- Al cambiar la versión, se crea nuevo cache

### 2. Detección de Actualización
```javascript
// En App.jsx
registration.addEventListener('updatefound', () => {
  // Nueva versión detectada
  setUpdateAvailable(true)
})
```

### 3. Modal de Actualización
- Overlay negro semi-transparente (z-index: 9999)
- Modal animado con bounce
- Botón grande con gradiente
- **No se puede cerrar** - obliga a actualizar

### 4. Aplicación de Actualización
```javascript
waitingWorker.postMessage({ type: 'SKIP_WAITING' });
// Activa el nuevo service worker
// Recarga la página automáticamente
```

## 📊 Versionado

Seguimos **Semantic Versioning**:
- **MAJOR**: Cambios incompatibles (1.0.0 → 2.0.0)
- **MINOR**: Nueva funcionalidad compatible (1.0.0 → 1.1.0)
- **PATCH**: Correcciones de bugs (1.0.0 → 1.0.1)

El script `update-version.ps1` incrementa automáticamente **PATCH**.

## 🧪 Probar Localmente

1. **Compilar en modo producción:**
   ```bash
   npm run build
   npm run preview
   ```

2. **Simular actualización:**
   - Abre la app en navegador
   - Incrementa versión en `service-worker.js`
   - Recarga la página (Ctrl+F5)
   - Debe aparecer el modal de actualización

## 🐛 Troubleshooting

### El modal no aparece
- Verifica que el service worker esté registrado (F12 → Application → Service Workers)
- Asegúrate de cambiar el `CACHE_NAME` en `service-worker.js`
- Desregistra el SW antiguo: `Application → Service Workers → Unregister`

### La app no se actualiza
- Fuerza actualización: Ctrl+Shift+R (hard reload)
- Limpia cache del navegador
- Verifica que la nueva versión esté deployada

### PWA no se instala
- Verifica que `site.webmanifest` esté accesible
- Requiere HTTPS (excepto localhost)
- Verifica íconos en `/public/`

## 📝 Checklist de Deploy

- [ ] Incrementar versión con `update-version.ps1`
- [ ] Verificar que ambos archivos tengan la misma versión
- [ ] Hacer commit: `git commit -m "chore: bump version to X.X.X"`
- [ ] Build de producción: `npm run build`
- [ ] Build de Docker: `docker build -t frontend:vX.X.X .`
- [ ] Push a registry
- [ ] Deploy en servidor
- [ ] Verificar que usuarios vean el modal de actualización

## 🎯 Mejores Prácticas

1. **Siempre** incrementar versión antes de deploy
2. **Nunca** reutilizar números de versión
3. **Probar** localmente antes de deploy
4. **Documentar** cambios en commit message
5. **Notificar** a usuarios si es actualización crítica

## 🔐 Seguridad

- Service Worker solo funciona en HTTPS
- Manifest require `start_url` y `scope` correctos
- Cache no almacena datos sensibles (solo assets estáticos)

## 📱 Compatibilidad

- ✅ Chrome/Edge (Desktop y Mobile)
- ✅ Safari (iOS 11.3+)
- ✅ Firefox (Desktop y Mobile)
- ✅ Samsung Internet
- ⚠️ IE11 no soportado

---

**Versión actual:** 1.0.87
**Última actualización:** 2025-11-30