Sistema de Conversaciones - Perfex AI

**Modelo:** `Conversations_model.php` | **Controlador:** `Chat.php`

---

1. **Crear**: El usuario inicia una conversación nueva → `Conversations_model::create()`
2. **Chatear**: Cada mensaje se guarda en `tblperfex_ai_messages` con role `user` o `model`
3. **Streaming**: Las respuestas se envían via SSE (Server-Sent Events) usando `Gemini_streaming`
4. **Tokens**: Cada respuesta actualiza `total_tokens` via `add_tokens()`
5. **Archivar**: El usuario puede archivar → `archive($id)` → `is_archived = 1`
6. **Expiración**: El cron exporta conversaciones archivadas antiguas a la KB y las elimina

| Columna | Tipo | Descripción |
|---------|------|-------------|
| `id` | INT AUTO_INCREMENT | PK |
| `title` | VARCHAR | Título (auto-generado de los primeros 50 chars) |
| `user_id` | INT | Staff user ID del propietario |
| `scope` | VARCHAR | Alcance: global, module, custom |
| `scoped_modules` | TEXT | JSON con módulos habilitados |
| `model` | VARCHAR | Modelo IA usado (gemini-2.0-flash, claude-sonnet, etc.) |
| `system_prompt` | TEXT | System prompt personalizado |
| `total_tokens` | INT | Total de tokens consumidos |
| `is_archived` | TINYINT | 0=activa, 1=archivada |
| `created_at` | DATETIME | Fecha de creación |
| `updated_at` | DATETIME | Última actualización |

| Columna | Tipo | Descripción |
|---------|------|-------------|
| `id` | INT AUTO_INCREMENT | PK |
| `conversation_id` | INT | FK → conversations (CASCADE on delete) |
| `role` | ENUM | user, model, function |
| `content` | LONGTEXT | Contenido del mensaje |
| `function_name` | VARCHAR(100) | Nombre de la función llamada (si aplica) |
| `function_args` | TEXT | Argumentos de la función (JSON) |
| `function_result` | LONGTEXT | Resultado de la función |
| `tokens_used` | INT | Tokens de este mensaje |
| `created_at` | DATETIME | Timestamp |

| Método | Descripción |
|--------|-------------|
| `get_all($user_id, $include_archived)` | Listar conversaciones (filtro ownership no-admin) |
| `get($id)` | Obtener conversación por ID |
| `create($data)` | Crear nueva conversación |
| `update($id, $data)` | Actualizar (title, scope, model, system_prompt, is_archived) |
| `add_tokens($id, $tokens)` | Incrementar tokens |
| `archive($id)` | Archivar (is_archived=1) |
| `restore($id)` | Restaurar (is_archived=0) |
| `delete($id)` | Eliminar (mensajes cascade via FK) |
| `get_expired($days)` | Obtener conversaciones archivadas más antiguas que X días |
| `export_to_markdown($id)` | Exportar conversación completa a formato Markdown |
| `get_stats($user_id)` | Estadísticas: total, tokens, activas |
| `get_recent($limit, $user_id)` | Conversaciones recientes activas |
| `search($query, $user_id)` | Buscar por título |
| `generate_title($message)` | Generar título desde primer mensaje (50 chars) |

- **Ownership**: Usuarios no-admin solo ven sus propias conversaciones
- **Permisos**: Requiere `perfex_ai:view` o `perfex_ai:chat`
- **CSRF**: Protegido por token CSRF de Perfex
- **Rate Limiting**: Configurable por requests/ventana y por IP

```
[Crear] → [Chatear] → [Archivar] → [Expirar (cron)] → [Exportar a KB] → [Eliminar]
```

- [Arquitectura](modulo_arquitectura.md) - Estructura general
- [Knowledge Base](modulo_knowledge_base.md) - Donde se exportan las conversaciones
- [Cron Jobs](modulo_cron_jobs.md) - Cron de expiración
- [Configuración](modulo_configuracion.md) - Setting `conversation_retention_days`