portal-requisicion-vacantes/README.md

# Portal Requisición de Vacantes

> Portal web interno para solicitar, aprobar y dar seguimiento a requisiciones de vacantes, centralizando el flujo de RRHH, Administración y Reclutamiento.

---

## Información General

| Campo                    | Detalle                             |
| ------------------------ | ----------------------------------- |
| Proyecto                 | Portal Requisición de Vacantes      |
| Área                     | RRHH                                |
| Estado                   | Prototipo / En definición funcional |
| Developer Principal      | Isaac Aracena                       |
| IT Manager               | Luis Matos                          |
| Fecha de Inicio          | A completar                         |
| Fecha de Cierre Estimada | A completar                         |
| Ciclo Shape Up           | A completar                         |
| Board de Ejecución       | A completar                         |
| PRD del Proyecto         | A completar                         |

---

## Objetivo

### Problema que resuelve

Actualmente, la requisición y seguimiento de vacantes depende de procesos manuales, hojas de cálculo, correos y validaciones dispersas. Esto dificulta tener visibilidad clara sobre aprobaciones, tiempos de respuesta, SLA, carga de recruiters y cuellos de botella en el proceso de reclutamiento.

### Solución propuesta

El Portal de Requisición de Vacantes busca centralizar el proceso completo en una aplicación web donde los usuarios puedan crear solicitudes, RRHH pueda validar, Administración pueda aprobar, Reclutamiento pueda dar seguimiento y Dirección pueda visualizar métricas de desempeño.

### Usuarios / Beneficiarios

* Solicitantes / Hiring Managers
* Equipo de RRHH
* Recruiters
* Administración
* Dirección de RRHH
* Gerencia regional o global

---

## Estado Actual del Proyecto

Este repositorio contiene actualmente un **prototipo inicial** desarrollado con Next.js y React.

El objetivo del prototipo es validar la experiencia visual, la navegación principal y la estructura base del portal antes de implementar completamente la lógica de backend, base de datos, autenticación, permisos, auditoría y automatizaciones.

---

## Características Principales

### Incluidas en el prototipo

* Interfaz web moderna y responsive.
* Estructura base del portal.
* Visualización inicial del flujo de reclutamiento.
* Componentes reutilizables.
* Base preparada para futuras integraciones.

### Funcionalidades objetivo

* Login con Google SSO.
* Creación de requisiciones de vacantes.
* Flujo de aprobación secuencial: RRHH → Administración.
* Estados de requisición y pipeline de reclutamiento.
* Cálculo de SLA por país, ciudad, posición y cantidad solicitada.
* Auditoría de cambios.
* Dashboard de TTF y cuellos de botella.
* Vista de carga de trabajo por recruiter.
* Notificaciones por cambios de estado, rechazos, aprobaciones y alertas de SLA.
* Migración de datos históricos desde el archivo actual de Reclutamiento LATAM.

---

## Arquitectura

### Arquitectura actual

```txt
Usuario
  ↓
Portal Web Next.js
  ↓
Prototipo Frontend
```

### Arquitectura objetivo

```txt
Usuario con Google SSO
  ↓
Portal Web Next.js
  ↓
Backend / API
  ↓
Base de datos PostgreSQL
  ↓
Notificaciones / Automatizaciones
  ↓
Dashboard y reportes de RRHH
```

---

## Stack Tecnológico

| Componente       | Tecnología                          | Propósito                                                      |
| ---------------- | ----------------------------------- | -------------------------------------------------------------- |
| Frontend         | Next.js / React                     | Interfaz web del portal                                        |
| Package Manager  | pnpm                                | Gestión de dependencias                                        |
| Backend          | A definir                           | Lógica de negocio, aprobaciones y seguridad                    |
| Base de datos    | PostgreSQL / Supabase recomendado   | Almacenamiento de requisiciones, usuarios, estados y auditoría |
| Autenticación    | Google SSO                          | Acceso con cuentas corporativas                                |
| Automatizaciones | n8n recomendado                     | Notificaciones, alertas y escalaciones                         |
| Reportes         | Dashboard interno / Power BI futuro | Visualización de métricas de reclutamiento                     |

---

## Integraciones Futuras

