312 lines
13 KiB
Markdown
312 lines
13 KiB
Markdown
# 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
|