# 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:

```tsx
// 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:

```typescript
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):

```css
.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:**

```typescript
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.