| Sistema               | Tipo de integración | Datos que fluyen                                  |
| --------------------- | ------------------- | ------------------------------------------------- |
| Google SSO            | OAuth / OIDC        | Autenticación de usuarios corporativos            |
| PostgreSQL / Supabase | Base de datos       | Requisiciones, usuarios, estados, auditoría y SLA |
| n8n                   | Webhook / API       | Notificaciones, alertas y escalaciones            |
| Email corporativo     | SMTP / Gmail OAuth  | Avisos de aprobación, rechazo, SLA y asignaciones |
| Power BI              | Conexión a datos    | Reportes ejecutivos de RRHH                       |

---

## Reglas de Negocio

1. El solicitante puede crear requisiciones y dar seguimiento a sus propias solicitudes.

2. La aprobación debe ser secuencial:

   * Primero RRHH.
   * Luego Administración.
   * Una requisición no debe avanzar si el paso anterior no ha sido aprobado.

3. Si RRHH o Administración rechaza una requisición, esta debe volver al estado de corrección.

4. El solicitante debe poder corregir una requisición rechazada y reenviarla sin crear una nueva desde cero.

5. El SLA debe iniciar desde el momento en que el solicitante crea la requisición.

6. El sistema debe diferenciar entre:

   * Tiempo en aprobación.
   * Tiempo en reclutamiento.
   * Tiempo total hasta cierre.

7. Los usuarios estándar solo deben ver sus propias requisiciones.

8. Los líderes por país solo deben ver requisiciones de su territorio.

9. Los usuarios regionales o globales pueden tener visibilidad ampliada.

10. Los campos sensibles como salario, presupuesto o paquete salarial deben estar restringidos según el rol.

11. Cada cambio importante debe quedar registrado en un audit log no editable.

12. La carga de trabajo de cada recruiter debe calcularse según complejidad de posición y volumen de vacantes.

13. Una requisición no puede pasar a Reclutando hasta que RRHH y Administración hayan aprobado.

14. Toda reasignación de recruiter debe quedar registrada con motivo, usuario responsable y fecha.

15. Si una requisición está próxima a vencer por SLA, debe marcarse visualmente y generar alerta.

---

## Flujo Principal

```txt
1. El solicitante crea una requisición.
2. El sistema registra fecha, usuario, país, posición y cantidad.
3. El SLA inicia automáticamente.
4. RRHH revisa la solicitud.
5. RRHH aprueba o rechaza.
6. Si RRHH aprueba, pasa a Administración.
7. Administración aprueba o rechaza.
8. Si Administración aprueba, la requisición pasa a Reclutando.
9. Se asigna recruiter.
10. El recruiter actualiza etapas del pipeline.
11. El sistema calcula TTF, SLA, carga de trabajo y cuellos de botella.
12. Al cerrar la requisición, se actualizan métricas y reportes.
```

---

## Estados del Proceso

### Estados sugeridos para la requisición

```txt
Draft
Submitted
Pending RRHH Approval
Correction Required
Pending Administration Approval
Approved
Reclutando
Closed
Cancelled
```

### Estados sugeridos para el pipeline de reclutamiento

```txt
Reclutando
1era Entrevista
2da Entrevista
Referencias
Exámenes Médicos
Seleccionado
Cerrado
```

---

## SLA Dinámico

El sistema debe evitar calcular SLA de forma lineal simple.

Ejemplo incorrecto:

```txt
1 merchandiser = 5 días
10 merchandisers = 50 días
```

Modelo recomendado:

```txt
Total SLA = Base Days + ((Cantidad - 1) × Incremental Factor)
```

Ejemplo:

```txt
Posición: Merchandiser
Ciudad: Santiago
País: República Dominicana
Base Days: 5
Incremental Factor: 1

Cantidad solicitada: 10

Total SLA = 5 + ((10 - 1) × 1)
Total SLA = 14 días hábiles
```

El cálculo debe considerar:

* País.
* Ciudad.
* Posición.
* Cantidad solicitada.
* Fines de semana.
* Feriados por país.

---

## Medición de Tiempos

El portal debe medir los tiempos del proceso completo para identificar cuellos de botella.

### Métricas principales

| Métrica                 | Descripción                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| Tiempo en aprobación    | Tiempo desde la creación hasta la aprobación final de Administración     |
| Tiempo en reclutamiento | Tiempo desde que pasa a Reclutando hasta el cierre                       |
| Tiempo total            | Tiempo desde la creación de la requisición hasta el cierre               |
| TTF                     | Time to Fill de la requisición                                           |
| Días en etapa           | Tiempo que una requisición o candidato permanece en una etapa específica |

---

## Recruiter Capacity Score

