# Actualización segura en cPanel — versión 3.0

Estas instrucciones son para una instalación existente del Sistema de Notas U. E. N. “Alberto Smith”. La actualización crea las estructuras nuevas automáticamente y conserva la información anterior.

## 1. Hacer respaldo antes de reemplazar archivos

Desde Terminal, dentro de la aplicación:

```bash
cd ~/notas_alberto_smith
python scripts/backup_cpanel.py
```

Además, exporte la base MySQL desde **phpMyAdmin** o genere una copia del archivo SQLite ubicado en `data/`, según la configuración usada. Descargue también una copia completa de la carpeta actual.

## 2. Archivos que deben conservarse

No elimine ni reemplace estos elementos de producción:

- `cpanel.env`
- `.env`, cuando exista
- carpeta `data/`
- carpeta `backups/`
- archivos de registro propios del alojamiento

El ZIP de esta entrega no contiene una base de producción; la carpeta `data/` solo contiene un marcador vacío.

## 3. Subir la versión 3

1. Descomprima el ZIP nuevo en una carpeta temporal de cPanel.
2. Copie sus archivos sobre `~/notas_alberto_smith/` y acepte reemplazar el código anterior.
3. Verifique nuevamente que `cpanel.env`, `data/` y `backups/` sigan presentes.
4. No copie el respaldo JSON como base de datos de producción. La actualización compara la semilla validada con la base existente y agrega únicamente las cédulas seguras que todavía no estén registradas; no modifica estudiantes existentes.

## 4. Actualizar dependencias

Active el entorno virtual que cPanel muestra en **Setup Python App** y ejecute:

```bash
cd ~/notas_alberto_smith
pip install -r requirements.txt
```

## 5. Ejecutar diagnóstico y reiniciar

```bash
cd ~/notas_alberto_smith
python scripts/diagnostico_cpanel.py
touch tmp/restart.txt
```

También puede usar el botón **Restart** de Setup Python App.

Al iniciar, el sistema:

- crea las tablas de años, matrículas, promociones y actas del Artículo 112;
- agrega la referencia de año escolar a evaluaciones y planificaciones anteriores;
- asigna los registros históricos sin año al año activo inicial;
- incorpora de forma idempotente los 27 estudiantes validados que falten, sin sobrescribir registros existentes;
- adapta la restricción de planificaciones para separar cada año escolar.

La migración es aditiva y no borra los registros existentes. En SQLite se reconstruye únicamente la tabla de planificaciones para actualizar su restricción única, por lo que el respaldo previo es obligatorio.

## 6. Verificación posterior

Abra:

```text
https://SU-SUBDOMINIO/health
```

Debe responder con `"status":"ok"`.

Luego revise, en este orden:

1. **Años escolares**: confirme el año activo y sus fechas.
2. **Secciones**: confirme la cantidad de estudiantes por sección.
3. **Períodos**: ajuste las ventanas del año activo.
4. **Reportes**: genere una prueba por lapso y otra anual.
5. **Promoción**: cree primero el año siguiente y pruebe con un solo estudiante antes de procesar un lote completo.
6. **Artículo 112**: abra una evaluación activada y compruebe la impresión del acta institucional.

## 7. Recomendación para la primera promoción real

- Crear el próximo año escolar en estado de planificación.
- Copiar las secciones del año actual.
- Revisar o crear las secciones necesarias.
- Promover primero una sección piloto.
- Verificar las matrículas del año de destino.
- Continuar con las demás secciones.
- Activar el nuevo año solo cuando su estructura y matrícula hayan sido revisadas.
- Cerrar el año anterior después de confirmar los reportes finales y respaldos.

## 8. Inconsistencia del respaldo

Dos registros no se incorporaron porque comparten la misma cédula. Consulte `VALIDACION_RESPALDO_SIAPA_V3.md` y verifique los documentos institucionales antes de crearlos manualmente.