dashboard-infra/README.md

📊 Análisis del Dashboard JIRA - DashLabs
🏗️ Arquitectura del Proyecto
Stack Tecnológico

Frontend: HTML5 + Vanilla JavaScript + Chart.js 4.4.1
Backend: Node.js Serverless (Vercel Function)
API: JIRA REST API v3
Autenticación: Basic Auth (Email + Token JIRA)
Caching: En memoria (24hs) + CDN (Vercel)

Estructura de Archivos
dashlabs-master/
├── index.html          (25 KB - Frontend completo)
└── api/
    └── data.js         (5.5 KB - Backend serverless)

📋 Componentes Principales
Frontend (index.html)
Elementos Visuales

Header

Título y metadata del proyecto
Botón de actualización manual
Badge de timestamp y estado de caché


Sección 1: Estado Actual del Equipo

4 KPIs principales:

SP En Progreso (color azul)
SP Por Hacer (color naranja)
SP Completados Total (color verde)
Devs Activos (color púrpura)


2 Gráficos:

SP en Progreso por Desarrollador (barras)
Estado Actual por Desarrollador (barras agrupadas)


Tabla Detallada:

Muestra por cada dev: Completados, En Progreso, Por Hacer
Barra de progreso visual




Sección 2: Completados por Período

Filtro por mes (dropdown)
3 KPIs dinámicos:

SP Completados en el período
Devs que completaron
Promedio SP por dev


3 Gráficos:

Velocity por mes (barras apiladas)
Top 15 Épicas
SP Completados por Desarrollador (período filtrado)


Tabla de Historial:

SP completados con % de participación






Backend (api/data.js)
Configuración JIRA
javascriptJIRA_HOST = 'invera.atlassian.net'
JQL = 'project = LABS AND cf[10016] is not EMPTY ORDER BY updated DESC'
Campos Customizados Mapeados
CampoCodeDescripciónStory Points Estimatecustomfield_10016Story points estimadoStory Points Finalescustomfield_11019SP final (prioridad sobre estimate)Desarrollador (Multi)customfield_10622Campo multi-usuario de asignaciónParentparentÉpicaResolution DateresolutiondateFecha de completado
Flujo de Datos
1. fetchJiraIssues()
   ├── Autentica con Basic Auth (JIRA_EMAIL + JIRA_TOKEN)
   ├── Ejecuta JQL query contra JIRA API
   └── Retorna issues con campos específicos

2. processIssues()
   ├── Mapea developers (customfield_10622 → displayName)
   ├── Extrae SP (prioriza customfield_11019)
   ├── Categoriza por status (done/indeterminate/todo)
   ├── Agrupa:
   │   ├── Por desarrollador (assigneeData)
   │   ├── Por mes (monthlyDone)
   │   └── Por épica (epicData)
   └── Retorna DATA object estructurado

3. Caching
   ├── En memoria: 24 horas
   ├── CDN (Vercel): s-maxage=86400
   └── Parámetro ?refresh=1 fuerza actualización

🔑 Características Principales
✅ Fortalezas Actuales

✨ Diseño limpio - UI coherente con color scheme profesional
📊 Múltiples perspectivas - Estado actual + Histórico
🎯 Enfoque en Story Points - Métrica clara de trabajo
⚡ Rendimiento - Arquitectura serverless + caché eficiente
🔄 Auto-refresh - Actualización automática cada 24hs
📱 Responsive - Funciona en móviles (media queries)
🎨 Charts.js - Gráficos interactivos y claros

⚠️ Áreas de Mejora
1. Hardcoding de Configuración
javascript// Actualmente:
const JIRA_HOST = 'invera.atlassian.net';
const JQL = 'project = LABS AND cf[10016] is not EMPTY...';

// Debería ser:
// Variables de entorno / archivo config
2. Limitación de Resultados
javascriptconst MAX_RESULTS = 100;  // ⚠️ Solo trae primeros 100 tickets
Si LABS tiene >100 tickets, faltan datos en el dashboard.
3. Sin Control de Errores Robusto

El error banner es genérico
No hay retry automático
La caché nunca se invalida si hay error

