# Estado vivo de SaludDigital

Actualizado: 2026-08-18 · Versión: `0.32.0-staging`

## Entornos y seguridad

- Producción: `/saluddigital`. No modificar durante la migración sin aprobación y respaldo.
- Staging conectado: `/saluddigital2`. Es el destino autorizado para cambios y pruebas actuales.
- Arquitectura actual: PHP, MariaDB/MySQL, JavaScript, Alpine.js, TCPDF y PhpSpreadsheet.
- Los datos privados se aíslan por `id_ips` y, cuando corresponde, por `id_sede`.
- SuperAdmin requiere una IPS activa explícita para operar datos empresariales.

## Capacidades disponibles

- El calendario permite cancelación auditada con motivo catalogado; libera agenda y anula únicamente atenciones y servicios pendientes.
- El recaudo diferencia cuota moderadora fija y copago porcentual, resolviendo afiliación, convenio, estrato, tarifa vigente y topes.
- La reprogramación y cancelación usan SweetAlert iOS; los errores permanecen en español y conservan el contexto.
- El recordatorio de cita usa el encabezado institucional, código verificable y presentación profesional.
- La voz prepara fecha, hora y observaciones en español colombiano, pero requiere revisión humana antes de programar.
- Una cita crea una atención pendiente. Para Homecare está pendiente un episodio de ingreso padre que agrupe múltiples citas sin mezclar sus ejecuciones.

- Programar citas está habilitado en Ingresos y crea una atención pendiente sin completar artificialmente el motivo clínico o la enfermedad actual.
- Una cita puede reservar cupo de agenda o usar asignación directa; el segundo modo exige motivo y conserva auditoría.
- Las citas validan afiliación y convenio vigentes, sede, clase, especialidad, profesional, cruce horario y requisitos de autorización.
- Los paquetes registran un padre facturable y componentes hijos incluidos, ejecutables y no facturables, evitando cobro doble.

- Las clases de cita heredadas están conciliadas con procedimientos, especialidades, finalidades, IPS y sede reales de staging.
- Configuración de Citas incluye tipos de atención, modalidades, entornos, motivos de desistimiento y conceptos de copago.
- La futura programación admite reserva con agenda o asignación directa para personal de planta; esta última requerirá motivo y auditoría.

- Área Financiera y Contable inicia con Facturación y precios versionados de procedimientos por convenio y manual.
- Las tarifas conservan historia, rechazan vigencias solapadas y resuelven el grupo RIPS desde el servicio seleccionado.
- Configuración permite relacionar tipos de procedimiento con servicios contractuales y procedimientos con servicios RIPS.

- Agenda de profesionales administra disponibilidad por IPS, sede, profesional y especialidad mediante fechas múltiples normalizadas.
- Los horarios pueden provenir de un turno institucional o definirse de forma personalizada; los cupos se calculan según la duración de la cita.
- El servidor valida sede, especialidad y profesional, e impide cruces de horario para una misma fecha.

- Configuración de Citas administra clasificaciones institucionales, causas externas y vías de asignación.
- Ingresos administra clases de citas por IPS/sede, con procedimiento, especialidad, finalidad automática y duración.
- Consultorios pertenece a una sede concreta y conserva capacidad, accesibilidad y especialidad opcional.

- La integración de correo institucional para glosas y solicitudes quedó documentada como iniciativa pendiente; se retomará junto con la arquitectura comercial y no está habilitada ni desplegada.

- Acceso institucional, recuperación de contraseña, usuarios, perfiles profesionales y administrativos.
- La edición de usuarios actualiza de forma segura los perfiles administrativos y profesionales; los errores conservan abierto el formulario y sus datos.
- Menú modular, permisos, notificaciones, chat interno, tickets y asistente contextual.
- Catálogos personales, empresariales, contables y contractuales con Select2 y paginación de 10 registros.
- Gestión de IPS, sedes, imágenes, resoluciones y configuración progresiva de ApiDian, RIPS y RDA.
- Los logos de IPS se conservan como archivos privados versionados, se muestran al editar y alimentan el encabezado compartido de PDF y Excel.
- Empresas clasificadas como EPS, empresa/tercero o ARL, relacionadas con la IPS y sede.
- Gestión de convenios EPS con convenio padre y cinco configuraciones derivadas:
  - tipos de afiliado;
  - contratos;
  - estratos, copagos y cuotas moderadoras;
  - servicios y manuales tarifarios.
  - procedimientos y tarifas con vigencias históricas.
