Módulo de Auditoría y Verificación (Backoffice)
1. Definición y Propósito
Este módulo permite al equipo administrativo de la plataforma validar la veracidad de la información legal y profesional proporcionada por los Profesionales de la Salud y las Entidades de Salud durante su registro.
- Contexto: En un ecosistema de salud, la confianza es el activo principal.
- Valor de Negocio: Previene el intrusismo profesional y garantiza que solo establecimientos legalmente constituidos (con NIT/Tax ID válido) sean visibles para los pacientes.
2. Actores y Responsabilidades
| Actor | Función en el Módulo |
|---|
| SuperAdmin | Puede aprobar/rechazar perfiles y revertir decisiones de validación. |
| Sistema (Cron) | Marca perfiles como "Expirados" si la validación anual ha vencido. |
3. Reglas de Negocio (Business Rules)
- BR-AUD-01 (Invisibilidad por Defecto): Ningún perfil de
DOCTOR o ENTITY_ADMIN será retornado por la API del Buscador Público si su status no es VERIFIED.
- BR-AUD-02 (Trazabilidad de Cambios): Toda aprobación o rechazo debe registrar el ID del administrador, la fecha y una razón justificada en el log de auditoría.
- BR-AUD-03 (Notificación Automática): Al cambiar el estado de un perfil, el sistema debe disparar automáticamente un correo/notificación al usuario informando el resultado del proceso.
- BR-AUD-04 (Bloqueo de Edición): Mientras un perfil esté en revisión, ciertos campos críticos (como No. de Colegiado o NIT) quedan bloqueados para el usuario.
- BR-AUD-05 (Terminología oficial): En UX usar "Profesional de la Salud"; en API mantener el tipo técnico
DOCTOR.
- BR-AUD-06 (Tipado canónico): En auditoría se usa
profile_type técnico (DOCTOR o ENTITY) para clasificar expedientes; esto no reemplaza roles RBAC (DOCTOR, ENTITY_ADMIN, SUPERADMIN).
4. Diccionario UX-Técnico por Pantalla
[AUD-100] Bandeja de Entrada de Validaciones
- Objetivo: Listar todas las solicitudes pendientes de revisión.
- Filtros Clave: Tipo (Profesional/Entidad), Fecha de registro, Especialidad.
- Mapeo de tipo técnico:
DOCTOR => Profesional de la Salud, ENTITY => Entidad de Salud.
| Elemento UI | ID Técnico (API) | Comportamiento / Lógica |
|---|
| Tabla de Solicitudes | pending_queue | Lista paginada de perfiles en estado PENDING. |
| Botón Revisar | btn_inspect | Redirige al detalle de auditoría [AUD-200]. |
[AUD-200] Detalle de Inspección de Perfil
- Objetivo: Comparar los datos ingresados con las pruebas legales.
| Elemento UI | ID Técnico (API) | Validación / Lógica |
|---|
| Link Colegio Médicos | external_validation_url | Abre en pestaña nueva la búsqueda oficial por No. de Colegiado. |
| Selector de Estado | new_status | Opciones: VERIFIED, REJECTED, INFO_REQUIRED. |
| Campo Observación | admin_notes | Obligatorio si el estado es REJECTED o INFO_REQUIRED. |
| Botón Confirmar | btn_submit_audit | Dispara el cambio de estado en DB y la notificación al usuario. |
5. Acciones Técnicas y Eventos (Backend)
- Evento
PROFILE_VERIFIED:
- Cambia
status a ACTIVE.
- Limpia la caché del motor de búsqueda para incluir al nuevo proveedor.
- Envía Email de "Bienvenida al Directorio".
- Evento
PROFILE_REJECTED:
- Mantiene el registro pero bloquea el acceso al dashboard.
- Registra el motivo del rechazo para futuras consultas de soporte.
5.1 Endpoints de Backoffice (OpenAPI)
| Recurso | Método | Descripción |
|---|
/api/v1/admin/audits/pending | GET | Cola de perfiles pendientes por profile_type técnico (DOCTOR/ENTITY). |
/api/v1/admin/audits/{id} | GET | Detalle de expediente y evidencias. |
/api/v1/admin/audits/{id}/decision | POST | Aprobar, rechazar o solicitar información adicional. |
6. Mermaid: Ciclo de Vida de Verificación Profesional
Este diagrama detalla cómo un Profesional de Salud llega a ser visible en el ecosistema.