# MERLOT v5.69 conectado a MySQL local — instalación

## Qué entrega el paquete

- `web/`: interfaz de **MERLOT v5.69**, con lectura y guardado en MySQL mediante la API. Su lógica visual y de planificación parte del ZIP proporcionado.
- `sql/001_schema.sql`: esquema MySQL, con tablas relacionales consultables y documento de estado completo con revisión.
- `backend/`: PHP 8.1+ (`pdo_mysql`), API, login por contraseña, token CSRF, control de versión y transacciones.
- `scripts/import_backup.php`: importación inicial **no destructiva** de un respaldo MERLOT.
- `scripts/check_db.php`: verificación de las tablas.
- `respaldo/`: copia del respaldo recibido **29/10/2026** como referencia; NO se importa automáticamente, ya que podría haber datos posteriores.

## Requisitos

PHP 8.1+ con PDO MySQL, MySQL 8.0+ o MariaDB 10.6+, Apache/PHP o servidor PHP local. Ejemplos para Linux/Mac/Windows con herramientas equivalentes. **Usar una computadora de pruebas y una base separada de producción**.

## Instalación paso a paso

1. Instalar MySQL y PHP. Crear la base y usuario de aplicación (en consola MySQL con usuario administrador):

```sql
CREATE DATABASE merlot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'merlot_app'@'localhost' IDENTIFIED BY 'CAMBIAR_POR_PASSWORD_FUERTE';
GRANT SELECT, INSERT, UPDATE, DELETE ON merlot.* TO 'merlot_app'@'localhost';
```

**Nota:** si se usa `127.0.0.1`, configurar el usuario MySQL que corresponda a TCP (`merlot_app`@`127.0.0.1`) según la instalación. El usuario empleado para crear el esquema requiere permisos DDL; no usar `merlot_app` para ello.

2. Crear el esquema con usuario administrador:

```bash
mysql -u root -p merlot < sql/001_schema.sql
```

3. Copiar `backend/config.example.php` a `backend/config.local.php` y completar conexión. Generar contraseña de acceso a la web (hash):

```bash
php -r "echo password_hash('UNA_CONTRASEÑA_LARGA_Y_UNICA', PASSWORD_DEFAULT), PHP_EOL;"
```

Pegar el hash en `app_password_hash`. **No dejar el texto `REEMPLAZAR_HASH_PASSWORD`.** No guardar el archivo `config.local.php` en un repositorio público.

4. **Elegir el JSON más reciente que realmente sea el vigente** en el sistema de la fábrica. Antes de importarlo, preservar una copia de ese JSON y una copia completa de la nueva base si ya hay datos. Para la primera importación:

```bash
php scripts/import_backup.php /ruta/al/MERLOT_Produccion_Respaldo_MAS_RECIENTE.json
php scripts/check_db.php
```

El importador **se niega** a modificar una base ya inicializada. El JSON incluido del 29/10 es solo referencia; puede estar desactualizado frente al navegador de ustedes.

5. Iniciar servidor local desde esta carpeta (solo para pruebas en una computadora):

```bash
php -S 127.0.0.1:8080 router.php
```

El `router.php` bloquea el acceso web a credenciales, scripts, SQL y respaldos. Abrir `http://127.0.0.1:8080/backend/login.php`, iniciar sesión y trabajar en `web/index.html`. No abrir `index.html` mediante doble clic / `file://`.

6. Probar con una copia de la base: editar una asignación de Carga, verificar estado **Guardado en MySQL**, actualizar la página, confirmar persistencia y consultar Planificación semanal. También probar un cambio en oportunidad comercial. Exportar JSON de seguridad.

## Preservación de datos y actualizaciones

- `merlot_state` contiene la estructura JSON completa y es la fuente oficial: proyectos, actividades, historial, responsables, clientes y campos futuros.
- Tablas `projects`, `activities`, `clients`, `prospects`, `opportunities`, `sales_designs` se sincronizan **en la misma transacción** para consultas SQL. Los campos completos se conservan en `details` JSON.
- Las futuras versiones de la interfaz deben seguir llamando a `backend/api.php` y **no reemplazar** la BD. Cambios de esquema se harán con migraciones versionadas (`sql/002_*.sql`, etc.).
- Al guardar, se usa revisión optimista. Si otro usuario guardó antes, el segundo recibe un conflicto; debe conciliar los cambios, no sobrescribir. **Este piloto no implementa edición multiusuario simultánea con fusión automática.**
- La API bloquea operaciones si no se inició sesión y exige CSRF para escritura. En esta fase hay **una contraseña compartida**, no roles verificables por usuario. Antes de exponer a internet implementar cuentas individuales, permisos del servidor, HTTPS, controles de sesión y auditoría por usuario.
- La cola de guardado muestra *Guardando* / *Guardado* / *NO GUARDADO*. Si falla la red, no afirmar que el cambio se conservó. El sistema puede exportar JSON como recuperación, pero no debe reemplazar MySQL.
- El módulo separado `portal_movil.html` **conserva su almacenamiento local original y NO está migrado al backend**. Requiere una siguiente fase antes de utilizarse con datos reales compartidos.
- Las utilidades demo/restauración JSON desde la pantalla se deshabilitan para evitar reemplazos accidentales. La importación controlada se hace por consola.

## Respaldos MySQL

Programar copias diarias con `mysqldump` o respaldo consistente administrado. Ejemplo:

```bash
mysqldump --single-transaction -u root -p merlot > merlot_backup_YYYY-MM-DD.sql
```

No guardar copias con contraseñas expuestas. Probar restauración en otra BD antes de depender de ella. **Nunca** ejecutar `DROP DATABASE`, `TRUNCATE` o una importación que reemplace registros reales durante actualizaciones.

## Limitaciones de validación de este paquete

Se realizaron comprobaciones de sintaxis, consistencia de estructura y empaquetado. En este entorno no hay servidor MySQL activo para una prueba de integración real; los programadores deben realizarla en su equipo antes de operar con datos reales. La v5.69 original contenía funciones `localStorage` de soporte; se conserva parte del código legado para compatibilidad, pero la carga inicial y los guardados principales apuntan a MySQL. No se debe considerar el programa endurecido para producción pública.