Actualizar README para proyecto Infra (Python/Flask)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
juan.beldomenico
@@ -1,112 +1,83 @@
|
|||||||
# 📊 Dashboard LABS — JIRA Story Points
|
# 📊 Dashboard Infra — Tickets
|
||||||
|
|
||||||
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.
|
Dashboard en tiempo real para visualizar la carga de trabajo y métricas del equipo de Infraestructura, usando datos extraídos directamente de la API de Jira.
|
||||||
|
|
||||||
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
|
## 🏗️ Stack Tecnológico
|
||||||
|
|
||||||
- **Frontend:** HTML5 + Vanilla TypeScript/JavaScript + [Chart.js (v4.4.1)](https://www.chartjs.org/)
|
- **Frontend:** HTML5 + Vanilla JavaScript + [Chart.js (v4.4.1)](https://www.chartjs.org/)
|
||||||
- **Backend:** Node.js Serverless Function
|
- **Backend:** Python + Flask
|
||||||
- **API:** Integración directa con Jira REST API v3
|
- **API:** Integración directa con Jira REST API v3
|
||||||
- **Autenticación:** Basic Auth mediante Email y API Token de Jira
|
- **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
|
## 🚀 Instalación y Configuración Local
|
||||||
|
|
||||||
### 1. Clonar el repositorio
|
### 1. Clonar el repositorio
|
||||||
Cloná este repositorio y accedé a la carpeta del proyecto:
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/kvilches1410/dashlabs.git
|
git clone https://git.beldo.duckdns.org/jpbeldomenico/dashboard-infra.git
|
||||||
cd dashlabs
|
cd dashboard-infra
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Instalar el CLI de Vercel
|
### 2. Instalar dependencias Python
|
||||||
Para correr las funciones *serverless* del backend (`api/data.js` de Vercel) localmente, necesitas instalar Vercel CLI de forma global:
|
|
||||||
```bash
|
```bash
|
||||||
npm install -g vercel
|
pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Configurar Variables de Entorno
|
### 3. Configurar Variables de Entorno
|
||||||
Copiá el archivo de entorno de ejemplo como `.env` en la raíz del proyecto.
|
|
||||||
|
Copiá el archivo de ejemplo y completá con tus credenciales:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cp ex.env .env
|
cp ex.env .env
|
||||||
```
|
```
|
||||||
Luego, editá el `.env` e ingresá tus credenciales de Jira:
|
|
||||||
|
Editá el `.env`:
|
||||||
|
|
||||||
```env
|
```env
|
||||||
# Ejemplo de .env
|
JIRA_HOST=invera.atlassian.net
|
||||||
JIRA_EMAIL=tu-email@tudominio.com
|
JIRA_EMAIL=tu-email@dominio.com
|
||||||
JIRA_TOKEN=tu-jira-api-token
|
JIRA_TOKEN=tu-jira-api-token
|
||||||
|
JIRA_PROJECT=IO
|
||||||
|
USE_TICKET_COUNT=true
|
||||||
```
|
```
|
||||||
> **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
|
> Podés generar un API Token en: https://id.atlassian.com/manage-profile/security/api-tokens
|
||||||
Para levantar el proyecto y la API simulando el entorno de Vercel, ejecutá:
|
|
||||||
|
### 4. Levantar el servidor
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
vercel dev
|
python server.py
|
||||||
```
|
```
|
||||||
Luego, abrí `http://localhost:3000` en tu navegador.
|
|
||||||
|
|
||||||
---
|
Abrí el navegador en: `http://localhost:8888`
|
||||||
|
|
||||||
## 🔧 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 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📁 Estructura del Proyecto
|
## 📁 Estructura del Proyecto
|
||||||
|
|
||||||
```text
|
```text
|
||||||
dashlabs/
|
dashboard-infra/
|
||||||
├── index.html # Frontend central. Contiene todo el layout, CSS y JS con Chart.js
|
├── index.html # Frontend: layout y gráficos
|
||||||
├── package.json # Dependencias y scripts
|
├── js/
|
||||||
├── vercel.json # Configuración para despliegue en Vercel
|
│ └── app.js # Lógica del dashboard (Chart.js, KPIs, filtros)
|
||||||
├── .gitignore
|
├── css/
|
||||||
├── ex.env # Variables de entorno de ejemplo (TEMPLATE)
|
│ └── styles.css # Estilos
|
||||||
└── api/
|
├── server.py # Backend Flask: fetch de Jira y endpoint /api/data
|
||||||
├── config.js # [Opcional] Configuración modular para el Request de JIRA
|
├── requirements.txt # Dependencias Python
|
||||||
└── data.js # Vercel Serverless Function: Maneja el fetch, transformación de datos y caché
|
├── ex.env # Ejemplo de variables de entorno
|
||||||
|
└── .gitignore
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🌐 Despliegue en Producción (Vercel)
|
## 📊 Métricas disponibles
|
||||||
|
|
||||||
El proyecto está diseñado para funcionar nativamente dentro de [Vercel](https://vercel.com/).
|
- **Carga de trabajo actual:** tickets En Progreso y Por Hacer por desarrollador
|
||||||
|
- **Alertas de salud:** tickets estancados, vencidos, sin asignar
|
||||||
1. Conectá el repositorio en el panel de Vercel.
|
- **Resultados del período:** tickets completados, promedio semanal, solicitudes por semana
|
||||||
2. Agregá en Vercel **Environment Variables**:
|
- Filtro por desarrollador y por rango de tiempo (hoy, 7d, 30d, 90d, 1 año, histórico)
|
||||||
- `JIRA_EMAIL`
|
|
||||||
- `JIRA_TOKEN`
|
|
||||||
3. Dale a **Deploy**.
|
|
||||||
|
|
||||||
La carpeta `/api` será parseada de manera automática y transformada en endpoints `/api/data` para que el `index.html` los consuma.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|||||||
Reference in New Issue
Block a user