Isaac_Aracena/seguimiento-impuestos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Actualizar README.md

Browse Source
This commit is contained in:
Isaac_Aracena
2026-07-27 15:45:16 +00:00
parent 0d6bff462c
commit 364b313240
1 changed files with 0 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
-385
View File
@@ -262,45 +262,6 @@ VITE_SUPABASE_ANON_KEY=REEMPLAZAR_CON_LA_ANON_KEY
Nunca colocar la llave `service_role` dentro del frontend. 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 ## INSTALACIÓN LOCAL
### 1. Clonar el repositorio ### 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 ## CONFIGURACIÓN DE N8N
@@ -430,321 +358,8 @@ Después de importarlo:
10. Cada envío exitoso se registra en Supabase. 10. Cada envío exitoso se registra en Supabase.
11. Los registros enviados quedan protegidos contra duplicados. 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**. Documento mantenido por el equipo **GLM IT**.