cruce-cuentas-glm-centralizado/IMPLEMENTACION_PANAMA.md

# Cruce de Cuentas GLM · Panamá (PA) · Instalación

Este paquete agrega **Panamá** como tercer país del portal centralizado de Cruce de Cuentas GLM sin reemplazar la lógica productiva de Guatemala, Trinidad y Tobago ni Bono 14.

## Archivos incluidos

### Workflows n8n
1. `Portal de Verificación de Nómina - Panamá.json`
   - Workflow principal Panamá.
   - Webhook: `POST /webhook/nominapa-bamboo-test`.
2. `Portal de Verificación de Nómina Panamá - Históricos.json`
   - Respaldo de Históricos Panamá.
   - Webhook: `GET /webhook/cruce-cuentas-pa-historicos`.
3. `Portal de Verificación de Nómina Panamá - Envío de Reporte.json`
   - Marcar reporte como resuelto + correo.
   - Webhook: `POST /webhook/cruce-cuentas-pa-marcar-resuelto`.
4. `Portal de Verificación de Nómina - Analizar Nómina con Gemini Guatemala Trinidad y Tobago y Panamá.json`
   - Sustituye el analizador compartido actual y conserva GT/TT agregando PA.
   - Webhook compartido: `POST /webhook/cruce-cuentas-analizar-nomina`.
5. `Portal de Verificación de Nómina - Reportar corrección BambooHR a RRHH - GT TT PA.json`
   - Sustituye el workflow compartido actual y conserva GT/TT agregando PA.
   - Webhook compartido: `POST /webhook/cruce-cuentas-bamboo-correccion`.

### Supabase
- `SUPABASE_Panama_READY.sql`
  - Amplía los checks de país a `GT`, `TT`, `PA`.
  - Habilita aliases y correcciones BambooHR para PA.
  - Actualiza las RPC de Históricos y Banco sin Bamboo para PA.
  - Mantiene la tabla histórica legada `public.cruces_cuentas_gt_reportes` como tabla multi-país por la columna `country`.
  - No elimina reportes ni datos históricos.

## Orden de instalación recomendado

### 1. Respaldo
Antes de tocar producción, exporta los workflows actuales compartidos y conserva una copia del ZIP actualmente desplegado de la app.

### 2. Supabase
Ejecuta `SUPABASE_Panama_READY.sql` en el SQL Editor del Supabase empresarial.

El bloque final incluye consultas de validación de solo lectura. Deben ejecutarse sin error.

### 3. Workflows compartidos
Desactiva temporalmente los workflows actuales que ocupan estas rutas:
- `cruce-cuentas-analizar-nomina`
- `cruce-cuentas-bamboo-correccion`

Importa las dos versiones `GT TT PA`, verifica credenciales y publícalas. No pueden quedar dos workflows activos utilizando el mismo path.

### 4. Workflows nuevos de Panamá
Importa y publica:
- Principal Panamá.
- Históricos Panamá.
- Envío de Reporte / Marcar Resuelto Panamá.

### 5. Credenciales n8n
Los JSON hacen referencia a credenciales ya usadas por los workflows productivos. Verifica que n8n las resuelva después de importar:
- `BambooHR GLM Full Access`
- `Google account 2`
- `Google account - Isaac Producción`
- `Gmail account 3`
- `Isaac - Gemini Api Pago`

**No hay `$env`, `process.env` ni variables `VITE_` en los workflows de n8n.** Los endpoints y valores requeridos por n8n están puestos directamente en los JSON, siguiendo la forma actual de producción.

### 6. Acceso de usuarios
La app sigue usando `cruce_cuentas_mi_acceso` para validar la sesión. Si la RPC devuelve una lista `paises`, agrega `PA` a los usuarios que deban reportar correcciones de Panamá a RRHH.

