296 lines
12 KiB
Markdown
296 lines
12 KiB
Markdown
# 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 |