# Plan: Mejora UX Módulo RRHH (RRHH-UX-01)

**Fecha:** 2026-05-17  
**Estado:** Completado 100% ✅  
**Repositorio frontend:** `pos-ventas`

---

## Contexto y problema

El módulo RRHH tiene backend completo (M01–M15) y 18 pestañas operativas, pero la experiencia del usuario es deficiente:

- Pestañas vacías sin ninguna indicación de qué hacer
- Formularios sin ejemplos de formato (`CI`, `IPS`, `fecha ingreso`)
- Procesos críticos que asumen prerrequisitos sin avisarlos (ej: liquidar sin parámetros, acreditar sin liquidación cerrada)
- Sin onboarding ni tour activo para nuevos usuarios
- Sin guía del flujo obligatorio: Configuración → Empleados → Novedades/Anticipos → Liquidación → IPS → Acreditaciones

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

---

## Principios UX aplicados

| Principio | Cómo se aplica |
|---|---|
| Navegación clara y lógica | Botones "Ir a configurar" navegan directamente a la pestaña necesaria |
| Minimizar pasos y fricción | Onboarding 3 slides + tour guiado; el checklist muestra exactamente qué falta |
| Interfaces limpias | Guía colapsable (oculta por defecto), no recarga visualmente la pantalla |
| Elementos consistentes | Un único componente `RRHHGuia` para todas las secciones; mismo patrón que `MarangatuGuia` |
| Ayuda contextual | Guía por pestaña + `FieldHint` con ejemplo y tooltip en campos críticos |
| Ejemplos prácticos | Diccionario `rrhhGuias.js` incluye ejemplos reales (Art. 219, SMLV, IPS 9%/16.5%) |
| Feedback inmediato | `InlineValidationBanner` al submit; toasts existentes con notistack |
| Responsive | Checklist colapsa a acordeón en `<600px` |
| Accesibilidad | `aria-describedby` en FieldHint; `focus-visible` en CTAs; contraste en chips |
| Optimización velocidad | `RRHHContext` carga todos los prereqs en un solo `Promise.allSettled` al montar |

---

## Arquitectura de la solución

### Componentes nuevos — `src/components/rrhh/_shared/`

| Archivo | Propósito |
|---|---|
| `RRHHGuia.jsx` | Acordeón colapsable "¿Cómo funciona?" — pasos numerados + notas importantes |
| `RRHHEmptyState.jsx` | Empty state estándar: icono + título + descripción + CTA primario + "Ver guía" + "¿Por qué no veo nada?" |
| `RRHHPrereqChecklist.jsx` | Tarjeta superior con checks de prerrequisitos. Ítems faltantes muestran "Ir a configurar" que cambia de pestaña |
| `RRHHContext.jsx` | Context + Provider con `setActiveTab` y snapshot reactivo de prereqs (empleadosActivos, parametros, conceptosSeed, cargos, departamentos, tiposEmpleado) |
| `RRHHOnboardingDialog.jsx` | Modal de bienvenida (flag `localStorage:rrhh-onboarding-v1`). 3 slides + botón "Iniciar tour guiado" |
| `FieldHint.jsx` | Wrapper de TextField con `helperText` estandarizado + ícono info con tooltip ampliado |
| `InlineValidationBanner.jsx` | Alert MUI con lista de errores + anchor scroll para navegar a cada campo |
| `rrhhGuias.js` | Diccionario completo de contenido (intro, pasos, notas) para las 18 secciones |
| `rrhhPrereqs.js` | Matriz de dependencias: qué prerrequisito requiere cada pestaña y a qué tab navegar |

### Patrón base reutilizado

- `src/components/marangatu/MarangatuGuia.jsx` → modelo exacto para `RRHHGuia`
- `src/tours/components/TourTrigger.jsx` + `src/tours/useTour.js` → tour interactivo
- `src/tours/definitions/rrhhTour.js` → ya existía, se integra con el Onboarding

---

## Matriz de prerrequisitos

| Pestaña destino | Prerrequisitos críticos | Tab origen |
|---|---|---|
| Empleados | Parámetros vigentes, Cargos, Departamentos, Tipos de empleado | Configuración |
| Novedades / Anticipos / Préstamos / Vacaciones | Empleados activos + Conceptos seed | Empleados / Configuración |
| Liquidación quincenal | Empleados + Conceptos + Parámetros del período | Configuración / Empleados |
| Liquidación mensual | Quincenal cerrada (si aplica) + Novedades aplicadas | Liquidaciones |
| Acreditaciones bancarias | Liquidación cerrada + Formato bancario + Cuenta bancaria | Liquidaciones / Configuración |
| Reportes IPS | Liquidación mensual cerrada | Liquidaciones |
| Desvinculaciones | Empleado activo + Última liquidación cerrada | Empleados / Liquidaciones |
| Planillas externas | Conceptos seed + Empleados activos | Configuración / Empleados |

---

