inq-roi-simulador-web/sprints/sprint-1-5/ETAPA_9_PROMPT.md

Sprint 1.5 — Etapa 9: Badge ⚡ naranja en BpmnCanvas (web)

Objetivo: rediseñar el overlay del badge "automatizable" sobre los nodos del diagrama BPMN en el workspace web. Migrar de fondo blanco/ámbar con ícono Bot a fondo naranja sólido con símbolo ⚡, posición robusta basada en left (no right), y consistencia con la identidad InQ aplicada en Sprint 1.5.

Pre-requisitos: Etapas 1-8 cerradas. Sistema de design tokens InQ disponible en tailwind.config.ts. Tokens --inq-orange, --inq-orange-lighter, etc., definidos.

Etapa siguiente: Etapa 10 — Validación E2E final del Sprint 1.5 (suite completa, generación de artefactos de verificación, reporte de cobertura).

---

1. Alcance estricto

Sí entra

• ✅ Rediseño visual del badge en BpmnCanvas.tsx: fondo #F59845 (inq-orange), símbolo ⚡ blanco
• ✅ Cambio de posición del badge: de { top, right } a { top, left: elementWidth - 12 } para robustez con bpmn-js v18
• ✅ Migración de hex hardcodeados pendientes en BpmnCanvas.tsx: #f59e0b, #fffbeb, #e2e8f0 a tokens CSS
• ✅ Tests visuales del overlay con Playwright
• ✅ Verificar que el badge aparece solo en actividades con automatable === true
• ✅ Verificar que el badge se actualiza correctamente cuando se toggle del switch en ActivityPanel

NO entra

• ❌ Cambios en los PDFs (cerrados en Etapas 4-8)
• ❌ Cambios en la lógica de detección de automatable (solo presentación)
• ❌ Reemplazo del emoji ⚡ por <Bot /> de Lucide (anotado para Sprint 2-3 — requiere assets refinados)
• ❌ Cambios en el panel de Automatización del ActivityPanel (cerrado en Etapa 3)
• ❌ Cambios en otros overlays de bpmn-js (highlight de selección, gateways, etc.)

---

2. Decisiones ya tomadas (no consultar de nuevo)

Decisión	Justificación
Fondo del badge: #F59845 (inq-orange sólido)	Brief sección 2.8, BRIEF.md Sprint 1.5
Símbolo: ⚡ blanco	Brief sección 2.8
Tamaño: 14px diameter	Brief sección 2.8
Border: 1.5px solid white	Brief sección 2.8 — para contraste sobre fondos claros
Posición: { top: -8, left: elementWidth - 12 }	Brief sección 2.8 — evita bug de right en bpmn-js v18
Emoji ⚡ se mantiene en Sprint 1.5	Refinamiento a <Bot /> agendado para Sprint 2-3

---

3. Estado actual del componente

src/features/workspace/BpmnCanvas.tsx tiene actualmente:

// Líneas aproximadas según audit Etapa 1:

// Línea 24: stroke del ícono Bot en SVG inline
stroke="#f59e0b"  // amber-500 (hardcodeado)

// Línea 40: fondo del badge
backgroundColor: '#fffbeb',  // amber-50 (hardcodeado)

// Línea 41: borde del badge
border: '1.5px solid #e2e8f0',  // slate-200 (hardcodeado)

Audit Etapa 1 dijo (entrada para BpmnCanvas.tsx):

Etapa 9 (Badge ⚡): rediseño completo del badge a naranja sólido.

Es decir, esta etapa es el cumplimiento de un trabajo ya planificado, no exploración nueva.

---

4. Especificación detallada del badge nuevo

4.1 Estructura visual

Badge automatizable (overlay sobre nodo BPMN):

  ┌────────────────┐
  │ Nodo BPMN      │
  │ "task_recv"    │ ← actividad automatizable
  │           ⚡   │ ← badge en esquina superior derecha
  │                │   (posicionado con left, no right)
  └────────────────┘

Estilo del badge:
  - Diámetro: 14px
  - Fondo: #F59845 (var(--inq-orange))
  - Border: 1.5px solid white
  - Border-radius: 50% (círculo perfecto)
  - Box-shadow: 0 1px 2px rgba(0,0,0,0.1) (sutil elevación)
  
Símbolo ⚡:
  - Color: white
  - Tamaño: 8px (font-size)
  - Font-weight: 700
  - Text-align: center
  - Line-height: 14px (centrado vertical)

Posición:
  - top: -8px (sale 8px por encima del nodo)
  - left: elementWidth - 12px (calculado dinámicamente desde bpmn-js)
  - z-index: 10 (sobre el nodo, debajo de tooltips)

4.2 Implementación técnica

bpmn-js usa el sistema de overlays para posicionar elementos sobre nodos del diagrama. La API relevante:

