# Integración CloudRestoreAS ↔ PANEL_BASES_ANEXO24

## Variables de entorno y configuración

| Panel (`.env`) | CloudRestoreAS (pestaña Config → PANEL) | Debe coincidir |
|----------------|-------------------------------------------|----------------|
| `CLOUDRESTORE_API_TOKEN` | `panel.api_token` | **Sí** — mismo valor en todas las instalaciones |
| `ENCRYPTION_KEY` | — | Solo panel (cifra credenciales de `restore_targets`) |
| URL del panel (ej. `https://panel:3000`) | `panel.api_url` | **Sí** — base URL sin barra final |
| — | `panel.instance_key` | Nombre de **este** servidor en el panel (`restore_targets.name`) |

Generar token:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Generar clave de cifrado (panel):

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

`BACKUP_PATH` del panel es independiente: lista respaldos en el dashboard. Cada CloudRestoreAS reporta su carpeta local vía `instance-config` (clave = nombre del servidor).

---

## Enrutamiento automático (todos los CRA)

No hay modos que configurar. **Todo CRA con panel** hace lo mismo:

1. Llega un ZIP a la carpeta de entrada.
2. `GET resolve-route?filename=X&instance=<esta instancia>` — el panel identifica el nodo y el servidor asignado.
3. Si `action=restore_local` → extract + RESTORE aquí (credenciales SQL de este servidor en el panel).
4. Si `action=forward` → SFTP del ZIP al `input_folder` del destino (credenciales SSH del destino).
5. Mover ZIP a `processed`; reportar `completed` o `forwarded`.

```mermaid
flowchart TB
    ZIP[ZIP en carpeta local]
    CRA[Any CRA con instance_key]
    Panel["resolve-route"]
    SFTP[SFTP al destino]
    SQL[RESTORE local]

    ZIP --> CRA --> Panel
    Panel -->|restore_local| SQL
    Panel -->|forward| SFTP
```

Aplica igual en Alfa, Omega o un hub donde llegan todos los ZIP:

| Situación | Qué hace el CRA |
|-----------|-----------------|
| Nodo asignado a **esta** instancia | RESTORE local |
| Nodo asignado a **otro** servidor | SFTP ZIP al destino |

La decisión la toma el **panel** (nodo + asignación en Gestión BD), no el operador.

### Qué configura cada instalación

| Campo | Para qué |
|-------|----------|
| URL + token del panel | Conectar al panel |
| **Instancia** | Identidad de este servidor (`restore_targets.name`) |
| Carpeta entrada | Dónde vigila ZIPs esta máquina |

El selector de instancia se llena desde `GET /api/restore/target-catalog`. No hay límite de servidores.

### Hub donde llegan todos los ZIP

Ejemplo: máquina **Alfa** recibe todos los archivos y también tiene bases propias:

1. Panel: servidor Alfa registrado; bases de Alfa/Omega/Gamma asignadas en Gestión BD.
2. CRA en Alfa: instancia **Alfa**, misma URL/token que el resto.
3. ZIP de base Alfa → RESTORE local.
4. ZIP de base Omega → SFTP a carpeta de Omega (card **Reportada**).
5. CRA Omega detecta el ZIP y restaura localmente.

No hay paso extra ni modo especial.

### Sin panel (legacy local)

Si `panel.api_url` está vacío, CloudRestoreAS usa nodos SQLite locales y SQL de la pestaña Config (sin reparto automático).

### Config legacy `panel.mode`

Valores antiguos (`orchestrator`, `hub_restore`, `colocated`) se **ignoran**. Se registra un aviso en log y se usa siempre `resolve-route`. El modo hub que subía `.bak` por SFTP ya no aplica.

---

## Contrato API (`/api/restore/*`)

Autenticación: `Authorization: Bearer <CLOUDRESTORE_API_TOKEN>`.

### GET `/api/restore/target-catalog`

**Cliente:** `panel_client.list_restore_target_names()`

| Respuesta 200 | Descripción |
|---------------|-------------|
| `targets[]` | `{ "id", "name" }` — sin credenciales |

### GET `/api/restore/resolve-route?filename=<zip>&instance=<nombre>`

**Cliente:** `panel_client.resolve_route()`

| Query | Obligatorio | Descripción |
|-------|-------------|-------------|
| `filename` | Sí | Nombre del ZIP (panel resuelve nodo desde el stem) |
| `instance` | Sí | Instancia de este CRA (`restore_targets.name`) |

| Respuesta 200 | Descripción |
|---------------|-------------|
| `action` | `restore_local` o `forward` |
| `db_name` | Base resuelta |
| `node_key` | Nodo en panel |
| `target` | Servidor destino (SQL/SSH + `input_folder`) |

| Código | Significado |
|--------|-------------|
| 404 | Sin nodo/base o sin servidor asignado |
| 503 | Destino sin `input_folder` reportado |

### GET `/api/restore/target-for?database=<db_name>&instance=<nombre>`

Usado por utilidades legacy; el flujo principal de jobs usa `resolve-route`.

### POST `/api/restore/job-result`

`status`: `completed` | `failed` | `forwarded`.

### POST `/api/restore/instance-config`

Reporte de carpeta de entrada (`instance_key` = nombre del servidor).

---

## Agregar servidores adicionales

1. Panel → **Servidores de Restauración → + Nuevo servidor**
2. **Gestión de Bases de Datos** → dropdown servidor por base
3. Instalar CRA → Config → instancia → Guardar (card **Reportada**)

---

## Despliegue inicial

### Orden de arranque (migraciones automáticas)

1. **a24c-postgres** — volumen Postgres.
2. **a24c-backend** — aplica `alembic upgrade head` al iniciar (incluye tablas CRA:
   `restore_targets`, `restore_job_logs`, `cloudrestore_status`, `restore_target_id`).
3. **Panel** (`docker compose up`) — espera el esquema CRA en Postgres antes de abrir el puerto 3000.

No hace falta ejecutar `database/migrations/*.sql` a mano: la fuente de verdad es Alembic en **a24c**.

### Panel

```bash
cd ~/dev/PANEL_BASES_ANEXO24
cp .env.example .env
docker compose up -d
```

Servidores de restauración + asignación de bases en Gestión BD.

### Cada Windows con CloudRestoreAS

| Config | Valor |
|--------|--------|
| URL PANEL | misma en todos |
| API Token | mismo en todos |
| **Instancia** | nombre de **este** servidor en panel |
| Carpeta Entrada | local de esta máquina |

### Verificaciones

| Paso | Qué comprobar |
|------|----------------|
| Cards en panel | **Reportada** con carpeta |
| ZIP propio | RESTORE local |
| ZIP ajeno en esta carpeta | SFTP al destino; bitácora `forwarded` |
| Destino recibe ZIP | RESTORE local allí |

### Troubleshooting

- **Sin reportar**: CRA destino no guardó config o no alcanza el panel.
- **503 en forward**: destino sin `input_folder` reportado.
- **Job diferido**: panel caído, sin `instance_key`, o base sin asignación.
- **401**: token distinto entre panel y CRA.

---

## Prueba local

Un CRA con `instance_key` igual al nombre en panel. El panel muestra una card por servidor; las no reportadas aparecen como **Sin reportar**.