# Configuración de Scope Extensions y Link Handling en Nucleo V3

## Resumen

Este documento describe la implementación de **Scope Extensions** y **Link Handling** en las PWAs del ecosistema Nucleo V3, permitiendo que múltiples aplicaciones web en diferentes subdominios funcionen como un sistema unificado de aplicaciones progresivas.

## ¿Qué son Scope Extensions?

Scope Extensions es una característica de las Progressive Web Apps que permite a una PWA extender su scope (alcance) a otros orígenes (dominios/subdominios). Esto significa que:

- Una PWA instalada puede "capturar" navegaciones a otros subdominios
- Los usuarios pueden moverse entre apps manteniendo la experiencia de PWA
- El ecosistema de apps se siente más integrado y cohesivo

## Arquitectura Implementada

### Hub Principal: Perfil PWA

La aplicación **perfil** (`inicio.nucleoriofrio.com`) actúa como el **hub principal** del ecosistema Nucleo V3, con la capacidad de capturar navegaciones a:

- `musica.nucleoriofrio.com` (RepoDructor)
- `docs.nucleoriofrio.com` (Nucleo Docs)
- `analitica.nucleoriofrio.com` (Analítica Nucleo)
- `seguidordelotes.nucleoriofrio.com` (Seguidor de Lotes)
- `whisper.nucleoriofrio.com` (Nucleo Whisper)
- `amigos.nucleoriofrio.com` (Amigos App)

### Apps Secundarias

Cada app secundaria puede:
- Funcionar de manera independiente como PWA
- Confirmar su asociación con la PWA de Perfil mediante archivos `.well-known`
- Capturar enlaces dentro de su propio scope

## Componentes de la Implementación

### 1. Manifests (nuxt.config.ts)

#### Perfil (Hub Principal)
```typescript
manifest: {
  // ... otras propiedades ...
  capture_links: 'existing-client-navigate',
  scope_extensions: [
    { origin: "https://musica.nucleoriofrio.com" },
    { origin: "https://docs.nucleoriofrio.com" },
    { origin: "https://analitica.nucleoriofrio.com" },
    { origin: "https://seguidordelotes.nucleoriofrio.com" },
    { origin: "https://whisper.nucleoriofrio.com" },
    { origin: "https://amigos.nucleoriofrio.com" }
  ]
}
```

#### Apps Secundarias
```typescript
manifest: {
  // ... otras propiedades ...
  capture_links: 'existing-client-navigate'
}
```

### 2. Archivos .well-known/web-app-origin-association

Cada app secundaria debe tener este archivo en `public/.well-known/web-app-origin-association`:

```json
{
  "web_apps": [
    {
      "manifest": "https://inicio.nucleoriofrio.com/manifest.webmanifest",
      "details": {
        "paths": ["/*"]
      }
    }
  ]
}
```

**Ubicaciones:**
- `/home/draganel/repos/repodructor/public/.well-known/web-app-origin-association`
- `/home/draganel/repos/nucleoDocs/nuxt4/public/.well-known/web-app-origin-association`
- `/home/draganel/repos/nucleoWhisper/nuxt4/public/.well-known/web-app-origin-association`
- `/home/draganel/repos/analiticaNucleo/nuxt4-app/public/.well-known/web-app-origin-association`
- `/home/draganel/repos/seguidorDeLotes/nuxt4-app/public/.well-known/web-app-origin-association`

### 3. Configuración de Traefik (docker-compose.yml)

Cada `docker-compose.yml` ha sido actualizado para servir los archivos `.well-known` **sin autenticación**, con alta prioridad:

```yaml
# Router público para recursos PWA (sin autenticación)
- "traefik.http.routers.${APP_NAME}-public.rule=Host(`${APP_DOMAIN}`) && (PathPrefix(`/.well-known`) || PathPrefix(`/manifest.webmanifest`) || ...)"
- "traefik.http.routers.${APP_NAME}-public.priority=100"
```

## Flujo de Usuario

1. **Instalación de Perfil PWA**
   - Usuario instala la PWA de Perfil desde `inicio.nucleoriofrio.com`
   - El navegador lee el manifest y detecta los `scope_extensions`
   - El navegador valida automáticamente los archivos `.well-known` en cada origen extendido

2. **Navegación entre Apps**
   - Usuario hace clic en un enlace a `musica.nucleoriofrio.com` desde cualquier app
   - Si la PWA de Perfil está instalada y configurada correctamente:
     - El navegador puede abrir el enlace dentro de la ventana de la PWA
     - En lugar de abrir el navegador normal
   - La experiencia es más fluida y cohesiva

3. **Apps Independientes**
   - Cada app puede seguir siendo instalada independientemente
   - Cada app mantiene su propio Service Worker y caché
   - Las apps pueden funcionar offline según su configuración individual

## Limitaciones Técnicas

### Same-Origin Policy
Aunque las apps comparten el link handling, **NO comparten**:
- Service Workers (cada origen tiene el suyo)
- Caches (cada origen tiene su propio cache storage)
- Almacenamiento local (localStorage, IndexedDB)
- Permisos (cada origen pide permisos independientemente)