- Maestro universal de procedimientos con clasificación clínica, laboratorio, códigos y homologación RIPS.
- Los procedimientos incorporan tipo de atención, duración en minutos, unidad, perfiles ejecutores y composición de paquetes.
- Gestión de procedimientos administra la composición de paquetes con procedimientos hijos, cantidad, obligatoriedad y orden; el guardado completo es transaccional.
- La barra de filtros de procedimientos conserva buscador, tipo, estado y Limpiar en una sola fila de escritorio, con adaptación responsiva.
- El mapeo heredado conserva evidencia y nivel de confianza: 160 propuestas automáticas aprobadas y 259 casos ambiguos pendientes de revisión.
- Un profesional es único por persona e IPS y puede tener varias especialidades y sedes sin duplicarse.
- Migración laboral aplicada en staging: 635 personas/cuentas, 625 profesionales únicos derivados de 707 filas heredadas, 19 administrativos, 9 perfiles mixtos y 701 relaciones activas de especialidad.
- Se recuperaron 609 firmas heredadas como archivos privados PNG/JPG, sin rutas rotas ni MIME inválido; siete referencias requieren carga manual.
- Los hashes bcrypt heredados se conservaron; la cuenta SuperAdmin mantuvo sus credenciales y estado de staging.
- La migración laboral es idempotente, conserva mapeos origen/destino y registra incidencias conciliables.
- Catálogo heredado cargado: 7.864 procedimientos, 157 servicios RIPS, 5 grupos y 125 registros padre; conserva IDs y no presenta relaciones huérfanas.
- Los nueve catálogos de procedimientos permiten buscar por nombre o código sin distinguir tildes y conservan paginación desde servidor.
- Migración empresarial aplicada en staging: 1.640 empresas, 22 EPS, 29 convenios, 59 afiliaciones, 21 contratos, 117 reglas de estrato y 65 servicios, sin relaciones huérfanas.
- Las empresas naturales muestran el nombre completo compuesto por nombres y apellidos; las jurídicas muestran exclusivamente su razón social. La búsqueda empresarial cubre ambos casos.
- Primer bloque de catálogos heredados migrado con IDs conservados: documentos, estado civil, discapacidad, etnia, geografía, barrios y población especial.
- Núcleo comercial para productos, planes, módulos, límites y suscripciones por IPS.
- Reportes institucionales PDF y Excel filtrados con datos reales.
- PDF y Excel están disponibles de forma consistente en los CRUD administrativos, incluidos Empresas, Convenios, Procedimientos, catálogos empresariales/contractuales/clínicos, Productos, Planes, Menús y Tickets.
- Área Administrativa iniciada con Admisión de pacientes: identidad única por IPS, afiliación versionada, contactos responsables y evidencia versionada de tratamiento de datos.
- Pacientes permite filtrar por EPS, tipo de afiliado, estado y rango de ingreso, con paginación de servidor, PDF y Excel.
- Los formularios por pasos reutilizan `sd-modal-pestanas`, con el patrón iOS de Convenios y navegación responsive accesible.
- El visor del consentimiento se superpone sin activar el cierre del formulario ni descartar datos diligenciados.
- El blur documental restaura en secuencia sexo → identidad y departamento → municipio sin romper Select2.
- Estratos y tipos de afiliado dependen del convenio; la API valida ambas relaciones antes de guardar.
- La migración de pacientes conserva identidades e historias y activa solo afiliaciones conciliadas sin ambigüedad.
- La tabla de pacientes usa anchos explícitos y jerarquía principal/secundaria para evitar datos concatenados.
- El catálogo de parentescos contiene los 15 registros heredados con IDs conservados, sin duplicados y disponible para responsables y consentimientos.
- La edición de pacientes traduce causas conocidas a español, conserva el modal y señala campos de sede, afiliación, estrato, parentesco, correo y fechas.
- El monitor de calidad de Admisión analiza métricas y anomalías agregadas por IPS en modo de solo lectura y sin exponer identidad de pacientes.
- PDF y Excel de pacientes reproducen el patrón institucional de Tipo de documento con KPI, filtros, identidad real de IPS y configuración de impresión.
- El agente diferencia solicitudes DIAN institucionales de controles RIPS/RDA del paciente y remite los datos sensibles a formularios seguros.
- Admisión exige permiso explícito del módulo; crear, editar, consultar, exportar y cambiar estado conservan el aislamiento de la IPS activa.
- El formulario de pacientes administra caracterización, lugar de nacimiento, ubicación, barrio, grupo sanguíneo, ocupación y campos administrativos sin crear columnas duplicadas.
- La edad y su unidad se recalculan desde la fecha de nacimiento; las relaciones de sexo-identidad, geografía, convenio, afiliado y estrato se validan en el servidor.
- Los cambios de EPS, convenio, tipo de afiliado o estrato versionan la afiliación: finalizan la anterior y crean una vigencia nueva.
- La edición consulta el estado y la versión real del consentimiento; solo solicita nueva aceptación cuando falta o cambió el documento vigente.
- Documentos informados separa plantillas versionadas, documentos emitidos y evidencias de firma; congela el contenido entregado y conserva hashes SHA-256.
- Antes de emitir, Documentos informados muestra una vista previa con el paciente real y la identidad institucional de la IPS; Gestión documental permite simular la plantilla con datos de ejemplo sin guardarla.
- El documento emitido conserva encabezado institucional, logo principal, datos de contacto, NIT, sede y logo Supersalud resueltos desde la IPS activa.
- La firma manuscrita usa SignaturePad con coordenadas internas iguales a las visibles; el canvas cancela la activación delegada del contenedor para impedir que escritorio accione el botón Limpiar al soltar. QR de un solo uso y huellero quedan pendientes de validación técnica específica.
- Documentos informados no mantiene plantillas paralelas: resuelve la versión publicada, activa y vigente de Gestión documental en cada apertura y vuelve a validarla al emitir.
- La plantilla vigente y el documento emitido se muestran dentro de un iframe autorizado del mismo origen; el emitido conserva la versión histórica que el paciente recibió.
- La captura manuscrita reutiliza SignaturePad 4.0.0 local, con suavizado y soporte uniforme para mouse, lápiz y táctil.
- La presentación documental normaliza títulos y cuerpo sin alterar el contenido versionado; los documentos históricos sin encabezado se envuelven únicamente para visualización institucional.
- El visor usa una superficie horizontal de hasta 1080 × 760 px en escritorio y ocupa la pantalla disponible en móvil.
- La vista previa del editor de Gestión documental utiliza el mismo documento institucional y tipografía de Documentos informados dentro de un iframe `srcdoc`; al cerrarla, conserva el borrador y vuelve al editor.
- El modal de documentos del paciente presenta nombre y código en dos niveles; versión, estado y acciones permanecen separados y alineados, con desplazamiento horizontal controlado en móvil.
- Autorización para tratamiento de datos y Consentimiento Homecare comparten el mismo formato visual institucional; cada uno conserva su nombre, código y contenido jurídico versionado.
- Gestión documental vuelve a abrir siempre la última versión creada y verifica su ID y hash después de guardar; el modal permanece abierto si el servidor no confirma la persistencia.
- Un borrador documental se conserva como nueva versión, pero no sustituye el documento operativo hasta publicarse.

