From 662cffda463cb7ae4845a8e0948b6e1d2001e2d0 Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Sat, 8 Aug 2026 16:27:44 +0000 Subject: [PATCH] Subir archivos a "/" --- README(20260808-160530).md | 613 +++++++++++++++++++++++++++++++++++++ 1 file changed, 613 insertions(+) create mode 100644 README(20260808-160530).md diff --git a/README(20260808-160530).md b/README(20260808-160530).md new file mode 100644 index 0000000..02030b2 --- /dev/null +++ b/README(20260808-160530).md @@ -0,0 +1,613 @@ +# Cruces de Seguridad Social + +> Repositorio centralizado de workflows de n8n para automatizar los cruces mensuales de Seguridad Social entre nómina, entidades locales y BambooHR en los distintos países de GomezLee Marketing. + +--- + +## INFORMACIÓN GENERAL + +| Campo | Detalle | +|---|---| +| **Proyecto** | Cruces de Seguridad Social | +| **Área** | Administración / Recursos Humanos / IT | +| **Estado** | En producción / mantenimiento evolutivo | +| **Developer Principal** | Isaac Aracena | +| **IT Manager** | Luis Matos | +| **Organización** | GomezLee Marketing | +| **Tecnología principal** | n8n | +| **Repositorio** | `cruces-seguridad-social` | +| **Países implementados** | Guatemala, Honduras, República Dominicana, Costa Rica y El Salvador | +| **Fecha de inicio** | 2026 | +| **Fecha de cierre estimada** | Proyecto evolutivo | +| **Ciclo Shape Up** | No documentado | +| **Board de ejecución** | No documentado | +| **PRD del proyecto** | No documentado | + +--- + +## OBJETIVO + +### Problema que resuelve + +La validación mensual de Seguridad Social requiere comparar manualmente la información de nómina de GomezLee Marketing contra los archivos oficiales o soportes utilizados por las entidades de Seguridad Social de cada país. + +Este proceso implica revisar, según el país: + +- Que todos los empleados presentes en nómina aparezcan en Seguridad Social. +- Que no existan personas reportadas en Seguridad Social que no estén en nómina. +- Diferencias de cédula, DUI, identidad u otros documentos. +- Diferencias de nombres y apellidos. +- Diferencias entre montos reportados o descontados. +- Casos especiales presentes en estructuras auxiliares de la nómina. +- Empleados presentes en nómina que no se encuentran claramente en BambooHR. +- Estado laboral y fecha de ingreso de empleados que requieren revisión. + +La revisión manual consume tiempo, depende de múltiples formatos y aumenta el riesgo de errores humanos. + +### Solución implementada + +Se desarrolló una colección centralizada de workflows independientes en **n8n**, uno por país, que recibe los documentos mensuales mediante formularios, interpreta los formatos reales utilizados por cada operación, normaliza los datos y genera automáticamente los cruces y reportes requeridos. + +Los workflows automatizan, según el país: + +- Cruce de identidad. +- Cruce de montos. +- Detección de empleados presentes únicamente en una fuente. +- Detección de identificadores distintos. +- Comparación robusta de nombres. +- Consulta de BambooHR. +- Generación de la hoja `Nómina sin BambooHR`. +- Generación y formato de reportes. +- Compartición automática de archivos. +- Envío de correos HTML con branding GLM. +- Auditoría de ejecuciones y hallazgos. +- Manejo controlado de errores. +- Retorno al formulario para realizar otro cruce. + +### Usuarios / Beneficiarios + +- Administración. +- Recursos Humanos. +- Responsables de nómina. +- Equipo IT. +- Personal encargado de validar obligaciones de Seguridad Social. + +--- + +## ARQUITECTURA + +### Diagrama de flujo general + +```text +[n8n Form] + ↓ +[Selección de período] + ↓ +[Carga de Nómina + Seguridad Social] + ↓ +[Validación de archivos] + ↓ +[Lectura y normalización] + ↓ +[Consulta BambooHR] + ↓ +[Cruce de Identidad] + ↓ +[Cruce de Montos] + ↓ +[Detección de Hallazgos] + ↓ +[Generación de Reporte] + ↓ +[Google Sheets / Google Drive] + ↓ +[Compartición de permisos] + ↓ +[Correo HTML GLM] + ↓ +[Auditoría] + ↓ +[Resultado final / Realizar otro cruce] +``` + +### Stack tecnológico + +| Componente | Tecnología | Propósito | +|---|---|---| +| Automatización | n8n | Orquestación completa de los procesos | +| Formularios | n8n Forms | Recepción mensual de documentos | +| RRHH | BambooHR API | Consulta de empleados | +| Reportes | Google Sheets API | Generación y formato de reportes | +| Archivos | Google Drive API | Almacenamiento y permisos | +| Notificaciones | Gmail OAuth | Envío de correos | +| Auditoría | Supabase / REST API | Registro de ejecuciones, archivos y hallazgos | +| Infraestructura | Servidor GLM / DigitalCompass | Hosting de n8n y formularios | + +### Integraciones externas + +| Sistema | Tipo de integración | Datos que fluyen | +|---|---|---| +| BambooHR | API REST | Nombre, estado, fecha de ingreso y datos laborales | +| Google Sheets | REST API / OAuth | Creación, escritura y formato de reportes | +| Google Drive | OAuth | Archivos, almacenamiento y permisos | +| Gmail | OAuth | Correos de resultados | +| Supabase | REST API | Auditoría de ejecuciones y hallazgos | +| n8n Forms | Form Trigger | Parámetros y documentos del usuario | + +--- + +## PAÍSES IMPLEMENTADOS + +### 🇬🇹 Guatemala + +Archivo: + +```text +Cruce de Seguridad Social - Guatemala.json +``` + +Automatiza el cruce mensual de Seguridad Social para Guatemala, incluyendo validaciones de identidad, diferencias entre fuentes, consulta complementaria de BambooHR y generación automatizada del reporte. + +### 🇭🇳 Honduras + +Archivo: + +```text +Cruce de Seguridad Social - Honduras.json +``` + +El formulario recibe el mes a validar, una o varias planillas IHSS en PDF y la nómina mensual. El workflow procesa identidades extraídas de las planillas IHSS, hojas válidas de la nómina, la hoja `IHSS-RAP`, personal especial cuando existe, cruce de identidad, cruce de montos IHSS, BambooHR, Nómina sin BambooHR, reporte final, permisos, correo y auditoría. + +### 🇩🇴 República Dominicana + +Archivo: + +```text +Cruce de Seguridad Social - República Dominicana.json +``` + +Procesa la nómina mensual contra los archivos oficiales de TSS y fue adaptado para trabajar directamente con el formato real utilizado por los archivos recibidos mensualmente, evitando depender de una preparación manual previa. + +Incluye solo en Nómina, solo en TSS, cruces de identidad y montos, información BambooHR, Nómina sin BambooHR, reporte en Google Sheets, correo y permisos automáticos. + +### 🇨🇷 Costa Rica + +Archivo: + +```text +Cruce de Seguridad Social - Costa Rica.json +``` + +Procesa la nómina mensual y la planilla oficial CCSS. Incluye cruce de presencia Nómina ↔ CCSS, validación de cédulas, comparación robusta de nombres, cruce de montos por empleado, conciliación de totales, validación del período, BambooHR, Nómina sin BambooHR y reporte con formato GLM. + +El lector de PDF de CCSS incluye controles para evitar generar reportes cuando la extracción del documento queda desalineada. + +### 🇸🇻 El Salvador + +Archivo: + +```text +Cruce de Seguridad Social - El Salvador.json +``` + +Procesa nómina y Planilla Única en Excel. El workflow contempla archivos históricos donde la hoja de nómina no siempre utiliza el mismo nombre, pudiendo resolver estructuras como `Nomina`, `FEBRERO`, `MARZO` o `Nómina` según el archivo recibido. + +Incluye cruce de DUI, nombres, posible mismo empleado con DUI diferente, montos, BambooHR, generación del Excel final, Google Drive, permisos, correo HTML, manejo de errores y botón para realizar otro cruce. + +--- + +## REGLAS DE NEGOCIO + +1. La nómina y los documentos de Seguridad Social deben corresponder al mismo período. +2. Cuando existe un identificador oficial confiable en ambas fuentes, este tiene prioridad sobre el nombre. +3. Los nombres deben normalizarse antes de comparar: mayúsculas/minúsculas, acentos, espacios, nombres adicionales y variaciones razonables de escritura. +4. Una coincidencia aproximada no debe aceptarse automáticamente cuando existan varios candidatos con similitud equivalente. +5. El cruce debe hacerse en ambos sentidos: `Nómina → Seguridad Social` y `Seguridad Social → Nómina`. +6. Las personas presentes únicamente en una fuente deben quedar identificadas como hallazgo. +7. Los empleados que requieran validación pueden complementarse con estado en BambooHR, fecha de ingreso y nombre registrado en BambooHR. +8. `Nómina sin BambooHR` debe contener exclusivamente empleados sin una coincidencia suficientemente confiable. +9. Los workflows deben tolerar variaciones ortográficas razonables sin producir falsos negativos. +10. Los reportes deben priorizar diferencias y hallazgos en lugar de llenar las hojas con registros que ya coinciden. +11. Las diferencias de montos deben considerar el redondeo correspondiente antes de marcar un caso como error. +12. Si la lectura del documento no es suficientemente confiable, el workflow debe detenerse antes de generar un reporte potencialmente incorrecto. +13. Un mismo documento cargado más de una vez no debe duplicar empleados ni montos. +14. Los reportes solo deben compartirse con los usuarios autorizados configurados para cada país. +15. Las credenciales nunca deben almacenarse directamente en el repositorio. + +--- + +## CONFIGURACIÓN Y SETUP + +### Prerrequisitos + +Se requiere acceso a: + +- n8n de GomezLee Marketing. +- BambooHR. +- Google Workspace. +- Google Drive. +- Google Sheets. +- Gmail. +- Supabase cuando el workflow utilice auditoría. +- Credenciales correspondientes configuradas en n8n. + +### Credenciales + +Las credenciales se administran desde el **Credential Manager de n8n**. + +Integraciones habituales: + +```text +BambooHR GLM Full Access +Google Drive OAuth +Google Sheets OAuth +Gmail OAuth +Supabase / REST API +``` + +Los nombres concretos pueden variar según el workflow. + +> **NUNCA commitear API Keys, passwords, tokens OAuth, secretos, service-account keys ni archivos de credenciales al repositorio.** + +### Variables de entorno + +Actualmente la mayor parte de las integraciones utiliza credenciales almacenadas directamente en n8n. Cuando un endpoint o secreto sea externalizado deberá documentarse mediante `.env.example`. + +Ejemplo: + +```env +N8N_BASE_URL= +SUPABASE_URL= +SUPABASE_ANON_KEY= +``` + +Los valores reales nunca deben almacenarse en Git. + +### Esquema de base de datos + +No existe un schema SQL único para todo el repositorio. Los workflows que utilizan Supabase consumen las estructuras de auditoría configuradas en la infraestructura de GLM. + +--- + +## INSTALACIÓN / DEPLOY + +Clonar el repositorio: + +```bash +git clone /Isaac_Aracena/cruces-seguridad-social.git +cd cruces-seguridad-social +``` + +Importar el workflow requerido desde n8n: + +```text +n8n +→ Workflows +→ Import from File +→ Seleccionar el JSON del país +``` + +Ejemplo: + +```text +Cruce de Seguridad Social - Honduras.json +``` + +Después de importar: + +1. Revisar las credenciales. +2. Confirmar IDs de Google Drive / Google Sheets utilizados. +3. Revisar destinatarios. +4. Confirmar URLs de producción del formulario. +5. Publicar el workflow. +6. Ejecutar una prueba con archivos reales. + +--- + +## CÓMO FUNCIONA + +### Flujo paso a paso + +1. **Trigger:** un usuario envía el formulario n8n del país correspondiente. +2. **Inicialización:** se genera un identificador de ejecución, se guarda el período y se inicializa la memoria temporal. +3. **Lectura de documentos:** los archivos son clasificados y procesados con la lógica específica del país. +4. **Normalización:** se normalizan identidades, DUI, cédulas, nombres, montos, fechas y estados. +5. **BambooHR:** los workflows que necesitan información laboral consultan BambooHR; cuando se requieren empleados históricos se utiliza `onlyCurrent=false`. +6. **Cruce de identidad:** se identifican coincidencias, solo nómina, solo Seguridad Social y diferencias de identidad. +7. **Cruce de montos:** los valores son conciliados según las reglas específicas del país. +8. **Reporte:** se genera el reporte final con formato GLM. +9. **Permisos:** el archivo se comparte con los usuarios autorizados. +10. **Correo:** se envía un correo HTML con branding GomezLee Marketing. +11. **Auditoría:** los workflows que utilizan Supabase registran la ejecución, archivos y hallazgos. +12. **Output:** la pantalla final permite regresar al formulario mediante el botón `Realizar otro cruce`. + +### Schedules / Triggers + +| Trigger | Frecuencia | Descripción | +|---|---|---| +| n8n Form Trigger | Bajo demanda | Administración ejecuta el cruce mensual correspondiente | + +Los workflows no dependen de un Cron para su ejecución normal. + +--- + +## TESTING + +### Casos de prueba mínimos + +| Caso | Input | Output esperado | Estado | +|---|---|---|---| +| Caso feliz | Documentos correctos del mismo período | Reporte generado | ✅ | +| Sin diferencias | Fuentes conciliadas | Sin hallazgos materiales | ✅ | +| Solo Nómina | Empleado faltante en Seguridad Social | Hallazgo visible | ✅ | +| Solo Seguridad Social | Persona inexistente en Nómina | Hallazgo visible | ✅ | +| Documento diferente | Misma persona con identificador distinto | Caso para revisión | ✅ | +| Diferencia ortográfica menor | Nombre equivalente | No generar falso faltante | ✅ | +| Nombre adicional | Misma identidad | Coincidencia válida | ✅ | +| Monto diferente | Valores distintos | Diferencia visible | ✅ | +| Diferencia de redondeo | Diferencia mínima | Aplicar tolerancia | ✅ | +| No encontrado en BambooHR | Empleado sin match | Nómina sin BambooHR | ✅ | +| Empleado inactivo | Registro histórico BambooHR | Mostrar Inactivo | ✅ | +| Archivo incorrecto | Formato o período inválido | Error controlado | ✅ | +| Documento duplicado | Archivo repetido | No duplicar resultados | ✅ | +| API externa no disponible | Timeout/error | Error controlado / retry | ✅ | + +--- + +## ERRORES CONOCIDOS Y TROUBLESHOOTING + +| Error | Causa probable | Solución | +|---|---|---| +| `Spreadsheet does not contain sheet called "Nomina"` | Archivo histórico utiliza otro nombre de hoja | Usar la detección dinámica de hojas implementada | +| `binary file 'data' ... none was found` | Una rama de fallback perdió el binario original | Recuperar el archivo original antes del siguiente intento | +| Empleado no encontrado en BambooHR | Variación de nombre | Revisar matching y consulta `onlyCurrent=false` | +| Muchos casos Solo Nómina / Solo SS | Lectura desalineada | Revisar el extractor antes de cambiar el cruce | +| Diferencia de pocos centavos | Redondeo | Revisar tolerancia y cálculo por empleado | +| PDF sin empleados | Documento escaneado o texto no extraíble | Revisar calidad y formato del PDF | +| Botón `Realizar otro cruce` falla | URL relativa o webhook incorrecto | Usar Production URL completa | +| Gmail no envía | Credencial OAuth | Revisar credencial y nodo de envío | +| Error de permisos Drive | Usuario o credencial sin acceso | Revisar credencial y propiedad del archivo | +| Timeout BambooHR | API lenta | Retry + timeout extendido | + +--- + +## MONITOREO + +### n8n Executions + +Revisar: + +```text +n8n → Workflow → Executions +``` + +Referencia: + +```text +Verde = ejecución exitosa +Rojo = ejecución fallida +``` + +Cuando exista un error debe identificarse primero el nodo exacto que falla antes de modificar la lógica global. + +### Auditoría Supabase + +Cuando está habilitada puede registrar: + +- Ejecución. +- País. +- Período. +- Archivos procesados. +- Hallazgos. +- Estado final. +- Métricas de resultado. + +### Output esperado + +Una ejecución normal debe finalizar con: + +- Cruces completados. +- Reporte generado. +- Archivo compartido. +- Correo enviado. +- Auditoría registrada cuando aplica. +- Página final disponible para realizar otro cruce. + +--- + +## ESTRUCTURA DEL REPOSITORIO + +```text +/cruces-seguridad-social +│ +├── README.md +│ +├── Cruce de Seguridad Social - Costa Rica.json +├── Cruce de Seguridad Social - El Salvador.json +├── Cruce de Seguridad Social - Guatemala.json +├── Cruce de Seguridad Social - Honduras.json +└── Cruce de Seguridad Social - República Dominicana.json +``` + +Cada JSON debe representar la **última versión estable del workflow del país correspondiente**. + +--- + +## CONVENCIÓN DE ACTUALIZACIÓN + +Después de realizar cambios en producción: + +```bash +git add "Cruce de Seguridad Social - Honduras.json" +git commit -m "Actualizar Cruce de Seguridad Social - Honduras" +git push origin main +``` + +Proceso recomendado: + +1. Validar el workflow en n8n. +2. Ejecutar una prueba real. +3. Exportar el JSON. +4. Reemplazar únicamente el archivo del país correspondiente. +5. Verificar que el JSON no incluya secretos. +6. Hacer commit. +7. Hacer push a Gitea. + +--- + +## CHANGELOG + +### 2026-08 — Consolidación del repositorio + +- Centralización de los workflows de Seguridad Social. +- Guatemala incorporado. +- Honduras incorporado. +- República Dominicana incorporado. +- Costa Rica incorporado. +- El Salvador incorporado. +- Integración BambooHR. +- Formularios mensuales. +- Reportes automatizados. +- Correos HTML GLM. +- Compartición automática. +- Auditoría Supabase en los workflows aplicables. + +### Costa Rica + +- Lectura robusta de los PDF oficiales de CCSS. +- Validación de período. +- Cruce de identidad y montos. +- Conciliación de totales. +- Matching robusto BambooHR. +- Nómina sin BambooHR. +- Formato optimizado del reporte. + +### El Salvador + +- Soporte para nóminas históricas con nombres de hoja variables. +- Preservación del binario entre intentos de lectura. +- Cruce DUI y montos. +- Matching BambooHR. +- Google Drive, permisos y correo final. +- Manejo de errores. +- Botón para realizar otro cruce. + +### Honduras + +- Lectura de múltiples planillas IHSS PDF. +- Procesamiento dinámico de hojas de nómina. +- Lectura de IHSS-RAP. +- Manejo de personal especial. +- Cruce de identidad y montos IHSS. +- BambooHR. +- Nómina sin BambooHR. +- Auditoría. + +### República Dominicana + +- Lectura del formato real de TSS. +- Cruce Nómina vs. TSS. +- Información BambooHR en diferencias. +- Nómina sin BambooHR. +- Formulario reutilizable mensualmente. + +--- + +## DECISIONS LOG + +### DEC-001 — Repositorio centralizado por dominio + +- **Fecha:** 2026 +- **Contexto:** los cruces de Seguridad Social utilizan una misma finalidad de negocio, pero existen múltiples implementaciones por país. +- **Opciones consideradas:** un repositorio por país vs. un repositorio centralizado. +- **Decisión:** mantener todos los workflows dentro del repositorio `cruces-seguridad-social`. +- **Razón:** facilita versionado, mantenimiento, documentación y expansión a nuevos países. + +### DEC-002 — Workflow independiente por país + +- **Fecha:** 2026 +- **Contexto:** cada institución utiliza documentos y estructuras distintas. +- **Opciones consideradas:** un único workflow universal vs. un workflow especializado por país. +- **Decisión:** mantener un JSON independiente por país. +- **Razón:** reduce el riesgo de que cambios realizados para una institución afecten las demás. + +### DEC-003 — Procesar documentos originales + +- **Fecha:** 2026 +- **Contexto:** algunos documentos anteriormente necesitaban preparación manual antes de ser procesados. +- **Opciones consideradas:** seguir modificando documentos manualmente vs. adaptar los workflows. +- **Decisión:** los workflows deben leer directamente los archivos en el formato real en que serán utilizados cada mes. +- **Razón:** Administración debe poder ejecutar el formulario sin depender de IT para modificar previamente los documentos. + +### DEC-004 — BambooHR como fuente complementaria + +- **Fecha:** 2026 +- **Contexto:** algunos hallazgos necesitan información adicional del empleado. +- **Opciones consideradas:** revisión manual en BambooHR vs. consulta automática. +- **Decisión:** utilizar BambooHR para complementar los cruces. +- **Razón:** permite conocer si un empleado existe, su estado, fecha de ingreso y nombre oficial. + +### DEC-005 — Matching conservador de identidad + +- **Fecha:** 2026 +- **Contexto:** los nombres pueden presentar errores ortográficos o variaciones entre fuentes. +- **Opciones consideradas:** matching estricto vs. matching aproximado sin control vs. matching aproximado conservador. +- **Decisión:** permitir variaciones razonables, pero no aceptar coincidencias ambiguas automáticamente. +- **Razón:** es preferible enviar un caso a revisión que asociar incorrectamente dos empleados distintos. + +--- + +## CONTACTOS DEL PROYECTO + +| Rol | Nombre | Contacto | +|---|---|---| +| IT Manager | Luis Matos | Interno GLM | +| Developer Principal | Isaac Aracena | `iaracena@gomezleemarketing.com` | +| Área usuaria | Administración / Recursos Humanos | Interno GLM | + +--- + +## DEFINITION OF DONE + +Un workflow de Seguridad Social se considera listo cuando: + +- [x] El formulario funciona. +- [x] Los documentos originales pueden cargarse sin preparación manual. +- [x] El cruce de identidad funciona. +- [x] El cruce de montos funciona. +- [x] Se analizan ambas direcciones del cruce. +- [x] BambooHR está integrado cuando corresponde. +- [x] Nómina sin BambooHR está disponible cuando aplica. +- [x] El reporte tiene formato legible. +- [x] Los usuarios autorizados reciben acceso. +- [x] El correo de resultado funciona. +- [x] Existe manejo de errores. +- [x] Se puede regresar al formulario. +- [x] El workflow fue probado con archivos reales. +- [x] El JSON estable está almacenado en Gitea. +- [x] El README está actualizado. + +--- + +## SEGURIDAD + +Este repositorio no debe contener secretos. + +Nunca incluir: + +```text +Passwords +API Keys +OAuth Client Secrets +Service Account Keys +Access Tokens +Refresh Tokens +Credenciales BambooHR +Credenciales Supabase +``` + +Todas las credenciales deben permanecer dentro del Credential Manager de n8n o de la infraestructura segura definida por GLM IT. + +--- + +> Documento mantenido por el equipo **GLM IT**.