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.0.0 hecho (data/conectores/foxpro/, 16 pruebas locales OK, sin probar con tablas reales ni en Windows). Módulo del sistema: pendiente (solo diseño).

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 previstas: Sistemas\nomina (empleados) y la tabla de clientes de SAGA (pacientes de la Agenda médica). Nombres reales de tablas y campos: por confirmar en el servidor.

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)

• 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.

Pendientes

• Revisar en el server (SSH, solo lectura, con permiso del usuario) las carpetas de nómina y clientes: tablas, campos, versión de los DBF y codificación (cp1252/cp850).
• Instalar el conector en C:\api_project\foxpro (node.exe portable + config.json + token + instalar-servicio.ps1) y probar desde el backend.
• Módulo del sistema: migración (conexiones, fuentes/mapeos, empleados, vínculo usuario↔empleado), backend modules/integrations, pantalla en Configuración, botón en Organización, alta de usuario desde nómina, búsqueda de pacientes externa en la Agenda.