# 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`](../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.