marcos/inq-roi-simulador-web
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
ce2dabfb76ac241e2f699efaefd9e07c102f4c2e
inq-roi-simulador-web/CLAUDE.md

10 KiB
Raw Blame History

CLAUDE.md — Contexto del Proyecto

Este archivo es leído automáticamente por Claude Code en cada sesión. Define el "norte" del proyecto y las reglas no negociables.

Identidad del Proyecto

Nombre de trabajo: Process Cost Platform (nombre comercial por definir)

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.

Estado Actual

  • 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)
  • 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 — Sprint 1

✅ Lo que SÍ entra en Sprint 1

  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 entra en Sprint 1

  • 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. Anotala en TODO.md.

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
Lenguaje TypeScript estricto
Framework React 18 + Vite
Routing TanStack Router
Estado Zustand
Canvas BPMN bpmn-js (Viewer, no Modeler)
UI shadcn/ui sobre Tailwind CSS
Iconos Lucide React
Gráficos Apache ECharts (vía echarts-for-react)
Persistencia IndexedDB vía Dexie
Validación Zod
Export PDF jsPDF + jsPDF-autotable + html2canvas
Export CSV papaparse
Testing Vitest + Playwright
Deploy Cloudflare Pages

No introduzcas librerías fuera de esta lista sin justificación explícita.

Arquitectura de Carpetas

src/
├── main.tsx
├── App.tsx
├── router.tsx
├── domain/           ← lógica de negocio pura, sin React, testeable
│   ├── types.ts
│   ├── 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 (v2 en Sprint 1)
├── features/         ← organizado por feature, no por tipo
│   ├── import/
│   ├── 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 (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.

Principios de Código

  1. TypeScript strict activado. Nada de any salvo en bordes con librerías sin tipos.
  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:
    • Componentes: PascalCase.tsx
    • Hooks: useCamelCase.ts
    • Utilidades: kebab-case.ts
    • 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 (sigue siendo CRÍTICO)

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
  • Densidad de información media-alta (audiencia: consultor profesional)

Definition of Done — Cada Feature

Antes de marcar una tarea como terminada:

  • Funciona en el happy path
  • Maneja el caso de datos vacíos sin crashear
  • 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

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)

Cómo Trabajar Conmigo (el Usuario)

  • Cuando termines una tarea grande, resumí qué cambió y qué falta.
  • Si una decisión no está clara, proponé 2-3 opciones con pros/contras antes de codear.
  • 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 y Equipo

  • Consultor de automatización de procesos basado en Paraguay
  • Construye esto como herramienta consultiva propia + del equipo de InQuality + para vender a colegas LATAM
  • Usa Claude Code Pro como único "equipo de desarrollo"
  • 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
Reference in New Issue View Git Blame Copy Permalink