Los archivos de claude code modificados

CLAUDE.md

@@ -9,7 +9,7 @@
 
 **Nombre de trabajo**: Process Cost Platform (nombre comercial por definir)
 
-**Una frase**: Plataforma web para que consultores de procesos transformen un archivo BPMN 2.0 en un reporte visual deslumbrante de costos operativos en minutos.
+**Una frase**: Plataforma web para que consultores de procesos cuantifiquen costos operativos y calculen ROI de automatización a partir de archivos BPMN 2.0.
 
 **Mantra**: *Los procesos de negocio son activos estratégicos de las empresas y un diferencial competitivo.*
 
@@ -17,37 +17,83 @@
 
 ## Estado Actual
 
-- **Fase**: 0 — MVP "Noche Cero"
+- **Fase**: 1 — Sprint 1 (ROI y escenarios de automatización)
+- **Fase anterior completada**: 0 — MVP "Noche Cero" (v0.1.0-mvp, deployado en https://process-cost-platform.pages.dev)
 - **Documento maestro**: `ARCHITECTURE.md` (raíz del repo)
-- **Fecha objetivo MVP**: una noche
-- **Deploy objetivo**: Cloudflare Pages (estático, gratis)
+- **Audiencia primaria del Sprint 1**: equipo de InQuality (consultora de procesos)
+- **Caso de uso primario**: pre-venta de proyectos de automatización con cálculo de ROI
+- **Deploy**: Cloudflare Pages (estático, gratis)
 
 ---
 
-## Reglas No Negociables del MVP
+## Reglas No Negociables — Sprint 1
 
-### ✅ Lo que SÍ hacemos esta noche
+### ✅ Lo que SÍ entra en Sprint 1
 
-1. Importar archivo `.bpmn` por drag & drop
-2. Renderizar el diagrama en read-only con bpmn-js
-3. Editar atributos de actividades (costo, tiempo, recursos asignados)
-4. CRUD de recursos (rol/persona/sistema/equipo/insumo + costo/hora)
-5. Configuración global (moneda, overhead %, nombre proceso, cliente)
-6. Motor de simulación determinístico agregado
-7. Reporte visual con mapa de calor sobre el diagrama
-8. Gráficos: KPIs, top actividades, costo por actividad, composición, costo por recurso
-9. Export a PDF (presentable a cliente) y CSV
-10. Persistencia en IndexedDB (Dexie)
+1. **Volumetría del proceso**: frecuencia anual de ejecución + horizonte de análisis (años)
+2. **Marcado de actividades automatizables** con costos automatizados (tiempo + costo fijo)
+3. **Inversión en automatización** como dato del proceso (un único valor agregado)
+4. **Motor de simulación dual**: corre escenarios "actual" y "automatizado" sobre el mismo BPMN
+5. **Sección de ROI en el reporte**: KPIs grandes, tabla comparativa, gráficos de payback y ahorros
+6. **5 KPIs de ROI**: Ahorro por ejecución, Ahorro anual, Payback (meses), Ahorro acumulado a N años, ROI % anualizado
+7. **Mecanismo de transparencia**: detecta valores cero o inversión cero y los expone en el reporte
+8. **Migración Dexie v1 → v2** con datos existentes preservados
+9. **Export PDF/CSV ampliado** para incluir páginas/datos de ROI
+10. **Documento metodológico anexo** sobre cómo calcular el costo automatizado por ejecución
 
-### ❌ Lo que NO hacemos esta noche
+### ❌ Lo que NO entra en Sprint 1
 
-Login · Multi-tenant · Backend · Colaboración · Edición del BPMN · Versionado · Distribuciones probabilísticas · Riesgos · Gobernanza/RACI · Jerarquía organizacional · IA · Elementos RPA/Agente custom · Tutoriales · Marketplace · i18n · PWA installable · Modo oscuro
+- Múltiples escenarios (más de 2)
+- Escenarios como entidad separada (modelo B) — sigue siendo modelo A: dos pares de campos por actividad
+- VPN, TIR, tasa de descuento (cálculos financieros sofisticados)
+- Captura desglosada del costo de automatización (licencias, desarrollo, infra) — un único campo
+- Análisis de sensibilidad ("¿qué pasa si la frecuencia cae 30%?")
+- Distribuciones probabilísticas
+- Modelar bots como recursos con capacidad
+- Multi-tenant, login, colaboración, versionado, IA, modo oscuro, i18n, PWA
 
-**Si dudás si una feature entra: NO ENTRA.** Defendé el alcance.
+**Si dudás si una feature entra: NO ENTRA.** Defendé el alcance. Anotala en `TODO.md`.
 
 ---
 
-## Stack Obligatorio (MVP)
+## Decisiones Arquitectónicas Adoptadas (Sprint 1)
+
+### Modelo de escenarios: Modelo A (dos campos por actividad)
+
+Cada actividad tiene:
+- `directCostFixed` y `executionTimeMinutes` (escenario actual, ya existían)
+- `automatedCostFixed` y `automatedTimeMinutes` (nuevos, escenario automatizado)
+- `automatable: boolean` (default false)
+
+**NO se modela con dos diagramas distintos.** Un BPMN, dos pares de campos por actividad. El motor recibe un parámetro `scenario: 'actual' | 'automated'` y aplica los campos correspondientes.
+
+Migración a "escenarios como entidad" se evaluará en Sprint 3-4 si InQuality lo demanda.
+
+### Volumetría: multiplicador en el reporte, no en el motor
+
+El motor sigue siendo **determinístico** y calcula "una ejecución". La volumetría (frecuencia anual + horizonte) es un parámetro del proceso que el reporte usa para extrapolar:
+- `costoAnual = costoUnitario × frecuenciaAnual`
+- `costoHorizonte = costoAnual × horizonteAños`
+
+No se introduce VPN ni Monte Carlo en Sprint 1.
+
+### ROI: cálculos nominales simples
+
+- `savingsPerExecution = costActual - costAutomated`
+- `annualSavings = savingsPerExecution × annualFrequency`
+- `paybackMonths = (automationInvestment / annualSavings) × 12`
+- `cumulativeSavingsHorizon = (annualSavings × horizonYears) - automationInvestment`
+- `roiAnnualPercent = (annualSavings / automationInvestment) × 100`
+
+Edge cases manejados explícitamente: inversión cero, ahorro negativo, división por cero.
+
+### Transparencia metodológica
+
+Si se detectan valores cero (costo automatizado en cero, inversión en cero, etc.), el reporte muestra una **sección visible pero discreta** ("Transparencia metodológica") con la lista de valores no informados. **Es feature, no bug**: convierte una posible debilidad en señal de seriedad profesional para el cliente.
+
+---
+
+## Stack Tecnológico (sin cambios respecto al MVP)
 
 | Capa | Tecnología |
 |---|---|
@@ -61,16 +107,16 @@ Login · Multi-tenant · Backend · Colaboración · Edición del BPMN · Versio
 | Gráficos | Apache ECharts (vía echarts-for-react) |
 | Persistencia | IndexedDB vía Dexie |
 | Validación | Zod |
-| Export PDF | jsPDF + html2canvas |
+| Export PDF | jsPDF + jsPDF-autotable + html2canvas |
 | Export CSV | papaparse |
-| Testing | Vitest |
+| Testing | Vitest + Playwright |
 | Deploy | Cloudflare Pages |
 
 **No introduzcas librerías fuera de esta lista sin justificación explícita.**
 
 ---
 
-## Arquitectura de Carpetas (obligatoria)
+## Arquitectura de Carpetas
 
 ```
 src/
@@ -79,22 +125,23 @@ src/
 ├── router.tsx
 ├── domain/           ← lógica de negocio pura, sin React, testeable
 │   ├── types.ts
-│   ├── simulation.ts ← motor de simulación
+│   ├── simulation.ts ← motor de simulación (acepta scenario)
+│   ├── roi.ts        ← NUEVO en Sprint 1: cálculos puros de ROI
 │   ├── bpmn-parser.ts
 │   └── schemas.ts    ← Zod schemas
 ├── store/            ← Zustand stores
-├── persistence/      ← Dexie / IndexedDB
+├── persistence/      ← Dexie / IndexedDB (v2 en Sprint 1)
 ├── features/         ← organizado por feature, no por tipo
 │   ├── import/
-│   ├── workspace/
-│   ├── simulation/
-│   └── report/
+│   ├── workspace/    ← ampliado en Sprint 1 (panel de automatización)
+│   ├── simulation/   ← ampliado (dispara dual scenario)
+│   └── report/       ← ampliado (tab Comparación + ROI)
 ├── components/ui/    ← shadcn copy-pastes
 ├── lib/              ← utilidades transversales (format, colors, pdf, csv)
 └── styles/
 ```
 
-**Reglas de dependencia**:
+**Reglas de dependencia (sin cambios)**:
 - `domain/` NO importa de React, ni de `store/`, ni de `features/`. Es puro.
 - `features/` puede importar de `domain/`, `store/`, `persistence/`, `lib/`, `components/`.
 - `store/` puede importar de `domain/` y `persistence/`. Nada más.
@@ -104,7 +151,7 @@ src/
 ## Principios de Código
 
 1. **TypeScript strict** activado. Nada de `any` salvo en bordes con librerías sin tipos.
-2. **Dominio puro**: el motor de simulación es una función pura testeable sin DOM.
+2. **Dominio puro**: motor y cálculos de ROI son funciones puras testeables sin DOM.
 3. **Componentes tontos, hooks inteligentes**: lógica en custom hooks, JSX limpio.
 4. **Sin lógica de negocio en componentes**.
 5. **Convenciones de naming**:
@@ -114,18 +161,24 @@ src/
    - Tipos: `PascalCase`, interfaces con prefijo `I` PROHIBIDO
 6. **Comentarios en español**, código (variables, funciones) en inglés.
 7. **Errores con mensajes accionables** para el usuario, nunca traces crudos en UI.
+8. **Migraciones de schema**: SIEMPRE incrementar versión en Dexie, escribir función de upgrade y test que valide preservación de datos.
 
 ---
 
-## Diferencial Visual (CRÍTICO)
+## Diferencial Visual (sigue siendo CRÍTICO)
 
-El 60% del valor del MVP está en **el reporte final**. Si el reporte se ve mediocre, el MVP fracasa aunque el resto funcione. Reglas:
+El reporte sigue siendo el corazón. En Sprint 1 se le agregan páginas. Reglas:
 
 - Tipografía: **Inter** para UI, **JetBrains Mono** para números/datos
 - Paleta heatmap: verde `#10b981` → amarillo `#f59e0b` → rojo `#ef4444`
+- Paleta ROI:
+  - Ahorro positivo: verde `#10b981`
+  - Ahorro marginal o neutro: gris `#64748b`
+  - Ahorro negativo o payback fuera de horizonte: rojo `#ef4444`
+  - Advertencias de transparencia: amarillo `#f59e0b` (no rojo: es informativo, no error)
 - Cifras de dinero siempre formateadas con separadores y símbolo de moneda
+- KPIs de ROI **más grandes** que los KPIs del reporte de costos (es la sección que vende)
 - El export PDF debe verse igual o mejor que la pantalla
-- Cada gráfico tiene título, leyenda clara y formato de moneda apropiado
 - Densidad de información media-alta (audiencia: consultor profesional)
 
 ---
@@ -136,20 +189,23 @@ Antes de marcar una tarea como terminada:
 
 - [ ] Funciona en el happy path
 - [ ] Maneja el caso de datos vacíos sin crashear
-- [ ] Persiste en IndexedDB cuando corresponde
+- [ ] Maneja edge cases definidos (división por cero, valores negativos, valores cero)
+- [ ] Persiste en IndexedDB cuando corresponde (con migración si cambió schema)
 - [ ] Tiene estilo consistente con el resto de la app
 - [ ] Si toca dominio: tiene al menos un test en Vitest
+- [ ] Si toca el flujo end-to-end: tiene cobertura en Playwright
 
 ---
 
 ## Comandos del Proyecto
 
 ```bash
-npm run dev        # desarrollo
-npm run build      # producción
-npm run test       # tests con Vitest
-npm run lint       # eslint
-npm run preview    # previsualizar build
+npm run dev              # desarrollo
+npm run build            # producción
+npm run test             # tests unitarios con Vitest
+npm run lint             # eslint
+npm run preview          # previsualizar build de producción
+npx playwright test      # tests E2E (Playwright headless)
 ```
 
 ---
@@ -161,13 +217,18 @@ npm run preview    # previsualizar build
 - Si encontrás que algo del documento de arquitectura está mal o falta, **avisame antes de improvisar**.
 - No agregues features no pedidas. Si algo se te ocurre, anotalo en `TODO.md`.
 - Cuando completes algo, **mostrame los archivos creados/modificados**, no los pegues completos en el chat salvo que te lo pida.
+- **Validá programáticamente** lo que yo no puedo ver visualmente (uso Mac + VS Code + Claude Code sin browser interactivo). Para flujos críticos: Playwright + extracción de datos del PDF/CSV generado.
+- Si un test revela algo raro: **NO racionalices el problema, investigá la causa raíz**. Los tests no mienten.
 
 ---
 
-## Contexto del Fundador
+## Contexto del Fundador y Equipo
 
 - Consultor de automatización de procesos basado en Paraguay
-- Construye esto como herramienta consultiva propia + para vender a colegas LATAM
+- Construye esto como herramienta consultiva propia + del equipo de InQuality + para vender a colegas LATAM
 - Usa Claude Code Pro como único "equipo de desarrollo"
-- Lo va a presentar a clientes reales en días, no meses
-- Valora: claridad, robustez, pulido visual, mantenibilidad
+- Sprint 1 es para uso interno de InQuality (no para mostrar a cliente todavía)
+- Casos de uso confirmados:
+  - Análisis de costos operativos en consultoría de procesos
+  - **Pre-venta de proyectos de automatización con cálculo de ROI** (caso estrella del Sprint 1)
+- Valora: claridad, robustez, pulido visual, mantenibilidad, validación rigurosa