# 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. --- ## ⚠️ Reglas de Marca — NO NEGOCIABLES (Sprint 1.5+) Estas reglas aplican a TODO string que aparezca en código, PDFs, CSVs, tests y documentación. ### 1. Ortografía de "InQ" — SIEMPRE I-n-Q ``` ✅ InQ ← correcto ✅ InQuality ← correcto (nombre completo) ✅ InQ ROI ← nombre del producto ❌ INQ ← bug ❌ Inq ← bug ❌ inq ← bug ❌ inQ ← bug ``` Cualquier desviación es un bug que debe corregirse antes de hacer commit. ### 2. Nombre del producto `InQ ROI` — nombre de trabajo para Sprint 1.5. Se reemplazará en Sprint 3-4. No debatir el nombre ahora. ### 3. Color protagonista ``` Primario: #F59845 (naranja InQ) Gradiente: #F59845 → #ED3E8F (naranja → magenta InQ) ``` El gradiente se usa SOLO en KPI Hero y banners principales. **NO usar morado de CONCILIA** (`#572FA2`, `#CB1889`) en este producto. ### 4. Footer de PDFs Tagline obligatorio: `"Powered by InQuality"` — en todos los footers de PDF, siempre. ### 5. Rol del consultor Si aparece un nombre de consultor en algún campo, es como "consultor responsable", no como "creador" ni "founder" del producto. --- ## 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 ```bash 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 --- ## Reglas de marca NO NEGOCIABLES - "InQ" siempre se escribe I-n-Q (mayúscula-minúscula-mayúscula) - Color protagonista: naranja #F59845 - Gradiente identidad: #F59845 → #ED3E8F - NO usar morado CONCILIA (#572FA2, #CB1889) - Footer obligatorio: "Powered by InQuality" - No promover a Marcos como creador