# Plan — Integración RRHH al IA Dashboard (IA-RRHH-01)

> **Estado:** aprobado, pendiente de implementación
> **Fecha:** 2026-05-18
> **Owner:** derlisd
> **Alcance:** Backend `smartfactvoice-backend` + Frontend `pos-ventas`

---

## Contexto

El módulo **RRHH / Nómina** (plan en `docs/plan-rrhh.md`, módulos M01–M15) ya tiene backend y UI funcional. El **IA Dashboard** (`src/ai-dashboard/*` + `pos-ventas/src/organismos/AIDashboard/*`) actualmente solo conoce dominios de ventas, créditos, cobros, compras y stock. Falta exponer el dominio RRHH al motor de IA para que:

- El **chat en lenguaje natural** pueda responder consultas de nómina, anticipos, vacaciones, IPS, etc.
- Las **alertas** detecten situaciones críticas de RRHH (liquidación no cerrada, IPS faltante, préstamos en mora).
- El **timeline** registre eventos de RRHH (cierres, acreditaciones, altas/bajas).
- Las **predicciones** proyecten costos de nómina e IPS.
- El **resumen ejecutivo** muestre KPIs de RRHH.

Pregunta guía en cada decisión: **"¿Esto hace la vida del usuario más fácil y rápida sin exponer datos sensibles?"**

---

## Decisiones tomadas (definidas con el usuario)

| # | Tema | Decisión |
|---|------|----------|
| 1 | Día de corte para alerta de liquidación no cerrada | **Configurable** por empresa en `ai_config` (default sugerido: día 5 del mes siguiente). |
| 2 | Empresas sin módulo RRHH activo | **Ocultar** chips, alertas, tarjetas y bloque RRHH del schema-context si la empresa no tiene el módulo activo. |
| 3 | Permisos | **Restringir** acceso a datos de nómina/liquidaciones al permiso `RRHH_VER_LIQUIDACIONES` (o equivalente). Si el usuario no lo tiene, no se le inyecta el contexto RRHH al chat ni se le muestran tarjetas/alertas RRHH. |
| 4 | Predicción de nómina | **Fase 1 simple**: promedio de últimos 3 meses cerrados. Modelos más finos quedan para Fase 4. |
| 5 | Chat IA con datos sensibles | **Restringir por seguridad**: el system prompt prohibe consultas individuales identificables ("¿cuánto gana Juan Pérez?") cuando el usuario no tenga `RRHH_VER_SALARIOS`. Permite agregados (totales por concepto, por mes, por sector). |
| 6 | UI Resumen ejecutivo | **Acordeón colapsable "RRHH"** para no saturar el dashboard. Colapsado por defecto. |

---

## Fases

### Fase 1 — Chat IA (prioridad alta, en este PR)

**Objetivo:** que el chat IA pueda responder preguntas sobre RRHH usando SQL generado por el LLM.

- Ampliar `src/ai-dashboard/chat/schema-context.ts` con un bloque `RRHH / Nómina`:
  - Tablas: `rrhh_empleados`, `rrhh_liquidaciones_cabecera`, `rrhh_liquidaciones_detalle`, `rrhh_conceptos_liquidacion`, `rrhh_parametros_sistema`, `rrhh_vacaciones_solicitudes`, `rrhh_prestamos`, `rrhh_anticipos_salario`, `rrhh_asistencia_novedades`, `rrhh_acreditaciones_bancarias`, `rrhh_desvinculaciones`.
  - Campos clave y descripciones breves (estado, periodo, monto, concepto, tipo).
  - Joins comunes (liquidación ↔ detalle ↔ concepto ↔ empleado).
  - 4–6 ejemplos SQL: nómina del mes, top conceptos, anticipos vigentes, vacaciones pendientes, IPS del mes, empleados activos por sector.
- Reglas de seguridad en system prompt:
  - Si el usuario no tiene permiso `RRHH_VER_SALARIOS`: prohibir consultas individuales identificables; permitir agregados.
  - Si la empresa no tiene módulo RRHH activo: no inyectar bloque RRHH.
- 4 chips de "consultas sugeridas" RRHH en `ChatIA.jsx`:
  - "Nómina del último mes"
  - "Empleados con préstamos vigentes"
  - "Vacaciones pendientes de tomar"
  - "Costo IPS del último mes"

### Fase 5 — Resumen ejecutivo (en este mismo PR)

**Objetivo:** mostrar KPIs RRHH en el dashboard ejecutivo.

- Backend: extender `insights.service.ts` para calcular (solo si empresa tiene RRHH + usuario tiene permiso):
  - Empleados activos (count)
  - Nómina del mes en curso (total bruto y neto)
  - Total IPS aporte (mes en curso)
  - Costo total mes anterior (para Δ%)
  - Proyección nómina próximo mes (Fase 1: promedio últimos 3 meses cerrados)
- Frontend: nuevo bloque `<AcordeonRRHH />` en `ResumenEjecutivo.jsx`, colapsado por defecto, con 4–5 tarjetas siguiendo el grid actual.
- Si la empresa no tiene RRHH o el usuario no tiene permiso → el acordeón no se renderiza.

