# Guía de Inicio con SLM Framework

Esta guía te ayudará a configurar y ejecutar tu primera aplicación SLM Framework.

## Prerrequisitos

- PHP 8.3 o superior
- Composer
- Docker y Docker Compose (recomendado)
- Un editor de texto o IDE

## Instalación

### Paso 1: Clonar o Descargar

```bash
git clone <url-repositorio> mi-proyecto
cd mi-proyecto
```

### Paso 2: Configuración del Entorno

Copia el archivo de entorno de ejemplo:

```bash
cp .env.example appweb/.env
```

Edita `appweb/.env` con tu configuración:

```env
# Aplicación
APP_NAME="Mi Aplicación"
APP_SHORT_NAME=MIAPP
APP_DEBUG=true
APP_URL=http://localhost

# Elasticsearch (Desarrollo)
DEV_ES_SERVER=http://elasticsearch:9200
DEV_ES_INDEX=mi-app-dev
DEV_ES_INDEX_LOG=mi-app-dev-log

# Email (MailHog para pruebas)
MAIL_HOST=mailhog
MAIL_PORT=1025

# Branding
LOGO_URL=/assets/images/logo.png
```

### Paso 3: Instalar Dependencias PHP

```bash
cd appweb/slm.framework/system
composer install
```

### Paso 4: Iniciar Servicios Docker

```bash
# Desde la raíz del proyecto
docker-compose up --build -d
```
o

```bash
# Desde la raíz del proyecto
docker compose  --project-name <appname> up --build -d
```

Esto inicia:
- **app** (PHP/Apache) en el puerto 80
- **elasticsearch** en el puerto 9200
- **kibana** en el puerto 5601
- **mailhog** en el puerto 8025

### Paso 5: Inicializar Elasticsearch

Crea los índices requeridos:

```bash
# Crear índice principal
curl -X PUT "http://localhost:9200/mi-app-dev" -H "Content-Type: application/json" -d '{
  "mappings": {
    "properties": {
      "slm": {
        "properties": {
          "type": { "type": "keyword" },
          "timestamp": { "type": "date", "format": "epoch_millis" }
        }
      },
      "name": { "type": "text", "fields": { "keyword": { "type": "keyword" } } },
      "email": { "type": "text", "fields": { "keyword": { "type": "keyword" } } },
      "status": { "type": "keyword" }
    }
  }
}'

# Crear índice de logs
curl -X PUT "http://localhost:9200/mi-app-dev-log" -H "Content-Type: application/json" -d '{
  "mappings": {
    "properties": {
      "log_type": { "type": "keyword" },
      "module": { "type": "keyword" },
      "script": { "type": "keyword" },
      "slm": {
        "properties": {
          "type": { "type": "keyword" },
          "timestamp": { "type": "date", "format": "epoch_millis" }
        }
      }
    }
  }
}'
```

### Paso 6: Crear Datos Iniciales

Crear un perfil:

```bash
curl -X POST "http://localhost:9200/mi-app-dev/_doc" -H "Content-Type: application/json" -d '{
  "name": "Administrador",
  "description": "Acceso completo",
  "status": "active",
  "acl": "{\"home\":{\"home.main\":[\"read\"]},\"example\":{\"example.items\":[\"read\",\"create\",\"update\",\"delete\"]}}",
  "slm": {
    "type": "profile",
    "timestamp": '$(date +%s000)'
  }
}'
```

Anota el ID del perfil de la respuesta, luego crea un usuario:

```bash
curl -X POST "http://localhost:9200/mi-app-dev/_doc" -H "Content-Type: application/json" -d '{
  "name": "Usuario Admin",
  "email": "admin@ejemplo.com",
  "status": "active",
  "profile": "<ID_DEL_PERFIL>",
  "slm": {
    "type": "user",
    "timestamp": '$(date +%s000)'
  }
}'
```

### Paso 7: Acceder a la Aplicación

Abre http://localhost en tu navegador.

1. Ingresa `admin@ejemplo.com`
2. Revisa MailHog en http://localhost:8025 para el código de seguridad
3. Ingresa el código de 6 dígitos
4. ¡Ya estás conectado!

## Estructura del Proyecto

```
mi-proyecto/
├── appweb/
│   ├── .env                    # Tu configuración
│   ├── public/
│   │   └── index.slm           # Punto de entrada
│   └── slm.framework/
│       ├── system/             # Core del framework
│       ├── security/           # Páginas de login
│       └── modules/            # Tus módulos
│           ├── home/           # Dashboard
│           └── example/        # Ejemplo CRUD
└── docs/                       # Documentación
```

## Creando tu Primer Módulo

### 1. Crear Directorio del Módulo

```bash
mkdir -p appweb/slm.framework/modules/mimodulo
```

### 2. Crear Archivo de Vista

Crear `view.list.slm`:

```php
<?php
/**
 * Mi Módulo - Vista de Lista
 */
?>
<div class="container-fluid">
    <h1>Mi Módulo</h1>
    <p>Hola, <?= htmlspecialchars(_SLM::$session['user']['name']) ?>!</p>
</div>
```

### 3. Agregar al Menú

Edita `slm.framework/system/slm_api.slm` y agrega a `getMenu()`:

```php
if ($getAll || _SLM::getSecurityAccess("mimodulo.list", $acl)) {
    $module["folder"] = "mimodulo.list";
    $module["name"] = "Mi Módulo";
    $module["visible"] = true;
    $section["modules"][] = $module;
    unset($module);
}
```

### 4. Agregar Permisos

Actualiza el ACL del perfil de usuario para incluir:

```json
{
  "mimodulo": {
    "mimodulo.list": ["read"]
  }
}
```

### 5. Acceder a tu Módulo

Navega a `http://localhost/?v=mimodulo.list`

## Flujo de Trabajo de Desarrollo

1. Haz cambios en los archivos `.slm`
2. Refresca el navegador (no requiere compilación)
3. Revisa la consola del navegador para errores de JavaScript
4. Revisa el log de errores PHP: `docker-compose logs app`
5. Revisa Elasticsearch: http://localhost:5601 (Kibana)
6. Revisa emails: http://localhost:8025 (MailHog)

## Solución de Problemas

### "Session index not found"

El índice de sesiones no ha sido creado. Se crea automáticamente en el primer acceso, pero puede que necesites refrescar.

### "Unable to login"

1. Verifica que el usuario existe en Elasticsearch
2. Verifica que el usuario tiene un perfil asignado
3. Verifica que el status del usuario es "active"

### Error de conexión a Elasticsearch

```bash
# Verificar si ES está corriendo
curl http://localhost:9200

# Ver logs de Docker
docker-compose logs elasticsearch
```

### Email no recibido

1. Revisa MailHog en http://localhost:8025
2. Verifica MAIL_HOST y MAIL_PORT en .env

## Próximos Pasos

- Lee [Desarrollo de Módulos](04-modules.md) para crear módulos complejos
- Lee [Guía de Elasticsearch](07-elasticsearch.md) para operaciones de datos
- Lee [Guía de Seguridad](08-security.md) para autenticación y ACL
- Revisa el módulo `example/items` para un ejemplo CRUD completo