## Convenciones obligatorias

- La capa `tablas-ios.css` se carga globalmente desde `ui-ios.js`; toda celda principal/secundaria usa `.sd-celda-doble` y nunca concatena visualmente ambos valores.

- El lienzo de firma no puede cambiar `width` ni `height` durante una captura: modificar esas propiedades borra el contexto y el trazo activo, especialmente en escritorio.

- La firma documental usa un único motor SignaturePad, exige confirmación, evita doble envío e incorpora imagen, firmante, fecha y hash al documento emitido sin alterar versiones anteriores.

- Documentos informados presenta en español la causa recibida, los errores de campos y el código de incidente; un fallo no cierra ni limpia el flujo activo.

- El editor documental permite alineación completa, títulos, tamaños, colores, resaltado, listas y sangrías; solo conserva HTML y CSS incluidos en la lista blanca de servidor.

- Español y UTF-8 sin BOM en interfaces, API, documentación y datos semilla.
- Modales, SweetAlert2, formularios y controles usan el patrón iOS compartido.
- Todos los select visibles usan Select2; en modales se configura `dropdownParent`.
- En Gestión documental, los Select2 conservan su ancho al cambiar pestañas; el modal reserva el espacio de la barra de desplazamiento y cierra desplegables abiertos durante el scroll.
- Documentos informados señala versiones pendientes desactualizadas y permite regenerarlas con la publicación vigente; solo anula pendientes anteriores y conserva intactos los firmados.
- Gestión documental permite abrir expresamente la versión publicada y activa, separada de la edición en curso; ambos módulos comparten el diseño institucional canónico del consentimiento Homecare.
- El visor de Gestión documental carga el documento completo mediante una URL temporal y el editor normaliza títulos, párrafos, listas y tablas con la escala institucional.
- Gestión documental presenta la vista saneada directamente dentro del modal, evitando incompatibilidades de iframe, srcdoc o URL blob.
- El contenido documental normaliza encabezados vacíos o sin cierre al editar, guardar y renderizar; las versiones históricas permanecen inmutables.
- Listados intervenidos consultan 10 registros por página desde el servidor.
- Tablas usan jerarquía principal/secundaria, anchos explícitos y acciones con `aria-label` y `data-tooltip`.
- Un error de validación o API nunca cierra ni limpia el formulario; solo se cierra por éxito o decisión explícita del usuario.
- Cada cambio visible incrementa versión y actualiza documentación y conocimiento de IA.