### Fase 2 — Alertas RRHH (siguiente PR)

Extender `alerts.service.ts` con detectores nuevos (clasificados por `modulo: 'rrhh'`):

| Criticidad | Detector |
|---|---|
| 🔴 Alta | Liquidación mensual no cerrada pasado el día configurado en `ai_config.rrhh_dia_corte_liquidacion`. |
| 🟠 Media | Empleados activos sin IPS configurado. |
| 🟠 Media | Empleados activos sin CBU para acreditación bancaria. |
| 🟠 Media | Préstamos vigentes con cuota no descontada en última liquidación cerrada. |
| 🟡 Baja | Vacaciones vencidas sin tomar (>14 meses desde generación). |
| 🟡 Baja | Empleados próximos a cambiar tramo de antigüedad (aguinaldo/preaviso). |

Frontend: no requiere cambios — `AlertasPanel.jsx` ya filtra por tipo/módulo.

### Fase 3 — Timeline RRHH (siguiente PR)

Eventos a registrar en `timeline.service.ts` con `modulo: 'rrhh'`:

- Liquidación cerrada (cabecera con periodo + total).
- Acreditación bancaria generada (archivo + total).
- Reporte IPS emitido (periodo).
- Alta de empleado.
- Baja de empleado (desvinculación con causal).
- Vacaciones aprobadas / iniciadas / finalizadas.

### Fase 4 — Predicciones RRHH (siguiente PR)

En `predictions.service.ts` agregar:

- `proyeccionNomina(empresaId, mesesAdelante)` — modelo más fino: histórico + parámetros vigentes + novedades cargadas + altas/bajas conocidas.
- `costoIpsEstimado(empresaId, periodo)` — proyección de aporte IPS.
- (Opcional) `empleadosRiesgoDesvinculacion` — empleados con patrón de faltas + anticipos repetidos.

---

## Arquitectura — Mecanismos transversales

### Detección de módulo RRHH activo

Crear helper `tieneModuloRRHH(empresaId): Promise<boolean>` en `src/ai-dashboard/shared/feature-flags.ts` (nuevo). Lógica: existencia de registros base (`rrhh_parametros_sistema`) o flag en `empresas.modulos_activos` si existe.

### Verificación de permisos

Crear helper `puedeVerRRHH(usuario, nivel: 'liquidaciones' | 'salarios'): boolean` en `src/ai-dashboard/shared/rrhh-permissions.ts`. Reutiliza el guard de permisos existente.

### Configuración por empresa

Agregar campos a la tabla/config `ai_config`:

- `rrhh_dia_corte_liquidacion: int` (default 5)
- `rrhh_alertas_habilitadas: boolean` (default true cuando módulo activo)

Si requiere migración Prisma, incluirla en el PR de Fase 2.

---

## Archivos críticos

### Backend — a modificar
```
src/ai-dashboard/chat/schema-context.ts            (Fase 1: bloque RRHH + reglas seguridad)
src/ai-dashboard/insights.service.ts                (Fase 5: KPIs RRHH)
src/ai-dashboard/alerts.service.ts                  (Fase 2)
src/ai-dashboard/timeline.service.ts                (Fase 3)
src/ai-dashboard/predictions.service.ts             (Fase 4 + proyección simple en Fase 5)
```

### Backend — nuevos
```
src/ai-dashboard/shared/feature-flags.ts            (tieneModuloRRHH)
src/ai-dashboard/shared/rrhh-permissions.ts         (puedeVerRRHH)
src/ai-dashboard/shared/rrhh-context-snippets.ts    (ejemplos SQL para system prompt)
```

### Frontend — a modificar
```
src/organismos/AIDashboard/ChatIA.jsx               (chips sugeridos RRHH)
src/organismos/AIDashboard/ResumenEjecutivo.jsx     (acordeón RRHH)
src/api/ai-dashboard.service.js                     (endpoints nuevos si hace falta)
```

### Frontend — nuevos
```
src/organismos/AIDashboard/AcordeonRRHH.jsx         (tarjetas KPIs RRHH)
```

### A consultar (no modificar)
```
docs/plan-rrhh.md                                   (referencia de módulos M01-M15)
prisma/schema.prisma                                (tablas rrhh_*)
src/rrhh-engine/*                                   (servicios existentes RRHH)
```

---

## Verificación end-to-end

1. **Empresa SIN módulo RRHH** → chat no inyecta bloque, resumen no muestra acordeón, no aparecen alertas RRHH.
2. **Empresa CON RRHH, usuario SIN permiso** → idem (oculto).
3. **Empresa CON RRHH, usuario CON `RRHH_VER_LIQUIDACIONES` pero SIN `RRHH_VER_SALARIOS`** → ve agregados, no ve individuales en chat.
4. **Usuario admin** → ve todo.
5. Probar 4 chips sugeridos + 2 preguntas libres en chat.
6. Verificar acordeón colapsado por defecto y datos correctos contra SQL manual.

---

## Fuera de alcance

- Cambios en lógica de cálculo de liquidación (`src/rrhh-engine/*`).
- Migración de tablas existentes RRHH.
- Modelos ML para predicción de desvinculación (queda en Fase 4 opcional).