---
name: modulo-respaldo-restauracion-php
description: >-
  Módulo reutilizable y seguro de Respaldo y Restauración para proyectos PHP y MySQL/MariaDB.
  Utilice esta skill cuando el usuario solicite implementar, migrar, adaptar o auditar funciones para
  descargar y restaurar copias de seguridad de la base de datos (SQL puro en streaming sin mysqldump ni exec),
  archivos multimedia o fotos (en ZIP) o una copia completa del sistema, con control de acceso para superadministradores,
  protección CSRF y registro en bitácora.
---

# Módulo de Respaldo y Restauración para PHP y MySQL

Esta skill proporciona la arquitectura completa, código fuente probado y procedimiento paso a paso para implementar un **Centro de Respaldo y Restauración** en cualquier aplicación web basada en PHP y MySQL/MariaDB.

---

## 🚀 Capacidades del Módulo

1. **Descarga de Base de Datos (.sql):**
   * Volcado completo en PHP puro (compatible con hosting compartido como BanaHosting, Hostinger, cPanel).
   * **No requiere** comandos de consola del sistema (`mysqldump`, `exec`, `shell_exec`).
   * Genera scripts SQL estándar compatibles con la opción "Importar" de phpMyAdmin.

2. **Descarga de Archivos / Fotos (.zip):**
   * Empaqueta recursivamente carpetas multimedia (fotos de perfil, carnets, documentos subidos).
   * Almacena imágenes sin recomprimir para máxima velocidad y ahorro de CPU.

3. **Respaldo Completo (.zip):**
   * Genera un paquete que contiene:
     * `base_datos/` (dump SQL completo).
     * `archivos/` (todas las imágenes y documentos adjuntos).
     * `configuraciones/` (archivos JSON de configuración).
     * `LEEME.txt` con instrucciones detalladas de restauración.

4. **Restauración de Base de Datos, Fotos o Completo:**
   * Motor de importación SQL por flujo (streaming) que procesa archivos grandes sin saturar memoria.
   * Manejo inteligente de strings con comillas, comentarios y `;` internos.
   * Blindaje contra ataques **Zip Slip** (Directory Traversal) y lista blanca estricta de extensiones seguras.

5. **Seguridad y Auditoría:**
   * Restringido exclusivamente al Administrador Principal o Superadmin.
   * Protección obligatoria con tokens CSRF.
   * Barrera de confirmación: exige escribir la palabra `RESTAURAR` antes de ejecutar.
   * Registro detallado de cada acción en la bitácora de auditoría.

---

## 📁 Archivos y Plantillas del Módulo

Las plantillas listas para copiar se encuentran en la carpeta `resources/` de esta skill:

| Archivo | Ubicación en el Proyecto | Propósito |
|---|---|---|
| [auth_helper.php](./resources/auth_helper.php) | `backend/auth_helper.php` | Valida si el usuario en sesión es Administrador Principal. |
| [respaldo_helper.php](./resources/respaldo_helper.php) | `backend/respaldo_helper.php` | Funciones de volcado SQL, parser streaming y manejo de ZIPs. |
| [generar_respaldo.php](./resources/generar_respaldo.php) | `backend/generar_respaldo.php` | Controlador que genera y transmite la descarga al navegador. |
| [procesar_restauracion.php](./resources/procesar_restauracion.php) | `backend/procesar_restauracion.php` | Controlador que recibe el archivo subido y ejecuta la restauración. |
| [respaldo.php](./resources/respaldo.php) | `respaldo.php` (raíz pública) | Interfaz visual con pestañas (Descargar / Restaurar), historial y confirmaciones SweetAlert2. |

Documentación complementaria:
* [Guía de Integración Paso a Paso](./references/guia_integracion.md)
* [Arquitectura Técnica y Seguridad](./references/arquitectura_seguridad.md)

---

## 🛠️ Procedimiento de Implementación en un Nuevo Proyecto

Sigue estos 5 pasos para instalar el módulo en cualquier proyecto PHP:

### Paso 1: Copiar los Archivos
Copia los 5 archivos desde `resources/` hacia las carpetas correspondientes de tu proyecto:
* `respaldo.php` a la raíz del sitio web.
* Los 4 archivos restantes a la carpeta `backend/` (o la carpeta de lógica del proyecto).

### Paso 2: Verificar la Conexión PDO
Asegúrate de que `backend/conexion.php` cree una variable `$pdo` conectada a MySQL con codificación `utf8mb4`:
```php
$pdo = new PDO("mysql:host=$host;dbname=$db;charset=utf8mb4", $user, $pass, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC
]);
```

### Paso 3: Ajustar la Regla del Superadministrador
Abre `backend/auth_helper.php` y define cómo tu sistema reconoce al Administrador Principal:
* **Por ID:** `$id === 1`
* **Por Rol:** `rol === 'superadmin'` o `rol === 'administrador'`

### Paso 4: Ajustar las Rutas de Carpetas Multimedia
En `backend/respaldo_helper.php`, `backend/generar_respaldo.php` y `backend/procesar_restauracion.php`:
* Reemplaza `img/fotos_personal` o `img/` por las rutas que use el proyecto (ej: `uploads/`, `archivos/`, `storage/`).

### Paso 5: Proteger la Navegación
En el menú de tu proyecto (navbar o sidebar), muestra el enlace al módulo únicamente para el administrador:
```php
<?php require_once 'backend/auth_helper.php'; ?>

<?php if (esAdminPrincipal($pdo)): ?>
  <a href="respaldo.php">💾 Respaldo y Restauración</a>
<?php endif; ?>
```

---

## 🧪 Verificación y Checklist de Pruebas

Antes de pasar a producción:
1. **Prueba de Descarga SQL:** Descargar la Base de Datos y verificar que el archivo `.sql` contenga sentencias `CREATE TABLE` e `INSERT INTO`.
2. **Prueba de Descarga ZIP:** Descargar Fotos y Respaldo Completo y confirmar que el `.zip` abra correctamente.
3. **Prueba de Acceso Restringido:** Iniciar sesión con un usuario estándar o secundario y confirmar que el botón no aparece y que acceder directamente a `respaldo.php` redirige con acceso denegado.
4. **Prueba de Restauración:** Subir una copia y verificar que exija escribir `RESTAURAR` y que aplique los cambios sin errores.
5. **Revisión de Bitácora:** Confirmar que tanto las descargas como las restauraciones queden registradas con hora, IP y usuario.
