Isaac_Aracena/seguimiento-impuestos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
be4c9682c500a072c3efa83625b79d128bbcd3e6
seguimiento-impuestos/README.md
T
Isaac_Aracena f034ce4914 Actualizar README.md
2026-08-07 14:39:45 +00:00

10 KiB
Raw Blame History

Seguimiento de Impuestos GLM

Aplicación interna que centraliza el calendario tributario regional de GomezLee Marketing y automatiza el envío de recordatorios por correo y WhatsApp.

INFORMACIÓN GENERAL

Campo Detalle
Proyecto Seguimiento de Impuestos GLM
Área Administración
Developer principal Isaac Aracena
IT Manager Luis Matos
Fecha de inicio 2026-07-24
Fecha de cierre 2026-07-27

OBJETIVO

Problema que resuelve

El seguimiento de las obligaciones tributarias de los diferentes países de GLM se realizaba mediante calendarios y archivos separados. Esto dificultaba consultar las fechas límite, identificar a los responsables y garantizar que los avisos fueran enviados a tiempo.

Además, agregar o cambiar destinatarios requería modificar manualmente los flujos de automatización.

Solución implementada

Seguimiento de Impuestos GLM centraliza en una sola aplicación:

  • El calendario tributario regional.
  • Las obligaciones de Nómina y Administración.
  • Los países y fechas límite.
  • Los contactos responsables.
  • Los canales habilitados para cada contacto.
  • El historial de notificaciones enviadas.

La aplicación permite administrar obligaciones y contactos desde una interfaz web. Un flujo de n8n consulta diariamente la información almacenada en Supabase y envía los recordatorios correspondientes por Gmail y WhatsApp.

Usuarios y beneficiarios

  • Equipo de Administración.
  • Equipo de Nómina.
  • Responsables tributarios de cada país.
  • Contactos regionales.
  • Dirección de Recursos Humanos.
  • Equipo de IT de GomezLee Marketing.

ARQUITECTURA

Diagrama general

Usuario autorizado
        |
        v
Frontend React + Vite
        |
        +------> Supabase Auth
        |
        +------> Supabase PostgreSQL
                       |
                       v
              Obligaciones y contactos
                       |
                       v
                n8n — Ejecución 8:00 AM
                       |
                       v
              RPC tax_due_reminders
                       |
              +--------+--------+
              |                 |
              v                 v
         Gmail HTML         WhatsApp
              |                 |
              +--------+--------+
                       |
                       v
              tax_notification_log

Stack tecnológico

Componente Tecnología Propósito
Frontend React 19 Interfaz de usuario
Lenguaje TypeScript Tipado y lógica de la aplicación
Bundler Vite Desarrollo y compilación
Estilos Tailwind CSS Diseño visual
Autenticación Supabase Auth + Google OAuth Control de acceso
Base de datos Supabase / PostgreSQL Obligaciones, países, contactos y bitácora
API de datos Supabase REST / PostgREST Comunicación entre frontend, n8n y base de datos
Automatización n8n Orquestación de recordatorios
Correo Gmail OAuth Envío de correos HTML
Mensajería WhatsApp GLM Envío de avisos por WhatsApp
Hosting EasyPanel / servidor GLM Despliegue de la aplicación y servicios

Integraciones externas

Sistema Tipo de integración Datos que fluyen
Supabase Auth Google OAuth Inicio de sesión y sesión del usuario
Supabase REST API REST / RPC Obligaciones, contactos, países y notificaciones
n8n Webhook y Schedule Trigger Ejecución manual, diaria y notificación de cambios
Gmail OAuth Correos de recordatorio
WhatsApp GLM API REST Mensajes de recordatorio
Google Workspace OAuth Identidad corporativa de los usuarios

REGLAS DE NEGOCIO

Regla de recordatorios

La fórmula principal es:

Miércoles estrictamente anterior y el mismo día de la fecha límite.

Ejemplos:

Fecha límite Primer aviso Segundo aviso
Lunes Miércoles anterior Lunes
Martes Miércoles anterior Martes
Miércoles Miércoles de la semana anterior Miércoles
Jueves Miércoles anterior Jueves
Viernes Miércoles anterior Viernes
Sábado Miércoles anterior Sábado
Domingo Miércoles anterior Domingo

El miércoles calculado debe ser estrictamente anterior. Si la obligación vence un miércoles, el primer aviso corresponde al miércoles de la semana anterior.

Enrutamiento de contactos

  • Los contactos de área Regional reciben todas las obligaciones de todos los países.
  • Los contactos regionales de Nómina reciben las obligaciones de Nómina de todos los países.
  • Los contactos regionales de Administración reciben las obligaciones administrativas de todos los países.
  • Los contactos de un país específico reciben solamente las obligaciones de su país y categoría.
  • Solo se utilizan contactos activos.
  • El correo se envía únicamente cuando el canal de correo está habilitado.
  • WhatsApp se envía únicamente cuando el canal de WhatsApp está habilitado.
  • Los números deben guardarse con código internacional.

