From 6e0f58823b8fcdb6cea3525d779dce88eddf04bf Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Thu, 16 Jul 2026 00:14:40 +0000 Subject: [PATCH] =?UTF-8?q?A=C3=B1adir=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 597 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 597 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..85ff5d0 --- /dev/null +++ b/README.md @@ -0,0 +1,597 @@ +# Cálculo de IR — Nicaragua + +> Automatización mensual que procesa las nóminas de primera y segunda quincena, recalcula el Impuesto sobre la Renta de cada empleado, identifica diferencias y genera una memoria de cálculo completa para Administración. + +--- + +## Información general + +| Campo | Detalle | +|---|---| +| **Proyecto** | Cálculo de IR — Nicaragua | +| **Área** | Administración / Nómina | +| **Estado** | Listo para producción | +| **Developer principal** | Isaac Aracena | +| **Product Owner / Sponsor** | Máximo Gomez | +| **IT Manager** | Luis Matos | +| **Fecha de inicio** | 2026-07-10 | +| **Fecha de cierre técnico** | 2026-07-15 | +| **Tipo de iniciativa** | Automatización operativa mensual | +| **Board de ejecución** | [Kan.bn — IR Nicaragua](https://pmit.digitalcompass.agency/cards/z7ms5z0ciw1k) | +| **Repositorio** | [Gitea — ir-nicaragua](https://git.digitalcompass.agency/Isaac_Aracena/ir-nicaragua) | +| **Workflow principal** | `Cálculo de IR - Nicaragua.json` | +| **Workflow auxiliar** | Limpieza de archivos temporales de IR Nicaragua | + +--- + +## Objetivo + +### Problema que resuelve + +Administración de Nicaragua utilizaba una memoria de cálculo de Excel para validar el IR mensual, pero debía copiar manualmente la información de cada empleado desde las nóminas de primera y segunda quincena. Aunque el Excel contenía las fórmulas fiscales, la digitación empleado por empleado consumía demasiado tiempo, aumentaba el riesgo de errores y dificultaba revisar oportunamente las diferencias del sistema de nómina. + +### Solución implementada + +El sistema presenta un formulario en n8n donde Administración selecciona el mes y el año, adjunta las dos nóminas en formato `.xlsx` y ejecuta la validación. El workflow lee automáticamente todas las pestañas operativas, cruza a los empleados, recalcula el IR, genera una memoria completa en Google Sheets y Excel, crea una pestaña exclusiva de diferencias y envía un resumen por correo. + +### Usuarios y beneficiarios + +- Administración de GomezLee Marketing Nicaragua. +- Personal responsable de validar nómina e IR. +- Recursos Humanos. +- Dirección administrativa. +- Dirección de Recursos Humanos. +- Equipo de IT que monitorea la automatización. + +--- + +## Arquitectura + +### Diagrama general + +```text +Formulario n8n + | + |-- Mes + |-- Año + |-- Nómina Q1 (.xlsx) + `-- Nómina Q2 (.xlsx) + | + v +Conversión temporal de XLSX a Google Sheets + | + v +Lectura de todas las pestañas operativas + | + v +Normalización y cruce de empleados + | + v +Recalculo independiente del IR + | + v +Creación de memoria de cálculo + |-- MEMORIA DE CALCULO + `-- DIFERENCIAS + | + +--> Compartir Google Sheet + +--> Exportar copia XLSX + +--> Enviar correo HTML + `--> Eliminar archivos temporales +``` + +### Stack tecnológico + +| Componente | Tecnología | Propósito | +|---|---|---| +| Automatización | n8n self-hosted | Orquestación del proceso | +| Interfaz de entrada | n8n Form Trigger | Recepción de período y archivos | +| Procesamiento | JavaScript nativo en Code nodes | Lectura lógica, normalización, cruce y cálculo | +| Conversión de archivos | Google Drive API | Conversión temporal de XLSX a Google Sheets | +| Lectura y escritura | Google Sheets API | Lectura multih hoja, fórmulas, formato y reporte | +| Notificaciones | Gmail OAuth2 | Envío del correo HTML y del Excel adjunto | +| Almacenamiento temporal | Google Drive | Archivos temporales durante la ejecución | +| Infraestructura | Servidor corporativo GLM | Hosting de n8n | +| Base de datos | No aplica | El flujo no requiere base de datos | + +### Integraciones externas + +| Sistema | Tipo de integración | Datos que fluyen | +|---|---|---| +| Google Drive | OAuth2 / REST API | Carga, conversión, exportación, permisos y eliminación | +| Google Sheets | OAuth2 / REST API | Lectura de pestañas, escritura, fórmulas y formato | +| Gmail | OAuth2 | Correo HTML y archivo Excel adjunto | +| n8n Form | Trigger web | Mes, año y nóminas Q1/Q2 | + +--- + +## Reglas de negocio + +### Archivos de entrada + +1. El formulario exige dos archivos: nómina de primera quincena y nómina de segunda quincena. +2. Ambos archivos deben estar en formato `.xlsx`. +3. Los dos libros deben corresponder al mismo mes y año seleccionados. +4. La validación del período se realiza con el contenido de cada pestaña, no únicamente con el nombre del archivo. +5. El archivo Q1 admite hojas con período del día 1 al 15. +6. El archivo Q2 admite hojas del día 16 al 28, 29, 30 o 31 y hojas mensuales del día 1 al 28, 29, 30 o 31. +7. Se excluyen automáticamente resúmenes, hojas auxiliares, copias de otros períodos, filas de totales y notas administrativas. + +### Fuente monetaria para el cálculo + +La fuente principal es la columna **Salario INSS**, porque representa el ingreso bruto sujeto a INSS antes de descontar el 7 %. + +Cuando `Salario INSS` está vacío, se aplican los siguientes respaldos: + +1. `Salario IR / 0.93`. +2. `INSS Laboral / 0.07`. +3. El registro se marca como dato derivado o incompleto. + +No se utiliza `Total Ingresos` como fuente principal, porque puede incluir subsidios u otros conceptos no sujetos a INSS o IR. + +### Cruce de empleados + +El orden de coincidencia es: + +1. Cédula normalizada. +2. Número de INSS válido. +3. Nombre normalizado. + +El empleado no necesita permanecer en la misma hoja, proyecto o cliente entre las dos quincenas. + +### Cálculo para personal quincenal + +```text +Ingreso sujeto mensual = Salario INSS Q1 + Salario INSS Q2 +INSS laboral = Ingreso sujeto mensual × 7 % +Base imponible = Ingreso sujeto mensual − INSS laboral +Proyección anual = Base imponible × 12 +``` + +A la proyección anual se le aplica la tabla progresiva del IR de Nicaragua. + +### Cálculo para personal mensual + +Para empleados incluidos en una hoja mensual dentro del archivo Q2: + +```text +Ingreso sujeto mensual = Salario INSS mensual de Q2 +``` + +No se busca una pareja en Q1 porque el valor de Q2 ya representa el mes completo. + +### Tabla fiscal aplicada + +| Renta anual | Porcentaje | Impuesto base | Exceso sobre | +|---:|---:|---:|---:| +| Hasta C$100,000.00 | 0 % | C$0.00 | C$0.00 | +| C$100,000.01 a C$200,000.00 | 15 % | C$0.00 | C$100,000.00 | +| C$200,000.01 a C$350,000.00 | 20 % | C$15,000.00 | C$200,000.00 | +| C$350,000.01 a C$500,000.00 | 25 % | C$45,000.00 | C$350,000.00 | +| Más de C$500,000.00 | 30 % | C$82,500.00 | C$500,000.00 | + +### Comparación + +```text +Diferencia = IR registrado en nómina Q2 − IR esperado +``` + +- Resultado negativo: la nómina retuvo menos IR del esperado. +- Resultado positivo: la nómina retuvo más IR del esperado. +- Diferencia absoluta menor o igual a C$1.00: tolerancia de redondeo. +- Diferencia absoluta mayor a C$1.00: diferencia material. + +### Estados del reporte + +| Estado | Significado | +|---|---| +| `VALIDADO` | El IR se encuentra dentro de la tolerancia | +| `DIFERENCIA IR` | Existe una diferencia material mayor a C$1.00 | +| `SOLO EN 1RA QUINCENA` | El empleado no aparece en Q2 | +| `SOLO EN 2DA QUINCENA` | El empleado no aparece en Q1 | +| `DATO DERIVADO` | Se utilizó un respaldo o el cruce fue por nombre | +| `DATO INCOMPLETO` | No fue posible obtener toda la información requerida | + +Los empleados presentes en una sola quincena se muestran como **No comparables**; el flujo no presenta un cálculo parcial como si fuera una validación mensual completa. + +### Colores del reporte + +- **Rojo:** diferencia material de IR. +- **Amarillo:** empleado presente en una sola quincena. +- **Naranja:** dato incompleto. +- **Azul:** dato derivado o emparejamiento por nombre. +- **Sin alerta:** empleado validado. + +--- + +## Reportes generados + +### Pestaña `MEMORIA DE CALCULO` + +Contiene a todos los empleados identificados y conserva la estructura de la memoria original: + +- NSS, cédula, nombres, cargo, empresa y departamento. +- Salario contractual, primera quincena y segunda quincena. +- Total, INSS, base imponible y proyección anual. +- Exceso, diferencia, porcentaje e impuesto base. +- IR anual, IR mensual e IR quincenal. + +La tabla fiscal y las columnas técnicas se mantienen ocultas para facilitar la lectura. + +### Pestaña `DIFERENCIAS` + +Muestra únicamente registros que requieren atención: + +- Diferencias materiales. +- Empleados presentes en una sola quincena. +- Datos derivados. +- Datos incompletos. + +Incluye IR esperado, IR de nómina, diferencia, estado, interpretación, observación, hojas de origen y método de cruce. + +### Correo HTML + +El correo incluye: + +- Branding y logo de GomezLee Marketing. +- Período procesado. +- Empleados Q1, Q2 y emparejados. +- Diferencias materiales. +- Empleados presentes en una sola quincena. +- Datos por revisar. +- Tabla con las principales diferencias. +- Botón para abrir el Google Sheet. +- Copia del reporte en formato Excel. + +--- + +## Destinatarios y permisos + +El correo y el acceso de edición al Google Sheet se asignan a: + +| Nombre | Correo | +|---|---| +| Isaac Aracena | `iaracena@gomezleemarketing.com` | +| Estefani Orozco | `administrativo@gomezleemarketing.com` | +| Angie Carolina Chavez Silva | `administrativonicaragua@gomezleemarketing.com` | +| Mati Soto Valenzuela | `msoto@gomezleemarketing.com` | +| Iveth Herrera | `iherrera@gomezleemarketing.com` | +| Máximo Gomez | `mgomez@gomezleemarketing.com` | + +No existe modo de prueba en la versión de producción. Cada ejecución envía el correo y comparte el documento con las seis personas configuradas. + +--- + +## Configuración y setup + +### Prerrequisitos + +- Acceso al servidor corporativo de n8n. +- Google Drive API habilitada. +- Google Sheets API habilitada. +- Credencial OAuth2 de Google Drive en n8n. +- Credencial OAuth2 de Google Sheets en n8n. +- Credencial OAuth2 de Gmail en n8n. +- Permisos de Google Workspace para crear, compartir y eliminar archivos. + +### Credenciales requeridas + +| Credencial | Uso | +|---|---| +| Google Drive OAuth2 | Conversión, exportación, permisos y eliminación | +| Google Sheets OAuth2 | Lectura, escritura, fórmulas y formato | +| Gmail OAuth2 | Envío del correo y adjunto | + +> Nunca incluir tokens, secretos OAuth ni contraseñas en el repositorio. + +### Variables de entorno + +El proyecto no requiere variables de entorno adicionales ni cambios al servidor. + +No necesita ExcelJS, `require()`, `NODE_FUNCTION_ALLOW_EXTERNAL`, Dockerfile personalizado ni paquetes npm externos. + +### Instalación + +```bash +git clone https://git.digitalcompass.agency/Isaac_Aracena/ir-nicaragua.git +cd ir-nicaragua +``` + +1. Abrir n8n. +2. Ir a **Workflows**. +3. Seleccionar **Import from File**. +4. Importar `Cálculo de IR - Nicaragua.json`. +5. Confirmar las credenciales de Google Drive, Google Sheets y Gmail. +6. Guardar y publicar el workflow. +7. Copiar la Production URL del Form Trigger. +8. Registrar la URL en Kan.bn y compartirla únicamente con usuarios autorizados. + +### Workflow de limpieza + +El workflow auxiliar revisa diariamente Google Drive y elimina archivos temporales cuyo nombre comienza con: + +```text +TMP_IR_NIC_ +``` + +Solo elimina temporales con más de 24 horas para cubrir ejecuciones interrumpidas. + +--- + +## Cómo funciona + +1. Administración abre el formulario. +2. Selecciona mes y año. +3. Adjunta Q1 y Q2. +4. n8n valida los archivos. +5. Google Drive los convierte temporalmente a Google Sheets. +6. Google Sheets API enumera las pestañas. +7. Se identifican las hojas operativas válidas. +8. Se normalizan encabezados e identificadores. +9. Se extrae Salario INSS y el IR de Q2. +10. Se cruzan los empleados. +11. Se recalcula el IR. +12. Se crea la memoria completa. +13. Se genera la pestaña `DIFERENCIAS`. +14. Se comparte el Google Sheet. +15. Se exporta el Excel. +16. Gmail envía el correo. +17. Se eliminan los temporales. +18. El formulario muestra la confirmación. + +### Triggers + +| Trigger | Frecuencia | Descripción | +|---|---|---| +| n8n Form Trigger | Bajo demanda | Administración carga las nóminas | +| Schedule Trigger de limpieza | Diario, 2:00 a. m. | Elimina temporales con más de 24 horas | + +--- + +## Testing + +### Regresión histórica + +| Período | Empleados Q1 | Empleados Q2 | Emparejados | Diferencias > C$1 | Solo en una quincena | +|---|---:|---:|---:|---:|---:| +| Marzo 2026 | 208 | 230 | 194 | 12 | 32 | +| Abril 2026 | 223 | 237 | 207 | 20 | 28 | +| Mayo 2026 | 225 | 245 | 220 | 14 | 13 | + +### Casos de prueba + +| Caso | Resultado esperado | Estado | +|---|---|---| +| Q1 y Q2 válidos | Reporte, correo y permisos correctos | Validado | +| Meses diferentes | Ejecución detenida | Validado | +| Archivo no XLSX | Rechazo antes de procesar | Validado | +| Hoja auxiliar | Excluida | Validado | +| Empleado mensual | Cálculo con Q2 mensual | Validado | +| Solo Q1 o solo Q2 | No comparable | Validado | +| Sin Salario INSS | Valor derivado y marcado | Validado | +| Diferencia ≤ C$1 | Redondeo | Validado | +| Diferencia > C$1 | Alerta roja | Validado | +| Error temporal de Google | Reintentos automáticos | Configurado | +| Fallo antes de limpiar | Limpieza diaria | Configurado | + +--- + +## Errores conocidos y troubleshooting + +| Error | Causa probable | Solución | +|---|---|---| +| Form Trigger con `?` | Versión incompatible | Usar `typeVersion: 2.3` | +| Error de `this.helpers` | Helper no soportado | Usar el workflow actual sin helpers | +| Google no convierte el XLSX | Sesión vencida o archivo incompatible | Iniciar una ejecución nueva | +| Error al aplicar formato | Columnas congeladas cortan celdas combinadas | Congelar solo filas | +| No encuentra hojas válidas | Mes/año incorrecto | Revisar archivos y selección | +| Coincidencia muy baja | Q1 y Q2 no corresponden | Cargar el mismo período | +| Correo no enviado | OAuth Gmail vencido | Reconectar la credencial | +| Permiso no creado | Restricción de Workspace | Revisar Google Admin | +| Timeout | Libro grande o servicio lento | Revisar retries y timeout | +| Temporales en Drive | Fallo antes de limpiar | Verificar workflow diario | + +--- + +## Monitoreo + +- Revisar **n8n → Executions** después de cada procesamiento. +- Verde significa completado; rojo significa fallo. +- Confirmar recepción del correo por los seis destinatarios. +- Confirmar las pestañas `MEMORIA DE CALCULO` y `DIFERENCIAS`. +- Confirmar el Excel adjunto. +- Confirmar la eliminación de temporales. +- Revisar el workflow de limpieza diariamente. + +### Output esperado + +1. Google Sheet con memoria completa. +2. Pestaña de diferencias. +3. Permisos de edición para seis destinatarios. +4. Correo HTML. +5. Excel adjunto. +6. Confirmación final en el formulario. +7. Eliminación de archivos temporales. + +--- + +## Seguridad + +- El formulario procesa datos sensibles de nómina. +- La URL debe compartirse únicamente con personal autorizado. +- No almacenar credenciales en el JSON. +- No publicar los reportes mediante acceso público por enlace. +- Eliminar temporales al finalizar. +- No subir nóminas reales ni reportes con datos personales al repositorio. + +--- + +## Estructura del repositorio + +```text +/ir-nicaragua +├── README.md +├── Cálculo de IR - Nicaragua.json +├── n8n/ +│ ├── workflow-principal.json +│ └── workflow-limpieza-temporales.json +├── docs/ +│ ├── arquitectura.md +│ ├── reglas-negocio.md +│ └── pruebas-historicas.md +├── CHANGELOG.md +└── DECISIONS.md +``` + +--- + +## Changelog + +### 2026-07-15 — v1.0.0 + +- Workflow listo para producción. +- Formulario con Q1 y Q2. +- Lectura dinámica de pestañas. +- Cruce de empleados. +- Cálculo progresivo de IR. +- Memoria completa y pestaña de diferencias. +- Branding GLM. +- Correo HTML y Excel adjunto. +- Permisos para seis destinatarios. +- Limpieza de temporales. +- Pruebas de marzo, abril y mayo. +- Modo de prueba eliminado. + +### 2026-07-13 — v0.9.0 + +- Ajustes de formato. +- Corrección de alineaciones y cuadrícula. +- Mejora de observaciones. +- Ajuste automático de filas. +- Corrección de celdas combinadas. + +### 2026-07-10 — v0.1.0 + +- Inicio del proyecto. +- Análisis de la memoria. +- Análisis de nóminas. +- Definición de reglas. + +--- + +## Decisions log + +### DEC-001 — Exigir ambas quincenas + +- **Decisión:** Q1 y Q2 son obligatorias. +- **Razón:** el IR depende de la suma real de ambas quincenas. + +### DEC-002 — Usar Salario INSS + +- **Decisión:** Salario INSS es la fuente principal. +- **Razón:** la memoria descuenta por sí misma el 7 %. + +### DEC-003 — No instalar módulos externos + +- **Decisión:** usar APIs de Google. +- **Razón:** no se puede modificar el servidor de n8n. + +### DEC-004 — Tolerancia de C$1.00 + +- **Decisión:** reportar como material una diferencia absoluta mayor a C$1. +- **Razón:** excluir redondeos normales. + +### DEC-005 — Dos pestañas + +- **Decisión:** `MEMORIA DE CALCULO` y `DIFERENCIAS`. +- **Razón:** mantener trazabilidad y simplificar la revisión. + +### DEC-006 — Una sola quincena no es comparable + +- **Decisión:** dejar IR esperado y diferencia en blanco. +- **Razón:** evitar cálculos mensuales parciales. + +### DEC-007 — Seis responsables + +- **Decisión:** correo y edición para Isaac, Estefani, Angie, Mati, Iveth y Máximo. +- **Razón:** responsables oficiales de operación y seguimiento. + +### DEC-008 — Limpieza automática + +- **Decisión:** workflow diario de temporales. +- **Razón:** seguridad y mantenimiento de Drive. + +--- + +## Contactos del proyecto + +| Rol | Nombre | Contacto | +|---|---|---| +| Product Owner / Sponsor | Máximo Gomez | `mgomez@gomezleemarketing.com` | +| IT Manager | Luis Matos | Contacto corporativo GLM | +| Developer principal | Isaac Aracena | `iaracena@gomezleemarketing.com` | +| Administración Nicaragua | Estefani Orozco | `administrativo@gomezleemarketing.com` | +| Administración Nicaragua | Angie Carolina Chavez Silva | `administrativonicaragua@gomezleemarketing.com` | +| Revisión | Mati Soto Valenzuela | `msoto@gomezleemarketing.com` | +| Revisión | Iveth Herrera | `iherrera@gomezleemarketing.com` | + +--- + +## Checklist mensual + +Antes: + +- [ ] Confirmar mismo mes en Q1 y Q2. +- [ ] Confirmar formato `.xlsx`. +- [ ] Seleccionar mes y año correctos. + +Después: + +- [ ] Confirmar ejecución verde. +- [ ] Abrir el Google Sheet. +- [ ] Revisar filas rojas. +- [ ] Revisar filas amarillas. +- [ ] Revisar datos derivados. +- [ ] Confirmar recepción del correo. +- [ ] Confirmar Excel adjunto. +- [ ] Confirmar permisos. +- [ ] Confirmar eliminación de temporales. + +--- + +## Definition of Done + +- [x] Memoria original analizada. +- [x] Nóminas históricas analizadas. +- [x] Reglas fiscales reproducidas. +- [x] Formulario funcionando. +- [x] Q1 y Q2 obligatorias. +- [x] Lectura multih hoja. +- [x] Cruce validado. +- [x] Google Sheet y Excel. +- [x] Pestaña de diferencias. +- [x] Correo HTML. +- [x] Permisos configurados. +- [x] Limpieza de temporales. +- [x] Pruebas históricas. +- [x] Workflow versionado. +- [x] README completo. +- [x] Modo de prueba eliminado. +- [ ] Validación formal final de Luis Matos. +- [ ] Aprobación formal final de Máximo Gomez. + +--- + +## Mantenimiento + +Todo cambio en la tasa del INSS, tabla fiscal, estructura de nóminas, encabezados, destinatarios, tolerancia o permisos debe: + +1. Documentarse. +2. Probarse con un período histórico. +3. Exportarse nuevamente desde n8n. +4. Actualizarse en Gitea. +5. Registrarse en el changelog. + +--- + +Documento mantenido por el equipo **GLM IT**. \ No newline at end of file