Create README.md
This commit is contained in:
kvilches1410
@@ -0,0 +1,300 @@
|
|||||||
|
📊 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?
|
||||||
Reference in New Issue
Block a user