inq-roi-simulador-web/sprints/sprint-3/BRIEF.md

Sprint 3 — Brief

Propósito: dos ejes paralelos — (1) construir la Process Library: una biblioteca navegable y organizada de procesos con jerarquía configurable y tags; (2) completar el Modelo A: indicador de simulación desactualizada, zoom en canvas BPMN, y recursos en el escenario automatizado.

Usuario objetivo: equipo de InQuality. Uso interno en talleres de análisis de procesos y pre-venta de automatización.

Sprint anterior: Sprint 2 — modelo de recursos utilizationMinutes + units (Dexie v3), ActivityPanel "wow", reporte web con filas expandibles, edición inline proceso/cliente, tabla de recursos en PDF. 548 tests al cierre. Ver cierre en methodology/CASE_STUDIES/inq-roi-sprint-2.md.

---

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.
• 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.
• Control preventivo de scope: incluir git diff --name-only HEAD en todo prompt. Archivo no autorizado en el diff → revertir y reportar. Ver methodology/PATTERNS.md C.7.
• Restricciones contradictorias: si un prompt tiene restricción ❌ sobre un archivo y el cambio solicitado genera conflicto inevitable, DETENER y reportar al director. No resolver unilateralmente. Ver methodology/ANTI_PATTERNS.md AP.9.

---

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.

1.3 Decisión estratégica: PostgreSQL diferido

La persistencia en Dexie (IndexedDB) se mantiene hasta Sprint 5+. La decisión fue tomada conscientemente: el driver para una migración a PostgreSQL (multi-usuario, multi-tenant) no existe todavía en el uso interno de InQuality. El schema de Dexie v4 debe diseñarse con relaciones normalizadas y UUIDs para que la migración futura a SQL sea limpia.

---

2. Estado real del producto (pre-Sprint 3)

2.1 Lo que existe en la persistencia (Dexie v3)

Tabla	Estado
processes	✅ { id, name, clientName, bpmnXml, currency, overheadPercentage, annualFrequency, analysisHorizonYears, automationInvestment, createdAt, updatedAt }
activities	✅ incluye assignedResources: ActivityResourceAssignment[], automatable, automatedCostFixed, automatedTimeMinutes
resources	✅ { id, processId, name, type, costPerHour }
gateways	✅ { id, processId, bpmnElementId, gatewayType, branches }
simulations	✅ { id, processId, executedAt, result, resultAutomated? }

2.2 Lo que falta y se construye en Sprint 3

Elemento	Estado actual	Sprint 3
Agrupación de procesos	❌ No existe	✅ Tabla groups + groupId en Process
Tags en procesos	❌ No existe	✅ Campo tags: string[] en Process
Configuración de etiquetas	❌ No existe	✅ Tabla settings con groupLabel configurable
Vista de biblioteca	❌ No existe	✅ Home navegable con grupos y procesos
Búsqueda y filtros	❌ No existe	✅ Búsqueda por nombre + filtro por tags
Indicador stale	❌ No existe	✅ Badge cuando proceso tiene cambios sin simular
Zoom/fit canvas BPMN	❌ No existe	✅ Botón fit-to-viewport
Recursos en escenario automatizado	❌ automatedCostFixed solamente	✅ automatedAssignedResources[] + simulación

---

3. Decisiones arquitectónicas del sprint (validadas por el director)

Decisión	Resolución
Versión Dexie	Incrementar a v4. Migración preserva datos existentes.
Jerarquía de biblioteca	Dos niveles: Grupo (etiqueta configurable) + Proceso
Etiquetas configurables	Una sola etiqueta para el nivel de grupo (groupLabel). Default: "Cliente". Configurable por workspace.
Scope de settings	Singleton en IndexedDB — un registro por instalación. Preparado para extensión en Sprint 5+ cuando llegue multi-tenant.
Indicador stale	Comparar process.updatedAt vs latestSimulation.executedAt. Requiere garantizar que guardar activity/resource/gateway actualiza process.updatedAt. Sin campo nuevo.
Recursos en automatizado	Nuevo campo automatedAssignedResources: ActivityResourceAssignment[] en Activity. Migración v4 popula con array vacío.
Costo automatizado total	automatedCostTotal = automatedCostFixed + SUM(automatedResourceCosts) — mismo patrón que AS-IS
UUIDs en nuevas tablas	groups y settings usan UUIDs para compatibilidad futura con PostgreSQL
PostgreSQL	Diferido a Sprint 5+. No afecta diseño de Sprint 3 salvo por las consideraciones de UUIDs y normalización.

