# Guía de Inicio Rápido: SLM Super Profile

> **Audiencia:** Desarrolladores y administradores que configuran SLM Framework por primera vez
>
> **Tiempo estimado:** 10-15 minutos
>
> **Prerrequisitos:** PHP 8.3+, Elasticsearch 7.9+

---

## 📖 ¿Qué es SLM Super?

**SLM Super** es el perfil administrativo fundamental del SLM Framework que proporciona acceso completo a los **módulos de configuración** del sistema:

| Módulo | Propósito | Acceso |
|--------|-----------|--------|
| `config.users` | Gestión de usuarios y permisos personalizados | CRUD completo |
| `config.profile` | Creación y edición de perfiles con ACL | CRUD completo |
| `config.modules` | Registro de nuevos módulos en el sistema | CRUD completo |

### ¿Por qué es importante?

- 🔑 **Punto de entrada:** Sin SLM Super, no puedes crear usuarios ni perfiles
- 🛠️ **Configuración central:** Todos los aspectos del sistema se gestionan desde aquí
- 🔐 **Máximo control:** Acceso completo a la configuración del framework
- 👥 **Gestión de equipo:** Permite crear usuarios para otros desarrolladores

---

## 🚀 Instalación en 3 Pasos

### Paso 1: Verificar Entorno

```bash
# Verificar PHP
php -v
# Debe mostrar: PHP 8.3.x o superior

# Verificar Elasticsearch
curl http://localhost:9200
# Debe retornar JSON con info de cluster
```

### Paso 2: Ejecutar Script de Setup

```bash
cd /ruta/a/tu/proyecto
php scripts/setup-slm-super.php
```

**Qué hace este script:**

1. ✅ Crea perfil **SLM Super** con ACL completo
2. ✅ Registra módulos: `home.main`, `config.users`, `config.profile`, `config.modules`
3. ✅ Crea estructura de menú (sidebar)
4. ✅ Crea usuario administrador con perfil SLM Super

**Salida esperada:**

```
╔════════════════════════════════════════════════════════════╗
║         SETUP: SLM Super Profile & Admin User             ║
╚════════════════════════════════════════════════════════════╝

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PASO 1: Crear Perfil SLM Super
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Creando perfil SLM Super...
   ✓ Perfil SLM Super creado (ID: abc123...)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PASO 2: Registrar Módulos de Configuración
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   📦 Registrando módulo: Inicio...
      ✓ Módulo registrado (ID: xyz456...)
   📦 Registrando módulo: Usuarios...
      ✓ Módulo registrado (ID: def789...)
   ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PASO 3: Crear Estructura de Menú
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   🔗 Creando menú simple: Inicio...
      ✓ Menú simple creado
   📂 Creando menú desplegable: Configuración...
      ✓ Menú desplegable creado
   ...

╔════════════════════════════════════════════════════════════╗
║                    ✓ SETUP COMPLETADO                      ║
╚════════════════════════════════════════════════════════════╝

   📧 Email: admin@example.com
   🔑 Password: admin123
```

### Paso 3: Primer Acceso

1. **Abrir navegador:**
   ```
   http://localhost
   ```

2. **Iniciar sesión:**
   - Email: `admin@example.com`
   - Password: `admin123`

3. **Verificar acceso:**
   - Debes ver el sidebar con:
     - **Menú** → Inicio
     - **Configuración** → Perfiles de usuario
     - **Configuración** → Usuarios
     - **Configuración** → Módulos

---

## 🎯 Flujo de Trabajo Típico

### 1. Crear Perfil para tu Aplicación

**Navegar a:** Configuración → Perfiles de usuario → Nuevo Perfil

**Ejemplo: Perfil "Editor"**

1. Nombre: `Editor`
2. Descripción: `Usuario con permisos de edición`
3. Vista por defecto: `home.main`
4. **ACL:** Seleccionar módulos y permisos
   - `home.main`: ✅ Leer
   - `blog.posts`: ✅ Leer, ✅ Crear, ✅ Actualizar
   - `blog.comments`: ✅ Leer, ✅ Actualizar

5. Guardar

### 2. Registrar Módulos de tu Aplicación

**Navegar a:** Configuración → Módulos → Nuevo Módulo

**Ejemplo: Módulo "Blog Posts"**

1. Nombre: `Blog Posts`
2. Directorio: `blog`
3. Archivo: `posts`
4. Folder: `blog.posts` (generado automáticamente)
5. Estado: `Activo`
6. Guardar

