From 364b313240de8258504bf6d686d1ecded46b6b6a Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Mon, 27 Jul 2026 15:45:16 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 385 ------------------------------------------------------ 1 file changed, 385 deletions(-) diff --git a/README.md b/README.md index 3aa27b6..a2e184c 100644 --- a/README.md +++ b/README.md @@ -262,45 +262,6 @@ VITE_SUPABASE_ANON_KEY=REEMPLAZAR_CON_LA_ANON_KEY Nunca colocar la llave `service_role` dentro del frontend. -### Variables y credenciales de n8n - -| Configuración | Descripción | -|---|---| -| Supabase URL | URL del Supabase empresarial | -| Supabase Service Role | Llave privada para ejecutar RPC y registrar envíos | -| Gmail Credential | Cuenta que envía los recordatorios | -| WhatsApp Base URL | Endpoint del servicio de WhatsApp | -| WhatsApp Instance | Instancia `botsoporte` | -| WhatsApp API Key | Credencial privada del servicio | -| GLM Tax App URL | `https://home.digitalcompass.agency/` | -| GLM Logo URL | Logo público utilizado en el correo HTML | - -Las llaves privadas deben administrarse en n8n o en el vault de credenciales de GLM. - -> **Nunca commitear `.env`, llaves privadas, tokens, contraseñas o credenciales reales al repositorio.** - -### Supabase Auth - -La URL autorizada para regresar a la aplicación después del login es: - -```text -https://home.digitalcompass.agency/ -``` - -En el servicio de Supabase Auth debe agregarse: - -```env -ADDITIONAL_REDIRECT_URLS=https://home.digitalcompass.agency/ -``` - -El callback de Google OAuth hacia Supabase permanece en: - -```text -https://dbit.digitalcompass.agency/auth/v1/callback -``` - ---- - ## INSTALACIÓN LOCAL ### 1. Clonar el repositorio @@ -358,39 +319,6 @@ npm run preview --- -## DESPLIEGUE - -La aplicación se publica directamente en la raíz del subdominio: - -```text -https://home.digitalcompass.agency/ -``` - -La configuración de Vite utiliza: - -```ts -base: "/" -``` - -Proceso general: - -```powershell -npm install -npm run build -``` - -El contenido generado en `dist/` debe desplegarse en el servicio correspondiente de EasyPanel. - -Después del despliegue: - -1. Abrir la aplicación. -2. Iniciar sesión con Google. -3. Confirmar que Supabase redirige a la raíz del subdominio. -4. Verificar que carguen obligaciones, países y contactos. -5. Crear un registro de prueba. -6. Confirmar su almacenamiento en Supabase. - ---- ## CONFIGURACIÓN DE N8N @@ -430,321 +358,8 @@ Después de importarlo: 10. Cada envío exitoso se registra en Supabase. 11. Los registros enviados quedan protegidos contra duplicados. -### Cambios desde la aplicación -Cuando el usuario: -- Crea una obligación. -- Actualiza una obligación. -- Elimina una obligación. -- Crea un contacto. -- Actualiza un contacto. -- Desactiva un contacto. -La información se guarda directamente en Supabase. - -El flujo de n8n consulta siempre la información vigente, por lo que no es necesario modificar manualmente el workflow cuando cambien los contactos. - -### Schedules y triggers - -| Trigger | Frecuencia | Descripción | -|---|---|---| -| Schedule Trigger | Diario, 8:00 a. m. | Envía los recordatorios correspondientes | -| Manual Trigger | Bajo demanda | Permite realizar pruebas desde n8n | -| Webhook `seguimiento-impuestos` | Bajo demanda | Recibe acciones del frontend o ejecuciones controladas | - -### Prueba con una fecha específica - -```json -{ - "action": "run_now", - "run_date": "2026-07-24" -} -``` - ---- - -## TESTING - -### Casos de prueba mínimos - -| Caso | Input | Resultado esperado | Estado | -|---|---|---|---| -| Login autorizado | Correo incluido en `tax_calendar_access` | Acceso concedido | Validado | -| Login no autorizado | Correo no incluido | Acceso denegado | Validado | -| Crear obligación | Fecha, descripción, categoría y país | Registro visible en calendario | Validado | -| País vacío | Obligación sin país | Formulario no permite guardar | Validado | -| Categoría inválida | Valor diferente a Nómina o Administración | Registro rechazado | Validado | -| Editar sin aviso | Obligación sin notificaciones | Cambios permitidos | Validado | -| Editar con aviso | Obligación ya notificada | Modo de solo lectura | Validado | -| Eliminar sin aviso | Obligación sin notificaciones | Eliminación permitida | Validado | -| Eliminar con aviso | Obligación ya notificada | Eliminación bloqueada | Validado | -| Más de tres obligaciones | Día con cuatro o más registros | Opción Ver todos disponible | Validado | -| Contacto regional | Área Regional activa | Recibe todas las obligaciones | Validado | -| Contacto regional de Nómina | País Regional y área Nómina | Recibe Nómina de todos los países | Validado | -| Correo deshabilitado | `email_enabled = false` | No se genera correo | Validado | -| WhatsApp deshabilitado | `whatsapp_enabled = false` | No se genera WhatsApp | Validado | -| Aviso duplicado | Mismo contacto, obligación, canal y tipo | Segundo envío bloqueado | Validado | -| API de WhatsApp caída | Error HTTP | Ejecución registrada como fallida | Pendiente de prueba controlada | -| Gmail no disponible | Error de credencial o servicio | Nodo falla y queda visible en Executions | Pendiente de prueba controlada | - ---- - -## ERRORES CONOCIDOS Y TROUBLESHOOTING - -| Error | Causa probable | Solución | -|---|---|---| -| El login vuelve a Supabase | Redirect URL incorrecta | Agregar `https://home.digitalcompass.agency/` a `ADDITIONAL_REDIRECT_URLS` | -| Pantalla en blanco después del deploy | Base de Vite incorrecta | Confirmar `base: "/"` y reconstruir | -| 401 Unauthorized en Supabase | Llave incorrecta o expirada | Revisar la llave pública o `service_role` según el componente | -| No cargan obligaciones | Error en URL, RLS o sesión | Revisar consola del navegador y políticas RLS | -| No llegan correos | Credencial de Gmail no seleccionada | Abrir el nodo Gmail y seleccionar la credencial | -| No llega WhatsApp | API key, número o instancia incorrectos | Revisar encabezado `apikey`, instancia y código internacional | -| Recordatorio duplicado | Bitácora no registrada correctamente | Revisar los nodos `Supabase - Registrar correo/WhatsApp` | -| Obligación editable después del aviso | Trigger de protección no instalado | Ejecutar el script actualizado de Supabase | -| Contacto no recibe avisos | País, área, canal o estado incorrecto | Revisar el contacto desde la app | -| Webhook no responde | Workflow inactivo o URL incorrecta | Revisar activación y Production URL en n8n | -| Error al compilar | Dependencias incompletas | Eliminar `node_modules`, ejecutar `npm install` y reconstruir | - ---- - -## MONITOREO - -### n8n - -Revisar periódicamente: - -- **Executions**. -- Ejecuciones fallidas. -- Respuesta de Gmail. -- Respuesta de WhatsApp. -- Respuesta de los nodos de registro en Supabase. - -Una ejecución normal debe finalizar sin nodos rojos y registrar cada canal enviado. - -### Supabase - -Revisar: - -- Nuevas obligaciones. -- Contactos activos. -- Estado de acceso de usuarios. -- Registros recientes en `tax_notification_log`. -- Duplicados o errores de datos. -- Obligaciones bloqueadas después del primer envío. - -### Resultado esperado - -Cada día a las 8:00 a. m.: - -- Se consultan las obligaciones pendientes. -- Se identifican los contactos aplicables. -- Se envían los canales habilitados. -- Se registra cada envío exitoso. -- No se repiten avisos ya enviados. - ---- - -## ESTRUCTURA DEL REPOSITORIO - -```text -seguimiento-impuestos/ -|-- README.md -|-- AGENTS.md -|-- package.json -|-- package-lock.json -|-- vite.config.ts -|-- tsconfig.json -|-- eslint.config.js -|-- index.html -|-- .env.example -|-- .gitignore -| -|-- public/ -| |-- favicon.ico -| |-- favicon-32.png -| |-- favicon-192.png -| └-- apple-touch-icon.png -| -|-- src/ -| |-- App.tsx -| |-- TaxApp.tsx -| |-- main.tsx -| |-- styles.css -| | -| |-- assets/ -| | └-- glm-logo.png -| | -| |-- auth/ -| | └-- AuthGate.tsx -| | -| └-- lib/ -| |-- supabase-auth.ts -| |-- supabase-data.ts -| └-- tax-utils.ts -| -|-- supabase/ -| |-- README.md -| |-- Seguimiento-de-Impuestos-GLM.sql -| |-- seguimiento_impuestos_auth.sql -| |-- actualizacion_eventos_bloqueados.sql -| └-- actualizacion_final_calendario_y_nomina.sql -| -|-- n8n/ -| |-- CONFIGURACION.md -| └-- Seguimiento-de-Impuestos-GLM.json -| -└-- dist/ - └-- Build generado para producción -``` - -`node_modules/`, `.env` y demás archivos sensibles o generados no deben subirse al repositorio. - ---- - -## CHANGELOG - -### 2026-07-27 — v1.0.0 - -- Aplicación preparada para producción. -- Migración del calendario histórico 2026 a Supabase. -- Login con Google y control de accesos. -- Gestión de obligaciones por país y categoría. -- Gestión dinámica de contactos. -- Filtros por país y nombre. -- Búsqueda en la vista Lista. -- Recordatorios por Gmail y WhatsApp. -- Correo HTML con identidad visual GLM. -- Prevención de envíos duplicados. -- Bloqueo de obligaciones después del primer aviso. -- Vista completa para días con más de tres obligaciones. -- Despliegue configurado en la raíz del subdominio. -- Flujo n8n con ejecución diaria a las 8:00 a. m. - -### 2026-07-25 — v0.9.0 - -- Integración del frontend con Supabase. -- Creación de las tablas principales. -- Migración de obligaciones históricas. -- Creación del flujo inicial de n8n. -- Incorporación de contactos regionales y por país. - -### 2026-07-24 — v0.1.0 - -- Limpieza del prototipo generado por Lovable. -- Eliminación de archivos y dependencias innecesarias. -- Estandarización del proyecto con React, Vite y TypeScript. -- Aplicación inicial del branding de GLM. - ---- - -## DECISIONS LOG - -### DEC-001 — Supabase como fuente única de datos - -- **Fecha:** 2026-07-24 -- **Contexto:** El prototipo almacenaba el calendario directamente en el frontend. -- **Opciones consideradas:** Mantener datos estáticos o migrarlos a Supabase. -- **Decisión:** Utilizar Supabase/PostgreSQL. -- **Razón:** Permite persistencia, administración multiusuario, integración con n8n y trazabilidad. - -### DEC-002 — Lógica determinística para las fechas - -- **Fecha:** 2026-07-24 -- **Contexto:** Se consideró utilizar Gemini para decidir cuándo enviar los avisos. -- **Opciones consideradas:** IA generativa o funciones de fechas en PostgreSQL. -- **Decisión:** Utilizar funciones determinísticas. -- **Razón:** La regla es exacta y no debe depender de interpretaciones probabilísticas. - -### DEC-003 — Contactos administrados desde la aplicación - -- **Fecha:** 2026-07-25 -- **Contexto:** Cada cambio de destinatario obligaba a editar n8n. -- **Opciones consideradas:** Contactos hardcodeados o contactos en Supabase. -- **Decisión:** Guardar contactos en `tax_contacts`. -- **Razón:** Los usuarios pueden mantener destinatarios sin modificar el workflow. - -### DEC-004 — Bloqueo después del primer envío - -- **Fecha:** 2026-07-26 -- **Contexto:** Modificar una obligación después de notificarla podía generar inconsistencias. -- **Opciones consideradas:** Permitir cambios siempre o bloquear después del envío. -- **Decisión:** Bloquear edición y eliminación después del primer aviso. -- **Razón:** Preserva la integridad del historial y evita discrepancias con mensajes ya enviados. - -### DEC-005 — Despliegue en subdominio - -- **Fecha:** 2026-07-27 -- **Contexto:** La app inicialmente utilizaba `/calendario-impuestos/` como base. -- **Opciones consideradas:** Ruta interna o subdominio independiente. -- **Decisión:** Publicar en `https://home.digitalcompass.agency/`. -- **Razón:** Simplifica navegación, OAuth, despliegue y mantenimiento. - ---- - -## CONTACTOS DEL PROYECTO - -| Rol | Nombre | Contacto | -|---|---|---| -| Solicitante funcional | Ada | Pendiente de documentar | -| IT Manager | Luis Matos | `lmatos@gomezleemarketing.com` | -| Developer principal | Isaac Aracena | `iaracena@gomezleemarketing.com` | -| Contacto regional de Nómina | Mati Soto Valenzuela | `msoto@gomezleemarketing.com` | -| Contacto regional de Nómina | Iveth Herrera | `iherrera@gomezleemarketing.com` | - ---- - -## DEFINITION OF DONE - -- [x] Calendario histórico migrado a Supabase. -- [x] Aplicación integrada con la base de datos. -- [x] Login con Google implementado. -- [x] Accesos administrables desde Supabase. -- [x] Obligaciones administrables desde la aplicación. -- [x] Contactos administrables desde la aplicación. -- [x] País obligatorio. -- [x] Categorías limitadas a Nómina y Administración. -- [x] Filtros y búsquedas implementados. -- [x] Regla del miércoles anterior implementada. -- [x] Aviso del mismo día implementado. -- [x] Correos HTML con branding GLM. -- [x] Envíos por WhatsApp. -- [x] Prevención de duplicados. -- [x] Bloqueo después del primer aviso. -- [x] Vista para días con más de tres obligaciones. -- [x] Workflow exportado en `/n8n`. -- [x] Scripts SQL almacenados en `/supabase`. -- [x] Variables públicas documentadas en `.env.example`. -- [x] Proyecto subido a Gitea. -- [x] Manual de uso elaborado. -- [ ] Ejecutar monitoreo controlado durante los primeros días en producción. -- [ ] Registrar el enlace definitivo del board de Kan.bn. -- [ ] Documentar la aprobación funcional final. - ---- - -## SEGURIDAD - -- No subir el archivo `.env`. -- No almacenar la llave `service_role` en React. -- No publicar la API key de WhatsApp. -- No almacenar contraseñas o tokens en el README. -- Utilizar únicamente llaves públicas en variables `VITE_*`. -- Mantener RLS activo en las tablas. -- Restringir los accesos mediante `tax_calendar_access`. -- Revisar periódicamente los usuarios autorizados. -- Rotar credenciales cuando una persona deje de necesitar acceso. - ---- - -## DOCUMENTACIÓN ADICIONAL - -- `AGENTS.md`: reglas para agentes y asistentes de programación. -- `supabase/README.md`: instrucciones específicas de la base de datos. -- `n8n/CONFIGURACION.md`: configuración del workflow. -- `supabase/Seguimiento-de-Impuestos-GLM.sql`: instalación completa. -- `n8n/Seguimiento-de-Impuestos-GLM.json`: workflow importable. - ---- Documento mantenido por el equipo **GLM IT**. \ No newline at end of file