4. Sin API REST moderna

El data.js es una Vercel Function directa
No hay validación de parámetros
Sin autenticación en el frontend

5. Estado Global con DATA
javascript// En window.DATA - manejo de estado débil
// Mejor: Usar módulo o estado centralizado

📈 Propuestas de Mejora
Fase 1: Críticas (Deberías hacer ya)

Aumentar MAX_RESULTS a 500 (o implementar paginación)

javascript   const MAX_RESULTS = 500;
   // O mejor: implementar loop hasta total

Validar tokens y secrets en variables de entorno

javascript   if (!email || !token) throw new Error('...');
   // ✅ Ya está, pero log más claro

Separar configuración de código

javascript   // config.js
   export const CONFIG = {
     jiraHost: process.env.JIRA_HOST || 'invera.atlassian.net',
     jiraProject: process.env.JIRA_PROJECT || 'LABS',
     customFields: { /* ... */ }
   };
Fase 2: Mejoras UX (Agregar valor)

Filtros interactivos en "Estado Actual"

Por desarrollador
Por status
Por épica
Por rango de SP


Tabla detallada de tickets

Mostrar tickets abiertos con links a JIRA
Filtros por dev, status, épica
Buscar por summary


Comparativas entre períodos

Velocidad mes a mes
Trending
Predictibilidad


Alertas/Warnings

Tickets en progreso > X días
SP sin asignar
Devs con carga desequilibrada



Fase 3: Arquitectura (Scaling)

API REST con autenticación

javascript   // api/issues    - GET listar con filtros
   // api/devs      - GET listar desarrolladores
   // api/epics     - GET listar épicas
   // api/stats     - POST calcular período custom

Frontend modular

Separar en componentes
State management (Zustand / Pinia)
Mejorar mantenibilidad


Database (opcional)

Guardar snapshots diarios
Querys históricas más rápidas
Trend analysis




🔧 Guía de Configuración
Variables de Entorno Requeridas (Vercel)
JIRA_EMAIL=tu-email@example.com
JIRA_TOKEN=abc123xyz...  # Generar en atlassian.net/account
Campos Customizados a Verificar
Cada Jira tiene IDs diferentes. Verificar en:

Settings → Custom fields
O ejecutar: curl -u email:token https://invera.atlassian.net/rest/api/3/fields

Para este proyecto:
cf[10016] → Story points estimate
cf[11019] → Story Points Finales
cf[10622] → Desarrollador (multi-user)
⚠️ IMPORTANTE: Estos IDs pueden cambiar entre instancias JIRA.

📊 Ejemplos de Datos Procesados
assigneeData
javascript{
  "Juan López": {
    done: 34,
    in_progress: 8,
    todo: 5
  },
  "María García": {
    done: 28,
    in_progress: 13,
    todo: 2
  }
}
monthlyDone
javascript{
  "2024-12": { "Juan López": 15, "María García": 12 },
  "2025-01": { "Juan López": 12, "María García": 18 },
  "2025-02": { "Juan López": 7, "María García": -2 }
}
epicData
javascript[
  {
    name: "Refactor Backend API",
    done: 45,
    in_progress: 21,
    todo: 8
  }
]

🚀 Próximos Pasos Recomendados

Inmediato:

Verificar campos customizados en tu instancia JIRA
Aumentar MAX_RESULTS
Revisar que caché funciona (badge de timestamp)


Corto plazo (1-2 semanas):

Agregar tabla de tickets con detalles
Implementar filtros en "Estado Actual"
Mejorar manejo de errores


Mediano plazo (1 mes):

API REST modularizada
Database para históricos
Alertas y predicciones




📝 Notas Finales
El proyecto es sólido y bien estructurado para un dashboard rápido. La arquitectura serverless de Vercel es ideal para consultas ocasionales. Si la demanda crece (100s de consultas/día) o necesitas más features, considera:

Agregar backend Node.js con Express
Database (PostgreSQL/MongoDB)
State management moderno
Testing automatizado

¿Necesitas ayuda implementando alguna de estas mejoras?