# Especificaciones Técnicas y de API — JYM AI Engine
> Este documento contiene el mapa estructural completo y las especificaciones de API del motor de agentes de J&M Tech Solutions para que sea leído por asistentes virtuales y modelos LLM.

---

## 📂 Estructura del Proyecto

El backend está construido sobre Node.js + Express en una arquitectura modular limpia:

- **/server.js**: Punto de entrada del servidor Express e inicialización de Socket.IO para flujos en tiempo real.
- **/src/routes/**: Capa de definición de rutas de la API.
  - `static.routes.js`: Servido de la landing comercial y redirecciones de SPA.
  - `auth.routes.js`: Control de inicio de sesión de clientes y administradores.
  - `client.routes.js`: Rutas privadas para el panel del cliente (Prompts, SMTP, Q10).
  - `admin.routes.js`: Rutas privadas del super-administrador.
  - `webhook.routes.js`: Conexión de entrada para webhooks de WhatsApp Meta.
- **/src/controllers/**: Controladores de negocio desacoplados.
  - `client.controller.js`: Operaciones de perfil de cliente.
  - `automation.controller.js`: Campañas programadas y recordatorios masivos.
  - `email.controller.js`: Configuración de correo y plantillas.
  - `facebook.controller.js`: Integración de plantillas y páginas de Meta.
  - `q10.controller.js`: Integración académica y de cobro con Q10.
  - `webhook.controller.js`: Recepción de mensajes de WhatsApp y lógica de desvío.
  - `admin.controller.js`: CRUD y control de consumo.
- **/src/services/**: Servicios centrales de infraestructura.
  - `ai.service.js`: Conexión con Groq SDK (Llama 3) implementando rotación automática de 6 API Keys.
  - `bot.service.js`: Orquestación lógica del bot, límites de uso y Socket.io.
  - `conversation.service.js`: Historial de conversaciones en Supabase y toggles humano/bot.
  - `prompt.service.js`: Extracción de prompts desde URLs o textos externos con IA.
  - `template.service.js`: Notificaciones proactivas vía plantillas de WhatsApp.
  - `email.service.js`: Envío multitenant de correos SMTP con plantillas responsivas.
- **/src/middlewares/**:
  - `auth.middleware.js`: Autenticación para rol admin (`ADMIN_SECRET`) y clientes (clave de acceso privada).
  - `metaSignature.middleware.js`: Validación de la firma `X-Hub-Signature-256` en producción para webhooks de Meta.

---

## 🗄️ Esquema de Base de Datos (Supabase)

El sistema opera bajo un diseño multitenant en Supabase:

1. **clientes**: Contiene el perfil de cada negocio.
   - `id` (uuid, PK)
   - `name` (text), `company` (text)
   - `meta_phone_id` (text), `meta_access_token` (text), `meta_verify_token` (text)
   - `system_prompt` (text)
   - `usage_limit` (integer), `usage_count` (integer)
   - `access_key` (text), `is_active` (boolean)
   - `smtp_config` (jsonb): Host, port, user, password para envíos de email.
   - `q10_config` (jsonb): API Key y subdominio Q10 de cada cliente.
2. **conversaciones**: Hilos de chat activos con números externos.
   - `id` (uuid, PK)
   - `client_id` (uuid, FK)
   - `phone` (text)
   - `is_human_active` (boolean): `true` pausa temporalmente la IA para atención humana.
   - `last_message_at` (timestamp)
3. **mensajes**: Mensajes individuales intercambiados.
   - `id` (uuid, PK)
   - `conversation_id` (uuid, FK)
   - `role` (text): 'user', 'assistant', 'system'.
   - `text` (text)
   - `created_at` (timestamp)
4. **notification_logs**: Registro de notificaciones masivas enviadas.
   - `id` (uuid, PK)
   - `client_id` (uuid, FK)
   - `phone` (text), `status` (text), `template_name` (text), `error` (text).

---

## 📡 Endpoints de la API

### 1. Webhooks de Meta (WhatsApp)
- **GET /webhook**: Validación del webhook requerida por Meta (usa `meta_verify_token`).
- **POST /webhook**: Recepción de eventos de mensaje. Valida la firma `X-Hub-Signature-256` en producción. Si `is_human_active` es falso, procesa el texto con `ai.service.js` y responde automáticamente vía WhatsApp Cloud API.

### 2. Panel Admin (Requiere cabecera `Authorization: Bearer <ADMIN_SECRET>`)
- **GET /api/admin/clients**: Listar todos los clientes creados.
- **POST /api/admin/clients**: Registrar un nuevo cliente SaaS. Genera una `access_key` aleatoria.
- **PUT /api/admin/clients/:id**: Modificar límites de uso, plan o credenciales.
- **DELETE /api/admin/clients/:id**: Suspender o eliminar cliente.

### 3. Panel Cliente (Requiere cabecera `Authorization: Bearer <client_id>:<access_key>`)
- **GET /api/client/profile**: Obtener datos del cliente actual.
- **POST /api/client/prompt/generate**: Llama a `prompt.service.js` para crear un prompt a partir del sitio web del cliente.
- **PUT /api/client/prompt**: Actualizar el prompt del sistema.
- **GET /api/client/conversations**: Obtener conversaciones y mensajes en tiempo real.
- **POST /api/client/conversations/:id/toggle-bot**: Alternar el control entre la IA y un agente humano.
- **POST /api/client/email/verify-smtp**: Verificar conexión SMTP con Nodemailer.
- **POST /api/client/q10/sync**: Consultar deudores y sincronizar deudas desde la API de Q10.
- **POST /api/client/q10/send-reminders**: Envío masivo de recordatorios de cobro vía plantillas de WhatsApp.

---

## 🔒 Reglas de Seguridad de Código para AIs
- **Limpieza de Raíz:** Nunca dejar archivos `.zip`, copias de bases de datos o scripts de prueba (`test_*.js`) en la raíz del repositorio. Deben ser ignorados en `.gitignore` y movidos a la carpeta `backup` o `scratch`.
- **Credenciales:** Nunca quemar contraseñas o llaves de API en el código; usar siempre variables de entorno (`process.env`).
- **Validaciones:** Comprobar siempre los tipos de datos cargados vía Multer para evitar scripts maliciosos.