Añadir README.md

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