project.linkedcorp.net/docs/CONEXIONES-EXTERNAS.md

Conexiones externas (fuentes de datos de otros sistemas)

Leer cuando: se trabaje en traer/consultar datos de sistemas externos (pacientes, empleados de nómina, FoxPro u otra tecnología). No leer si: la tarea no toca datos externos. Contrato técnico de los conectores: data/conectores/README.md.

Estado (2026-10-29): conector FoxPro 1.1.0 instalado y funcionando en Exilaser (ver abajo). Módulo del sistema hecho en dev (migración 038, backend/src/modules/integrations, job integrationSync), sin commit ni producción.

Arquitectura

El sistema no se conecta directo a las bases de origen. En cada servidor origen se instala un conector (API HTTP de solo lectura) y el sistema habla con él por un contrato único (v1). Para otra tecnología (SQL Server, Excel, etc.) se desarrolla otro conector con el mismo contrato; el sistema no cambia. Ver decisión #2 en DECISIONES.md.

• Primer caso: Exilaser, Windows Server 192.168.0.253 (SAGA/SistViso en FoxPro), alcanzado por la VPN WireGuard. Conector en C:\api_project\foxpro, puerto 8455.
• Fuentes reales (revisadas por SSH, solo estructura, 2026-10-29):

Fuente	Ruta	Tabla	Registros	Codificación	Campos útiles
Nómina	C:\Sistema\Nomina\Datos\Exilaser	empleado.DBF (VFP 0x30, sin memo)	31	cp1252	EMPCED, EMPAPE, EMPNOM, EMPTEL, EMPTEL1, EMPFECNAC, EMPCARGO, EMPDEPART, EMPINGRESO, EMPSALIDA, EMPACTIVO
SAGA clientes	C:\Sistema\Datos\exilaser	clientes.DBF (VFP 0x30, sin memo, ~20 MB)	32 985	cp850	CLICOD, CLIRUC, CLINOM, CLITEL, CLIEMAIL, CLIDIR, CLICIU, CLIPERSONA, CLITIPRUC, CLISEXO, INACTIVO, CLIESTADO, FECHAACT

• No exponer de nómina: EMPSUELDO, EMPBANCO, EMPCUENT, EMPTIPOCUE, EMPNUMIESS, EMPLET*, FIJO1-5, EMPCARGAS, EMPESTADO (es estado civil) (van en denyFields o se usa lista de campos permitidos).
• Nómina no tiene correo: al crear un usuario desde nómina el correo se escribe a mano.
• Clientes: el nombre viene en un solo campo (CLINOM), sin nacimiento; incluye empresas (RUC) — para pacientes filtrar personas naturales (CLIPERSONA/CLITIPRUC). El orden apellidos/nombres de CLINOM se confirma con una muestra al instalar.
• exilaser14…exilaser25 son cierres de años anteriores: no se exponen.
• clientes.DBF cambia todo el día (SAGA escribe): conviene modo importar o caché con recarga mínima, para no copiar 20 MB en cada consulta.

Requisitos acordados con el usuario

1. Dos modos por fuente (lo elige el superadmin): importar (copiar a nuestra BD) o consulta en vivo (leer siempre del origen). En consulta en vivo, al agendar se guarda una copia mínima del paciente porque las citas necesitan el registro local.
2. Formas de conexión que no comprometan al origen (superadmin): todo pasa por el conector de solo lectura; el sistema no guarda credenciales del origen, solo el token del conector (cifrado AES-256-GCM, nunca vuelve al navegador).
3. Mapeo en dos pasos (superadmin): 1) conexión al servidor (URL del conector + token, botón Probar); 2) qué fuente/tabla usar y a qué destino (Pacientes, Empleados).
4. Importación al configurar o solo consultas: al terminar la configuración se ofrece "Importar ahora" o dejarla solo para consultas.
5. Diseño por drivers/conectores con la misma interfaz (aprobado).
6. Empleados de nómina: se importan a una tabla local de empleados (clave: cédula; los que desaparecen del origen quedan inactivos, no se borran). Botón "Actualizar empleados" a pedido, visible para admin y superadmin. Debe funcionar con cualquier tipo de origen.
7. Vista previa: el superadmin ve las columnas y filas reales de la tabla y elige qué columnas usar en el sistema.
8. Crear usuario desde nómina: en Organización → Usuarios → Nuevo, opción de elegir un empleado de la lista importada; precarga nombre, correo, cargo y departamento si están mapeados, y deja el usuario vinculado. No se ofrecen empleados que ya tienen usuario.

Seguridad (resumen)

• Regla (usuario, 2026-10-29): todo lo que se busque o traiga de SAGA es por la API del conector, también las búsquedas que haga Claude a pedido. El SSH al Windows es solo para administrar el conector (instalar, actualizar, decidir qué tablas/campos expone), con permiso del usuario. Una tabla nueva primero se agrega a config.json del conector con los campos mínimos; después se consulta por la API.

• En el conector: solo GET, token (se guarda solo el SHA-256), IPs permitidas en el conector y en el firewall de Windows, tablas/campos permitidos y denegados (sueldos, claves), sin rutas ni SQL libres, límites de peticiones/concurrencia/página/tiempo, log sin tokens ni valores buscados.

• FoxPro: se lee una copia temporal de DBF+FPT, nunca el original (no bloquea a SAGA).

