# Process Cost Platform

> Transformá un archivo BPMN 2.0 en un reporte visual de costos operativos —
> y calculá el ROI de automatizar ese proceso — en minutos, sin backend, sin registro.

**Hecho desde Paraguay 🇵🇾 · Herramienta interna de InQuality · Sprint 1 en desarrollo activo**

---

## ¿Qué hace esto?

Un consultor de procesos recibe un diagrama BPMN del cliente. Con esta plataforma puede:

1. **Importar** el diagrama (.bpmn) y ver el proceso renderizado al instante.
2. **Configurar costos** actividad por actividad: costo fijo, tiempo, recursos humanos/sistemas.
3. **Simular** para obtener el costo esperado de una ejecución completa, con propagación de probabilidades a través de gateways XOR, AND e inclusivos.
4. **Ver el reporte** con mapa de calor sobre el diagrama, KPIs, gráficos, tabla de actividades.
5. **Exportar** a PDF (presentación para el cliente) o CSV (datos para Excel).

En Sprint 1 (en curso):

6. **Marcar actividades como automatizables** y configurar sus costos en el escenario automatizado.
7. **Calcular el ROI** del proyecto de automatización: payback, ahorro anual, acumulado a N años.
8. **Mostrar un reporte comparativo** Actual vs. Automatizado con transparencia metodológica.

**Audiencia primaria**: consultores de InQuality que usan esto en pre-venta de proyectos de automatización.
No es un producto de consumo masivo. El diseño prioriza densidad de información y velocidad de uso.

---

## Inicio rápido

```bash
git clone <repo>
cd simulador-web
npm install --legacy-peer-deps
npm run dev
```

Abre `http://localhost:5173`. Arrastrá un `.bpmn` o hacé clic en uno de los tres procesos de ejemplo.

> **Sin instalación de backend.** Todo corre en el navegador. Los datos se guardan en IndexedDB
> del browser — si borrás el caché, perdés los procesos guardados. Exportá el PDF/CSV antes de limpiar.

---

## Flujo de uso detallado

### 1. Importar un proceso

Arrastrá tu archivo `.bpmn` a la pantalla de inicio, o cargá uno de los procesos de ejemplo:
- **Proceso lineal simple** — para entender el flujo básico
- **Aprobación de crédito** — con gateways XOR y AND paralelo
- **Control de calidad con revisión** — con loop

La plataforma soporta BPMN 2.0 con **múltiples pools** (colaboraciones): todos los pools se importan y sus actividades aparecen configurables en el workspace.

### 2. Configurar el workspace

El panel derecho tiene tres tabs:

**Tab "Actividad"** (al hacer click en un nodo del diagrama):
- Costo directo fijo por ejecución
- Tiempo de ejecución en minutos
- Recursos asignados (rol/sistema/equipo con % de utilización)
- Sección "Automatización" *(Sprint 1)*: toggle + costo y tiempo del escenario automatizado

**Tab "Recursos"**: CRUD de recursos reutilizables con costo/hora.

**Tab "Global"**:
- Nombre del proceso y cliente
- Moneda (USD, PYG, BRL, ARS, EUR, COP, MXN, CLP)
- Overhead (% de costos indirectos sobre directos)
- Frecuencia anual de ejecución *(Sprint 1)*
- Horizonte de análisis en años *(Sprint 1)*
- Inversión total en automatización *(Sprint 1)*

Las actividades marcadas como automatizables muestran un badge Bot ámbar (⚙️) en la esquina superior derecha del nodo en el canvas.

### 3. Simular

El botón "Simular" corre el motor determinístico. Si hay gateways XOR con probabilidades que no suman 100%, el botón queda deshabilitado y se muestran advertencias en la topbar.

Desde Sprint 1, el motor corre **dos escenarios simultáneamente** (actual + automatizado) y los guarda como un único snapshot. Cualquier cambio en los datos invalida ambos resultados — hay que re-simular.

### 4. Reportar y exportar

El reporte muestra mapa de calor, KPIs, gráficos y tabla de actividades. En Sprint 1 se agregan tabs de comparación y ROI.

Exportación:
- **PDF**: 3+ páginas presentables ante el cliente, con heatmap embebido como imagen JPEG.
- **CSV**: datos con BOM UTF-8 para compatibilidad con Excel regional.

---

## Arquitectura técnica