## Flujo de usuario recomendado

```
1. Primer acceso → RRHHOnboardingDialog (3 slides)
       ↓ "Iniciar tour guiado"
2. Tour overview → recorre las 11 pestañas explicando cada una
       ↓ (tour completado)
3. Configuración → Parámetros → Conceptos → Cargos → Departamentos → Tipos → Formatos bancarios
       ↓
4. Empleados → Alta con FieldHint en CI, IPS, salario, fecha ingreso
       ↓
5. Novedades / Anticipos / Préstamos (opcional, por período)
       ↓
6. Liquidación quincenal → calcular → revisar → cerrar
       ↓
7. Liquidación mensual → calcular → revisar → cerrar
       ↓
8. IPS / REOP → generar → descargar REOP → marcar declarado
       ↓
9. Acreditaciones bancarias → generar archivo → enviar al banco → confirmar
       ↓
10. Desvinculaciones (cuando corresponda) → calcular finiquito → aprobar → pagar
```

---

## Contenido por pestaña (resumen)

Contenido completo en `rrhhGuias.js`. Secciones:

- **configuracion** — orden recomendado + alert "Primer paso obligatorio"
- **parametros** — SMLV, tasas IPS, vigencia; alert "Sin esto no podés liquidar"
- **conceptos** — seed del sistema (SALARIO_BASE, IPS_*); no borrar los del sistema
- **cargos / departamentos / tiposEmpleado / centrosCosto** — catálogos obligatorios
- **formatosBancarios** — template por banco (Continental, Atlas, etc.)
- **empleados** — CI único, salario base, régimen IPS, fecha ingreso
- **vacaciones** — Art. 219 CT: 12d/<5años, 18d/5-10años, 30d/>10años
- **novedades** — ausencias, tardanzas, licencias con `impacta_liquidacion`
- **anticipos** — máx 30% salario neto; debe estar APROBADO para descontar
- **prestamos** — cuotas mensuales; total descuentos ≤ 30% salario
- **planillas** — plantilla XLSX/CSV; código de concepto debe ser exacto
- **liquidaciones** — BORRADOR → PRE_LIQUIDACION → CERRADA (inmutable)
- **acreditaciones** — solo desde liquidaciones CERRADAS; CBU requerida
- **ips** — solo sobre liquidaciones MENSUALES cerradas; base ≥ SMLV
- **desvinculaciones** — motivo legal determina cálculo (renuncia / despido / causa)

---

## Archivos modificados

### Nuevos
```
src/components/rrhh/_shared/RRHHGuia.jsx
src/components/rrhh/_shared/RRHHEmptyState.jsx
src/components/rrhh/_shared/RRHHPrereqChecklist.jsx
src/components/rrhh/_shared/RRHHContext.jsx
src/components/rrhh/_shared/RRHHOnboardingDialog.jsx
src/components/rrhh/_shared/FieldHint.jsx
src/components/rrhh/_shared/InlineValidationBanner.jsx
src/components/rrhh/_shared/rrhhGuias.js
src/components/rrhh/_shared/rrhhPrereqs.js
```

### Modificados
```
src/components/templates/RRHHTemplate.jsx   ← RRHHProvider + RRHHOnboardingDialog + useTour overview
src/components/rrhh/LiquidacionesTab.jsx    ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/EmpleadosTab.jsx        ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/DesvinculacionesTab.jsx ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/VacacionesTab.jsx       ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/PlanillasExternasTab.jsx ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/AcreditacionesBancariasTab.jsx ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/ReportesIpsTab.jsx      ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/PrestamosTab.jsx        ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/AnticiposTab.jsx        ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/NovedadesTab.jsx        ← RRHHGuia + RRHHPrereqChecklist
src/components/rrhh/ParametrosTab.jsx       ← RRHHGuia
src/components/rrhh/ConceptosTab.jsx        ← RRHHGuia
src/components/rrhh/ConfiguracionTab.jsx    ← RRHHGuia (defaultOpen) + Alert "Primer paso"
```

---

## Verificación end-to-end

Recorrer flujo en **empresa vacía** (sin datos cargados):

1. Entrar a RRHH → ver `RRHHOnboardingDialog` con 3 slides → botón "Iniciar tour"
2. Tour overview navega las 11 pestañas con explicaciones
3. Ir a Liquidaciones → `RRHHPrereqChecklist` muestra 3 ítems faltantes → cada uno tiene "Ir a configurar"
4. Click "Ir a configurar" → cambia a pestaña Configuración con guía abierta y Alert de advertencia
5. Configurar Parámetros, Conceptos, Cargos, Departamentos, Tipos
6. Volver a Empleados → checklist ahora verde → cargar empleado (guiado por FieldHint)
7. Registrar novedad → ver helperText con ejemplos
8. Liquidar quincenal → calcular → cerrar
9. Liquidar mensual → calcular → cerrar
10. IPS → generar (checklist solo verde si liq mensual cerrada)
11. Acreditaciones → generar archivo bancario
12. Desvinculación → bloqueada hasta cerrar liquidación del período
13. Recargar → validar `rrhh-onboarding-v1` en localStorage (no reaparece el modal)
14. QA responsive en `<600px`: checklist colapsa correctamente
15. Lector de pantalla: verificar `aria-describedby` en campos FieldHint