3.1 Schema Dexie v4 — cambios

// NUEVA tabla — ProcessGroup
export interface ProcessGroup {
  id: UUID           // generado con crypto.randomUUID()
  name: string
  createdAt: number  // timestamp Unix ms
  updatedAt: number
}

// NUEVA tabla — AppSettings (singleton)
export interface AppSettings {
  id: 'singleton'    // siempre un solo registro
  groupLabel: string // default: 'Cliente'
}

// Process — campos NUEVOS (migración v4 popula con defaults)
export interface Process {
  // ... campos existentes sin cambio ...
  groupId: UUID | null  // 🆕 null = "Sin clasificar"
  tags: string[]        // 🆕 []
}

// Activity — campo NUEVO (migración v4 popula con [])
export interface Activity {
  // ... campos existentes sin cambio ...
  automatedAssignedResources: ActivityResourceAssignment[]  // 🆕 []
}

3.2 Migración v3 → v4

this.version(4)
  .stores({
    processes:  'id, name, updatedAt, groupId',   // groupId indexado para queries por grupo
    activities: 'id, processId, bpmnElementId',
    gateways:   'id, processId, bpmnElementId',
    resources:  'id, processId, name',
    simulations:'id, processId, executedAt',
    groups:     'id, name, updatedAt',             // nueva tabla
    settings:   'id',                              // nueva tabla (singleton)
  })
  .upgrade(async (tx) => {
    // Processes: agregar groupId y tags
    await tx.table('processes').toCollection().modify((proc) => {
      if (proc.groupId === undefined) proc.groupId = null
      if (!Array.isArray(proc.tags))  proc.tags = []
    })
    // Activities: agregar automatedAssignedResources
    await tx.table('activities').toCollection().modify((act) => {
      if (!Array.isArray(act.automatedAssignedResources)) {
        act.automatedAssignedResources = []
      }
    })
    // Settings: crear singleton con defaults
    await tx.table('settings').put({ id: 'singleton', groupLabel: 'Cliente' })
  })

3.3 Fórmula de costo automatizado actualizada

costoRecursoAutomatizado = resource.costPerHour × assignment.utilizationMinutes / 60 × assignment.units
costoAutomatizadoActividad = automatedCostFixed + SUM(costoRecursoAutomatizado por cada automatedAssignment)

La función simulate(input, scenario) ya existe. Al pasar scenario = 'automated', para actividades automatable = true, usar automatedAssignedResources en lugar de assignedResources.

---

4. Features del sprint

---

Feature A — Dexie v4: fundación del modelo de biblioteca (Etapa 1)

Peso estimado: 10% del sprint.

Data layer puro. Sin cambios de UI. Objetivo: que el schema esté correcto y los datos existentes preservados antes de construir cualquier UI encima.

• Nuevas interfaces ProcessGroup y AppSettings en types.ts
• Nuevos campos groupId y tags en Process, automatedAssignedResources en Activity
• db.ts: versión 4 con las dos nuevas tablas y función de upgrade
• Tests de migración: proceso existente conserva todos los campos, groupId = null, tags = [], automatedAssignedResources = []
• Test de idempotencia: ejecutar upgrade dos veces no corrompe datos

Criterio de aceptación:

• Migración v3→v4 sin pérdida de datos (test automatizado)
• ProcessGroup y AppSettings disponibles en TypeScript sin errores
• settings singleton creado con groupLabel: 'Cliente' por defecto
• Build limpio sin errores TypeScript
• git diff --name-only HEAD muestra solo los archivos autorizados

Archivos autorizados: src/domain/types.ts, src/persistence/db.ts, tests de migración.

---

Feature B — Vista de biblioteca + gestión de grupos (Etapa 2)

Peso estimado: 20% del sprint.

La biblioteca pasa a ser la home de la aplicación. El flujo anterior (importar BPMN directamente al llegar) se mantiene como acción secundaria desde la biblioteca.

Versión mínima:

