# CLAUDE.md — Guía rápida del proyecto `evaluacion`

Sistema de **Evaluación y Gestión Docente** (Klee Software) para la Universidad Compensar.
PHP sobre un **framework MVC propio** (`core/`), MySQL, plantilla Metronic 8.

> 📚 **La base de conocimiento completa está en [`docs/`](docs/00-indice.md).**
> Consúltala antes de asumir cómo funciona algo: casi nada sigue las convenciones de Laravel/Symfony.

| Necesitas… | Lee |
|---|---|
| Contexto de negocio y roles | [docs/01-vision-general.md](docs/01-vision-general.md) |
| Cómo funciona el framework, el ORM y el DSL `criteria` | [docs/02-arquitectura.md](docs/02-arquitectura.md) |
| Tablas, vistas SQL y catálogos | [docs/03-modelo-datos.md](docs/03-modelo-datos.md) |
| Dónde está el código de un módulo | [docs/04-modulos.md](docs/04-modulos.md) |
| Evaluación, consolidación, IA, sincronización, ODS | [docs/05-flujos-clave.md](docs/05-flujos-clave.md) |
| Autenticación, permisos y riesgos | [docs/06-seguridad-permisos.md](docs/06-seguridad-permisos.md) |
| Academusoft, Ollama, Microsoft SSO, correo, PDF | [docs/07-integraciones.md](docs/07-integraciones.md) |
| Escribir código nuevo (recetas + trampas) | [docs/08-guia-desarrollo.md](docs/08-guia-desarrollo.md) |
| Configurar, desplegar, deuda técnica | [docs/09-operacion-deuda-tecnica.md](docs/09-operacion-deuda-tecnica.md) |

## Lo mínimo imprescindible

**Enrutamiento**: no hay URLs amigables. `?c=<modulo>&a=<accion>`.
`public/index.php` = portal público · `public/admin/index.php` = backoffice.
Todo arranca en `core/AutoLoad.php`.

**Una acción existe** solo si está declarada en `loadAccessControl()` del controlador
(`'*'` pública, `'@'` requiere sesión + permiso) **y** existe el método `<accion>Action()`.
Si falta cualquiera de las dos cosas, hay redirección silenciosa al login.

**ORM**: los modelos declaran columnas en `getOptionsAttributes()`. Consultas con el array
`criteria` (`WHERE`/`GROUP_BY`/`ORDER_BY`/`LIMIT`). El tercer parámetro de los `get*` son los
**filtros de sesión** (`Periodo`, `Estado`): pasa `array()` para desactivarlos.

**`save()` vs `saveOnly()`**: `save()` repuebla el modelo desde `$_POST`; `saveOnly()` no.
En procesos batch usa siempre `saveOnly()`.

**Periodo**: eje temporal de todo. `PeriodosModel::getSesionId()`.

**Menú y permisos** quedan cacheados en sesión al iniciar sesión: tras cambiarlos hay que
volver a entrar.

## Comandos

```bash
composer install
php -S localhost:8000 -t public     # portal / y backoffice /admin/
```

No hay tests, linter ni migraciones. El esquema de BD no está versionado: si tu cambio
necesita DDL, documéntalo en el PR.

## Antes de tocar código

- No commitear `app/config/ConfigEnv.php`, `app/config/DataEnv.php`, `vendor/`,
  `public/metronic*/`, `files/`, `.idea/`.
- Rama principal `master`; se trabaja en ramas nominales. Commits en español.
- La capa de datos **no usa sentencias preparadas**: al añadir consultas, no interpoles entrada
  de usuario en `criteria` sin sanear. Ver [docs/06](docs/06-seguridad-permisos.md#61-inyección-sql).
- **No hay transacciones**: diseña los procesos masivos para ser idempotentes.