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

8.1 KiB
Raw Blame History

CLAUDE.md — InQ ROI · Contexto de implementación

Leído automáticamente por Claude Code al arrancar desde este directorio. Contiene reglas de código, arquitectura, marca y convenciones de implementación. Para contexto estratégico y de colaboración ver cowork/InQ ROI - Simulador de procesos/CLAUDE.md.

⚠️ Reglas de Marca — NO NEGOCIABLES

Estas reglas aplican a TODO string que aparezca en código, PDFs, CSVs, tests y documentación.

Ortografía de "InQ" — SIEMPRE I-n-Q

✅ InQ          ← correcto
✅ InQuality    ← correcto (nombre completo)
✅ InQ ROI      ← nombre del producto

❌ INQ  ❌ Inq  ❌ inq  ❌ inQ   ← todos son bugs

Paleta protagonista

Primario:  #F59845  (naranja InQ)
Gradiente: #F59845 → #ED3E8F  (naranja → magenta InQ)

El gradiente se usa SOLO en KPI Hero y banners principales. NO usar colores CONCILIA (#572FA2, #CB1889) en este producto.

Logos disponibles en assets/:

  • MARCA FINAL 2023 AREA DE SEGURIDAD 1 COLOR.png — logo horizontal color (uso principal)
  • MARCA FINAL 2023 AREA DE SEGURIDAD 1 BCO.png — logo horizontal blanco (sobre fondos oscuros)
  • MARCA FINAL 2023 AREA DE SEGURIDAD 2 COLOR.png — versión con área de seguridad 2
  • MARCA FINAL 2023 AREA DE SEGURIDAD 2 ISO COLOR LOGO BCO.png — isotipo + logo blanco

Usar el logo PNG en lugar de texto "InQ" / "InQuality" en headers de PDF y en la UI cuando corresponda.

Footer de PDFs

Tagline obligatorio: "Powered by InQuality" — en todos los footers de PDF, siempre.

Identidad del Proyecto

Nombre de trabajo: InQ ROI 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. Deploy: Cloudflare Pages — https://process-cost-platform.pages.dev Estado: Sprint 2 en curso (ver sprints/sprint-2/BRIEF.md)

Stack Tecnológico (sin cambios hasta nuevo aviso)

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 (actualmente v2)
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 y consulta al director.

Arquitectura de Carpetas

src/
├── main.tsx
├── App.tsx
├── router.tsx
├── domain/           ← lógica de negocio pura, sin React, testeable
│   ├── types.ts      ← tipos TypeScript del dominio
│   ├── simulation.ts ← motor de simulación (acepta scenario: 'actual' | 'automated')
│   ├── roi.ts        ← cálculos puros de ROI
│   ├── bpmn-parser.ts
│   └── schemas.ts    ← Zod schemas
├── store/            ← Zustand stores
├── persistence/      ← Dexie / IndexedDB
│   └── db.ts         ← schema + migraciones (versión actual: v2)
├── features/         ← organizado por feature, no por tipo
│   ├── import/
│   ├── workspace/    ← ActivityPanel, ResourcesPanel, BpmnCanvas, WorkspacePage
│   ├── simulation/
│   └── report/       ← ReportPage, ActivitiesTable, CostByResourceChart, etc.
├── components/ui/    ← shadcn copy-pastes
├── lib/              ← utilidades transversales (format, colors, pdf, csv)
│   └── export/       ← pdf-sections.ts, pdf-sections-roi.ts, csv.ts
└── styles/

Reglas de dependencia (no negociables)

  • 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.

Estado del modelo de recursos (pre-Sprint 2)

El modelo de recursos está parcialmente implementado desde el MVP. Lo que existe:

  • Resource en types.ts: { id, processId, name, type, costPerHour }
  • ActivityResourceAssignment embebido en Activity: { resourceId, utilizationPercent: number (0-1) }
  • Tabla resources en Dexie desde v1
  • ResourcesPanel.tsx: CRUD de recursos por proceso
  • ActivityPanel.tsx: asignación con slider de porcentaje
  • Motor de simulación: ya calcula cost = costPerHour × (executionTimeMinutes/60) × utilizationPercent
  • CostByResourceChart.tsx: gráfico en reporte

Sprint 2 mejora este modelo. No construye desde cero. Ver sprints/sprint-2/BRIEF.md para scope exacto.

Principios de Código

  1. TypeScript strict activado. Nada de any salvo en bordes con librerías sin tipos.
  2. Dominio puro: funciones en domain/ son 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

El reporte es el corazón del producto. Reglas:

  • Tipografía: Inter para UI, JetBrains Mono para números/datos
  • Paleta heatmap: verde #10b981 → amarillo #f59e0b → rojo #ef4444 (saturados, calibrados en E2E)
  • Paleta ROI:
    • Ahorro positivo: verde #10b981
    • Ahorro marginal: gris #64748b
    • Ahorro negativo: rojo #ef4444
    • Advertencias de transparencia: amarillo #f59e0b
  • Cifras de dinero: siempre con separadores y símbolo de moneda
  • KPIs de ROI más grandes que KPIs de costos
  • Export PDF igual o mejor que pantalla
  • Densidad de información media-alta (audiencia: consultor profesional)

Definition of Done — Cada Feature

  • Funciona en happy path
  • Maneja datos vacíos sin crashear
  • Maneja edge cases (división por cero, valores negativos, cero)
  • Persiste en IndexedDB cuando corresponde (con migración si cambió schema)
  • Estilo consistente con el resto de la app
  • Si toca dominio: al menos un test en Vitest
  • Si toca flujo end-to-end: 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)

Verificación final antes de entregar artefactos

Antes de presentar cualquier PDF o pantalla:

  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
  4. La marca "InQ" se escribe siempre I-n-Q

Política de iniciativa proactiva

Antes de aplicar un cambio fuera del scope del prompt actual, evaluar en orden:

  1. ¿Resuelve un ítem listado en TECH_DEBT.md, BACKLOG.md o archivos de planificación? → Nivel 3 (consultar antes)
  2. ¿Choca con restricción explícita del prompt ("NO entra", "NO tocar")? → Nivel 3
  3. ¿Modifica paginación, layout, estructura de salida, o contenido visible? → Nivel 2 mínimo (ejecutar y reportar)
  4. ¿Afecta marca, identidad, dependencias o configuración? → Nivel 3
  5. Si nada aplica → Nivel 1 (ejecutar libremente)

Argumentos NO válidos para evitar consulta:

  • "Es mejora de legibilidad"
  • "Es consistencia con etapa anterior"
  • "Es trivial de revertir"
  • "Resuelve un bug menor" (si está en TECH_DEBT.md, es Nivel 3)

Ver methodology/PATTERNS.md C.6 y methodology/ANTI_PATTERNS.md AP.8.

Reference in New Issue View Git Blame Copy Permalink