Subir archivos a "/"

2026-08-08 16:27:44 +00:00
parent 43bc22db27
commit 662cffda46
1 changed files with 613 additions and 0 deletions
@@ -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 <URL_GITEA>/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**.