inq-roi-simulador-web/CLAUDE.md

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 transformen un archivo BPMN 2.0 en un reporte visual deslumbrante de costos operativos en minutos.

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

---

Estado Actual

• Fase: 0 — MVP "Noche Cero"
• Documento maestro: ARCHITECTURE.md (raíz del repo)
• Fecha objetivo MVP: una noche
• Deploy objetivo: Cloudflare Pages (estático, gratis)

---

Reglas No Negociables del MVP

✅ Lo que SÍ hacemos esta noche

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)

❌ Lo que NO hacemos esta noche

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

Si dudás si una feature entra: NO ENTRA. Defendé el alcance.

---

Stack Obligatorio (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 + html2canvas
Export CSV	papaparse
Testing	Vitest
Deploy	Cloudflare Pages

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

---

Arquitectura de Carpetas (obligatoria)

src/
├── main.tsx
├── App.tsx
├── router.tsx
├── domain/           ← lógica de negocio pura, sin React, testeable
│   ├── types.ts
│   ├── simulation.ts ← motor de simulación
│   ├── bpmn-parser.ts
│   └── schemas.ts    ← Zod schemas
├── store/            ← Zustand stores
├── persistence/      ← Dexie / IndexedDB
├── features/         ← organizado por feature, no por tipo
│   ├── import/
│   ├── workspace/
│   ├── simulation/
│   └── report/
├── components/ui/    ← shadcn copy-pastes
├── lib/              ← utilidades transversales (format, colors, pdf, csv)
└── styles/

Reglas de dependencia:

• 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: el motor de simulación es una función pura testeable 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.

---

Diferencial Visual (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:

• Tipografía: Inter para UI, JetBrains Mono para números/datos
• Paleta heatmap: verde #10b981 → amarillo #f59e0b → rojo #ef4444
• Cifras de dinero siempre formateadas con separadores y símbolo de moneda
• 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)

---

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
• Persiste en IndexedDB cuando corresponde
• Tiene estilo consistente con el resto de la app
• Si toca dominio: tiene al menos un test en Vitest

---

Comandos del Proyecto

npm run dev        # desarrollo
npm run build      # producción
npm run test       # tests con Vitest
npm run lint       # eslint
npm run preview    # previsualizar build

---

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.

---

Contexto del Fundador

• Consultor de automatización de procesos basado en Paraguay
• Construye esto como herramienta consultiva propia + 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