# 01 - Getting Started

## Requisitos

| Requisito | Versión mínima |
|---|---|
| PHP | 8.x |
| Composer | 2.x |
| MySQL | 5.7+ / MariaDB 10.3+ |
| Extensiones PHP | `gd`, `mbstring`, `pdo`, `pdo_mysql`, `openssl`, `curl` |

## Configuración inicial

### 1. ConfigEnv.php

Copiar el archivo de ejemplo y ajustar:

```bash
cp app/config/ConfigEnv.example.php app/config/ConfigEnv.php
```

Este archivo define la clase `ConfigEnv extends Config` con propiedades estáticas:

```php
class ConfigEnv extends Config
{
    static $appId              = 'KleePlanner2';
    static $tenantId           = 1;
    static $nombre_institucion = 'Mi Aplicación';
    static $LOGIN_AUTOMATICO   = false;
    static $LOGIN_MANUAL       = true;
    static $MODULES_OVERRIDE   = [];    // habilitar/deshabilitar módulos por tenant
    static $TENANTS            = [];    // configuración multi-tenant (opcional)
    static $cambio_rol         = false;
    static $correos_diarios    = 20;
    static $DB_CONNECTIONS     = [
        'klee' => [
            'name'     => 'klee',
            'driver'   => 'mysql',
            'dbname'   => 'klee_planner2',
            'host'     => 'localhost',
            'user'     => 'root',
            'password' => '',
            'instance' => '',
        ],
    ];
}
ConfigEnv::applyEnvironmentOverrides(); // aplica valores desde .env
```

### 2. Archivo .env

Crear `.env` en la raíz del proyecto. Referencia completa de variables:

#### Aplicación

| Variable | Descripción | Ejemplo |
|---|---|---|
| `APP_ID` | Identificador único de la aplicación | `KleePlanner2` |
| `APP_NAME` | Nombre visible | `KleePlanner2` |
| `APP_DEBUG` | Modo debug (`true`/`false`) | `false` |
| `TENANT_ID` | ID del tenant activo | `1` |
| `APP_COLOR` | Color del tema Metronic | `blue` |
| `APP_LOGO` | Logo principal (en `public/assets/`) | `logo_klee.png` |
| `APP_LOGO_LOGIN` | Logo del login | `logo_klee.png` |
| `APP_ICON` | Ícono de la app | `icon.png` |
| `APP_MASTER_KEY` | Llave maestra de acceso | `123` |
| `APP_NO_PAYMENT` | Deshabilitar pagos | `false` |
| `APP_VALUES_TO_UPPER` | Convertir valores a mayúsculas | `false` |
| `APP_PUBLISHED` | Aplicación publicada | `true` |
| `APP_TIMEZONE` | Zona horaria PHP | `America/Bogota` |
| `APP_LOCALE` | Locale general | `es_CO.utf8` |
| `APP_LOCALE_MONETARY` | Locale monetario | `es_CO.utf8` |
| `APP_LOCALE_TIME` | Locale de tiempo | `Spanish_Colombia` |

#### Seguridad y comportamiento

| Variable | Descripción | Ejemplo |
|---|---|---|
| `LOG_ACTIONS` | Registrar acciones de usuario | `true` |
| `LOG_MODULES` | Registrar actividad de módulos | `true` |
| `LOG_ACCESS` | Registrar accesos (login/logout) | `true` |
| `IP_BLOCKING` | Activar bloqueo por IP | `false` |
| `NO_COPY` | Deshabilitar copiar texto | `false` |
| `DROP_FILES` | Habilitar arrastrar archivos | `false` |
| `LOGIN_MANUAL` | Permitir login con usuario/contraseña | `true` |
| `LOGIN_AUTOMATICO` | Permitir login automático | `true` |
| `CSRF_STRICT` | Modo estricto de CSRF (rechaza POST sin token) | `false` |
| `CAMBIO_ROL` | Permitir cambio de rol en sesión | `true` |
| `CORREOS_DIARIOS` | Límite de correos diarios | `20` |

#### Base de datos

| Variable | Descripción | Ejemplo |
|---|---|---|
| `DB_DRIVER` | Driver PDO | `mysql` |
| `DB_HOST` | Host del servidor | `localhost` |
| `DB_NAME` | Nombre de la base de datos | `klee_planner2` |
| `DB_USER` | Usuario de BD | `root` |
| `DB_PASS` | Contraseña de BD | *(vacío)* |
| `DB_INSTANCE` | Instancia (SQL Server) | *(vacío)* |