const overlays = modeler.get('overlays');

overlays.add(elementId, 'automatable-badge', {
  position: {
    top: -8,
    left: elementWidth - 12,  // NO usar right (bug v18)
  },
  html: `<div class="automatable-badge">⚡</div>`,
});

CSS del badge (en BpmnCanvas.tsx o archivo asociado):

.automatable-badge {
  width: 14px;
  height: 14px;
  background: var(--inq-orange);  /* #F59845 */
  border: 1.5px solid white;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  color: white;
  font-size: 8px;
  font-weight: 700;
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
  cursor: default;
}

4.3 Lifecycle del badge

El badge debe:

1. Aparecer cuando una actividad se marca como automatable === true
2. Desaparecer cuando se desmarca (toggle del switch en ActivityPanel)
3. Persistir al hacer zoom, pan, o re-render del canvas
4. Re-renderizar correctamente después de hot-reload en desarrollo

Patrón recomendado:

useEffect(() => {
  const overlays = modeler.get('overlays');
  const overlayIds: Record<string, string> = {};
  
  activities.forEach(activity => {
    if (activity.automatable) {
      const element = elementRegistry.get(activity.bpmnElementId);
      if (!element) return;
      
      const id = overlays.add(activity.bpmnElementId, 'automatable-badge', {
        position: {
          top: -8,
          left: element.width - 12,
        },
        html: '<div class="automatable-badge">⚡</div>',
      });
      overlayIds[activity.bpmnElementId] = id;
    }
  });
  
  return () => {
    Object.values(overlayIds).forEach(id => overlays.remove(id));
  };
}, [activities, modeler]);

---

5. Migración de hex hardcodeados pendientes

Según audit Etapa 1, BpmnCanvas.tsx tiene 3 hex residuales que deben migrarse:

Línea aprox.	Hex actual	Significado actual	Nueva referencia
24	#f59e0b	stroke ícono Bot en SVG inline (legacy)	ELIMINAR: el ícono Bot se reemplaza por el badge ⚡
40	#fffbeb	fondo del badge (legacy amber-50)	ELIMINAR: el badge nuevo usa var(--inq-orange)
41	#e2e8f0	borde del badge (legacy slate-200)	ELIMINAR: el badge nuevo usa border blanco

El badge legacy se reemplaza completo. No se trata de migrar colores, sino de rediseñar el componente.

---

6. Validaciones automatizadas mandatorias

Antes de present_files, ejecutá y confirmá:

1. El componente BpmnCanvas.tsx renderiza sin errores
   - npm run build limpio
   - npm run typecheck sin errores
   - Sin warnings nuevos de React