### Soporte de Navegadores
- **Chromium-based browsers** (Chrome, Edge): Soporte completo
- **Firefox**: Soporte limitado o experimental
- **Safari**: Sin soporte actualmente

## Validación y Testing

### Verificar Implementación

1. **Verificar archivos .well-known:**
```bash
# Debe devolver el JSON de asociación
curl https://musica.nucleoriofrio.com/.well-known/web-app-origin-association
```

2. **Verificar manifest de Perfil:**
```bash
# Debe contener scope_extensions
curl https://inicio.nucleoriofrio.com/manifest.webmanifest | grep scope_extensions
```

3. **Instalar y probar:**
   - Instalar la PWA de Perfil en Chrome/Edge
   - Hacer clic en enlaces a otras apps del ecosistema
   - Verificar que se abren dentro de la ventana de la PWA

### Debugging

**Chrome DevTools:**
1. Abrir DevTools → Application → Manifest
2. Verificar que `scope_extensions` aparece correctamente
3. En la consola, verificar errores relacionados con `.well-known`

**Edge DevTools:**
Similar a Chrome, con soporte adicional para PWA features

## Mantenimiento

### Agregar una Nueva App al Ecosistema

1. **Actualizar el manifest de Perfil** (`/home/draganel/repos/perfil/nuxt4/nuxt.config.ts`):
```typescript
scope_extensions: [
  // ... extensiones existentes ...
  {
    origin: "https://nuevaapp.nucleoriofrio.com"
  }
]
```

2. **Crear `.well-known` en la nueva app**:
```bash
mkdir -p /ruta/a/nuevaapp/public/.well-known
```

Crear `/ruta/a/nuevaapp/public/.well-known/web-app-origin-association`:
```json
{
  "web_apps": [
    {
      "manifest": "https://inicio.nucleoriofrio.com/manifest.webmanifest",
      "details": {
        "paths": ["/*"]
      }
    }
  ]
}
```

3. **Actualizar docker-compose.yml** de la nueva app:
```yaml
- "traefik.http.routers.nuevaapp-public.rule=Host(`nuevaapp.nucleoriofrio.com`) && (PathPrefix(`/.well-known`) || ...)"
```

4. **Agregar capture_links** al manifest de la nueva app:
```typescript
manifest: {
  // ... otras propiedades ...
  capture_links: 'existing-client-navigate'
}
```

### Remover una App del Ecosistema

1. Remover el origen de `scope_extensions` en el manifest de Perfil
2. Eliminar el archivo `.well-known` de la app
3. Rebuild y redeploy ambas apps

## Archivos Modificados

### Manifests Actualizados
- ✅ `/home/draganel/repos/perfil/nuxt4/nuxt.config.ts`
- ✅ `/home/draganel/repos/repodructor/nuxt.config.ts`
- ✅ `/home/draganel/repos/nucleoDocs/nuxt4/nuxt.config.ts`
- ✅ `/home/draganel/repos/nucleoWhisper/nuxt4/nuxt.config.ts`
- ✅ `/home/draganel/repos/analiticaNucleo/nuxt4-app/nuxt.config.ts`
- ✅ `/home/draganel/repos/seguidorDeLotes/nuxt4-app/nuxt.config.ts`

### Archivos .well-known Creados
- ✅ `/home/draganel/repos/repodructor/public/.well-known/web-app-origin-association`
- ✅ `/home/draganel/repos/nucleoDocs/nuxt4/public/.well-known/web-app-origin-association`
- ✅ `/home/draganel/repos/nucleoWhisper/nuxt4/public/.well-known/web-app-origin-association`
- ✅ `/home/draganel/repos/analiticaNucleo/nuxt4-app/public/.well-known/web-app-origin-association`
- ✅ `/home/draganel/repos/seguidorDeLotes/nuxt4-app/public/.well-known/web-app-origin-association`

### Docker Compose Actualizados
- ✅ `/home/draganel/repos/perfil/docker-compose.yml`
- ✅ `/home/draganel/repos/repodructor/docker-compose.yml`
- ✅ `/home/draganel/repos/nucleoDocs/docker-compose.yml`
- ✅ `/home/draganel/repos/nucleoWhisper/docker-compose.yml`
- ✅ `/home/draganel/repos/analiticaNucleo/docker-compose.yml`
- ✅ `/home/draganel/repos/seguidorDeLotes/docker-compose.yml`

## Referencias

- [Building multiple Progressive Web Apps on the same domain - Google](https://web.dev/building-multiple-pwas/)
- [Handle links to a PWA - Microsoft Edge Developer](https://docs.microsoft.com/en-us/microsoft-edge/progressive-web-apps-chromium/how-to/handle-links)
- [Scope Extensions for Web App Manifest - W3C](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md)

## Soporte

Para problemas o preguntas sobre esta configuración, contactar a:
- **Desarrollador:** Dario (Leouch, Draganel, nucleo000)
- **Empresa:** Nucleo Rio Frio

---

**Fecha de implementación:** 2025-10-17
**Versión:** 1.0
**Sistema:** Nucleo V3