El portal debe calcular una puntuación de carga por recruiter para ayudar a Dirección de RRHH a balancear el trabajo.

### Complejidad por posición

| Tipo de posición                              | Puntos |
| --------------------------------------------- | -----: |
| Tier 1: Merchandiser / Promotor / Impulsadora |      1 |
| Tier 2: Supervisor / Analista / Trade Pro     |      3 |
| Tier 3: Manager / Coordinador / Rol regional  |      5 |

### Multiplicador por volumen

| Cantidad de vacantes | Puntos adicionales |
| -------------------- | -----------------: |
| 1 - 2 vacantes       |                 +0 |
| 3 - 10 vacantes      |                 +2 |
| 11+ vacantes         |                 +4 |

### Semáforo de carga

|   Score | Estado       | Acción recomendada                         |
| ------: | ------------ | ------------------------------------------ |
|  0 - 15 | Disponible   | Puede recibir nuevas requisiciones         |
| 16 - 25 | En capacidad | Evitar asignaciones grandes                |
|     26+ | Sobrecargado | Reasignar casos o contratar apoyo temporal |

### Ejemplo de cálculo

```txt
Recruiter: María

Caso 1:
Posición: Manager
Complejidad: Tier 3 = 5 puntos
Cantidad: 1 vacante = +0 puntos
Total caso 1 = 5 puntos

Caso 2:
Posición: Merchandiser
Complejidad: Tier 1 = 1 punto
Cantidad: 15 vacantes = +4 puntos
Total caso 2 = 5 puntos

Carga total de María = 10 puntos
```

---

## Reasignación de Requisiciones

El portal debe permitir que Dirección de RRHH o Coordinación pueda reasignar requisiciones entre recruiters cuando exista sobrecarga, vacaciones, salida de personal o necesidad operativa.

### Reglas de reasignación

1. Solo roles autorizados pueden reasignar requisiciones.
2. La reasignación debe solicitar un motivo obligatorio.
3. El sistema debe restar la carga al recruiter anterior.
4. El sistema debe sumar la carga al nuevo recruiter.
5. El requester debe ser notificado sobre la reasignación.
6. El nuevo recruiter debe recibir el historial completo del caso.
7. La reasignación debe quedar registrada en audit log.

### Ejemplo de evento de auditoría

```txt
Req #405 transferida de María a José.
Motivo: María superó el límite de carga permitido.
Usuario responsable: HR Director.
Fecha: YYYY-MM-DD HH:mm:ss.
```

---

## Modelo de Datos Objetivo

Tablas sugeridas:

```txt
users
roles
countries
cities
positions
requisitions
requisition_status_history
approvals
audit_logs
sla_rules
public_holidays
recruiter_assignments
recruiter_capacity
notifications
```

### Tabla principal: requisitions

Campos sugeridos:

```txt
id
requester_id
country_id
city_id
position_id
quantity
salary_package
budget
status
assigned_recruiter_id
sla_deadline
created_at
updated_at
closed_at
```

### Tabla de auditoría: audit_logs

Campos sugeridos:

```txt
id
requisition_id
user_id
action
old_value
new_value
created_at
```

### Tabla de SLA: sla_rules

Campos sugeridos:

```txt
id
country_id
city_id
position_id
base_days
incremental_factor
created_at
updated_at
```

### Tabla de feriados: public_holidays

Campos sugeridos:

```txt
id
country_id
holiday_date
holiday_name
created_at
```

### Tabla de asignaciones: recruiter_assignments

Campos sugeridos:

```txt
id
requisition_id
recruiter_id
assigned_by
assigned_at
is_active
```

### Tabla de historial de asignaciones: requisition_assignment_history

Campos sugeridos:

```txt
id
requisition_id
previous_recruiter_id
new_recruiter_id
transfer_reason
transferred_by
transfer_timestamp
```

---

## Seguridad y Permisos

### Autenticación

El sistema debe usar Google SSO con cuentas corporativas.

```txt
Usuario ingresa con Google
  ↓
Sistema valida dominio corporativo
  ↓
Sistema consulta rol y país del usuario
  ↓
Sistema aplica permisos de visualización y edición
```

### Roles sugeridos

