# Espejo Fidel Drive — respaldo local por tenant (fase 3 del módulo 31)

Agente headless que mantiene una **copia local completa** de los documentos
de la firma en su propia infraestructura (PC Windows, servidor Linux o NAS).
Diseño aprobado por el owner el 2026-08-17.

## Las tres reglas de oro (irrevocables)

1. **UNIDIRECCIONAL** — solo baja. `Api.cs` no contiene un solo método de
   escritura (únicamente `HttpMethod.Get`): el espejo no puede subir ni
   modificar nada en el servidor, por construcción.
2. **LOS BORRADOS NO BORRAN** — un tombstone del feed mueve el archivo local
   a `_Archivo del espejo/<fecha>/<ruta original>`. Nada se destruye jamás.
3. **MISMA SANGRE QUE EL DRIVE** — autentica con clave de aplicación
   (Mi Perfil → Claves para Office y Drive) contra el API de sync del
   módulo 31. Nada de rclone, S3 directo ni credenciales de nube en
   hardware del cliente.

## Qué copia

Todo lo visible para el ADMINISTRADOR del tenant, con la estructura
idéntica al árbol del Drive:

```
1. Mis documentos/                  personales del admin
2. Reclamaciones/<radicado> <nombre>/...
3. Procesos judiciales/<radicado> <nombre>/1. Documentos | 2. Actuaciones Judiciales | 3. Actuaciones Prejudiciales
4. Carpetas compartidas/...
_Archivo del espejo/<fecha>/...     borrados del servidor (conservados)
_Espejo Fidel Drive/                manifiesto, log y temporales del agente
```

El espejo pide `?respaldo=1` al API: ignora los "estados excluidos" del
Drive (decisión owner: un respaldo a medias no es respaldo). El servidor
solo acepta ese modo a roles administrador/subadministrador
(`RESPALDO_SOLO_ADMIN` si no).

Fuera de alcance v1 (decisión owner): bases de datos (son del sistema, no
del cliente). Nota técnica: los documentos personales de OTROS usuarios no
viajan (el API de sync no los expone); ver PENDIENTES en el reporte de fase.

## Cómo funciona

- **Llenado inicial** reanudable: recorre el árbol paginado; si se corta a
  mitad, la próxima corrida continúa donde iba (manifiesto por expediente).
- **Delta continuo** cada `intervaloSegundos` (default 120 s) desde el
  cursor de `/sync/cambios`: nuevos/editados se bajan, renombrados se
  reubican sin re-bajar, tombstones se archivan.
- **Reconciliación completa** cada `reconciliacionDias` (default 7):
  verifica todo contra el servidor (tamaño+versión), repara archivos
  locales perdidos o dañados y archiva lo borrado con el agente apagado.
  Las carpetas compartidas solo se refrescan aquí (no viajan por el delta,
  mismo contrato de Mac/Windows).
- **Manifiesto** (`_Espejo Fidel Drive/manifiesto.json`, escritura atómica):
  docId → ruta/versión/tamaño. **Log legible** en `espejo.log` (rotación 5 MB).
- Clave revocada → mensaje claro y reintento cada 10 min (nunca crashea).

## Comandos

```
FidelEspejo conectar      asistente (o --subdominio --correo --clave --destino)
FidelEspejo ejecutar      bucle continuo (default sin comando)
FidelEspejo una-vez       un ciclo y salir (para cron)
FidelEspejo reconciliar   fuerza reconciliación completa ahora
FidelEspejo estado        resumen del manifiesto
```

Config en `~/.config/fidel-espejo/config.json` (o `--config` /
`FIDEL_ESPEJO_CONFIG`); en Unix queda 600. También por variables de entorno
(Docker): `FIDEL_ESPEJO_SUBDOMINIO/_CORREO/_CLAVE/_DESTINO`.

## Instalación por plataforma

- **Windows**: descomprimir el zip → `instalacion\instalar-windows.ps1`
  como admin (tarea programada como SYSTEM, arranca con el equipo).
- **Linux**: descomprimir el tar.gz → `sudo ./instalacion/instalar-linux.sh`
  (servicio systemd `fidel-espejo`).
- **NAS / Docker**: `instalacion/docker-compose.ejemplo.yml` con la imagen
  `fidel360/espejo-drive` (Synology Container Manager, QNAP Container
  Station, Unraid, TrueNAS).

Empaque de los tres artefactos + imagen: `scripts/empaquetar-espejo.sh`.

## E2E ejecutado (QA `pruebaqa`, 2026-08-17)

Llenado inicial 42/42 docs con estructura y md5 verificados; reanudación
tras SIGKILL y con manifiesto parcial (solo re-baja lo faltante); delta
crear/editar/renombrar/borrar (tombstone → `_Archivo del espejo/2026-08-17/`);
reconciliación repara perdido+corrupto y archiva borrados sin delta;
`respaldo=1` ignora estados excluidos (verificado con exclusión real y
revertida); 403 a rol colaborador; clave revocada manejada. Ciclo cerrado
con CERO claves vivas en QA.