2. Tests unitarios:
   - El badge aparece cuando activity.automatable === true
   - El badge NO aparece cuando activity.automatable === false
   - El badge tiene fondo naranja InQ (#F59845)
   - El badge usa posición left, no right
   - Cleanup del badge al desmontar componente

3. Tests E2E (Playwright):
   - Cargar simple-linear, marcar primera actividad como automatable
   - Verificar que el badge ⚡ naranja aparece sobre el nodo correcto
   - Toggle del switch off — verificar que el badge desaparece
   - Toggle on de nuevo — verificar que el badge reaparece

4. Screenshot Playwright en tests/screenshots/etapa-9/:
   - workspace-badge-on.png: workspace con simple-linear y 2-3 
     actividades automatizables, badges naranja visibles
   - workspace-badge-detail.png: zoom in sobre un nodo automatizable 
     mostrando el badge con detalle

5. Sin regresiones:
   - Otros tests del web app siguen verdes (~515+ del sprint)
   - PDFs no se regeneran en esta etapa (no aplica validación)

Si CUALQUIER validación falla, NO uses present_files. Reportá qué falló.

---

7. Entregables (Definition of Done)

[ ] BpmnCanvas.tsx rediseñado: badge ⚡ naranja sólido reemplaza al 
    badge legacy amber con Bot
[ ] Posición del badge usa left (no right) — robusto a bpmn-js v18
[ ] CSS del badge usa var(--inq-orange) y var(--inq-orange-lighter) 
    según corresponda (sin hex hardcodeados)
[ ] 3 hex hardcodeados pendientes del audit Etapa 1 eliminados
[ ] Tests unitarios del overlay (al menos 5 casos)
[ ] Tests E2E del lifecycle del badge (al menos 3 escenarios)
[ ] 2 screenshots Playwright generados y commiteados
[ ] 515+ tests previos siguen verdes
[ ] Build limpio, typecheck limpio, lint limpio
[ ] Screenshot presentado para validación visual
[ ] Decisiones tomadas por iniciativa documentadas según política 
    refinada (post-Etapa 8) de CLAUDE.md

---

8. Validación visual del director

Después de Claude Code presente los screenshots, abrí el dev server y validá:

1. Cargá un proceso (idealmente simple-linear o medium-with-gateways)
2. Marcá 2-3 actividades como automatizables desde el ActivityPanel
3. Mirá el canvas BPMN y verificá:

[ ] El badge ⚡ aparece sobre cada actividad marcada
[ ] El badge tiene fondo naranja sólido (#F59845)
[ ] El símbolo ⚡ se ve nítido en blanco
[ ] El badge está en la esquina superior derecha del nodo
[ ] El badge NO se sale del área del nodo al hacer zoom in/out
[ ] El badge desaparece al desmarcar la actividad
[ ] No hay badges huérfanos al cambiar de proceso o limpiar

Tu impresión visceral: ¿el badge se siente parte de la identidad InQ o se siente "agregado"? Es un detalle pequeño pero importante para coherencia visual.

---

9. Reporte final a entregar

1. Tabla de archivos modificados con líneas
2. 5 validaciones automatizadas confirmadas (resultados específicos)
3. Cantidad final de tests verdes
4. 2 screenshots Playwright presentados con paths absolutos
5. Confirmación de migración de hex hardcodeados (los 3 del audit Etapa 1)
6. Hallazgos no esperados
7. Decisiones tomadas por iniciativa clasificadas según política refinada de CLAUDE.md

---

10. Reglas operativas (recordatorios)

1. NO TOCAR los PDFs. Cerrados en Etapas 4-8. Esta etapa es solo web app.

2. NO REEMPLAZAR el emoji ⚡ con <Bot /> u otro icono. Está agendado para Sprint 2-3 cuando InQuality tenga assets refinados.

3. NO CAMBIAR la lógica de detección de automatable. Solo la presentación visual.

4. USAR POSICIÓN basada en left, no right. Está documentado como bug conocido de bpmn-js v18 en el brief (sección 5.3). El position calculado dinámicamente con elementWidth - 12 es la solución probada.

5. Política de iniciativa proactiva refinada (post-Etapa 8):

   • Si el cambio resuelve un ítem listado en TECH_DEBT.md o BACKLOG.md → Nivel 3 (consultar previa)
   • Si choca con restricción explícita del prompt ("NO entra", "NO tocar") → Nivel 3
   • Si modifica paginación, layout, estructura de salida, o contenido visible → Nivel 2 mínimo (reportar)
   • Si afecta marca, identidad, dependencias o configuración → Nivel 3
   • Si nada aplica → Nivel 1
   • Argumentos NO válidos: "mejora de legibilidad", "consistencia con etapa anterior", "trivial de revertir", "resuelve bug menor"

6. Si encontrás que el badge actual usa Bot de Lucide en lugar de algún SVG genérico, NO migres a <Bot /> ni a otro componente. Reemplaza el badge completo según especificación de §4.

7. Validación visual del director es mandatoria. No declarar etapa terminada sin que el director haya visto los screenshots y verificado el dev server.

8. Si encontrás contradicción entre prompt y código: PARÁ y consultá.

---

11. Contexto: por qué esta etapa importa

El badge ⚡ es el indicador visual más importante del workspace BPMN. Cuando un consultor importa un proceso de 15 actividades y empieza a marcar automatizables, necesita ver de un vistazo cuáles ya marcó y cuáles faltan. Un badge legítimo, visible y consistente con la marca es la diferencia entre "herramienta profesional" y "prototipo".

Hasta ahora el badge era ámbar tenue con un ícono Bot que pasaba desapercibido. Con esta etapa el badge se vuelve el segundo elemento visual más identitario del producto después del logo y los KPI Hero (los dos elementos donde aparece el naranja InQ con peso).

Si el badge queda bien:

• El workspace transmite "identidad de marca" sin texto
• Las screenshots de pre-venta muestran un producto cohesivo
• El consultor tiene feedback visual claro de qué activó

Si queda mal:

• Inconsistencia visual entre web y PDFs
• Sensación de "componente legacy no actualizado"

Apuntá al primero.

---

12. Esta etapa cierra el rediseño visual del Sprint 1.5

Después de Etapa 9, los componentes visuales clave del producto están todos rediseñados:

• ✅ Web app workspace (Etapa 3)
• ✅ Web app reporte ROI (Etapa 3)
• ✅ PDFs header/footer compartidos (Etapa 4)
• ✅ PDFs layout híbrido (Etapa 5)
• ✅ PDF ROI página 1 completa (Etapa 6)
• ✅ PDF ROI páginas 2-5 (Etapa 7)
• ✅ PDFs Actual/Automatizado (Etapa 8)
• ⏳ Badge ⚡ en BpmnCanvas (Etapa 9 — esta)

Lo que queda después es validación final (Etapa 10) y polish + documentación (Etapa 11). El rediseño visual del producto está completo después de Etapa 9.