• En el sistema: configuración solo superadmin; "Actualizar empleados" admin/superadmin; auditoría de pruebas de conexión, importaciones y consultas.

Instalación en Exilaser (2026-10-29)

• C:\api_project\foxpro, Node 24 del servidor, tarea programada LinkedCorp-Conector-FoxPro (al arranque, usuario SYSTEM, reinicio si cae), regla de firewall del mismo nombre: TCP 8455 solo desde 192.168.222.3 (prod) y 192.168.222.40 (dev).
• URL desde LinkedCorp: http://192.168.0.253:8455 (por la VPN). Token: archivo ~/.config/linkedcorp/conector-foxpro-exilaser.token (600) en el equipo de desarrollo; en el Windows solo está su SHA-256.
• Probado desde dev: sin token → 401; nómina 31 empleados (11 campos permitidos); clientes 32 988 (13 campos); primera carga de clientes ~8 s, luego caché (recarga como mínimo cada 60 s); incremental changedField=FECHAACT OK; tildes/ñ correctas (cp850).
• CLINOM viene como APELLIDOS NOMBRES (ej. "GONZALEZ JIMENEZ RAUL VICENTE"): al importar se separa en las 2 primeras palabras = apellidos, resto = nombres (los apellidos compuestos se corrigen a mano). Pacientes = CLIPERSONA = Natural (en una muestra de 1000: 988 naturales).
• Mejora a futuro: correr la tarea con una cuenta de dominio de solo lectura en vez de SYSTEM.
• Actualizar el conector: copiar src/ a C:\api_project\foxpro\src, detener la tarea, matar el node del conector y volver a iniciar la tarea.

Decisiones del usuario sobre pacientes (2026-10-29)

• Con conexión activa se permite crear pacientes a mano (quedan como locales).
• Al vincular por cédula, si los datos difieren manda SAGA (el cambio queda en auditoría).

Pendientes

• Revisar en el server las carpetas de nómina y clientes (estructura, codificación).
• Instalar el conector en C:\api_project\foxpro y probar desde dev.
• Módulo del sistema (ver "Cómo quedó en el sistema").
• Commit, revisión y producción (migraciones 036–038, conexión y fuentes a configurar allá).

Cómo quedó en el sistema (2026-10-29)

• Configuración → Conexiones externas (superadmin): conexiones (URL + token cifrado, Probar) y fuentes Pacientes/Empleados: conexión → fuente → tabla, vista previa de 20 filas, mapeo de campos, filtro (ej. CLIPERSONA = Natural), campo de cambios (FECHAACT) y modo (pacientes: importar o en vivo). Botones "Traer cambios" y "Sincronización completa".
• Programación (job en el backend, cada 5 min revisa): pacientes en modo importar → completa lunes a viernes a las 05:00 (recoge borrados: quedan inactivos) e incremental cada 15 min de 06:00 a 21:00 (agregados por _recno + modificados por FECHAACT). La primera vez hace la completa. El conector solo copia el DBF cuando el sistema le pide datos (como mínimo cada 60 s).
• Organización → Empleados (admin/superadmin): listado y "Actualizar empleados" (a pedido). Los que salen de la nómina quedan inactivos. Nuevo usuario → Desde nómina precarga nombre, cargo y departamento (si coincide por nombre) y vincula el usuario con el empleado.
• Médicos (2026-10-29): casi todos facturan como proveedores de SAGA (provedor.DBF, expuesto en el conector solo con código, nombre, RUC, teléfono, correo, ciudad, tipo e inactivo). Se cargan como empleados con origin=provider con backend/src/scripts/import-provider-employees.js (lee del conector por código de proveedor; sin datos personales en Git). En dev: 9 proveedores + 2 que ya eran de nómina (Torres Palacios Nataly, Rodríguez Nava Christian). Códigos usados: 137+031 142+033 809 234 040 794 817 565 540 405 676 (--position=MEDICO).
• Médico nuevo (desde 2026-10-29): Organización → Empleados → "Agregar desde proveedores" (admin/superadmin): buscar por nombre, apellido o cédula en la fuente "Proveedores" (Configuración → Conexiones externas, en dev: clientes/PROVEDOR), elegir, confirmar apellidos, nombres y cargo (por defecto MEDICO) y guardar como empleado (origin=provider). Marca "Ya es empleado" a los existentes. Luego, si entra al sistema: Nuevo usuario → Desde nómina, y Personal de la Agenda. Los 11 médicos ya cargados se mantienen. El script queda para cargas masivas.
• Protección: un empleado con usuario en el sistema (p. ej. médico) no se actualiza ni se inactiva al "Actualizar empleados"; los de origen proveedor tampoco los toca la nómina.
• Agenda: en modo importar se busca entre los importados (también por nombre de origen); en modo en vivo el selector agrega los del origen ("Del sistema origen") y al elegir uno se trae solo ese. El detalle del paciente muestra su origen.
• Nombres de SAGA: CLINOM no tiene orden fijo (a veces nombre primero), así que no se separa: se guarda entero como nombre visible (name_split=0). Al editar el paciente, recepción separa apellidos y nombres; desde ahí la sincronización ya no pisa su nombre (sí cédula/teléfono/correo).
• Prueba en dev con datos reales: 31 empleados (24 activos), 31 220 pacientes en 24 s; repetir la completa sin cambios 1,7 s; 14 cédulas repetidas en SAGA quedan sin cédula en el segundo registro.