# Guía para actualizar SIIF2 sin romperlo

Qué hacer y qué no hacer al cambiar código, dependencias o el servidor.

## Antes de tocar nada

- Trabaja en una rama, no directo en `develop`, cuando el cambio sea grande o riesgoso.
- `git pull` primero. Si alguien más subió cambios, intégralos antes de empezar.
- Haz un respaldo de la base de datos antes de cualquier cambio que toque datos o estructura:
  `docker compose -f docker-compose.prod.yml exec db mariadb-dump -u"$DB_USERNAME" -p"$DB_PASSWORD" "$DB_DATABASE" > respaldo-$(date +%F).sql`

## Después de cada cambio, antes de subirlo

```bash
php artisan test          # 48 tests: seguridad, roles, login, token offline, rutas rotas, clases duplicadas
npm run build             # debe terminar sin errores
```

Si un test falla, el cambio rompió algo que antes funcionaba. No lo subas "para arreglarlo después".

Qué cubre cada grupo de tests:

| Test | Te avisa si... |
|---|---|
| `Seguridad/AccesoSinSesionTest` | una ruta con datos quedó accesible sin iniciar sesión |
| `Seguridad/ControlDeRolesTest` | un RFV puede entrar a algo que es solo de supervisores/gerentes |
| `Seguridad/LoginTest` | el login dejó de funcionar o dejó de bloquear intentos repetidos |
| `Offline/TokenOfflineTest` | el token offline dejó de ser solo para RFV o expone la clave |
| `Integridad/RutasTest` | una ruta apunta a un controlador o método que ya no existe |
| `Integridad/ClasesDuplicadasTest` | hay dos archivos declarando la misma clase (`Foo.php` y `foo.php`) |

## Código

**Hacer**

- Nombrar el archivo exactamente igual que la clase, con la misma mayúscula inicial (`GerencialController.php` para `class GerencialController`). En Windows/Mac da igual; en el servidor Linux no.
- Proteger toda ruta nueva. Dentro del grupo `auth` de `routes/web.php`, y con `->middleware('role:SIIF,GRT,SUP')` si no es para todos los roles. Ocultar un botón en el menú no protege nada: la ruta sigue respondiendo.
- Agregar la ruta nueva a `AccesoSinSesionTest::rutasProtegidas()`.
- Validar todo lo que llega del navegador (`$request->validate([...])`).
- Usar `TPersona::findOrFail($request->user()->idPersona)` cuando necesites `esRepresentante()`, `Clientes()`, etc. `Auth::user()` devuelve un `User`, que no tiene esos métodos.
- Filtrar siempre por `idFabricante` del usuario: una empresa nunca debe ver datos de otra.
- Si agregas un dato personal nuevo (un campo, un permiso del dispositivo), actualizar `resources/js/pages/Terminos.vue`.

**No hacer**

- No borrar un archivo "duplicado" sin comprobar cuál se usa (`grep -rn NombreDeLaClase app routes`).
- No renombrar columnas con buscar-y-reemplazar en todo el proyecto. Revisa cada resultado: ya produjo una clave repetida en un `create([...])`.
- No editar `public/sw.js` ni nada dentro de `public/build/`: se generan con `npm run build` y se sobrescriben.
- No usar APIs del navegador sin comprobar que existen (`'Notification' in window`). iOS no tiene varias, y un error ahí deja la app entera en negro.
- No dejar `dd()`, `dump()` ni `console.log()` con datos de usuarios.
- No subir `.env`, claves, ni volcados de base de datos con datos reales.
- No cambiar una migración que ya se ejecutó en producción: crea una nueva.

## Dependencias

Revisar una vez al mes, y de inmediato cuando haya un aviso de seguridad:

```bash
composer audit            # debe decir "No security vulnerability advisories found"
npm audit --omit=dev
```

Para actualizar:

```bash
composer update           # respeta composer.json: no cambia de versión mayor
php artisan test
npm run build
```

- Actualiza de a poco y prueba. No mezcles "actualizar dependencias" con "agregar una función" en el mismo commit.
- No cambies versiones mayores (Laravel 12 → 13, maatwebsite/excel 3 → 4) sin leer la guía de migración de ese paquete.
- Sube siempre `composer.lock` junto con el cambio.

**PHP:** el `Dockerfile` usa `php:8.3-fpm` y se niega a construir con una versión anterior a 8.3.36. Cuando PHP publique un parche de seguridad, sube ese número mínimo en `.docker/php/Dockerfile` y reconstruye con `--pull`.

## Desplegar en el servidor

```bash
git pull
docker compose -f docker-compose.prod.yml build --pull app    # --pull trae el PHP parcheado
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml exec app composer install --no-dev --optimize-autoloader
docker compose -f docker-compose.prod.yml exec app php artisan migrate --force
docker compose -f docker-compose.prod.yml exec app php artisan optimize
npm install && npm run build      # donde tengas Node; el resultado queda en public/build/
```

- `composer install` hay que correrlo a mano después de cada `git pull` que cambie `composer.lock`: el contenedor solo instala dependencias la primera vez (cuando `vendor/` no existe).
- Comprueba que no exista `public/hot`. Si existe, bórralo.
- Verifica después de desplegar:
  - `docker compose -f docker-compose.prod.yml exec app php -v` → 8.3.36 o superior.
  - `curl -s https://appweb.gestoriasif.com/up` → responde 200.
  - Entra con un usuario de cada rol y abre Toma de Pedidos y Nuevo Reporte.
  - `docker compose -f docker-compose.prod.yml logs --tail 50 app nginx` sin errores nuevos.

**No hacer en producción**

- No dejar `APP_DEBUG=true`.
- No correr `migrate:fresh`, `migrate:refresh` ni `db:wipe`: borran todos los datos.
- No correr `docker compose down -v`: la `-v` borra el volumen de la base de datos.
- No borrar los datos del navegador de un RFV que tenga pedidos en la Cola de Sincronización: se pierden.

## Prueba de carga

`tests/carga/carga.js` simula usuarios simultáneos con k6. Las instrucciones están al inicio del archivo. Úsala con un usuario de prueba y fuera del horario de trabajo.

## Si algo sale mal

1. `docker compose -f docker-compose.prod.yml logs --tail 100 app nginx` y `storage/logs/laravel.log`.
2. Volver a la versión anterior: `git log --oneline` para ver el commit previo, `git checkout <commit>`, y repetir los pasos de despliegue.
3. Si el problema es de datos, restaurar el respaldo que hiciste antes de empezar.
