marcos/inq-roi-simulador-web
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
602957b6c97e1fd382b4c74a79c4639137104e67
inq-roi-simulador-web/sprints/sprint-2/BRIEF.md

13 KiB
Raw Blame History

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

// 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
Reference in New Issue View Git Blame Copy Permalink