Eliminar README.md

2026-08-07 15:30:17 +00:00
parent 56d1a5aed0
commit da656ce9b7
1 changed files with 0 additions and 364 deletions
@@ -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**.