Troubleshooting de usuario final

Esta página resuelve los problemas operativos más frecuentes. Si no encuentras tu caso, escribe a soporte@emahealth.io con un screenshot del error y la URL de tu pantalla.

Consejo

Antes de reportar un bug: prueba con Ctrl + Shift + R (hard refresh) y verifica que tu navegador esté actualizado. El 60% de los “bugs” reportados se resuelven con esto.

No puedo loguearme

”Credenciales inválidas”

• Revisa que el correo esté escrito sin espacios.
• Confirma con tu admin que tu usuario está activo.
• Si olvidaste la contraseña, click en ¿Olvidaste tu contraseña? → recibirás un magic link por email.

”Tenant no resuelto”

• Verifica que estés en la URL correcta de tu lab (ej: aurora.lab.emahealth.io, no lab.emahealth.io directamente).
• Limpia el localStorage del navegador (DevTools → Application → Local Storage → Clear).
• Pídele a tu admin que verifique tu fila en user_roles con product='lab'.

”Tu sesión expiró”

• Normal después de ~1h de inactividad.
• Solo vuelve a loguearte. Los drafts de resultado se preservan.

El check-in rechaza un tubo con “barcode no encontrado”

Causas:

• Etiqueta dañada — barcode no escanea bien. Re-imprime etiqueta con Imprimir etiqueta desde la orden.
• Orden de otro tenant — el barcode existe pero en otro lab. Verifica con recepción del lab origen.
• Barcode generado fuera del sistema — solo aceptamos códigos generados por EMA Lab (Code 128B + Luhn).

Solución: si la etiqueta está dañada, escanear manualmente el código o ingresarlo a mano y re-imprimir.

El TM no ve un test en su worklist

Causas posibles:

1. El test fue ruteado a otra sección — verificar routing_rules. Si la sección destino es errónea, admin puede corregir.
2. Tu rol no tiene acceso a esa sección — verificar tech_section_auth (L028). Admin agrega tu fila.
3. El test sigue en orden, no llegó muestra — Specimen.status debe ser received antes de aparecer en worklist.

”No autorizado para validar esta sección”

Causa: tu tech_section_auth no tiene esa sección + level activo.

Solución:

• Admin va a Settings → Users → <tu nombre> → Tab Secciones.
• Marca el checkbox de la sección correspondiente.
• Selecciona level: technical (puedes validar técnico) o clinical (puedes firmar clínico — director).
• Click Guardar.
• Refresh tu navegador.

El resultado no entra a Stage 2 EMI (queda en Stage 1)

Causas:

• tech_section_auth no autorizó tu firma técnica → revisar arriba.
• Resultado fuera de rangos físicos (ej: glicemia=10000) → sistema bloquea Stage 2 hasta que TM corrija o confirme.
• EMI evaluator timeout → esperar 30s o re-trigger con POST /api/validation/stage2/:id/retry.

El reporte XLSX se descarga vacío

Causas:

• Sin datos en el rango — el engine corre sobre el periodo seleccionado. Si no hay órdenes, sale vacío.
• Filtros mal aplicados — verifica que el cliente / sección seleccionados sí tengan actividad.
• R2 binding no configurado — error 501 visible. Avisar a admin.

El Hub local no se conecta

Diagnóstico paso a paso:

1. Verificar Docker corriendo: docker ps | grep emalab-hub.
2. Ver logs: docker logs emalab-hub | tail -100.
3. Probar internet desde container: docker exec emalab-hub ping -c 3 lab.emahealth.io.
4. Verificar token activo: admin chequea hub_registry en DB.
5. Renovar token si expiró: admin ejecuta POST /api/hub/renew-token y actualiza el .env del Docker.
6. Cambiar CONNECTION_MODE si el firewall bloquea SSE: polling es el más conservador.
7. Hacer pull de la última imagen: docker pull ghcr.io/emahealth/emalab-hub:0.2.0 y restart.

El cultivo está en stage incubation por días sin moverse

Causas:

• TM olvidó marcar growth_detected — sistema no lee la placa por vos, hay que actualizar manual.
• Cultivo realmente sin crecimiento — esperar timeout (48h o específico por tipo) y marcar negative (NO automático per ADR-021).

Hemocultivo+ no generó Task crítica

Causas posibles (ver FAQ técnica):

1. critical_value_source no marcó la Observation como critical (L047). Verificar:

   SELECT * FROM emalab.critical_value_source
   WHERE observation_fhir_id = '<id>';

2. Trigger del flag hemocultivo+ no se activó — re-trigger manual: POST /api/micro/cultures/:id/escalate-critical con razón.
3. Notification settings del MD están off — admin verifica client_config.notification_channels.

El QR del reporte no verifica

Causas:

• Verify code expirado (90 días default) → re-firmar DR.
• DR fue amended → el QR del original se invalida. Usar el del DR actual.
• Tenant slug incorrecto en URL → debe ser /portal/verify/:code?tenant={slug} exacto.
• Rate limit (30/min público) → esperar 1 min.

La importación molecular falla

Causas:

• Parser no registrado — admin agrega parser nuevo a parser-registry.ts.
• Header del archivo cambió (vendor actualizó formato) — admin ajusta match() del parser.
• Archivo corrupto / no es CSV/JSON válido — verificar abrir en Excel o text editor.

El conector HL7v2 outbound rechaza con “ACK no AA”

Causas:

• EHR cliente recibió pero rechazó (mensaje malformado, paciente no encontrado, etc.) — ver el ACK detail.
• Sistema lo encola en retry queue (L048) — espera reintento automático cron */5min.
• Si después de N retries sigue fallando → DLQ alert (Loops email) al admin.

Olvidé mi contraseña / quiero cambiarla

• En login, click ¿Olvidaste tu contraseña?.
• Recibes magic link (válido 15 min).
• Al ingresar, configuras nueva en Mi perfil.

¿Cómo veo los cambios que hice?

Cualquier rol puede ver el audit de su propia actividad en Mi perfil → Mi actividad. El admin puede ver el de todo el lab en Config → Audit logs.

Reportar un bug

Si nada de lo anterior aplica:

1. Reproducir el bug.
2. Tomar screenshot.
3. Abrir DevTools (F12) → tab Console → screenshot también.
4. Enviar a soporte@emahealth.io con:
   • Pasos para reproducir.
   • Screenshots.
   • Hora aprox del bug.
   • Tu rol y la URL de tu lab.

Consejo

EMI puede ayudarte a diagnosticar errores. Click en el botón coral, pega el mensaje de error y pregunta. Cuando esté habilitado en Wave 5, tendrá contexto del producto.