Diagnóstico de incidencias
Registrar síntoma, hora UTC, entorno, commit, URL y comando reproducible. Redactar tokens, credenciales, correos y contenido privado antes de compartir logs. No corregir un fallo local cambiando producción.
| Síntoma | Comprobación y siguiente paso |
|---|---|
| Instalación o Vite falla | Comparar Node/Bun con preparación, instalación congelada y lockfile correcto para raíz/panel. No regenerar locks como primera medida. |
lint falla por runtime ausente |
Usar npm run lint, que ejecuta prelint; revisar la salida de generación antes del error TypeScript. |
Falta dist/.vite/manifest.json |
Ejecutar npm run build antes de npm run check:bundle. El control incluye la ruta editor y exige seis paneles diferidos y menos de 1.300.000 bytes iniciales. |
| MCP o API devuelve 503 | Revisar orígenes, proyecto y credencial Admin del servidor sin imprimir valores. Es comportamiento cerrado ante configuración ausente; véase configuración. |
| API devuelve HTML | Revisar ruta, rewrites y artefacto remoto. vite preview solo no verifica los adaptadores productivos. |
| Emulador no inicia | Revisar Java 17, descarga inicial y ocupación 8080/9099; usar los scripts que fijan firebase.test.json y demo-nexusbuilder. |
| Emuladores rechazados | Mantener modo cliente mcp-test, proyecto demo, servidor NODE_ENV=test y hosts loopback explícitos. No debilitar las validaciones. |
| Chromium no disponible | npx playwright install chromium; en Linux CI instala también dependencias. Si existe binario compatible, usar la variable admitida por el runner concreto. |
| Test de navegador espera indefinidamente | Revisar proceso Vite, puerto y logs del runner; no dejar servidores huérfanos. WOOKCOM_BROWSER_LOG solo sirve al runner Wookcom. |
| Panel deniega acceso | Distinguir sesión Firebase del custom claim admin: true; tras un cambio de rol se requiere renovar sesión. No otorgar privilegios para resolver una prueba con fixtures. |
| Credencial comercial no descifra | Revisar disponibilidad de la clave de facturación original. Rotar la clave implica volver a guardar credenciales cifradas; no borrar datos para ocultar el error. |
| Dominio publicado no responde | Separar resolución DNS, certificado TLS, asociación al alojamiento y mapeo de publicación. No declarar un wildcard operativo por existir configuración local. |
Si CI falla y local pasa, comparar versiones y aislamiento de red Linux, artefactos del job y comandos exactos. Las pruebas de navegador no cubren lectores de pantalla manuales ni servicios productivos reales. Un resultado histórico en docs/ui-audit no sustituye una reproducción actual.