# 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