From fbd128a19e9de20f2bb13b385d9ea66a3393552b Mon Sep 17 00:00:00 2001 From: Ricardo Gonzalez Date: Tue, 26 May 2026 01:56:40 -0500 Subject: [PATCH] documentar arquitectura de Alpha y metricas PMI --- docs/arquitectura_alpha.md | 180 ++++++++++++++++++++ docs/metricas_pmi.md | 331 +++++++++++++++++++++++++++++++++++++ 2 files changed, 511 insertions(+) create mode 100644 docs/arquitectura_alpha.md create mode 100644 docs/metricas_pmi.md diff --git a/docs/arquitectura_alpha.md b/docs/arquitectura_alpha.md new file mode 100644 index 0000000..973b207 --- /dev/null +++ b/docs/arquitectura_alpha.md @@ -0,0 +1,180 @@ +# Alpha — Documento Técnico + +> **Alpha = KAPPA Hub**. Aplicación Tauri + Vue 3 para gestión multi-proyecto. +> Semilla de RUMBO. POC en producción como herramienta de Business Analyst. + +**Versión**: 0.1.0 | **Fecha**: 2026-05-26 | **Autor**: Ricardo Gonzalez (Teloprax) + +--- + +## 1. Stack tecnológico + +| Capa | Tecnología | Versión | +|------|-----------|---------| +| Desktop shell | Tauri v2 | 2.11 | +| Frontend | Vue 3 + TypeScript + Vite | 3.4 / 5.x | +| Runtime JS | Bun | 1.3+ | +| Estado | Pinia | 2.1 | +| Base de datos local | Turso (libSQL) | Embedded | +| Cache navegador | Dexie.js (IndexedDB) | 4.0 | +| UI Components | shadcn-vue (reka-ui) | 2.7 / New York | +| Estilos | Tailwind CSS v4 | 4.3 | +| Tablas | @tanstack/vue-table → AG Grid | 8.21 / planned | +| i18n | vue-i18n | 11.4 | +| Iconos | Lucide + Tabler Icons | — | +| HTTP | fetch() nativo | — | +| Auth | Bearer token KAPPA | — | + +## 2. Arquitectura + +``` +┌──────────────────────────────────────────────┐ +│ Alpha (Tauri) │ +│ │ +│ ┌──────────┐ ┌───────────┐ ┌───────────┐ │ +│ │ Vue 3 FE │ │ Pinia │ │ Dexie.js │ │ +│ │ (Vite) │ │ Stores │ │ (offline) │ │ +│ └────┬─────┘ └───────────┘ └───────────┘ │ +│ │ │ +│ ┌────┴──────────────────────────────────┐ │ +│ │ Rust Backend (Tauri) │ │ +│ │ ┌─────────┐ ┌────────────────────┐ │ │ +│ │ │ Commands│ │ Turso/libSQL DB │ │ │ +│ │ │ (invoke)│ │ ~/Library/... │ │ │ +│ │ └─────────┘ │ alpha.db │ │ │ +│ │ └────────────────────┘ │ │ +│ └───────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────┐ │ +│ │ Vite Dev Proxy │ │ +│ │ /api → kappa.lambdaanalytics.co │ │ +│ └───────────────────────────────────────┘ │ +└──────────────────────────────────────────────┘ +``` + +### 2.1 Flujo de datos + +1. **Auth**: Login → Bearer token → localStorage → Pinia store +2. **KAPPA sync**: fetch() vía proxy Vite → store Pinia → opcional cache Dexie +3. **Datos locales**: Tauri invoke → Rust commands → Turso/libSQL → retorna JSON al frontend +4. **Offline**: Dexie.js guarda cache del scheduler y datos de sesión + +### 2.2 Base de datos local (Turso) + +Archivo: `~/Library/Application Support/com.teloprax.alpha/alpha.db` + +Tablas actuales: +- `projects` — caché de iniciativas KAPPA +- `work_items` — caché de historias de usuario y tareas + +Tablas planeadas (módulo usuarios): +- `users` — cache KAPPA + campos locales (rol, seniority, célula) +- `cells` — células/equipos +- `cell_members` — relación usuario ↔ célula +- `project_members` — relación usuario ↔ proyecto +- `absences` — ausencias (vacaciones, permisos) +- `daily_logs` — registro diario por usuario +- `performance_snapshots` — métricas calculadas + +## 3. Estructura del proyecto + +``` +kappa-hub/ +├── src/ # Frontend Vue 3 +│ ├── components/ +│ │ ├── ui/ # shadcn-vue (30+ componentes) +│ │ ├── dashboard/ # Cards, tabla, sidebar, charts +│ │ ├── AppSidebar.vue # Navegación principal +│ │ ├── NavProjects.vue # Selector de proyectos +│ │ └── NavUser.vue # Perfil de usuario +│ ├── views/ +│ │ ├── LoginView.vue # Auth +│ │ ├── NewDashboardView.vue # Dashboard multi-sección +│ │ ├── ProjectListView.vue # Lista de proyectos +│ │ ├── CalendarView.vue # Calendario colombiano +│ │ └── SchedulerView.vue # Recetas automáticas +│ ├── stores/ # Pinia +│ │ ├── auth.ts # Autenticación +│ │ ├── projects.ts # Proyectos KAPPA +│ │ ├── workitems.ts # Work items +│ │ └── scheduler.ts # Reglas + logs +│ ├── services/ +│ │ ├── kappa-api.ts # Cliente HTTP KAPPA +│ │ ├── calendar.ts # Feriados Colombia + días hábiles +│ │ └── scheduler.ts # Motor de recetas +│ ├── types/kappa.ts # Tipos TypeScript KAPPA +│ ├── i18n/ # es.json, en.json +│ └── composables/ # useSearch, useTheme +├── src-tauri/ # Backend Rust +│ ├── src/ +│ │ ├── main.rs # Entry point, comandos Tauri +│ │ └── db.rs # Operaciones Turso/libSQL +│ ├── tauri.conf.json # Config Tauri +│ └── icons/ # Iconos app (macOS, Windows, iOS, Android) +└── public/ # Assets estáticos + └── Alpha.svg # Logo vectorial +``` + +## 4. APIs KAPPA integradas + +| Endpoint | Método | Uso | +|----------|--------|-----| +| `/users/login/` | POST | Auth | +| `/users/all/` | GET | Listar usuarios | +| `/initiatives-all/` | GET | Listar proyectos | +| `/userstorys/` | GET | HUs por proyecto | +| `/userstorys/create/` | POST | Crear HU | +| `/logbooks/` | GET | Bitácoras | +| `/logbooks_master/create/` | POST | Crear bitácora | +| `/logbooks/create/` | POST | Entrada bitácora | +| `/plannings/` | GET | Planeaciones | +| `/plannings_master/create/` | POST | Crear planeación | +| `/plannings/create/` | POST | Entrada planeación | +| `/business-rules/` | GET | Reglas de negocio | +| `/business-rules/create/` | POST | Crear regla | +| `/functionalrequirements/` | GET | Requisitos | +| `/functionalrequirements/create/` | POST | Crear requisito | +| `/employees/` | GET (paginado) | Usuarios ↔ proyectos | + +## 5. Autenticación + +- **Método**: Bearer token (JWT de Django REST) +- **Almacenamiento**: localStorage (`kappa_token`) +- **Flujo**: Login → POST `/users/login/` → token → header `Authorization: Bearer ` +- **Persistencia**: Recordar email en `alpha_remember_email` +- **Proxy dev**: Vite redirige `/api/*` → `https://kappa.lambdaanalytics.co` + +## 6. Sincronización entre máquinas + +- **Código**: iCloud Drive (`com~apple~CloudDocs/AI/Teloprax/`) +- **Datos KAPPA**: Servidor remoto (el Hub es solo cliente) +- **Token**: localStorage del navegador (logueo por máquina) +- **Turso DB**: Local por máquina (`~/Library/Application Support/`) + +## 7. Decisiones técnicas + +| Decisión | Razón | +|----------|-------| +| Tauri v2 en vez de Electron | Binario <10MB, RAM <50MB, Rust nativo | +| Turso/libSQL en vez de SQLite puro | Compatible SQLite, embedded, MCP server built-in | +| Dexie.js para offline | IndexedDB wrapper, API simple, ya integrado | +| shadcn-vue New York | Estilo moderno, copiable, Tailwind v4 nativo | +| Bun runtime | Más rápido que npm/yarn, compatible con Node | +| fetch() nativo | Sin dependencia axios, suficiente para REST | +| AG Grid (planeado) | Reemplaza @tanstack/vue-table para tablas complejas | + +## 8. Roadmap técnico + +| Fase | Alcance | Estado | +|------|---------|--------| +| Auth + Proyectos | Login, listado, dashboard individual | ✅ | +| Layout + Navegación | Sidebar, tabs, shadcn-vue | ✅ | +| Calendario | Feriados Colombia, Ley Emiliani | ✅ | +| Scheduler | Recetas automáticas, Dexie, notificaciones | ✅ | +| i18n | Español/Inglés | ✅ | +| Tauri | Migración web → desktop app | ✅ | +| Módulo Usuarios | AG Grid, Turso, roles, células | 🔜 F1 | +| Métricas PMI | SPI, CPI, Velocity, Burndown | 🔜 F4 | +| Daily | Registro diario + recálculo | 🔜 F5 | +| Calendarios externos | Google/Outlook OAuth2 | ⬜ K-21 | +| Alertas post-reunión | Detección fin reunión → captura | ⬜ K-22 | diff --git a/docs/metricas_pmi.md b/docs/metricas_pmi.md new file mode 100644 index 0000000..304aef4 --- /dev/null +++ b/docs/metricas_pmi.md @@ -0,0 +1,331 @@ +# Alpha — Métricas de Desempeño en Proyectos + +> **Qué mido, cómo lo mido y por qué**. Justificación para reportes de avance a stakeholders. + +**Versión**: 1.0 | **Fecha**: 2026-05-26 | **Autor**: Ricardo Gonzalez (Teloprax) + +--- + +## 1. Fundamentos + +Alpha mide el desempeño de proyectos y desarrolladores usando el marco **Earned Value Management (EVM)** del PMI, complementado con métricas ágiles (Scrum/Kanban). Toda unidad de trabajo se expresa en **Story Points (SP)**, donde **1 SP = 1 hora de trabajo efectivo**. + +### Fuentes de datos + +| Fuente | Dato | Frecuencia | +|--------|------|------------| +| KAPPA `/userstorys/` | HUs asignadas, estado, prioridad | On-demand | +| KAPPA `/plannings/` | Fechas planeadas (inicio/fin) | On-demand | +| KAPPA `/employees/` | Asignación usuario ↔ proyecto | On-demand | +| Alpha Daily Log | Avance diario, horas, impedimentos | Diario | +| Alpha Absences | Vacaciones, permisos, enfermedad | Eventual | +| `calendar.ts` | Feriados Colombia (Ley Emiliani) | Automático | + +--- + +## 2. Métricas de Proyecto (PMI-EVM) + +### 2.1 SPI — Schedule Performance Index + +> ¿Vamos al ritmo planeado? + +``` +SPI = EV / PV +``` + +| Variable | Definición | Cálculo | +|----------|-----------|---------| +| **EV** (Earned Value) | Valor del trabajo completado | SP completados × costo/hora | +| **PV** (Planned Value) | Valor del trabajo planeado | SP planeados en el período × costo/hora | + +| SPI | Interpretación | +|-----|---------------| +| > 1.0 | Adelantado respecto al plan | +| = 1.0 | Exactamente en plan | +| < 1.0 | Atrasado respecto al plan | + +**Ejemplo**: Plan 40 SP en 2 semanas. Se completaron 32 SP. +- PV = 40, EV = 32 +- SPI = 32/40 = **0.80** → 20% de atraso + +--- + +### 2.2 CPI — Cost Performance Index + +> ¿Somos eficientes con las horas? + +``` +CPI = EV / AC +``` + +| Variable | Definición | Cálculo | +|----------|-----------|---------| +| **EV** (Earned Value) | Valor del trabajo completado | SP completados × costo/hora | +| **AC** (Actual Cost) | Costo real incurrido | Horas reales registradas × costo/hora | + +| CPI | Interpretación | +|-----|---------------| +| > 1.0 | Por debajo del presupuesto (eficiente) | +| = 1.0 | Exactamente en presupuesto | +| < 1.0 | Por encima del presupuesto (ineficiente) | + +**Ejemplo**: 32 SP completados, pero se gastaron 38 horas reales. +- EV = 32, AC = 38 +- CPI = 32/38 = **0.84** → 16% de sobrecosto en horas + +--- + +### 2.3 SV — Schedule Variance + +``` +SV = EV - PV +``` + +Desviación en horas/dinero. **Positivo** = adelantado, **Negativo** = atrasado. + +--- + +### 2.4 CV — Cost Variance + +``` +CV = EV - AC +``` + +Desviación en costo. **Positivo** = ahorro, **Negativo** = sobrecosto. + +--- + +### 2.5 EAC — Estimate at Completion + +``` +EAC = BAC / CPI +``` + +| BAC | Budget at Completion | SP totales del proyecto | + +Proyección del costo total al final del proyecto basado en el CPI actual. + +--- + +### 2.6 Días hábiles reales + +``` +días_hábiles = días_calendario_período + - fines_de_semana (sábado + domingo) + - feriados Colombia (Ley Emiliani, ver calendar.ts) + - ausencias del equipo (vacaciones, permisos, enfermedad) +``` + +Esto garantiza que las proyecciones de SPI y fechas de entrega sean realistas para el contexto colombiano. + +--- + +## 3. Métricas Ágiles (por desarrollador) + +### 3.1 Velocity + +``` +velocity = Σ(SP completados) / período +``` + +| Período | Uso | +|---------|-----| +| Sprint (2 semanas) | Planificación de capacidad | +| Semanal | Seguimiento táctico | +| Diario | Micro-ajustes | + +**Interpretación**: Si un dev completa en promedio 16 SP/sprint, no se le deben asignar más de 16 SP en el siguiente sprint. + +--- + +### 3.2 Burndown Chart + +``` +SP_restantes(día) = SP_totales - SP_completados(día) +``` + +Gráfico de SP restantes vs días hábiles. La línea ideal va del total a cero en la fecha de entrega. La línea real muestra si hay desviación. + +--- + +### 3.3 Compliance (Cumplimiento) + +``` +compliance = HUs_completadas / HUs_asignadas +``` + +Porcentaje de historias de usuario entregadas vs comprometidas en el período. + +| Compliance | Calificación | +|-----------|-------------| +| ≥ 95% | Excelente | +| 85-94% | Bueno | +| 70-84% | Regular | +| < 70% | Crítico | + +--- + +### 3.4 Throughput + +``` +throughput = Work_Items_completados / período +``` + +Cantidad de ítems de trabajo terminados por unidad de tiempo. Útil para predecir capacidad futura (método Monte Carlo o percentiles). + +--- + +### 3.5 Lead Time + +``` +lead_time = fecha_completada - fecha_asignada +``` + +Tiempo total desde que se asigna un HU hasta que se entrega. Incluye tiempo de espera + tiempo activo. + +--- + +### 3.6 Cycle Time + +``` +cycle_time = fecha_completada - fecha_inicio_trabajo +``` + +Tiempo activo de trabajo (sin esperas). Idealmente < 3 días por HU. + +--- + +## 4. Indicador Compuesto de Desempeño (CPI) + +``` +CPI_dev = (SPI × 0.25) + (CPI × 0.25) + (Compliance × 0.25) + (Velocity × 0.15) + (1 - Impedimentos/máx × 0.10) +``` + +| CPI_dev | Nivel | +|---------|-------| +| ≥ 0.90 | Alto desempeño | +| 0.75 - 0.89 | Desempeño esperado | +| 0.60 - 0.74 | Necesita atención | +| < 0.60 | Crítico — intervención requerida | + +--- + +## 5. Factores que afectan las métricas + +### 5.1 Feriados y días no laborables + +La función `isWorkingDay()` en `calendar.ts` excluye automáticamente: +- Sábados y domingos +- 18 feriados colombianos (incluyendo Ley Emiliani) + +### 5.2 Ausencias del equipo + +Las ausencias registradas (vacaciones, enfermedad, permisos) descuentan días hábiles del cálculo de capacidad, ajustando el PV (Planned Value) esperado. + +``` +PV_ajustado = PV × (días_hábiles_disponibles / días_hábiles_totales) +``` + +### 5.3 Impedimentos + +Cada impedimento registrado en el Daily Log afecta el indicador compuesto. Más de 3 impedimentos activos en una semana dispara una alerta. + +--- + +## 6. Cálculo por proyecto + +### Paso a paso + +1. **Obtener línea base**: Fechas de inicio/fin del proyecto (de KAPPA plannings) +2. **Calcular SP totales**: Sumar SP de todas las HUs del proyecto +3. **Calcular días hábiles**: `workingDays(inicio, fin) - ausencias` +4. **SP/día planeado**: `SP_totales / días_hábiles` +5. **PV acumulado(día)**: `SP/día_planeado × día_del_proyecto` +6. **EV acumulado(día)**: `Σ(SP de HUs completadas hasta el día)` +7. **AC acumulado(día)**: `Σ(horas reales registradas)` +8. **Calcular SPI, CPI, SV, CV** con las fórmulas anteriores + +### Ejemplo numérico + +| Dato | Valor | +|------|-------| +| Proyecto | 10 días hábiles (2 semanas) | +| SP totales | 40 SP | +| SP/día planeado | 4 SP/día | +| Día 5 | PV = 20, EV = 16, AC = 18 horas | +| SPI | 16/20 = 0.80 | +| CPI | 16/18 = 0.89 | +| EAC | 40/0.89 = 45 horas (5 horas extra proyectadas) | + +--- + +## 7. Cálculo por desarrollador + +Mismas fórmulas, pero filtradas por `assigned_to = user_id`: + +``` +SPI_dev = EV_dev / PV_dev +CPI_dev = EV_dev / AC_dev +``` + +Donde: +- `EV_dev` = SP completados por el dev en el período +- `PV_dev` = SP planeados para el dev (proporcional a su asignación) +- `AC_dev` = Horas reales registradas por el dev + +--- + +## 8. Visualización de reportes + +### Dashboard de proyecto + +| Widget | Métrica | Visualización | +|--------|---------|--------------| +| Semaforo SPI | SPI actual | 🟢 >1.0 🟡 0.8-1.0 🔴 <0.8 | +| Semaforo CPI | CPI actual | 🟢 >1.0 🟡 0.8-1.0 🔴 <0.8 | +| Burndown | SP restantes vs días | Gráfico de línea | +| Velocity trend | Últimos 4 sprints | Gráfico de barras | +| Top impediments | Impedimentos activos | Lista ordenada | + +### Dashboard de desarrollador + +| Widget | Métrica | +|--------|---------| +| CPI compuesto | Indicador numérico + semáforo | +| HUs asignadas vs completadas | Barra de progreso | +| Velocity semanal | Sparkline | +| Lead time promedio | Número (días) | +| Impedimentos activos | Contador | + +--- + +## 9. Períodos de cálculo + +| Período | Actualización | Propósito | +|---------|--------------|-----------| +| Diario | Cada daily log guardado | Micro-seguimiento | +| Semanal | Lunes 8:00 AM | Reporte de avance | +| Sprint (2 sem) | Fin de sprint | Replanificación | +| Proyecto | Bajo demanda | Reporte ejecutivo | + +--- + +## 10. Referencias + +- **PMI PMBOK 7th Edition** — Earned Value Management (EVM) +- **Scrum Guide 2020** — Velocity, Sprint Burndown +- **Kanban Method** — Lead Time, Cycle Time, Throughput +- **Ley Emiliani (Colombia)** — Traslado de feriados al lunes +- **Algoritmo de Butcher** — Cálculo de Pascua (base para feriados variables) + +--- + +## 11. Notas para stakeholders + +> Este documento respalda la metodología de medición usada en Alpha. Cualquier reporte generado por la herramienta se basa en estas fórmulas, alineadas con estándares internacionales de gestión de proyectos (PMI) y metodologías ágiles (Scrum/Kanban). + +**Alpha no reemplaza a un PM**. Es una herramienta de apoyo que: +1. Centraliza datos de múltiples fuentes (KAPPA, daily logs, calendario) +2. Calcula métricas objetivas automáticamente +3. Genera reportes justificables con trazabilidad a los datos fuente +4. Permite al BA/PM tomar decisiones informadas basadas en evidencia