Saltar al contenido principal

Dashboard de Entidad de Salud

1. Definición y Propósito​

Permite a la entidad gestionar sedes, convenios con aseguradoras, staff afiliado y agenda por consultorio, manteniendo la Validación Triple y ocupación óptima.

2. Lógica Visual y de Procesos​

2.1 Board Miro (referencia visual)​

2.2 Flujo Lógico Canonico​

Resumen textual (fallback)​

  • Home: KPIs de ocupación por sede y alertas de convenios vencidos.
  • Staff: alta/baja de profesionales de la salud afiliados, asignación de salas/horarios.
  • Convenios: carga/actualización de aseguradoras y planes; invalida caché tras cambios.
  • Agenda Sede: vista de slots por consultorio, bloqueos operativos.
  • Multimedia: gestión de fotos/amenidades de la sede.

Evidencia visual​

  • Fuente canonica: diagrama Mermaid de esta seccion.
  • Si UX adjunta board Miro, se agrega como anexo y no reemplaza la especificacion contractual.

3. Actores y Permisos (RBAC)​

ActorPermisos
Entidad AdminGestiona sedes, staff, convenios, amenidades. Roles acumulativos: puede mantener PATIENT y/o DOCTOR además de ENTITY_ADMIN.
Profesional de Salud afiliadoSolo visualiza sus citas en esa sede.
Admin PlataformaPuede forzar bloqueos y validar convenios críticos.

4. Reglas de Negocio (BR)​

  • BR-DE-01: Cambios en convenios invalidan caché de búsqueda y Validación Triple de inmediato.
  • BR-DE-02: No se puede eliminar una sede con citas futuras; aplicar borrado lógico (deleted_at).
  • BR-DE-03: Staff afiliado requiere relación en affiliations con horarios válidos.
  • BR-DE-04: Imagen de portada obligatoria por sede visible en buscador.
  • BR-DE-05: Datos mínimos para crear entidad (todos obligatorios, salvo donde se indique):
    • type: clínica | laboratorio | farmacia.
    • name (Nombre comercial).
    • legal_name (Razón social).
    • email (precargado del usuario, editable).
    • phone.
    • geography_id (país/departamento/municipio) + address (texto libre).
    • location (lat/lng) si se dispone; si no, derivar de geocoding de la dirección.
    • schedules (horarios de atención) – al menos uno.
    • services (JSON de servicios ofrecidos).
    • terms_version_accepted (bool + timestamp).

5. Endpoints (referencia OpenAPI)​

RecursoMétodoDescripción
/api/v1/insurance-agreementsPOSTRegistrar convenio sede-seguro.
/api/v1/insurance-agreementsGETListar convenios por sede.
/api/v1/entitiesPOSTCrear sede.
/api/v1/entities/{id}PATCHActualizar sede.
/api/v1/affiliationsPOSTAfiliar profesional de la salud a sede.
/api/v1/appointmentsGETLista citas por sede (role=ENTITY_ADMIN/DOCTOR).
/api/v1/professional/couponsPOSTCrear cupón de la entidad.
/api/v1/professional/coupons/{id}PATCHEditar cupón de la entidad.

Implementación Backend (Go, DDD + Clean Architecture):

  • Handlers en interfaces/http/entity mapean DTOs a use cases CreateEntity, UpdateEntity, CreateAgreement, ListAgreements, AffiliateDoctor, ListEntityAppointments en application/entity.
  • Repos EntityRepo, AgreementRepo, AffiliationRepo, AppointmentRepo como interfaces; implementaciones en infrastructure/persistence (Postgres) y infrastructure/cache (invalidación inmediata).
  • DTOs de OpenAPI son de interfaz; entidades de dominio permanecen aisladas de persistencia.
  • Nomenclatura completa: ver arquitectura-y-despliegue.md §7.1.

6. Métricas y Observabilidad​

  • Ocupación por sede y consultorio.
  • Tiempo de invalidación de caché tras cambio de convenio.
  • Latencia P95 de ListAgreements < 300ms; CreateAgreement < 500ms.
  • Trazas con trace_id, entity_id, agreement_id, doctor_id.

7. Casos de Borde y Manejo de Errores​

  • Eliminar sede con citas futuras → 409 “Sede con citas activas”.
  • Crear convenio duplicado (misma sede/seguro) → 409.
  • Afiliar profesional de la salud sin horarios válidos → 422.
  • Carga de imagen sin portada → 422.
  • Archivo de portada/convenio con MIME/peso inválido → 422.
  • Doble submit en convenio → idempotencia por combinación sede+seguro.

8. Control de Abuso/Fraude y Auditoría​

  • Rate limit en creación de convenios y afiliaciones para evitar spam.
  • Validar MIME/peso de imágenes de sede.
  • Auditoría obligatoria:
    • ENTITIES: evento ENTITY_UPDATED con changed_by, timestamp, IP/UA, diff; aprobaciones/rechazos registran motivo.
    • Convenios: AGREEMENT_UPDATED.
    • Invitaciones/afiliaciones de staff: AFFILIATION_CREATED/UPDATED.

9. Checklist de QA / Testing​

  • Crear sede y actualizar datos básicos.
  • Registrar convenio y verificar invalidación de cache en buscador.
  • Afiliar profesional de la salud y ver citas filtradas por sede.
  • Borrado lógico bloqueado si hay citas futuras.
  • Subida de portada valida formato/peso.
  • Doble submit de convenio no duplica registros.

10. Requerimientos No Funcionales (NFR)​

  • P95 entity_update < 400ms; agreement_create < 500ms.
  • Disponibilidad 99.9% para lectura de convenios y sedes.
  • Cache hit >80% en lecturas de convenios.

11. Variables de Entorno (Front)​

  • VITE_API_BASE=https://api.example.com/api/v1
  • VITE_ENTITY_PAGE_SIZE=20
  • VITE_ENTITY_IMAGE_MAX_MB=2

12. Accesibilidad (A11y)​

  • Formulario de sede navegable por teclado.
  • Notificaciones de estado con aria-live al crear/actualizar.
  • Tabla de convenios con encabezados accesibles.

13. Métricas de Producto (Funnel)​

  • Sedes creadas → convenios activos → profesionales de la salud afiliados → citas atendidas.
  • Tiempo medio de publicación de convenios; % de sedes con portada.

14. Enlaces y Trazabilidad​

  • Swagger UI: /swagger.html (acceso desde /swagger) y contrato YAML en /openapi.yaml.
  • Relacionados: admin-catalogos.md (geo/specialties), agenda-citas.md, esquema-de-base-de-datos.md (entities, agreements, affiliations).

15. Dependencias​

  • health_entities, insurance_agreements, affiliations, appointments, file_assets.