#### Correo (SMTP)

| Variable | Descripción | Ejemplo |
|---|---|---|
| `MAIL_NAME` | Nombre del remitente | `Sistema` |
| `MAIL_HOST` | Host SMTP | `smtp.ejemplo.com` |
| `MAIL_PORT` | Puerto SMTP | `465` |
| `MAIL_USER` | Usuario SMTP | `usuario@ejemplo.com` |
| `MAIL_PASS` | Contraseña SMTP | `secret` |
| `MAIL_ENCRYPTION` | Tipo de cifrado (`tls`/`ssl`) | `tls` |
| `MAIL_HEADER` | HTML de encabezado de correos | `<p>SISTEMA DE MENSAJERIA</p>` |
| `MAIL_FOOTER` | HTML de pie de correos | `<p>No conteste este mensaje</p>` |

#### Multi-tenant (opcional)

| Variable | Descripción | Ejemplo |
|---|---|---|
| `KLEE_TENANT` | Fuerza un tenant específico por nombre | `academico` |

El selector de tenant busca en orden: (1) env `KLEE_TENANT`, (2) `?tenant=<key>` en URL, (3) coincidencia de `HTTP_HOST`, (4) fallback a `default`.

### 3. Instalar dependencias

```bash
composer install
```

### 4. Base de datos

```bash
php bin/migrate up
php bin/seed --group=demo   # local/demo (usuarios + datos de monitoreo demo)
# php bin/seed --group=klee # implementación inicial / producción (baseline mínimo)
```

### 5. Diagnóstico

```bash
php bin/doctor
```

Valida: archivos de configuración, variables DB/SMTP, extensiones PHP, permisos de directorios, classmap e integridad de BD.

## Estructura de directorios

```
├── app/
│   ├── config/          # Configuración de la aplicación
│   │   ├── Config.php           # Config base
│   │   ├── ConfigEnv.php        # Config local (no versionada)
│   │   ├── Modules.php          # Registro central de módulos
│   │   ├── Menu.php             # Generación de menú
│   │   └── ...
│   ├── controllers/     # Controladores MVC
│   ├── models/          # Modelos MVC
│   ├── views/           # Vistas organizadas por módulo
│   ├── layouts/         # Layouts (metronic, empty, etc.)
│   └── fonts/           # Fuentes para PDF
├── core/                # Framework base
│   ├── attributes/      # 26 tipos de atributo para modelos
│   ├── contracts/       # Interfaces y adapters legacy
│   ├── db/              # Wrappers de conexión BD
│   ├── helpers/         # Utilidades (Env, Debug, Output)
│   ├── middleware/       # Auth, CSRF, RateLimit
│   └── traits/          # HasCache, HasTenant, HasAuditLog, HasValidation
├── database/
│   ├── migrations/      # Migraciones de BD
│   └── seeders/         # Seeders de datos
├── bin/                 # CLI (make, migrate, seed, cache, doctor, smoke)
├── docs/                # Documentación
├── logs/                # Logs de la aplicación
├── public/              # Document root del servidor web
├── storage/             # Cache, archivos procesados
└── vendor/              # Dependencias Composer
```

## Servidor web

El document root debe apuntar a `public/`. La entrada principal es `public/index.php`.

Ejemplo de VirtualHost Apache:

```apache
<VirtualHost *:80>
    DocumentRoot "/ruta/al/proyecto/public"
    ServerName klee.local
    <Directory "/ruta/al/proyecto/public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

## Verificación mínima antes de desarrollar

1. `php bin/doctor` sin errores críticos.
2. `php bin/migrate status` accesible.
3. Login funcional en entorno local.

## Comandos frecuentes

```bash
php bin/make module NombreModulo    # Scaffolding de módulo completo
php bin/make seeder NombreSeeder    # Crear seeder individual
php bin/migrate up|down|status      # Gestión de migraciones
php bin/seed [Seeder] | --list      # Ejecutar seeders (demo por defecto)
php bin/seed --group=demo|klee      # Elegir grupo de semillas
php bin/cache clear|verify|status   # Gestión de caché/classmap
php bin/doctor [--strict]           # Diagnóstico de entorno
php bin/smoke [--json]              # Smoke tests HTTP
```