> **Nota:** El folder debe coincidir con la estructura de carpetas en `appweb/slm.framework/modules/blog/`

### 3. Crear Usuarios

**Navegar a:** Configuración → Usuarios → Nuevo Usuario

**Ejemplo: Usuario Editor**

1. **Tab "Información":**
   - Nombre: `Juan`
   - Apellido: `Pérez`
   - Email: `juan@example.com`
   - Teléfono: `+52 55 1234 5678`
   - Perfil: `Editor` (seleccionar del dropdown)

2. **Tab "Permisos Específicos":** (Opcional)
   - Marcar: ☑️ "Este usuario tiene permisos personalizados"
   - Configurar overrides si es necesario
   - Ejemplo: Dar acceso temporal a reportes

3. Guardar

**Sistema envía email con token para activar cuenta**

---

## 🔐 Sistema de Permisos

### Estructura de ACL

El ACL (Access Control List) define qué puede hacer un usuario:

```json
{
  "GROUP_ID": {
    "module.action": ["read", "create", "update", "delete"]
  }
}
```

**Ejemplo completo:**

```json
{
  "abc123-group-menu": {
    "home.main": ["read"],
    "blog.posts": ["read", "create", "update"],
    "blog.comments": ["read", "update", "delete"]
  }
}
```

### Niveles de Permisos

#### Nivel 1: Perfil (Base)

Todos los usuarios con el perfil heredan estos permisos:

```
Perfil "Editor" → blog.posts: [read, create, update]
```

#### Nivel 2: Usuario (Override)

Permisos específicos que sobrescriben el perfil:

```
Usuario "Juan" → blog.posts: [read]  ← Solo lectura (override)
Usuario "María" → reports.advanced: [read]  ← Permiso adicional
```

### Reglas de Fusión

| Caso | Perfil ACL | Usuario ACL | Resultado |
|------|------------|-------------|-----------|
| **Heredado** | `["read", "create"]` | `null` | `["read", "create"]` |
| **Override** | `["read", "create", "update"]` | `["read"]` | `["read"]` |
| **Revocado** | `["read", "create"]` | `[]` | `[]` (sin acceso) |
| **Adicional** | `null` | `["read"]` | `["read"]` |

---

## 📋 Casos de Uso Comunes

### Caso 1: Desarrollador Frontend

**Necesidad:** Acceso a módulos de UI, sin acceso a configuración

**Solución:**

1. Crear perfil "Frontend Developer"
2. ACL:
   ```json
   {
     "GROUP_MAIN": {
       "home.main": ["read"],
       "ui.components": ["read", "update"],
       "ui.styles": ["read", "update"]
     }
   }
   ```
3. Crear usuario con este perfil

### Caso 2: Consultor Temporal

**Necesidad:** Acceso limitado por 30 días a módulo de reportes

**Solución:**

1. Crear usuario con perfil "Viewer"
2. En tab "Permisos Específicos":
   - ☑️ Este usuario tiene permisos personalizados
   - Agregar: `reports.analytics` → [read]
3. Después de 30 días, desmarcar el checkbox de permisos personalizados

### Caso 3: Admin sin Acceso a Usuarios

**Necesidad:** Admin de contenido sin poder modificar usuarios

**Solución:**

1. Crear perfil "Content Admin" con acceso a todos los módulos de contenido
2. En tab "Permisos Específicos":
   - ☑️ Este usuario tiene permisos personalizados
   - `config.users` → [] (revocar)

---

## 🛠️ Comandos Útiles

### Verificar Perfil SLM Super

```bash
# Buscar perfil en Elasticsearch
curl -X GET "http://localhost:9200/slm-app-dev/_search" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must": [
          {"term": {"slm.type": "profile"}},
          {"term": {"name.keyword": "SLM Super"}}
        ]
      }
    }
  }'
```

### Listar Módulos Registrados

```bash
curl -X GET "http://localhost:9200/slm-app-dev/_search" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {"term": {"slm.type": "module"}},
    "size": 50
  }'
```

### Listar Usuarios con SLM Super

```bash
curl -X GET "http://localhost:9200/slm-app-dev/_search" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must": [
          {"term": {"slm.type": "user"}},
          {"term": {"profile.keyword": "PROFILE_ID_HERE"}}
        ]
      }
    }
  }'
```