```
src/
├── domain/           ← Lógica de negocio pura, sin React, 100% testeable
│   ├── types.ts      ← Todas las interfaces del modelo de dominio
│   ├── simulation.ts ← Motor: propaga probabilidades por el grafo BPMN
│   ├── roi.ts        ← Cálculos de ROI: payback, ahorro, acumulado (Sprint 1)
│   ├── bpmn-parser.ts← Parser XML BPMN 2.0 → grafo en memoria
│   └── schemas.ts    ← Validación Zod de todas las entidades
│
├── store/            ← Estado global con Zustand
│   ├── process-store.ts     ← Proceso actual, actividades, gateways, recursos
│   └── simulation-store.ts  ← Resultados actual + automatizado, invalidación reactiva
│
├── persistence/      ← IndexedDB vía Dexie (schema versión 2)
│   ├── db.ts         ← Schema y migraciones
│   └── repositories.ts ← CRUD de entidades (@internal: solo llamar desde stores)
│
├── features/
│   ├── import/       ← Landing, drag & drop, carga de ejemplos
│   ├── workspace/    ← Canvas BPMN + panel lateral de configuración
│   ├── simulation/   ← Hook useSimulate: dispara ambos escenarios
│   └── report/       ← Reporte visual, heatmap, gráficos, export
│
└── lib/
    ├── export/       ← pdf-export.ts, csv-export.ts (lazy-loaded al hacer clic)
    ├── colors.ts     ← Gradiente heatmap: verde → ámbar → rojo
    └── format.ts     ← Formateo de moneda, tiempo, porcentajes
```

### Reglas de dependencia

```
domain/    ← no importa nada del proyecto (puro TypeScript)
store/     ← importa solo de domain/ y persistence/
features/  ← importa de domain/, store/, persistence/, lib/, components/
```

La regla ESLint `no-restricted-imports` hace que cualquier import de
`persistence/repositories` desde fuera de `store/` falle en `npm run lint`.
La única excepción intencional es `simulation-store.ts`, que importa
`process-store.ts` para suscribirse a cambios y mantener la invariante
de invalidación dual (documentado como excepción en el archivo).

### Motor de simulación — decisiones clave

El motor acepta `scenario: 'actual' | 'automated'`. En `'automated'`, las
actividades con `automatable=true` usan sus campos alternativos de costo y tiempo.
La probabilidad de ejecución **no cambia entre escenarios** — solo los costos.

Overlays en el canvas: se usa `overlays.add()` de diagram-js con posición
`{ top: -8, left: element.width - 12 }` obtenida via `elementRegistry.get()`.
**No usar** `position.right` directamente: la fórmula interna de diagram-js es
`left = right * -1 + width`, lo que con `right: -8` produce `left = width + 8`
(badge enteramente fuera del nodo, sin overlap de esquina).

---

## Stack tecnológico

| Capa | Tecnología | Nota |
|---|---|---|
| Framework | React 19 + Vite 8 (Rolldown) | |
| Routing | TanStack Router 1.x | Type-safe |
| Estado | Zustand 5 | Stores: process + simulation |
| Canvas BPMN | bpmn-js 18 / diagram-js | Viewer (read-only) |
| UI | shadcn/ui + Tailwind CSS | Components copy-pasted |
| Iconos | Lucide React | |
| Gráficos | Apache ECharts 5 | Lazy-loaded |
| Persistencia | Dexie 4 (IndexedDB) | Schema v2, migraciones automáticas |
| Validación | Zod 3 | |
| Export PDF | jsPDF + jspdf-autotable | Lazy-loaded |
| Export CSV | papaparse 5 | |
| Tests unitarios | Vitest 4 | 336+ tests |
| Tests E2E | Playwright | Con análisis de PDF y píxeles |
| Linting | ESLint 10 (flat config) | `no-restricted-imports` custom |
| Deploy | Cloudflare Pages | Estático, gratis |

---

## Comandos

```bash
# Desarrollo
npm run dev              # Servidor local en localhost:5173 con HMR

# Build y preview
npm run build            # TypeScript check + Vite build → dist/
npm run preview          # Preview del build en localhost:4173

# Testing
npm run test             # Tests unitarios e integración (Vitest)
npx playwright test      # Tests E2E contra localhost:4173 (requiere build previo)
npx playwright test --config=playwright.prod.config.ts  # Smoke test vs producción

# Calidad
npm run lint             # ESLint — 0 errores esperados

# Deploy
CLOUDFLARE_ACCOUNT_ID=<id> npx wrangler pages deploy dist \
  --project-name=process-cost-platform
```

---

## Producción

**URL**: https://process-cost-platform.pages.dev  
**Plataforma**: Cloudflare Pages (estático, sin servidor)

Smoke test post-deploy: `npx playwright test --config=playwright.prod.config.ts`
Genera `tests/e2e/__output__/prod-smoke.pdf` como evidencia del flujo completo.

---

## Documentación adicional

| Archivo | Contenido |
|---|---|
| `ARCHITECTURE.md` | Diseño del sistema, ADRs 1-15, roadmap completo |
| `CHANGELOG.md` | Historial detallado de cambios por versión |
| `TODO.md` | Backlog de features y deuda técnica |
| `METHODOLOGY_AUTOMATED_COST.md` | Guía para calcular el costo automatizado por ejecución |

---

*Los procesos de negocio son activos estratégicos de las empresas y un diferencial competitivo.*