# AI Chat Agent (Agente Financiero)

## Responsabilidad
Proveer un asistente conversacional conectado a los datos financieros reales del dashboard. El usuario pregunta en español (o inglés), y el agente responde con análisis basado en datos de QBO, CRM y comisiones.

## Estado actual (Mockup)
El chat en `dashboard.html` es 100% simulado:
- Respuestas hardcodeadas con setTimeout (1.8-2.8s delay)
- Simula análisis de margen de Zona Sur, comisiones de instalador C. Méndez
- No hay backend real

## Fase de implementación
**Fase 3** — Este agente NO es parte del MVP (Fase 1).

## Fase 1 (MVP)
- El chat panel se mantiene visible en el dashboard pero deshabilitado o con mensaje:
  "El Agente Financiero estará disponible próximamente. Usa el drill-down para explorar transacciones."
- O alternativamente, mantener las respuestas simuladas del mockup como demo

## Fase 3 — Arquitectura propuesta

### Flujo
```
Usuario escribe: "¿Por qué bajó el margen en Zona Sur?"
  │
  ├─ 1. Frontend envía POST /api/chat { message, conversationId }
  │
  ├─ 2. Backend construye contexto:
  │     - Últimos 3 mensajes de la conversación
  │     - Schema de cached_transactions (columnas disponibles)
  │     - KPIs actuales del dashboard
  │     - Empresa(s) activa(s)
  │
  ├─ 3. LLM genera SQL query (Text-to-SQL):
  │     "SELECT class_name, AVG(amount) as avg_margin, COUNT(*) as txn_count
  │      FROM cached_transactions
  │      WHERE class_name = 'Zona Sur' AND txn_date >= '2025-06-01'
  │      GROUP BY class_name"
  │
  ├─ 4. Backend ejecuta SQL sobre MySQL (read-only, con timeout)
  │
  ├─ 5. LLM recibe resultados + genera respuesta en español:
  │     "El margen en Zona Sur bajó por 3 factores principales..."
  │     Con datos concretos y fuentes citadas
  │
  └─ 6. Frontend renderiza respuesta en chat bubble
```

### Capacidades
- **Text-to-SQL**: Preguntas en lenguaje natural → queries sobre cached_transactions
- **Análisis de varianza**: Comparar períodos, zonas, instaladores
- **Recomendaciones**: Basadas en patrones en los datos
- **Drill-down conversacional**: "Muéstrame las transacciones de C. Méndez" → tabla inline
- **Escenarios**: "¿Qué pasa si renegociamos con SolarTech?" → cálculo proyectado

### Seguridad
- SQL generado se ejecuta como READ-ONLY (usuario MySQL con solo SELECT)
- Query timeout de 5 segundos
- Validar que el SQL solo toque tablas permitidas (cached_*)
- No exponer datos de otras empresas si el usuario no tiene acceso

### Stack sugerido
- LLM: Claude API (Anthropic) o GPT-4
- Text-to-SQL: prompt engineering con schema + examples
- Conversación: almacenar en tabla `chat_conversations` con TTL

## Dependencias futuras
- `ChatController.php`
- `ChatService.php` — orquesta LLM + SQL execution
- `chat.js` — frontend (ya existe estructura base del mockup)
- Tabla `chat_conversations` (id, user_id, messages JSON, created_at)