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
Product Owner	Máximo Gómez

---

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

Usuario
  ↓
Portal Web Next.js
  ↓
Prototipo Frontend

Arquitectura objetivo

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

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

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

Estados sugeridos para el pipeline de reclutamiento

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:

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

Modelo recomendado:

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

Ejemplo:

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

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

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:

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:

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:

id
requisition_id
user_id
action
old_value
new_value
created_at

Tabla de SLA: sla_rules

Campos sugeridos:

id
country_id
city_id
position_id
base_days
incremental_factor
created_at
updated_at

Tabla de feriados: public_holidays

Campos sugeridos:

id
country_id
holiday_date
holiday_name
created_at

Tabla de asignaciones: recruiter_assignments

Campos sugeridos:

id
requisition_id
recruiter_id
assigned_by
assigned_at
is_active

Tabla de historial de asignaciones: requisition_assignment_history

Campos sugeridos:

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.

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

pnpm install

Ejecutar en desarrollo

pnpm run dev

El servidor estará disponible en:

http://localhost:3000

Build de producción

pnpm run build

Ejecutar build local

pnpm run start

---

Variables de Entorno

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

Ejemplo sugerido:

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:

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

[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.