# 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

## Verificación final antes de present_files

Antes de presentar cualquier PDF al usuario, verificá que:
1. El header/footer dice "InQ ROI" (no "Process Cost Platform" ni otro)
2. El footer incluye "Powered by InQuality"
3. No hay caracteres rotos (símbolos sin renderizar)
4. La marca "InQ" se escribe siempre I-n-Q

---

## Política de iniciativa proactiva

Cuando detectés una oportunidad de mejora fuera del scope del prompt actual:

- Cambios triviales (variables internas, reordenar imports): ejecutar
- Cambios visibles pero reversibles (wording, spacing, tooltips):
  ejecutar y reportar explícitamente al final
- Cambios de marca, arquitectura o datos (paleta, dependencias,
  estructura, features nuevas): CONSULTAR ANTES DE PROCEDER

Estructura de propuesta cuando hay un cambio Nivel 3:

  PROPUESTA DE CAMBIO NIVEL 3 — requiere aprobación antes de implementar
  Cambio sugerido: [descripción]
  Justificación: [por qué lo considero valioso]
  Impacto: [qué afecta]
  Alternativa si se rechaza: [qué hacer en lugar]

Ver methodology/PRINCIPLES.md sección "Política de iniciativa agéntica" para detalle completo.

### Criterios refinados (post-Sprint 1.5)

Antes de aplicar un cambio fuera del scope explícito del prompt actual,
evaluá en este orden:

1. ¿El cambio resuelve un ítem listado en TECH_DEBT.md, BACKLOG.md u 
   archivos de planificación? → Nivel 3 (consultar), sin importar el 
   tamaño técnico
2. ¿Choca con restricción explícita del prompt ("NO entra", "NO tocar")? 
   → Nivel 3 (consultar)
3. ¿Modifica paginación, layout, estructura de salida, o contenido 
   visible? → Nivel 2 mínimo (reportar)
4. ¿Afecta marca, identidad, dependencias o configuración? → Nivel 3
5. Si nada aplica → Nivel 1

Argumentos NO válidos para evitar consulta:
- "Es mejora de legibilidad"
- "Es consistencia con etapa anterior" (verificar si esa etapa fue 
  autorizada)
- "Es trivial de revertir" (reversibilidad NO es criterio de clasificación)
- "Resuelve un bug menor" (si el bug está en TECH_DEBT.md, es Nivel 3)

Referencia completa: methodology/PATTERNS.md C.6 refinado + 
methodology/ANTI_PATTERNS.md AP.8.