### 7. App
El ZIP de la app contiene:
- Código fuente React/TypeScript/Vite actualizado.
- `dist/` listo para servir en `/cruce-cuentas/`.
- `.env.local` con los endpoints actuales, incluyendo PA.
- `.env.example` actualizado.

Si tu despliegue sirve archivos estáticos directamente, publica el contenido de `dist/` bajo `/cruce-cuentas/`.

Si prefieres compilar en tu infraestructura, ejecuta normalmente `npm ci` y `npm run build` en un ambiente con dependencias nativas compatibles con su sistema operativo.

## Reglas Panamá V1 implementadas

- País: `PA` / Panamá.
- Moneda: USD.
- Bandera: `https://dbit.digitalcompass.agency/storage/v1/object/public/public-assets/Flag_of_Panama.svg`.
- BambooHR usa `onlyCurrent=false`.
- Permite múltiples planillas en un mismo período: quincenal, extraordinarias, vacaciones y XIII Mes/Décimo.
- Soporta Plan 1582 y Plan 1644.
- `Referencia` se usa como fallback controlado cuando `Cuenta Destino` no es una cuenta válida; no se equiparan ambos campos globalmente.
- La inclusión bancaria es **fila por fila y guiada por la nómina**, no por el nombre del plan ni por el texto de `Concepto`.
- Una fila respaldada por nómina puede entrar aunque el concepto diga `PAGO A PROVEEDORES` o contenga texto desactualizado.
- Honorarios, Pluxee, proveedores/acreedores, pensiones, préstamos y viáticos sin respaldo de nómina permanecen fuera de Panamá V1.
- No se fuerzan matches ambiguos de nombres/BambooHR.
- Las cuentas y nombres mantienen trazabilidad al archivo/envío/plan de origen.
- Si ya existe el reporte del mismo país/año/mes/período, reutiliza el Google Sheet, preserva resoluciones que sigan correspondiendo y envía correo de **Reporte actualizado**.
- Si es una ejecución nueva, envía correo de **Nuevo reporte generado**.
- Marcar un reporte como resuelto actualiza Supabase y envía el correo de resolución.
- `Banco sin Bamboo` puede enviarse a RRHH mediante el mismo flujo compartido usado por GT/TT.

## RRHH Panamá

La versión entregada envía las correcciones de identidad de Panamá a:
- Delarys Peñalba — `dpenalba@gomezleemarketing.com`
- Ariadne Cortéz — `acortez02@gomezleemarketing.com`

## Estructura del reporte

Se conserva la misma estructura del portal:
1. `01 Nómina vs Banco`
2. `02 Banco sin Nómina`
3. `03 Banco sin Bamboo`
4. `04 Diferencias nombre banco`
5. `05 Cuenta Mal Digitada` cuando existan casos
6. `06 Resumen` si existe la hoja anterior; de lo contrario `05 Resumen`

La columna `Resolución` se conserva en las hojas de revisión para permitir actualización sin perder los comentarios vigentes que sigan correspondiendo al mismo caso.

## Regresión recomendada

1. Probar **enero 2026 Q15** y **enero 2026 Q30**.
2. Probar **febrero 2026 Q15/Q30** para validar archivos mixtos y conceptos engañosos.
3. Probar **marzo 2026** para validar discrepancias/pagos sin nómina.
4. Probar **abril 2026** para validar XIII Mes/Décimo y suplementos.
5. Validar que el correo cambie de `Nuevo reporte generado` a `Reporte actualizado` al ejecutar de nuevo el mismo período.
6. Desde Históricos, marcar un reporte resuelto y confirmar correo.
7. Abrir un caso Banco sin Bamboo, reportarlo a RRHH y comprobar que el alias quede guardado para futuras ejecuciones.
8. Ejecutar una prueba rápida de GT y TT para confirmar que los dos workflows compartidos siguen sin regresión.

## Nota de seguridad operativa

No publiques simultáneamente dos versiones de un workflow compartido con el mismo webhook. Importa primero, valida credenciales y luego cambia cuál versión queda activa.