From da656ce9b7d47f0de2276882d281f3373a3ee62a Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Fri, 7 Aug 2026 15:30:17 +0000 Subject: [PATCH] Eliminar README.md --- README.md | 364 ------------------------------------------------------ 1 file changed, 364 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index f2c7747..0000000 --- a/README.md +++ /dev/null @@ -1,364 +0,0 @@ -# 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 - -```text -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: - -```text -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: - -```text -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: - -```powershell -Copy-Item .env.example .env -``` - -Configurar: - -```env -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: - -```env -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 - -```powershell -git clone https://git.digitalcompass.agency/Isaac_Aracena/seguimiento-impuestos.git -cd seguimiento-impuestos -``` - -### 2. Instalar dependencias - -```powershell -npm install -``` - -### 3. Crear el archivo de entorno - -```powershell -Copy-Item .env.example .env -``` - -Editar `.env` con la configuración pública correspondiente. - -### 4. Ejecutar en desarrollo - -```powershell -npm run dev -``` - -Aplicación local: - -```text -http://localhost:5173/ -``` - -### 5. Validar el proyecto - -```powershell -npm run typecheck -npm run lint -npm run format:check -``` - -### 6. Generar el build - -```powershell -npm run build -``` - -### 7. Probar el build - -```powershell -npm run preview -``` - ---- - - -## CONFIGURACIÓN DE N8N - -Importar el archivo: - -```text -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**. \ No newline at end of file