Obligaciones tributarias

  • El país es obligatorio.
  • Las únicas categorías disponibles son:
    • Nómina.
    • Administración.
  • Una obligación puede editarse o eliminarse mientras no tenga avisos enviados.
  • Después del primer correo o WhatsApp registrado, la obligación queda bloqueada.
  • Las obligaciones bloqueadas permanecen disponibles en modo de solo lectura.
  • Cuando un día tiene más de tres obligaciones, la opción Ver todos permite consultar la lista completa.

Prevención de duplicados

Cada notificación enviada se registra en tax_notification_log.

La combinación de obligación, contacto, canal y tipo de aviso evita que el mismo recordatorio sea enviado dos veces.

BASE DE DATOS

Tablas

La aplicación utiliza cinco tablas:

Tabla Propósito
tax_calendar_access Correos autorizados para ingresar
tax_countries Catálogo de países
tax_obligations Obligaciones y eventos tributarios
tax_contacts Contactos responsables y canales habilitados
tax_notification_log Bitácora de correos y WhatsApp enviados

Funciones principales

Función Propósito
has_tax_calendar_access Valida si el correo puede utilizar la aplicación
tax_previous_wednesday Calcula el miércoles estrictamente anterior
tax_due_reminders Devuelve los recordatorios y destinatarios pendientes
tax_record_notification Registra un envío exitoso
tax_obligation_delivery_status Consulta si una obligación ya fue notificada
tax_prevent_sent_obligation_changes Bloquea cambios después del primer aviso

Instalación completa

Para una instalación nueva, ejecutar en Supabase:

supabase/Seguimiento-de-Impuestos-GLM.sql

El script incluye:

  • Tablas.
  • Índices.
  • Triggers.
  • Funciones RPC.
  • Políticas RLS.
  • Accesos iniciales.
  • Países.
  • Contactos.
  • Obligaciones históricas de 2026.
  • Prevención de notificaciones duplicadas.

Actualizaciones incrementales

Para bases que ya tenían una versión anterior:

supabase/actualizacion_eventos_bloqueados.sql
supabase/actualizacion_final_calendario_y_nomina.sql

No ejecutar actualizaciones incrementales si ya se utilizó el script completo más reciente.

CONFIGURACIÓN Y SETUP

Prerrequisitos

  • Node.js instalado.
  • npm instalado.
  • Acceso al Supabase empresarial.
  • Acceso a Google Cloud y Supabase Auth.
  • Acceso a n8n.
  • Credencial de Gmail configurada en n8n.
  • Acceso a la API de WhatsApp de GLM.
  • Acceso al hosting de EasyPanel.
  • Correo autorizado para ingresar a la aplicación.

Variables del frontend

Copiar el archivo de ejemplo:

Copy-Item .env.example .env

Configurar:

VITE_SUPABASE_URL=https://dbit.digitalcompass.agency
VITE_SUPABASE_PUBLISHABLE_KEY=REEMPLAZAR_CON_LA_LLAVE_PUBLICA
VITE_TAX_WEBHOOK_URL=https://agenteit.digitalcompass.agency/webhook/seguimiento-impuestos

También puede utilizarse:

VITE_SUPABASE_ANON_KEY=REEMPLAZAR_CON_LA_ANON_KEY

Nunca colocar la llave service_role dentro del frontend.

INSTALACIÓN LOCAL

1. Clonar el repositorio

git clone https://git.digitalcompass.agency/Isaac_Aracena/seguimiento-impuestos.git
cd seguimiento-impuestos

2. Instalar dependencias

npm install

3. Crear el archivo de entorno

Copy-Item .env.example .env

Editar .env con la configuración pública correspondiente.

4. Ejecutar en desarrollo

npm run dev

Aplicación local:

http://localhost:5173/

5. Validar el proyecto

npm run typecheck
npm run lint
npm run format:check

6. Generar el build

npm run build

7. Probar el build

npm run preview

CONFIGURACIÓN DE N8N

Importar el archivo:

n8n/Seguimiento-de-Impuestos-GLM.json

Después de importarlo:

  1. Seleccionar la credencial en Gmail - Enviar recordatorio.
  2. Configurar la conexión privada con Supabase.
  3. Configurar el endpoint y la API key de WhatsApp.
  4. Verificar la zona horaria America/Santo_Domingo.
  5. Ejecutar una prueba manual.
  6. Confirmar el correo recibido.
  7. Confirmar el WhatsApp recibido.
  8. Verificar el registro en tax_notification_log.
  9. Activar el workflow.

CÓMO FUNCIONA

Flujo diario

  1. El Schedule Trigger inicia el workflow a las 8:00 a. m.
  2. n8n obtiene la fecha correspondiente a la ejecución.
  3. El nodo de Supabase llama la RPC tax_due_reminders.
  4. Supabase identifica las obligaciones que deben notificarse.
  5. Supabase cruza cada obligación con los contactos aplicables.
  6. n8n genera el correo HTML con el branding de GLM.
  7. n8n genera el mensaje de WhatsApp.
  8. Gmail envía los correos habilitados.
  9. La API de WhatsApp envía los mensajes habilitados.
  10. Cada envío exitoso se registra en Supabase.
  11. Los registros enviados quedan protegidos contra duplicados.

Documento mantenido por el equipo GLM IT.

Reference in New Issue View Git Blame Copy Permalink