From d675e914b7774add2cb4bd58196693e080440255 Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Fri, 12 Jun 2026 20:31:25 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 765 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 745 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 325bea5..3c349bf 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,754 @@ -# Portal Requisición Vacantes +# Portal Requisición de Vacantes -Portal web para la requisición y gestión de vacantes. Desarrollado con Next.js y React. +> Portal web interno para solicitar, aprobar y dar seguimiento a requisiciones de vacantes, centralizando el flujo de RRHH, Administración y Reclutamiento. -## Características +--- -- Interfaz moderna y responsive -- Gestión de ciclo de reclutamiento (Recruitment Pipeline) -- Integración con base de datos y backend -- Construido con buenas prácticas y componentes reutilizables +## Información General -## Requisitos previos +| 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 | -- Node.js (v18 o superior) -- pnpm +--- -## Instalación y ejecución +## Objetivo -1. Instalar dependencias: - ```bash - pnpm install - ``` +### Problema que resuelve -2. Ejecutar el servidor de desarrollo: - ```bash - pnpm run dev - ``` +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. -El servidor estará disponible en `http://localhost:3000`. +### 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.