## Procedimientos y tarifas — 0.17.0-staging

- Los catálogos clínicos y el maestro de procedimientos son universales para evitar duplicación entre IPS.
- La tarifa es privada por IPS y depende del convenio, el manual y el procedimiento.
- Un cambio de precio crea una nueva vigencia; el precio histórico no se sobrescribe.
- El sistema bloquea intervalos activos solapados para el mismo procedimiento y manual.
- Las búsquedas, filtros y cambios de página consultan el servidor en bloques de 10.

## Migración de catálogos — 0.17.1-staging

- La semilla es idempotente y fue probada dentro de una transacción con rollback.
- Departamentos, municipios y barrios se cargaron respetando su orden y claves foráneas.
- No existen municipios o barrios huérfanos después de la carga.
- Los duplicados naturales heredados se conservaron para no romper referencias por ID.
- Está pendiente contrastar el catálogo geográfico con una fuente DANE completa y aprobada.

## Migración clínica — 0.17.3-staging

- Los procedimientos y catálogos RIPS se cargaron de padres a hijos mediante una semilla idempotente.
- Se conservó el tipo de procedimiento con ID `0` mediante `NO_AUTO_VALUE_ON_ZERO`.
- Los 137 códigos CUPS repetidos se preservaron porque representan registros heredados distintos; el código se mantiene indexado, pero no es único.
- Los estados nulos heredados se normalizaron a activo y los booleanos nulos a `0`.
- Seis valores de sexo vacíos o `0` se homologaron a `A` (aplica a ambos).
- La prueba completa con `ROLLBACK` pasó antes de aplicar la carga definitiva.

## Riesgos conocidos

- Existen 69 procedimientos heredados marcados como paquete sin hijos activos; requieren composición manual validada y no deben inferirse por nombre.

- El VPS debe confirmar soporte IMAP, conectividad TLS, antivirus y límites de almacenamiento antes de activar la sincronización de correo institucional.

