nuevo dash

2026-03-31 16:57:26 -03:00
parent b4a0dfae24
commit 5467427a08
9 changed files with 820 additions and 732 deletions
@@ -1,300 +1,121 @@
-📊 Análisis del Dashboard JIRA - DashLabs
-🏗️ Arquitectura del Proyecto
-Stack Tecnológico
+# 📊 Dashboard LABS — JIRA Story Points

-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)
+Un dashboard en tiempo real para visualizar métricas, progreso de Story Points (SP), y la velocidad del equipo utilizando datos extraídos directamente de la API de Jira.

-Estructura de Archivos
-dashlabs-master/
-├── index.html          (25 KB - Frontend completo)
+Este proyecto está diseñado con un frontend ligero sin frameworks pesados y un backend *Serverless* preparado para ser desplegado en plataformas como Vercel o funcionar de manera local.
+
+---
+
+## 🏗️ Stack Tecnológico
+
+- **Frontend:** HTML5 + Vanilla TypeScript/JavaScript + [Chart.js (v4.4.1)](https://www.chartjs.org/)
+- **Backend:** Node.js Serverless Function 
+- **API:** Integración directa con Jira REST API v3
+- **Autenticación:** Basic Auth mediante Email y API Token de Jira
+- **Caching:** Caché en memoria (24hs) + CDN-level Cache con "stale-while-revalidate"
+
+## ✨ Características Principales
+
+1. **Estado Actual del Equipo:**
+   - Visualización de KPIS clave: SP en Progreso, SP por Hacer, SP Completados y Desarrolladores Activos.
+   - Gráficos detallados del progreso por desarrollador.
+   - Tabla que resume el porcentaje de carga de trabajo de cada uno.
+
+2. **Histórico por Período:**
+   - Resumen mensual de los Story Points completados.
+   - Velocidad histórica del equipo a lo largo del tiempo.
+   - Gráfico de top Épicas y distribución de SP.
+
+3. **Performance Optimizado:**
+   - Consulta eficiente con parámetros JQL directos.
+   - Sistema de caché dual (Node memory + Vercel Edge) para evitar excesos de *Rate Limiting* en Jira y cargar instantáneamente.
+
+---
+
+## 🚀 Instalación y Configuración Local
+
+### 1. Clonar el repositorio
+Cloná este repositorio y accedé a la carpeta del proyecto:
+```bash
+git clone https://github.com/kvilches1410/dashlabs.git
+cd dashlabs
+```
+
+### 2. Instalar el CLI de Vercel
+Para correr las funciones *serverless* del backend (`api/data.js` de Vercel) localmente, necesitas instalar Vercel CLI de forma global:
+```bash
+npm install -g vercel
+```
+
+### 3. Configurar Variables de Entorno
+Copiá el archivo de entorno de ejemplo como `.env` en la raíz del proyecto.
+```bash
+cp ex.env .env
+```
+Luego, editá el `.env` e ingresá tus credenciales de Jira:
+```env
+# Ejemplo de .env
+JIRA_EMAIL=tu-email@tudominio.com
+JIRA_TOKEN=tu-jira-api-token
+```
+> **Nota:** Podés generar un API Token de Jira en tu la configuración de seguridad de tu cuenta de Atlassian.
+
+### 4. Entorno de Desarrollo
+Para levantar el proyecto y la API simulando el entorno de Vercel, ejecutá:
+```bash
+vercel dev
+```
+Luego, abrí `http://localhost:3000` en tu navegador. 
+
+---
+
+## 🔧 Configuración del Modelo de Datos de JIRA
+
+Los campos personalizados (Custom Fields) varían según cada entorno de Jira. Actualmente, el mapeo de campos está de la siguiente manera:
+
+| Campo / Tipo | Código (Custom Field) | Descripción |
+| :--- | :--- | :--- |
+| **Story Points Estimate** | `customfield_10016` | La estimación de SP original del ticket |
+| **Story Points Finales** | `customfield_11217` | SP finales acordados (Suele tener prioridad) |
+| **Desarrollador** | `customfield_10628` | Campo Multi-usuario para asignación de tareas |
+
+> ⚠️ **Importante**: Verificá en tu instancia de Jira (`https://<tu-instancia>.atlassian.net/rest/api/3/fields`) que los IDs de estos campos correspondan a los utilizados en la API del dashboard. Si implementaste la nueva arquitectura, vas a pordelo modificar directamente en `api/config.js`.
+
+---
+
+## 📁 Estructura del Proyecto
+
+```text
+dashlabs/
+├── index.html        # Frontend central. Contiene todo el layout, CSS y JS con Chart.js
+├── package.json      # Dependencias y scripts
+├── vercel.json       # Configuración para despliegue en Vercel
+├── .gitignore        
+├── ex.env            # Variables de entorno de ejemplo (TEMPLATE)
 └── api/
-    └── data.js         (5.5 KB - Backend serverless)
+    ├── config.js     # [Opcional] Configuración modular para el Request de JIRA
+    └── data.js       # Vercel Serverless Function: Maneja el fetch, transformación de datos y caché
+```

-📋 Componentes Principales
-Frontend (index.html)
-Elementos Visuales
+---

-Header
+## 🌐 Despliegue en Producción (Vercel)

-Título y metadata del proyecto
-Botón de actualización manual
-Badge de timestamp y estado de caché
+El proyecto está diseñado para funcionar nativamente dentro de [Vercel](https://vercel.com/). 

+1. Conectá el repositorio en el panel de Vercel.
+2. Agregá en Vercel **Environment Variables**:
+   - `JIRA_EMAIL`
+   - `JIRA_TOKEN`
+3. Dale a **Deploy**.

-Sección 1: Estado Actual del Equipo
+La carpeta `/api` será parseada de manera automática y transformada en endpoints `/api/data` para que el `index.html` los consuma.

-4 KPIs principales:
+---

-SP En Progreso (color azul)
-SP Por Hacer (color naranja)
-SP Completados Total (color verde)
-Devs Activos (color púrpura)
+## 🤝 Contribuciones y Futuras Mejoras

-
-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?
+Algunos puntos clave (propuestos) a iterar en las siguientes versiones:
+- Paginación o control de loop dinámico para extraer más allá de `MAX_RESULTS` sin quemar límites.
+- Implementar Zustand o algún state-manager si el frontend de "Vanilla JS" crece en complejidad.
+- Posibilidad de tener filtros aplicados mediante *Query Params* o selectores en la UI antes de ejecutar cálculos.