| Rol              | Permisos principales                                     | Visibilidad                       |
| ---------------- | -------------------------------------------------------- | --------------------------------- |
| Requester        | Crear requisiciones, ver estado, corregir rechazadas     | Solo sus propias requisiciones    |
| HR Regional      | Aprobar, rechazar, asignar recruiter, actualizar estados | Requisiciones de su país o región |
| Admin / Finanzas | Aprobación final, revisión de presupuesto                | Según permiso asignado            |
| Recruiter        | Actualizar pipeline de reclutamiento                     | Requisiciones asignadas           |
| HR Director      | Dashboard global, auditoría, carga de recruiters         | Global                            |
| Super Admin      | Administración completa del sistema                      | Global                            |

---

## Configuración y Setup

### Requisitos previos

* Node.js v18 o superior.
* pnpm.
* Acceso al repositorio.
* Variables de entorno configuradas.

### Instalación

```bash
pnpm install
```

### Ejecutar en desarrollo

```bash
pnpm run dev
```

El servidor estará disponible en:

```txt
http://localhost:3000
```

### Build de producción

```bash
pnpm run build
```

### Ejecutar build local

```bash
pnpm run start
```

---

## Variables de Entorno

Crear un archivo `.env.local` basado en `.env.example`.

Ejemplo sugerido:

```env
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Base de datos / Backend
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
DATABASE_URL=

# Auth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Automatizaciones
N8N_WEBHOOK_URL=
```

> Nunca commitear credenciales reales al repositorio. Todas las llaves, tokens y secretos deben guardarse en el vault o gestor de credenciales definido por GLM IT.

---

## Estructura del Repositorio

Estructura sugerida:

```txt
portal-requisicion-vacantes/
│
├── README.md
├── .env.example
├── package.json
├── pnpm-lock.yaml
│
├── app/ o src/
│   ├── components/
│   ├── pages/
│   ├── hooks/
│   ├── lib/
│   ├── services/
│   └── styles/
│
├── docs/
│   ├── PRD.md
│   ├── DATABASE_SCHEMA.md
│   ├── WORKFLOW.md
│   └── DECISIONS.md
│
├── supabase/ o backend/
│   ├── migrations/
│   ├── functions/
│   └── seed.sql
│
└── scripts/
    └── migrate-excel-data/
```

---

## Cómo Funciona

### Flujo paso a paso

1. El usuario inicia sesión con Google SSO.
2. El sistema identifica su rol, país y permisos.
3. El solicitante crea una nueva requisición.
4. El sistema guarda la requisición y registra el inicio del SLA.
5. RRHH recibe la solicitud para validación inicial.
6. RRHH aprueba o rechaza.
7. Si RRHH aprueba, Administración recibe la solicitud.
8. Administración aprueba o rechaza.
9. Si Administración aprueba, la requisición pasa a Reclutando.
10. Se asigna recruiter.
11. El recruiter actualiza el avance del pipeline.
12. El dashboard actualiza métricas de SLA, TTF, etapas y carga de trabajo.
13. Al cerrar la requisición, el sistema registra el cierre y actualiza los reportes.

---

## Testing

Casos mínimos de prueba:

| Caso                         | Input                             | Output esperado                           | Estado    |
| ---------------------------- | --------------------------------- | ----------------------------------------- | --------- |
| Crear requisición válida     | Datos completos                   | Requisición creada correctamente          | Pendiente |
| Crear requisición incompleta | Campos obligatorios vacíos        | Validación visible para el usuario        | Pendiente |
| Rechazo por RRHH             | Requisición enviada               | Estado cambia a Correction Required       | Pendiente |
| Aprobación secuencial        | RRHH aprueba                      | Pasa a Pending Administration Approval    | Pendiente |
| Aprobación final             | Administración aprueba            | Pasa a Reclutando                         | Pendiente |
| Cálculo de SLA               | País, ciudad, posición y cantidad | SLA calculado correctamente               | Pendiente |
| Restricción por país         | Usuario de un país                | Solo ve requisiciones permitidas          | Pendiente |
| Audit log                    | Cambio de estado                  | Registro creado en audit_logs             | Pendiente |
| Reasignación de recruiter    | Caso activo                       | Se actualiza recruiter y carga de trabajo | Pendiente |
| Alerta por sobrecarga        | Recruiter con score 26+           | Se muestra alerta crítica                 | Pendiente |

---

## Errores Conocidos y Troubleshooting