### Reiniciar Setup (⚠️ Desarrollo solamente)

```bash
# CUIDADO: Esto elimina TODOS los datos
curl -X DELETE "http://localhost:9200/slm-app-dev"
curl -X PUT "http://localhost:9200/slm-app-dev"

# Volver a ejecutar setup
php scripts/setup-slm-super.php
```

---

## ❓ Preguntas Frecuentes

### ¿Puedo tener múltiples usuarios con SLM Super?

**Sí.** Puedes crear varios usuarios con perfil SLM Super. Útil para equipos con múltiples administradores.

```
Navegar a: Configuración → Usuarios → Nuevo Usuario
Perfil: SLM Super
```

### ¿Puedo modificar el perfil SLM Super?

**Sí, pero con cuidado.** Puedes agregar más permisos, pero NO remuevas acceso a módulos de configuración o no podrás gestionar el sistema.

### ¿Qué pasa si olvido la contraseña del admin?

**Resetear via Elasticsearch:**

```bash
# Actualizar password a "newpass123"
curl -X POST "http://localhost:9200/slm-app-dev/_update/USER_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "doc": {
      "password": "cc03e747a6afbbcbf8be7668acfebee5"
    }
  }'
```

> Hash MD5 de "newpass123" = cc03e747a6afbbcbf8be7668acfebee5

### ¿Cómo elimino el perfil SLM Super?

**No debes hacerlo.** Sin SLM Super, pierdes acceso a módulos de configuración. Si necesitas crear un nuevo sistema, ejecuta el script setup nuevamente.

### ¿El script setup es idempotente?

**Sí.** Puedes ejecutarlo múltiples veces. Si ya existen los recursos, los detecta y los salta.

---

## 🔍 Troubleshooting

### Error: "Profile SLM Super already exists"

**Causa:** Ya ejecutaste el script antes

**Solución:** Esto es normal. El script continuará y verificará los otros componentes.

### Error: "Connection refused" a Elasticsearch

**Causa:** Elasticsearch no está corriendo o configuración incorrecta

**Solución:**

```bash
# Verificar Elasticsearch
curl http://localhost:9200

# Si no responde, iniciar Elasticsearch
# Docker:
docker-compose up -d elasticsearch

# Local:
./elasticsearch-7.x/bin/elasticsearch
```

### Error: "Module not found" al crear perfil

**Causa:** Los módulos no están registrados

**Solución:**

```bash
# Re-ejecutar setup para registrar módulos
php scripts/setup-slm-super.php
```

### No aparece menú de Configuración después del login

**Causa:** Usuario no tiene perfil SLM Super asignado

**Solución:**

1. Verificar que el perfil del usuario sea correcto
2. Cerrar sesión y volver a iniciar
3. Verificar ACL del perfil en Elasticsearch

### Usuario creado no puede hacer login

**Causa:** Email no confirmado o usuario inactivo

**Solución:**

```bash
# Activar usuario manualmente
curl -X POST "http://localhost:9200/slm-app-dev/_update/USER_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "doc": {
      "email_confirmed": true,
      "status": "active"
    }
  }'
```

---

## 📚 Documentación Relacionada

- 📘 [Guía Completa de Módulos](05-modules-complete-guide.md) - Cómo crear módulos, menús y perfiles
- 🔐 [Permisos Específicos de Usuario](06-user-specific-permissions.md) - Sistema de permisos de dos niveles
- 📖 [Profile, User, Module & Menu](03-profile-user-module-menu.md) - Ejemplos de Elasticsearch
- 🏗️ [Arquitectura del Sistema](10-ARCHITECTURE.md) - Diseño interno del framework
- 🚀 [Getting Started](01-getting-started.md) - Configuración inicial completa

---

## 🎓 Próximos Pasos

Después de configurar SLM Super:

1. ✅ **Crear perfiles específicos** para tu aplicación
2. ✅ **Registrar módulos** de tu proyecto
3. ✅ **Crear usuarios** para tu equipo
4. ✅ **Configurar menú** según necesidades
5. ✅ **Implementar módulos** con CRUD

**Recursos adicionales:**

- Ver `scripts/README.md` para scripts de setup adicionales
- Ver `README.md` para documentación completa
- Revisar `docs/es_MX/` para guías detalladas

---

**¿Preguntas o problemas?**

Revisa la sección de Troubleshooting o crea un issue en el repositorio.

---

**Última actualización:** 2026-01-22
