ricardo/Alpha
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentar arquitectura de Alpha y metricas PMI

Browse Source
This commit is contained in:
Ricardo Gonzalez
2026-05-26 01:56:40 -05:00
parent a083782246
commit fbd128a19e
2 changed files with 511 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/arquitectura_alpha.md
+180
View File
@@ -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 <token>`
- **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 |
docs/metricas_pmi.md
+331
View File
@@ -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