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)

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:

   "version": "1.0.88"  // Incrementar número
   

2. Actualizar public/service-worker.js:

   const CACHE_NAME = 'ayutec-v1.0.88';  // Mismo número
   

3. Hacer build y deploy:

   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

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

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:

   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