75e7b9da3d
Dashboard Features: - 8 navigation sections: Overview, Outcomes, Poor CX, FCR, Churn, Agent, Call Explorer, Export - Beyond Brand Identity styling (colors #6D84E3, Outfit font) - RCA Sankey diagram (Driver → Outcome → Churn Risk flow) - Correlation heatmaps (driver co-occurrence, driver-outcome) - Outcome Deep Dive (root causes, correlation, duration analysis) - Export functionality (Excel, HTML, JSON) Blueprint Compliance: - FCR: 4 categories (Primera Llamada/Rellamada × Sin/Con Riesgo de Fuga) - Churn: Binary view (Sin Riesgo de Fuga / En Riesgo de Fuga) - Agent: Talento Para Replicar / Oportunidades de Mejora - Fixed FCR rate calculation (only FIRST_CALL counts as success) Technical: - Streamlit + Plotly for interactive visualizations - Light theme configuration (.streamlit/config.toml) - Fixed Plotly colorbar titlefont deprecation Documentation: - Updated PROJECT_CONTEXT.md, TODO.md, CHANGELOG.md - Added 4 new technical decisions (TD-014 to TD-017) - Created TROUBLESHOOTING.md with 10 common issues Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
204 lines
3.8 KiB
Markdown
204 lines
3.8 KiB
Markdown
# TROUBLESHOOTING.md
|
|
|
|
> Guía de problemas comunes y sus soluciones
|
|
|
|
---
|
|
|
|
## Dashboard Streamlit
|
|
|
|
### TS-001: Dashboard muestra fondo negro / tema oscuro
|
|
|
|
**Síntomas:**
|
|
- Texto no visible sobre fondo negro
|
|
- Elementos UI con colores incorrectos
|
|
|
|
**Causa:**
|
|
Streamlit usa tema oscuro por defecto basado en preferencias del sistema.
|
|
|
|
**Solución:**
|
|
Crear `.streamlit/config.toml`:
|
|
```toml
|
|
[theme]
|
|
base = "light"
|
|
primaryColor = "#6D84E3"
|
|
backgroundColor = "#FFFFFF"
|
|
secondaryBackgroundColor = "#F8F8F8"
|
|
textColor = "#000000"
|
|
```
|
|
|
|
---
|
|
|
|
### TS-002: Puerto en uso al lanzar Streamlit
|
|
|
|
**Síntomas:**
|
|
```
|
|
Error: Address already in use
|
|
Port 8501 is in use by another program
|
|
```
|
|
|
|
**Causa:**
|
|
Otra instancia de Streamlit o aplicación usando el puerto.
|
|
|
|
**Solución:**
|
|
1. Usar puerto alternativo en `.streamlit/config.toml`:
|
|
```toml
|
|
[server]
|
|
port = 8510
|
|
```
|
|
|
|
2. O especificar en línea de comandos:
|
|
```bash
|
|
python -m streamlit run dashboard/app.py --server.port 8510
|
|
```
|
|
|
|
---
|
|
|
|
### TS-003: Plotly ValueError: Invalid property 'titlefont'
|
|
|
|
**Síntomas:**
|
|
```
|
|
ValueError: Invalid property specified for object of type plotly.graph_objs.heatmap.ColorBar: 'titlefont'
|
|
```
|
|
|
|
**Causa:**
|
|
Plotly deprecó `titlefont` en versiones recientes. Ahora debe usarse estructura anidada.
|
|
|
|
**Solución:**
|
|
```python
|
|
# Antes (deprecated)
|
|
colorbar=dict(
|
|
title="Label",
|
|
titlefont=dict(size=12),
|
|
)
|
|
|
|
# Ahora (correcto)
|
|
colorbar=dict(
|
|
title=dict(text="Label", font=dict(size=12)),
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### TS-004: Streamlit 'use_container_width' deprecation warning
|
|
|
|
**Síntomas:**
|
|
```
|
|
Please replace `use_container_width` with `width`.
|
|
`use_container_width` will be removed after 2025-12-31.
|
|
```
|
|
|
|
**Causa:**
|
|
Streamlit cambió la API de `st.dataframe()` y `st.plotly_chart()`.
|
|
|
|
**Solución:**
|
|
```python
|
|
# Antes
|
|
st.dataframe(df, use_container_width=True)
|
|
|
|
# Después
|
|
st.dataframe(df, width='stretch')
|
|
```
|
|
|
|
**Nota:** Este warning no rompe funcionalidad actualmente.
|
|
|
|
---
|
|
|
|
### TS-005: No batch data found
|
|
|
|
**Síntomas:**
|
|
Dashboard muestra "No batch data found" y no carga.
|
|
|
|
**Causa:**
|
|
No hay datos de análisis en `data/output/`.
|
|
|
|
**Solución:**
|
|
1. Ejecutar pipeline primero:
|
|
```bash
|
|
python cli.py run my_batch -i data/audio -o data/output
|
|
```
|
|
|
|
2. Verificar que existe `data/output/<batch_id>/summary.json`
|
|
|
|
---
|
|
|
|
## Pipeline de Análisis
|
|
|
|
### TS-006: AssemblyAI transcription falla
|
|
|
|
**Síntomas:**
|
|
```
|
|
Error: AssemblyAI API error: ...
|
|
```
|
|
|
|
**Soluciones:**
|
|
1. Verificar `ASSEMBLYAI_API_KEY` en `.env`
|
|
2. Verificar formato de audio (soporta: mp3, wav, m4a, flac)
|
|
3. Verificar conectividad a internet
|
|
|
|
---
|
|
|
|
### TS-007: OpenAI JSON parsing error
|
|
|
|
**Síntomas:**
|
|
```
|
|
Error: Failed to parse JSON response
|
|
```
|
|
|
|
**Causa:**
|
|
LLM generó JSON malformado.
|
|
|
|
**Solución:**
|
|
1. El sistema tiene auto-repair built-in
|
|
2. Si persiste, usar `--model gpt-4o` (más robusto)
|
|
3. Verificar que transcript no está vacío
|
|
|
|
---
|
|
|
|
### TS-008: Pipeline resume no funciona
|
|
|
|
**Síntomas:**
|
|
Pipeline reprocesa llamadas ya completadas.
|
|
|
|
**Causa:**
|
|
Manifest corrupto o eliminado.
|
|
|
|
**Solución:**
|
|
1. Verificar `data/output/<batch>/manifests/*.json`
|
|
2. Si corrupto, usar `--no-resume` para empezar de cero
|
|
3. No eliminar archivos de manifest manualmente
|
|
|
|
---
|
|
|
|
## Problemas de Datos
|
|
|
|
### TS-009: FCR rate muestra 0% cuando hay llamadas
|
|
|
|
**Causa:**
|
|
El campo `fcr_status` no está siendo llenado por el LLM.
|
|
|
|
**Solución:**
|
|
1. Usar `--no-compression` para dar más contexto al LLM
|
|
2. Verificar que prompt v2.0 está activo
|
|
3. Revisar que transcripts tienen suficiente información
|
|
|
|
---
|
|
|
|
### TS-010: Drivers vacíos en análisis
|
|
|
|
**Síntomas:**
|
|
`poor_cx_drivers: []` en todos los análisis.
|
|
|
|
**Causa:**
|
|
- Transcripts muy cortos
|
|
- Compresión eliminó información clave
|
|
- LLM no encontró evidencia
|
|
|
|
**Solución:**
|
|
1. Usar `--no-compression`
|
|
2. Verificar calidad de transcripts
|
|
3. Revisar logs para errores de LLM
|
|
|
|
---
|
|
|
|
**Última actualización**: 2026-01-19
|