---

## Fase 6 — Completado ✅ (2026-05-17)

- [x] **`FieldHint` en EmpleadosTab** — CI, RUC, N°IPS, nombres, apellidos, fecha nacimiento, fecha ingreso, fecha egreso, salario base, cuenta bancaria con placeholder + helper text + anchor IDs
- [x] **`InlineValidationBanner` en EmpleadosTab** — reemplaza Alert ad-hoc; `validar()` retorna `{campo, mensaje, anchorId}`
- [x] **Tour steps completos** — 7 pestañas nuevas: `empleados`, `vacaciones`, `novedades`, `anticipos`, `prestamos`, `planillas`, `configuracion`. Las 11 pestañas cubiertas.
- [x] **Badge de conteo en tabs** — `RRHHContext` carga anticipos PENDIENTES, préstamos APROBADOS, vacaciones SOLICITADAS. Tabs con badge naranja reactivo.
- [x] **Arquitectura `RRHHInner`** — `RRHHTemplate` refactorizado con componente interno que consume `useRRHHContext` para badges + tour por tab activo.
- [x] **`RRHHEmptyState` integrado en 3 tabs** — Anticipos, Préstamos y Novedades con descripción, CTA "Registrar" y botón "Ver guía".

---

## Estado final por tab (auditoría 2026-05-17 — completo)

| Pestaña | Guia | Prereq | EmptyState | FieldHint form | InlineVal | Tour |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| Empleados | ✅ | ✅ | — (lista) | ✅ | ✅ | ✅ |
| Liquidaciones | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| IPS / REOP | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
| Acreditaciones | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
| Desvinculaciones | ✅ | ✅ | ❌ ad-hoc | ✅ | ✅ | ✅ |
| Vacaciones | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
| Novedades | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Anticipos | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Préstamos | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Planillas externas | ✅ | ✅ | ✅ | — (upload) | ❌ | ✅ |
| Configuración | ✅ alert | — | — | — | — | ✅ |
| Cargos (sub) | ✅ | — | ✅ | ❌ | ❌ | — |
| Departamentos (sub) | ✅ | — | ✅ | ❌ | ❌ | — |
| Tipos empleado (sub) | ✅ | — | ✅ | ❌ | ❌ | — |
| Centros costo (sub) | ✅ | — | ✅ | ❌ | ❌ | — |
| Conceptos (sub) | ✅ | — | ✅ | ❌ | ❌ | — |
| Parámetros (sub) | ✅ | — | ✅ | ❌ | ❌ | — |
| Formatos bancarios (sub) | ✅ | — | ✅ | ❌ | ❌ | — |

---

## Fase 7 — Completado ✅ (2026-05-17)

- [x] **7A** — `RRHHEmptyState` en CargosTab, DepartamentosTab, TiposEmpleadoTab, CentrosCostoTab, FormatosBancariosTab, VacacionesTab (saldos + solicitudes)
- [x] **7B** — `RRHHGuia` en las 5 sub-tabs de Configuración sin guía
- [x] **7C** — Field hints (`<small>`) en AnticiposTab (monto, año período), PrestamosTab (monto, cuotas), NovedadesTab (fecha, minutos tardanza), DesvinculacionesTab (tipo, fecha último día)
- [x] **7D** — `InlineValidationBanner` reemplaza toasts de validación en AnticiposTab, PrestamosTab, NovedadesTab, DesvinculacionesTab
- [x] **7E** — `reloadBadges()` tras mutaciones en AnticiposTab (crear/aprobar/anular), PrestamosTab (crear/cambiar estado), VacacionesTab (aprobar/cancelar/rechazar)
- [x] **7F** — Badge `novedades` en `RRHHContext`: cuenta novedades del mes en curso con `impacta_liquidacion: true`. Tab Novedades muestra badge naranja.

---

## Fase 8 — Completado ✅ (2026-05-17)

- [x] **EmptyState** en LiquidacionesTab (CTA → `setShowCrear(true)`) + FieldHint en campo año período
- [x] **EmptyState** en ReportesIpsTab (CTA → `handleAbrirGenerar`)
- [x] **EmptyState** en AcreditacionesBancariasTab (CTA → `abrirWizard`)
- [x] **EmptyState** en PlanillasExternasTab (CTA → `handleNuevaImportacion`)
- [x] **EmptyState** en ConceptosTab (sin CTA — el Alert de seed lo cubre)
- [x] **EmptyState** en ParametrosTab (título dinámico `soloVigentes`, sin CTA — seed Alert lo cubre)

---

## Sin pendientes — plan 100% completo ✅