• Nueva ruta / o equivalente que muestra la biblioteca
• Lista de grupos con contador de procesos
• Sección "Sin clasificar" para groupId = null
• CRUD de grupos: crear, renombrar, eliminar
  • Eliminar grupo: procesos del grupo pasan a "Sin clasificar" (no se borran)
• Vista de procesos dentro de un grupo: nombre, cliente, fecha de última modificación
• Botón "Nuevo proceso" (importar BPMN) disponible globalmente y dentro de cada grupo
• Al crear/importar un proceso desde dentro de un grupo, asigna groupId automáticamente

Versión con wow (recomendada): Todo lo anterior más:

• Empty state diseñado para la primera vez (sin grupos ni procesos): ilustración o mensaje de bienvenida con CTA para crear el primer grupo o importar un proceso
• Empty state para grupo vacío: "Este grupo no tiene procesos. Importá un BPMN para empezar."
• Hover sobre proceso: preview con fecha de última simulación y costo total (si existe)
• Breadcrumb al entrar a un grupo: groupLabel / nombre del grupo

Criterio de aceptación:

• Navegación entre biblioteca y grupos funciona sin recargar
• CRUD de grupos opera correctamente (incluyendo caso de borrado con procesos)
• Procesos existentes sin grupo aparecen en "Sin clasificar"
• Asignación automática de grupo al crear proceso desde dentro de uno
• Validación visual del director aprobada

---

Feature C — Tags + búsqueda + configuración de etiquetas (Etapa 3)

Peso estimado: 15% del sprint.

C.1 — Tags en procesos

Chip input en el workspace del proceso (cerca del nombre y cliente) para agregar y quitar tags. Los tags son strings libres. Autocompletado con tags ya existentes en la base (evita fragmentación "BPMN" / "bpmn" / "Bpmn").

C.2 — Búsqueda y filtros en biblioteca

• Búsqueda en tiempo real por nombre de proceso (filtra mientras se escribe)
• Filtro por tags: chips seleccionables que muestran solo procesos con esos tags
• Los filtros activos se muestran visualmente como chips removibles
• La búsqueda opera tanto dentro de un grupo como en "todos los procesos"

C.3 — Configuración de etiquetas

Pantalla de configuración (ruta /settings o modal) donde el usuario define:

• groupLabel: cómo se llama el nivel de agrupación (default: "Cliente"). Este label aparece en toda la UI donde antes decía "Grupo".
• La configuración persiste en la tabla settings de Dexie.

Versión con wow (recomendada): Todo lo anterior más:

• En la vista de biblioteca sin filtro activo: mostrar un tag cloud visual con los tags más usados — click en un tag activa el filtro
• El label configurado se refleja en tiempo real en la UI sin recargar (reactive desde el settings store)

Criterio de aceptación:

• Tags se guardan y persisten en el proceso
• Autocompletado funciona con tags existentes (case-insensitive)
• Búsqueda filtra procesos en tiempo real
• Filtro por tags funciona en modo AND (proceso debe tener todos los tags seleccionados)
• groupLabel configurable y reflejado en la UI
• Validación visual del director aprobada

---

Feature D — Indicador de simulación desactualizada + zoom BPMN (Etapa 4)

Peso estimado: 10% del sprint.

D.1 — Indicador stale

Cuando el usuario guarda cambios en actividades, recursos o gateways de un proceso sin volver a simular, el workspace muestra un indicador persistente.

Implementación: garantizar que db.processes.update(id, { updatedAt: Date.now() }) se ejecuta siempre que se guarden activities, resources o gateways del proceso. El indicador es process.updatedAt > (latestSimulation?.executedAt ?? 0).

Versión mínima: badge "Simular para actualizar" en el botón Simular (o cerca). Desaparece al ejecutar.

Versión con wow (recomendada): Todo lo anterior más:

• El indicador menciona cuántas actividades tienen cambios sin simular (requiere comparar activity.updatedAt — agregar este campo solo si el esfuerzo es < 40% del mínimo; si no, omitir)
• El indicador también aparece en el reporte web como banner sutil: "Los resultados pueden estar desactualizados — hay cambios sin simular" con botón "Simular ahora"

D.2 — Zoom/fit canvas BPMN

Botón "Encuadrar diagrama" (ícono fit-to-screen o similar) en la toolbar del BpmnCanvas. Al hacer click: bpmnViewer.get('canvas').zoom('fit-viewport'). Detectado en validación Sprint 2 como problema real en talleres.