| Error                        | Causa probable                          | Solución                                 |
| ---------------------------- | --------------------------------------- | ---------------------------------------- |
| La app no levanta localmente | Dependencias no instaladas              | Ejecutar `pnpm install`                  |
| Puerto ocupado               | Otro proceso usa el puerto 3000         | Cambiar puerto o cerrar proceso          |
| Variables undefined          | `.env.local` incompleto                 | Revisar `.env.example`                   |
| Login falla                  | Google SSO no configurado               | Revisar Client ID, Secret y Redirect URI |
| Datos no cargan              | Backend o base de datos no conectado    | Validar variables y logs                 |
| Build falla                  | Dependencias o configuración incorrecta | Revisar logs de `pnpm run build`         |

---

## Monitoreo Futuro

Cuando el backend esté implementado, monitorear:

* Logs de aplicación.
* Errores de autenticación.
* Fallos de conexión a base de datos.
* Requisiciones vencidas por SLA.
* Notificaciones fallidas.
* Recruiters en estado crítico de carga.
* Acciones registradas en audit log.
* Errores de automatizaciones o webhooks.

---

## Changelog

```txt
[YYYY-MM-DD] v0.1 — Inicio del repositorio y prototipo visual.
[YYYY-MM-DD] v0.2 — Documentación inicial del README.
```

---

## Decisions Log

### DEC-001 — Uso de Next.js para el prototipo

* Fecha: Junio 2026.
* Contexto: Se necesitaba construir rápidamente una base visual para validar el portal.
* Opciones consideradas: Next.js vs React SPA tradicional.
* Decisión: Usar Next.js con React.
* Razón: Permite una estructura escalable, buen rendimiento y facilidad para evolucionar hacia una aplicación completa.

### DEC-002 — SLA inicia desde la creación de la requisición

* Fecha: Junio 2026.
* Contexto: El proceso debe medir el tiempo completo desde que el solicitante crea la requisición.
* Opciones consideradas: Iniciar SLA al crear la requisición vs iniciar SLA cuando Administración aprueba.
* Decisión: El SLA inicia al momento de crear la requisición.
* Razón: Permite medir responsabilidad total del proceso, incluyendo retrasos en aprobaciones.

### DEC-003 — Flujo de aprobación secuencial

* Fecha: Junio 2026.
* Contexto: La requisición debe pasar por validaciones ordenadas.
* Opciones consideradas: Aprobación paralela vs aprobación secuencial.
* Decisión: Usar aprobación secuencial RRHH → Administración.
* Razón: Evita que Administración revise solicitudes que aún no han sido validadas por RRHH.

### DEC-004 — Audit log obligatorio

* Fecha: Junio 2026.
* Contexto: El sistema debe permitir trazabilidad completa del proceso.
* Opciones consideradas: Registrar solo cambios de estado vs registrar todas las acciones importantes.
* Decisión: Registrar cambios de estado, aprobaciones, rechazos, reasignaciones y modificaciones críticas.
* Razón: Permite auditoría, control interno y análisis posterior de errores o retrasos.

### DEC-005 — Recruiter Capacity Score

* Fecha: Junio 2026.
* Contexto: Dirección de RRHH necesita visualizar carga real de trabajo, no solo cantidad de requisiciones.
* Opciones consideradas: Contar requisiciones vs calcular carga por complejidad y volumen.
* Decisión: Calcular carga usando complejidad de posición más multiplicador por volumen.
* Razón: Una requisición de 15 merchandisers no representa el mismo esfuerzo que una requisición de 1 posición administrativa.

---

## Contactos del Proyecto

| Rol           | Nombre        | Contacto    |
| ------------- | ------------- | ----------- |
| Product Owner | Máximo Gomez  | A completar |
| IT Manager    | Luis Matos    | A completar |
| Developer     | Isaac Aracena | A completar |

---

## Definition of Done

* README completo y actualizado.
* PRD documentado en `/docs`.
* Variables de entorno documentadas en `.env.example`.
* Prototipo funcional en ambiente local.
* Flujo principal validado con usuarios clave.
* Backend definido o implementado según alcance aprobado.
* Esquema de base de datos documentado.
* Reglas de negocio documentadas.
* Casos básicos de prueba ejecutados.
* Código commiteado y pusheado al repositorio.
* Validación final del Product Owner.
* Validación final de IT Manager.
* Probado en ambiente real, no solo local.

---

## Notas Finales

Este repositorio representa la base inicial del Portal de Requisición de Vacantes. Aunque actualmente el proyecto se encuentra en fase de prototipo, la documentación está preparada para evolucionar hacia una aplicación completa con backend, base de datos, autenticación, permisos, auditoría, SLA dinámico y dashboard operativo para RRHH.