# 05 - Operación y Diagnóstico

## Doctor de entorno

```bash
php bin/doctor           # Diagnóstico estándar
php bin/doctor --strict  # Con validaciones adicionales
```

### Qué valida

| Verificación | Detalle |
|---|---|
| Archivos de config | `Config.php`, `ConfigEnv.php`, `.env` existen y son legibles |
| Variables de BD | `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS` definidas |
| Variables SMTP | `MAIL_HOST`, `MAIL_USER`, `MAIL_PASS` definidas |
| Versión PHP | >= 8.0 |
| Extensiones PHP | `gd`, `mbstring`, `pdo`, `pdo_mysql`, `openssl` cargadas |
| Permisos de escritura | `storage/`, `logs/`, `files/` son escribibles |
| Classmap | Integridad del autoload fallback verificada |
| Conexión BD | Conexión PDO exitosa a la base de datos |

### Interpretación de salida

```
[ok]  Config.php exists
[ok]  ConfigEnv.php exists
[ok]  .env loaded
[ok]  DB variables set
[ok]  SMTP variables set
[ok]  PHP 8.2.12
[ok]  Extension: gd
...
[ok]  Directory writable: storage/
[ok]  Classmap integrity
[ok]  Database connection

errors=0 warnings=0
```

- **0 errors**: listo para desarrollo/producción.
- **warnings**: no bloqueantes pero deben atenderse.
- **errors**: el sistema no funcionará correctamente.

## Cache y classmap

```bash
php bin/cache status    # Muestra estado actual del cache
php bin/cache verify    # Verifica integridad del classmap
php bin/cache clear     # Limpia cache (regenera classmap si aplica)
```

**Flujo recomendado:**

1. `php bin/cache verify` — verificar si hay inconsistencias.
2. Solo si hay problemas: `php bin/cache clear` — limpiar y regenerar.
3. `php bin/cache status` — confirmar estado limpio.

## Smoke tests

```bash
php bin/smoke           # Ejecutar tests HTTP
php bin/smoke --json    # Salida en formato JSON
```

### Variables de entorno para smoke tests

| Variable | Descripción | Default |
|---|---|---|
| `SMOKE_BASE_URL` | URL base de la aplicación | `http://localhost` |
| `SMOKE_USER` | Usuario para login | *(vacío)* |
| `SMOKE_PASS` | Contraseña para login | *(vacío)* |
| `SMOKE_TIMEOUT` | Timeout en segundos | `30` |
| `SMOKE_JSON` | Forzar salida JSON | `false` |
| `SMOKE_JSON_FILE` | Guardar resultado en archivo | *(vacío)* |

### Qué verifica

- Conectividad HTTP al entry point.
- Login funcional (si se proporcionan credenciales).
- Endpoints principales accesibles.
- Códigos de respuesta esperados.

## Cola de correos

```bash
php bin/process-mail-queue              # Procesar hasta 100 correos pendientes
php bin/process-mail-queue --limit=25   # Procesar lote más pequeño
php bin/process-mail-queue --dry-run    # Validar payloads sin enviar
```

### Comportamiento

- Lee `storage/pendientes/mail_queue.jsonl`.
- Envía cada correo con `MailService::send()`.
- Mueve resultados a `storage/pendientes/processed/`:
	- `mail_sent_YYYYMMDD.jsonl`
	- `mail_failed_YYYYMMDD.jsonl`
	- `mail_invalid_YYYYMMDD.jsonl`
- Usa lock exclusivo para evitar ejecuciones concurrentes sobre la misma cola.

### Programación recomendada

```bash
*/5 * * * * php /ruta/proyecto/bin/process-mail-queue
```

## Logs

Los logs se guardan en `logs/`. El archivo `logs/viewer.html` permite visualizarlos en el navegador.

### Tipos de log

| Componente | Descripción |
|---|---|
| `LoggerManager` | Interfaz unificada de logging |
| `LoggerConfig` | Configuración de niveles y destinos |
| `LogsConsole` | Logs de depuración en consola del navegador |
| `Logger` | Logger base del framework |

### Activación por .env

```dotenv
LOG_ACTIONS=true   # Registrar acciones de usuario
LOG_MODULES=true   # Registrar CRUD en módulos (HasAuditLog)
LOG_ACCESS=true    # Registrar login/logout
```

## Runbook de incidencias

| Paso | Comando | Propósito |
|---|---|---|
| 1 | `php bin/doctor` | Diagnosticar estado general |
| 2 | `php bin/cache verify` | Verificar integridad de classmap |
| 3 | Revisar `logs/` | Buscar errores recientes |
| 4 | Verificar `.env` | Credenciales BD y SMTP correctas |
| 5 | `php bin/migrate status` | Verificar migraciones pendientes |
| 6 | `php bin/smoke` | Verificar conectividad HTTP (si aplica) |

## Comandos CLI — Referencia rápida

```bash
# Scaffolding
php bin/make module NombreModulo [--basic] [--no-migration] [--category=X]
php bin/make seeder NombreSeeder

# Base de datos
php bin/migrate up        # Ejecutar migraciones pendientes
php bin/migrate down      # Revertir última migración
php bin/migrate status    # Ver estado de migraciones

# Seeders
php bin/seed              # Ejecutar grupo demo (default)
php bin/seed --group=demo # Ejecutar dataset demo
php bin/seed --group=klee # Ejecutar baseline mínimo de implementación
php bin/seed NombreSeeder # Ejecutar uno específico
php bin/seed --list       # Listar disponibles por grupo actual

# Cache
php bin/cache status
php bin/cache verify
php bin/cache clear

# Diagnóstico
php bin/doctor [--strict]
php bin/smoke [--json]
php bin/process-mail-queue [--limit=100] [--dry-run]
```