Criterio de aceptación:

• Indicador aparece al guardar actividad sin re-simular
• Indicador desaparece al ejecutar simulación
• Botón fit-to-viewport funciona en BpmnCanvas
• Validación visual del director aprobada

---

Feature E — Recursos en escenario automatizado (Etapa 5)

Peso estimado: 20% del sprint.

Esta es la feature más compleja de Modelo A. El campo automatedAssignedResources ya existe en el schema (creado en Etapa 1). Etapa 5 construye la UI y la lógica de simulación.

E.1 — UI en ActivityPanel

En la sección "Automatización" del ActivityPanel (visible cuando automatable = true), agregar una subsección "Recursos automatizados" paralela a la del escenario actual:

• Mismo componente de asignación de recursos (resourceId, utilizationMinutes, units)
• Recursos disponibles: los mismos del catálogo del proceso (tabla resources)
• Label diferenciador: "Recursos en AS-IS" / "Recursos en TO-BE" (o "Actual" / "Automatizado")

E.2 — Motor de simulación

Al simular con scenario = 'automated', para actividades automatable = true:

• Usar automatedAssignedResources en lugar de assignedResources
• Costo total = automatedCostFixed + SUM(costoRecursoAutomatizado)
• El resourceCostBreakdown en ActivitySimResult refleja los recursos automatizados

E.3 — Reporte web

En las filas expandibles de ActivitiesTable para actividades automatizables:

• Versión mínima: mostrar desglose de recursos del escenario que corresponde (actual en columna actual, automatizado en columna automatizado)
• Versión con wow: comparación lado a lado — fila expandida muestra "Actual: X recursos" / "Automatizado: Y recursos" con sus costos individuales

Criterio de aceptación:

• Se pueden asignar recursos al escenario automatizado desde el ActivityPanel
• La simulación usa esos recursos al calcular el costo automatizado
• El reporte muestra el desglose de recursos del escenario automatizado
• Escenario sin recursos automatizados: comportamiento idéntico al anterior (solo automatedCostFixed)
• Tests unitarios: costo automatizado con recursos, sin recursos, mixto (fijo + recursos)
• Validación visual del director aprobada

---

Feature F — PDF actualizado + tests del sprint (Etapa 6)

Peso estimado: 15% del sprint.

F.1 — PDF con recursos automatizados

Si el proceso tiene actividades con automatedAssignedResources, la tabla de recursos en página 4 del PDF (introducida en Sprint 2) muestra ambos escenarios:

• Sección "Recursos AS-IS" (existente)
• Sección "Recursos TO-BE" (nueva, condicional — solo si hay recursos automatizados)

Si ninguna actividad tiene recursos automatizados, la tabla PDF no cambia respecto a Sprint 2.

F.2 — Tests del sprint

• Tests unitarios de migración Dexie v4 (cobertura de los nuevos campos)
• Tests unitarios del motor de simulación con automatedAssignedResources
• Test E2E del flujo completo de la biblioteca: crear grupo → importar proceso → asignar a grupo → agregar tags → buscar → filtrar
• Tests de la configuración de groupLabel (cambio se refleja en UI)

Criterio de aceptación:

• PDF con sección TO-BE aparece cuando hay recursos automatizados
• PDF sin recursos automatizados: sin cambio respecto a Sprint 2
• Todos los tests nuevos del sprint verdes
• Validación visual del director aprobada (abrir el PDF generado)

---

Feature G — Polish + validación final (Etapa 7)

Peso estimado: 10% del sprint.

Refinamientos post-validación visual del director de las etapas anteriores. Edge cases de la biblioteca (nombre de grupo muy largo, proceso sin nombre, muchos tags, tag muy largo). Ajustes de animación o spacing que emerjan en uso real. Cualquier inconsistencia de estilo entre la biblioteca nueva y el resto de la app.

Esta etapa no tiene scope predefinido — se construye a partir del feedback acumulado de la validación visual de Etapas 2-6.

Criterio de aceptación:

• Director da OK formal al producto visual completo del sprint
• Sin regresiones en features existentes (tests E2E del sprint anterior siguen verdes)

---

5. Estructura de etapas

