Antes de la última revisión de etapa 4. Sprint 1. Previo al ajuste de look n feel de app, reportes, nombre y colores.

2026-05-15 22:14:53 -03:00
parent b6f31f4371
commit 8b71c6ee13
54 changed files with 6497 additions and 261 deletions
--- a/README.md
+++ b/README.md
@@ -1,46 +1,223 @@
-# Process Cost Platform — MVP Fase 0
+# Process Cost Platform

-Plataforma web que transforma un archivo BPMN 2.0 en un reporte visual
-de costos operativos, listo para presentar a clientes en minutos.
-100% en el navegador — sin backend, sin registro, datos guardados localmente.
+> 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.

-## Cómo usarlo
+**Hecho desde Paraguay 🇵🇾 · Herramienta interna de InQuality · Sprint 1 en desarrollo activo**

-1. **Importá** tu archivo `.bpmn` arrastrándolo a la pantalla principal,
-   o cargá uno de los tres procesos de ejemplo incluidos.
-2. **Configurá** los costos fijos y tiempos de cada actividad en el workspace.
-   Ajustá las probabilidades de los gateways XOR si las hay.
-3. **Simulá** para generar el análisis agregado de costos.
-4. **Exportá** el reporte en PDF (presentación para el cliente) o CSV (datos).
+---

-## Stack
+## ¿Qué hace esto?

-| Capa | Tecnología |
-|---|---|
-| Framework | React 19 + Vite 8 |
-| Routing | TanStack Router |
-| Estado | Zustand 5 |
-| Canvas BPMN | bpmn-js 18 (Viewer) |
-| UI | shadcn/ui + Tailwind CSS |
-| Gráficos | Apache ECharts |
-| Persistencia | IndexedDB vía Dexie 4 |
-| Export PDF | jsPDF + jspdf-autotable |
-| Export CSV | papaparse |
-| Testing | Vitest + Playwright |
-| Deploy | Cloudflare Pages |
+Un consultor de procesos recibe un diagrama BPMN del cliente. Con esta plataforma puede:

-## Scripts
+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
-npm run dev        # Servidor de desarrollo (localhost:5173)
-npm run build      # Build de producción en dist/
-npm run preview    # Preview del build en localhost:4173
-npm run test       # Tests unitarios con Vitest
-npx playwright test  # Tests E2E con Playwright
+git clone <repo>
+cd simulador-web
+npm install --legacy-peer-deps
+npm run dev
 ```

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

-**MVP Fase 0** — funcionalidad completa para uso consultivo básico.
-Las features adicionales (multi-tenant, IA, versionado, etc.)
-están documentadas en `TODO.md` para la Fase 1.
+> **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.*