Sprint 2 Etapas 1-2: modelo recursos utilizationMinutes+units, Dexie v3, ActivityPanel wow

sprints/sprint-2/BRIEF.md

@@ -0,0 +1,311 @@
+# Sprint 2 — Brief
+
+> **Propósito:** completar y elevar el modelo de recursos con costo por hora (ya parcialmente implementado), con foco en la experiencia "wow" en el workspace y en la visibilidad de recursos en el reporte y el PDF. Complementado con mejoras de UX para uso en talleres y pre-venta.
+>
+> **Usuario objetivo:** equipo de InQuality. Uso interno en talleres de análisis de procesos y pre-venta de automatización. Ocasionalmente presentado a clientes directamente.
+>
+> **Sprint anterior:** Sprint 1.5 — identidad visual completa, PDFs de clase profesional, badge ⚡ en canvas, ROI con 5 KPIs. Ver cierre en `methodology/CASE_STUDIES/`.
+
+---
+
+## 0. Reglas no negociables (heredadas)
+
+- **Marca:** "InQ" siempre I-n-Q. "InQ ROI" nombre del producto.
+- **Paleta:** naranja `#F59845`, gradiente `#F59845 → #ED3E8F`. No usar morado CONCILIA.
+- **Logo:** usar PNGs de `assets/` en lugar de texto "InQ" / "InQuality" donde corresponda. Logo principal: `MARCA FINAL 2023 AREA DE SEGURIDAD 1 COLOR.png`.
+- **Footer PDFs:** "Powered by InQuality" — obligatorio en los tres PDFs.
+- **Identidad visual:** estable hasta Sprint 4+. No reabrir paleta, tipografía ni sistema de componentes.
+- **Validación visual:** tests verdes ≠ aprobación final. Todo artefacto visual requiere OK del director antes de cerrar etapa.
+- **Iniciativa agéntica:** clasificar cambios por nivel (1/2/3). Ver `methodology/PATTERNS.md` C.6.
+
+Para referencia completa del manual de marca, tokens CSS y logo, ver `assets/InQ manual de marca- 3.0.pdf` y `sprints/sprint-1-5/BRIEF.md` sección 1.
+
+---
+
+## 1. Contexto estratégico
+
+### 1.1 Rebalanceo web/PDF
+
+| Componente | Inversión esperada |
+|---|---|
+| Web app (workspace + reporte + features) | 60–70 % |
+| PDF (refinamientos, nuevas secciones) | 15–25 % |
+| Infraestructura / deuda técnica | 10–15 % |
+| Documentación / metodología | 5–10 % |
+
+### 1.2 Criterio de wow (obligatorio)
+
+Cada etapa con feature nueva incluye:
+- **Versión mínima:** cumple la funcionalidad.
+- **Versión con wow:** mismo objetivo + 1-2 detalles de experiencia que generan impacto positivo.
+
+Por defecto: versión con wow si el costo extra < 40% del tiempo de la mínima.
+
+---
+
+## 2. Estado real del modelo de recursos (pre-Sprint 2)
+
+**El modelo de recursos existe parcialmente desde el MVP.** Sprint 2 no construye desde cero.
+
+### Lo que ya existe en el código
+
+| Componente | Estado |
+|---|---|
+| `Resource` en `types.ts` | ✅ `{ id, processId, name, type, costPerHour }` |
+| `ActivityResourceAssignment` en `Activity` | ✅ `{ resourceId, utilizationPercent: number (0–1) }` |
+| Tabla `resources` en Dexie | ✅ Existe desde v1 |
+| `ResourcesPanel.tsx` | ✅ CRUD completo de recursos por proceso |
+| `ActivityPanel.tsx` asignación | ✅ Slider de % de utilización |
+| Motor de simulación | ✅ Calcula `cost = costPerHour × (execTimeMin/60) × utilizationPercent` |
+| `CostByResourceChart.tsx` en reporte | ✅ Muestra totales por recurso (o "Sin recursos") |
+| Desglose por actividad en reporte | ❌ No existe |
+| PDF con recursos | ❌ No existe |
+
+### Problema del modelo actual
+
+El modelo `utilizationPercent` no es intuitivo para consultores: "¿qué % de la actividad ocupa este recurso?" es menos claro que "¿cuántos minutos dedica este recurso a cada ejecución?". En un taller con cliente, la pregunta inevitable es "¿cómo llegaste a ese costo?" — la respuesta con minutos es verificable, con porcentajes no.
+
+---
+
+## 3. Decisiones arquitectónicas del sprint (validadas por el director)
+
+| Decisión | Resolución |
+|---|---|
+| Scope de recursos | Por proceso. Catálogo global en Sprint 3 con feedback real. |
+| Costo fijo convive con recursos | Sí. `costoTotal = directCostFixed + costoRecursos` |
+| Recursos en escenario automatizado | Solo AS-IS en Sprint 2. TO-BE sigue con `automatedCostFixed`. |
+| Modelo de utilización | Migrar `utilizationPercent` → `utilizationMinutes + units` |
+| Versión Dexie | Incrementar a v3. Migración preserva datos existentes. |
+
+### 3.1 Modelo migrado — `ActivityResourceAssignment`
+
+```typescript
+// Antes (v2)
+interface ActivityResourceAssignment {
+  resourceId: UUID
+  utilizationPercent: number  // 0–1, fracción del tiempo de la actividad
+}
+
+// Después (v3) — Sprint 2
+interface ActivityResourceAssignment {
+  resourceId: UUID
+  utilizationMinutes: number  // minutos del recurso por ejecución (independiente del tiempo de la actividad)
+  units: number               // cantidad de unidades del recurso (default 1)
+}
+```
+
+### 3.2 Fórmula de costo actualizada
+
+```
+costoRecurso = resource.costPerHour × assignment.utilizationMinutes / 60 × assignment.units
+costoTotalActividad = directCostFixed + SUM(costoRecurso por cada assignment)
+```
+
+### 3.3 Migración v2 → v3
+
+La migración convierte datos existentes con la heurística:
+```
+utilizationMinutes = Math.round(activity.executionTimeMinutes × assignment.utilizationPercent)
+units = 1
+```
+Para asignaciones sin ejecutionTimeMinutes disponible, `utilizationMinutes = 0` (conservador, evita sobrestimación).
+
+### 3.4 Lo que NO cambia en Sprint 2
+
+- `Resource` type (solo `utilizationMinutes` cambia en `ActivityResourceAssignment`, no en `Resource`)
+- Motor de simulación: recibe costo ya calculado o adapta la fórmula localmente
+- Escenario automatizado: sin cambios
+- ROI: opera sobre resultado de simulación, sin cambio
+
+---
+
+## 4. Features del sprint
+
+### Feature A — Migración del modelo de recursos (Etapa 1)
+
+**Peso estimado:** 15% del sprint.
+
+- Actualizar `ActivityResourceAssignment` en `types.ts` y `schemas.ts`
+- Actualizar fórmula en `simulation.ts`
+- Dexie v3 con función de upgrade que migra `utilizationPercent → utilizationMinutes + units`
+- Test de migración: procesos con asignaciones previas se convierten correctamente
+- Tests unitarios de dominio: edge cases del nuevo modelo
+
+**Criterio de aceptación:**
+- [ ] Proceso sin recursos: comportamiento idéntico al actual
+- [ ] Proceso con recursos: costo calculado correctamente con nueva fórmula
+- [ ] Migración v2→v3: datos preservados, sin pérdida
+- [ ] Tests de dominio verdes
+
+---
+
+### Feature B — ActivityPanel "wow" (Etapa 2)
+
+**Peso estimado:** 20% del sprint.
+
+**Versión mínima:**
+- Reemplazar slider de % por inputs de `utilizationMinutes` (número) y `units` (número entero ≥ 1)
+- Mostrar costo calculado por recurso debajo del input
+
+**Versión con wow (recomendada):**
+Todo lo anterior más:
+- Cálculo en tiempo real: el costo se actualiza al tipear (debounce de 300ms)
+- Subtotal de recursos visible en el panel antes de guardar
+- Helper contextual bajo el total: _"Esta actividad consume el equivalente a **2.3 días** de trabajo del Analista Senior al mes"_ (calculado con `annualFrequency / 12 × utilizationMinutes / 60 / 8`)
+- El campo `directCostFixed` con label explícito: "Costo fijo (insumos, licencias, etc.)" para diferenciar visualmente de los recursos
+
+**Criterio de aceptación:**
+- [ ] Inputs reemplazan slider de %
+- [ ] Costo por recurso visible antes de guardar
+- [ ] Helper contextual aparece cuando hay `annualFrequency > 0` y recursos asignados
+- [ ] Validación visual del director aprobada
+
+---
+
+### Feature C — Reporte web: desglose de recursos (Etapa 3)
+
+**Peso estimado:** 20% del sprint.
+
+#### C.1 Desglose por actividad en ActivitiesTable
+
+**Versión mínima:** columna "Recursos" en la tabla que muestra el costo total de recursos de la actividad.
+
+**Versión con wow:** filas expandibles que muestran el desglose: fijo + recurso 1 + recurso 2 + subtotal. El expand/collapse usa animación consistente con el sistema de diseño.
+
+#### C.2 CumulativeSavingsChart — arrancar en `-inversión` (TECH_DEBT)
+
+El gráfico web parte de `(Año 0, 0)`. El PDF ya lo hace correcto (`(Año 0, -inversión)`). Inconsistencia que notarán analistas en pre-venta. Cambiar punto inicial en `CumulativeSavingsChart.tsx`.
+
+#### C.3 Payback label superpuesto (TECH_DEBT — trivial)
+
+Ajustar offset del label "Payback · X meses" para que no colisione con eje Y. ~15 min.
+
+#### C.4 Badge ⚡ — evaluar tamaño (TECH_DEBT)
+
+Evaluar 16×16px o 18×18px. Si no genera colisiones en nodos chicos: implementar y reportar. Si genera problemas: mantener 14×14px y documentar.
+
+**Criterio de aceptación:**
+- [ ] Tabla muestra desglose de recursos por actividad
+- [ ] CumulativeSavingsChart arranca en `-automationInvestment`
+- [ ] Payback label no colisiona con eje Y
+- [ ] Validación visual del director aprobada
+
+---
+
+### Feature D — UX rápidos (Etapa 4)
+
+**Peso estimado:** 10% del sprint.
+
+#### D.1 Edición inline de nombre de proceso y cliente
+
+**Problema:** requiere ir a configuración global. En un taller interrumpe el flujo.
+
+**Versión mínima:** campo editable inline en el header del workspace (click para editar, Enter/blur para guardar).
+
+**Versión con wow:** animación sutil texto → input → texto, guardado con checkmark naranja breve que desaparece en 1.5s.
+
+**Criterio de aceptación:**
+- [ ] Se puede editar nombre y cliente sin ir a configuración
+- [ ] Los cambios persisten en IndexedDB
+- [ ] Validación visual del director aprobada
+
+---
+
+### Feature E — PDF: recursos + verificación de truncamiento (Etapa 5)
+
+**Peso estimado:** 15% del sprint.
+
+#### E.1 Tabla de recursos en PDF (procesos Actual/Automatizado)
+
+Sección condicional al final del PDF (solo si hay actividades con recursos asignados):
+- Tabla: Actividad | Recurso | Tipo | Costo/hora | Minutos | Unidades | Costo
+- Subtotal por actividad
+- Si ninguna actividad tiene recursos: la sección no aparece
+
+**Versión mínima:** tabla simple.
+**Versión con wow:** chip de color por tipo de recurso (rol = naranja, sistema = azul slate, persona = verde, equipamiento = gris, insumo = amarillo).
+
+#### E.2 Verificación de truncamiento (TECH_DEBT)
+
+Test E2E que valide ancho de cada línea en los tres PDFs. Si pasa → cerrar ítem. Si hay truncamiento → aplicar `doc.splitTextToSize()`.
+
+**Criterio de aceptación:**
+- [ ] Sección de recursos aparece cuando hay datos, no aparece cuando no hay
+- [ ] Test E2E confirma ausencia de truncamiento en los tres PDFs
+- [ ] Validación visual del director aprobada
+
+---
+
+## 5. Estructura de etapas
+
+| Etapa | Contenido | Peso |
+|---|---|---|
+| 1 | Migración modelo: `utilizationPercent` → `utilizationMinutes + units`. Dexie v3. Tests unitarios. | 15% |
+| 2 | ActivityPanel "wow": inputs minutos/unidades, cálculo tiempo real, helper contextual | 20% |
+| 3 | Reporte web: desglose recursos por actividad (expandible), CumulativeSavingsChart -inversión, payback fix, badge | 20% |
+| 4 | UX rápidos: edición inline proceso/cliente | 10% |
+| 5 | PDF: tabla recursos + verificación truncamiento | 15% |
+| 6 | E2E tests completos + validación visual director | 10% |
+| *(buffer)* | *(imprevistos o profundizar wow)* | 10% |
+
+**Regla operativa:** ninguna etapa arranca sin su `ETAPA_X_PROMPT.md` aprobado por el director.
+
+---
+
+## 6. Lo que explícitamente NO entra en Sprint 2
+
+- Catálogo global de recursos compartido entre procesos → Sprint 3
+- Recursos en escenario automatizado (TO-BE) → Sprint 3 con Modelo B
+- Múltiples simulaciones / historial de escenarios → Sprint 3
+- Distribuciones de probabilidad → Fase 2
+- Export Excel → Backlog sin driver urgente
+- Modo oscuro, i18n, PWA → Fase 2
+- Login, multi-tenant, colaboración → Fase 2
+
+---
+
+## 7. Deuda técnica que se cierra en este sprint
+
+| Ítem en TECH_DEBT.md | Etapa |
+|---|---|
+| CumulativeSavingsChart arranca en `-inversión` (web) | 3 |
+| Payback label superpuesto con eje Y | 3 |
+| Badge ⚡ tamaño (evaluar 16-18px) | 3 |
+| Verificación truncamiento notas metodológicas PDF | 5 |
+
+---
+
+## 8. Definition of Done — Sprint 2
+
+- [ ] Features A–E: todos los criterios de aceptación cumplen
+- [ ] Migración Dexie v2→v3: test automatizado confirma preservación de datos
+- [ ] Tests unitarios: fórmula nueva, edge cases (sin recursos, units > 1, solo fijo, mixto)
+- [ ] E2E: flujo completo asignar recurso → simular → verificar costo en reporte → exportar PDF
+- [ ] Validación visual: reporte web con desglose, PDF con tabla de recursos, chart con -inversión
+- [ ] TECH_DEBT.md actualizado: ítems cerrados documentados
+- [ ] OBSERVATIONS.md limpio al cerrar
+- [ ] STRATEGIC_DIRECTION.md actualizado con reflexiones post-sprint
+- [ ] Ratio web/PDF respetado (verificar con conteo de etapas)
+
+---
+
+## 9. Riesgos
+
+| Riesgo | Probabilidad | Mitigación |
+|---|---|---|
+| La migración de `utilizationPercent` → `utilizationMinutes` produce valores incorrectos en procesos existentes | Media | Test de migración obligatorio antes de cualquier otra etapa. La heurística es conservadora (redondeo hacia abajo). |
+| El helper contextual en ActivityPanel requiere acceso a `annualFrequency` del proceso | Baja | `useReportData` o contexto del workspace ya tiene el proceso. Verificar en Etapa 2. |
+| La tabla de recursos en PDF excede el espacio disponible en página 4 | Media | Diseñar como página separada si supera el espacio. Sección completamente condicional. |
+
+---
+
+## 10. Referencias
+
+- `CLAUDE.md` (simulador-web) — reglas de implementación
+- `STRATEGIC_DIRECTION.md` — decisiones estratégicas post-Sprint 1.5
+- `BACKLOG.md` — ítems "Recursos", "Edición inline"
+- `TECH_DEBT.md` — ítems CumulativeSavingsChart, Payback, Badge, Truncamiento
+- `methodology/PATTERNS.md` — C.6, C.1
+- `methodology/ANTI_PATTERNS.md` — AP.8
+- `sprints/sprint-1-5/BRIEF.md` — manual de marca completo y tokens CSS
+- `assets/InQ manual de marca- 3.0.pdf` — manual de marca oficial