Etapa	Contenido	Peso
1	Dexie v4: nuevas tablas, campos, migración, tests	10%
2	Vista de biblioteca + gestión de grupos	20%
3	Tags + búsqueda + configuración de etiquetas	15%
4	Indicador simulación desactualizada + zoom BPMN	10%
5	Recursos en escenario automatizado (UI + simulación + reporte)	20%
6	PDF recursos automatizados + tests del sprint	15%
7	Polish + validación final	10%

Proporción por componente: web app ~75% (etapas 2, 3, 4, 5) · PDF + tests ~25% (etapas 1, 6, 7).

Regla operativa: ninguna etapa arranca sin su ETAPA_X_PROMPT.md aprobado por el director.

---

6. Lo que explícitamente NO entra en Sprint 3

• Catálogo global de recursos compartido entre procesos → evaluar Sprint 4 con feedback de uso real
• Modelo B (AS-IS / TO-BE con dos BPMNs) → decisión diferida a Sprint 4+
• Múltiples simulaciones / historial de escenarios → BACKLOG
• Migración a PostgreSQL → Sprint 5+ (decisión tomada explícitamente)
• Login, multi-tenant, colaboración → Fase 2
• Gateway OR inclusivo nativo → BACKLOG
• Distribuciones de probabilidad → Fase 2
• Export Excel → BACKLOG

---

7. Deuda técnica que se cierra en este sprint

Ítem en TECH_DEBT.md	Etapa
Toggle automatable + Guardar requerido para badge (INVESTIGATING)	4 — resolver como parte del indicador stale
Indicador visual actividades automatizables en reporte (BACKLOG)	5 — cubierto por desglose en filas expandibles
Controles de zoom en canvas BPMN (BACKLOG)	4

---

8. Definition of Done — Sprint 3

• Features A–G: todos los criterios de aceptación cumplidos
• Migración Dexie v3→v4: test automatizado confirma preservación de datos y correctos defaults
• Tests unitarios: motor de simulación con automatedAssignedResources (sin recursos, solo fijo, mixto, solo recursos)
• Test E2E: flujo completo de biblioteca (crear grupo, asignar proceso, tags, búsqueda, filtro)
• Validación visual: biblioteca navegable, indicador stale, comparación recursos en reporte, PDF TO-BE
• TECH_DEBT.md actualizado: ítems cerrados documentados
• OBSERVATIONS.md limpio al cerrar
• STRATEGIC_DIRECTION.md actualizado con reflexiones post-sprint
• Ratio web/PDF respetado (~75% web, ~25% PDF + infra)

---

9. Riesgos

Riesgo	Probabilidad	Mitigación
La Etapa 5 (recursos automatizados) tiene dependencias de tipo transitivas con archivos de etapas anteriores	Media	Incluir instrucción AP.9 explícita: si hay conflicto en archivos restringidos, DETENER y reportar.
El indicador stale requiere rastrear updatedAt a nivel de actividad (actualmente no existe)	Media	Especificado en el BRIEF: solo comparar process.updatedAt vs simulation.executedAt. Si se quiere granularidad por actividad, evaluar esfuerzo antes de comprometerse.
La biblioteca reemplaza la home y puede romper el flujo de importación existente	Media	Diseñar la biblioteca para que el flujo de importación sea acción prominente, no secundaria. Testear el E2E de importación como parte de Etapa 2.
settings singleton asume una instalación = un usuario. Si en el futuro hay multi-usuario en el mismo browser, colisiona.	Baja	Aceptado conscientemente. El diseño con id: 'singleton' es limpio y fácil de migrar cuando llegue multi-tenant.

---

10. Referencias

• CLAUDE.md (simulador-web) — reglas de implementación
• STRATEGIC_DIRECTION.md — decisiones estratégicas post-Sprint 2
• BACKLOG.md — ítems "Indicador simulación desactualizada", "Zoom BPMN", "Tags"
• TECH_DEBT.md — ítems toggle automatable, indicador visual, zoom
• methodology/PATTERNS.md — C.6, C.7
• methodology/ANTI_PATTERNS.md — AP.8, AP.9
• sprints/sprint-2/BRIEF.md — contexto del modelo de recursos y Dexie v3
• methodology/CASE_STUDIES/inq-roi-sprint-2.md — lecciones del sprint anterior
• assets/InQ manual de marca- 3.0.pdf — manual de marca oficial