- El código heredado contiene archivos sin uso confirmado; no eliminarlos sin inventario y evidencia.
- Algunos secretos regulatorios heredados aún requieren migración completa a almacenamiento cifrado.
- Las integraciones externas deben probarse por etapas y nunca asumir éxito por el guardado local.
- La cobertura automática de pruebas todavía es limitada; cada despliegue exige pruebas de humo en staging.
- Cinco regímenes históricos detallados se consolidaron en sus categorías regulatorias canónicas; debe validarse funcionalmente su presentación antes de promover a producción.
- Tres cuentas de prueba previas no tienen una persona válida relacionada; permanecen inactivas y con `identidad_validada=0` hasta conciliación manual.
- Cuatro usuarios heredados repetidos se renombraron con sufijo `.legacy<ID>` y quedaron inactivos para revisión.
- La mayoría de módulos del sistema anterior todavía no existen en la nueva arquitectura; sus permisos quedaron documentados como pendientes y no se concedieron por aproximación.
- De 1.710 pacientes heredados, 1.558 pertenecen a EPS con varios convenios activos posibles; sus convenios no deben inferirse automáticamente durante la migración.
- Los 1.710 consentimientos heredados son indicadores declarados sin firma recuperable; deben conservarse como históricos y no presentarse como aceptación digital firmada.

## Próximas prioridades

1. Corregir los bloqueadores documentados en la auditoría integral de Admisión de pacientes.
2. Completar edición, estado y detalle longitudinal del paciente antes de migrar datos heredados.
3. Definir reglas verificables para conciliar afiliaciones heredadas pendientes sin inferir convenios ambiguos.
4. Construir Documentos Informados y Cambio de Documento sobre las tablas versionadas ya disponibles.
5. Poblar los catálogos clínicos con fuentes regulatorias verificadas.

## Cambio de documento — 0.25.0-staging

- El módulo permite solicitar correcciones de identificación y conserva el documento anterior, el nuevo, motivo, solicitante, decisor y fechas.
- Aplicar o rechazar está reservado a SuperAdmin; los demás usuarios requieren permiso explícito para consultar y solicitar.
- La aplicación conserva el ID de `p_datos_personales`, por lo que no modifica las relaciones del paciente, historia, afiliaciones o documentos.
- El servidor bloquea documentos duplicados, solicitudes simultáneas y cambios cuya identidad anterior ya no coincida.
- Incluye paginación de 10 registros, KPI, filtros y reportes institucionales PDF y Excel.

## Sugerencia vigente

## Calendario y recaudos de citas — 0.31.0-staging

Estado complementario: edición de citas disponible y 359 precios heredados cargados en
`e_procedimiento_convenio`, sin registros huérfanos. El archivo fuente validado se conserva en
`database/datos/precios_procedimientos_heredados_20260816.json` y el proceso reproducible en
`scripts/migrar_precios_procedimientos.php`.

- Programar citas dispone de vistas mensual, semanal y diaria.
- La reprogramación por arrastre exige motivo, vuelve a validar cruces y conserva historial.
- Copagos y cuotas moderadoras se calculan desde convenio y estrato, se registran con consecutivo por IPS y generan colilla institucional.
- Cada cita permite imprimir un recordatorio institucional; la colilla de recaudo no se presenta como factura electrónica.

Después de validar tarifas, conviene continuar con pacientes y afiliaciones; luego agenda, órdenes y facturación podrán consumir convenio, procedimiento y precio vigente sin duplicar reglas.

## Correcciones de calendario y recaudo — 0.31.1-staging

- El concepto del recaudo proviene de `c_copagos`, se conserva en `c_cita_recaudo` y se imprime en la colilla.
- El calendario permite crear una cita pulsando el día y editar una cita pulsando el evento.
- Se eliminó el desfase de fecha provocado por calcular el día actual directamente en UTC.
- La edición incluye la agenda ocupada por la cita actual para que un cupo lleno no bloquee su propio formulario.
- El diagnóstico confirmó que la cita crea atención pendiente y servicios, pero no órdenes ambulatorias ni financieras porque esas tablas aún no existen en staging.
- Próxima decisión: crear el esquema de preliquidación y generar en una sola transacción la orden clínica y el detalle financiero con la tarifa vigente congelada.