diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index a77a502..35fab7e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -5,11 +5,12 @@ | Atributo | Valor | |---|---| -| Versión del documento | 0.1.0 | +| Versión del documento | 0.2.0 | | Fecha | Mayo 2026 | -| Estado | Draft — Fase 0 (MVP "Noche Cero") en construcción | +| Estado | Fase 0 completada · Sprint 1 (ROI) en construcción | | Autor | Equipo fundador + Claude (arquitectura) | -| Alcance | MVP de esta noche + Norte V1.0 (12–18 meses) | +| Alcance | MVP completado + Sprint 1 + Norte V1.0 (12–18 meses) | +| Deploy actual | https://process-cost-platform.pages.dev (v0.1.0-mvp) | --- @@ -18,14 +19,15 @@ 1. [Contexto y Propuesta de Valor](#1-contexto-y-propuesta-de-valor) 2. [Glosario y Convenciones](#2-glosario-y-convenciones) 3. [Norte Estratégico — Visión V1.0](#3-norte-estratégico--visión-v10) -4. [Fase 0 — MVP "Noche Cero"](#4-fase-0--mvp-noche-cero) -5. [Roadmap de Evolución](#5-roadmap-de-evolución) -6. [Arquitectura Técnica](#6-arquitectura-técnica) -7. [Modelo de Dominio](#7-modelo-de-dominio) -8. [Decisiones Arquitectónicas (ADRs)](#8-decisiones-arquitectónicas-adrs) -9. [Atributos de Calidad](#9-atributos-de-calidad) -10. [Riesgos y Mitigaciones](#10-riesgos-y-mitigaciones) -11. [Anexos](#11-anexos) +4. [Fase 0 — MVP "Noche Cero" (COMPLETADO)](#4-fase-0--mvp-noche-cero) +5. [Fase 1 — Sprint 1: ROI y Escenarios de Automatización](#5-fase-1--sprint-1-roi-y-escenarios-de-automatización) +6. [Roadmap de Evolución](#6-roadmap-de-evolución) +7. [Arquitectura Técnica](#7-arquitectura-técnica) +8. [Modelo de Dominio](#8-modelo-de-dominio) +9. [Decisiones Arquitectónicas (ADRs)](#9-decisiones-arquitectónicas-adrs) +10. [Atributos de Calidad](#10-atributos-de-calidad) +11. [Riesgos y Mitigaciones](#11-riesgos-y-mitigaciones) +12. [Anexos](#12-anexos) --- @@ -55,12 +57,20 @@ Las consultoras, gerentes de operaciones y profesionales de eficiencia operativa ### 1.4 Audiencia objetivo -**MVP (Fase 0)**: el propio fundador como consultor de automatización de procesos. +**MVP (Fase 0 - COMPLETADO)**: el propio fundador como consultor de automatización de procesos. + +**Sprint 1 (en curso)**: el **equipo de InQuality** como herramienta interna de consultoría y **pre-venta de proyectos de automatización con cálculo de ROI**. **V1.0**: consultores independientes y boutique de procesos, gerentes de operaciones de pymes LATAM, equipos de Project/Process Office. **V2+**: estudiantes y entusiastas de eficiencia operativa (tier educativo gratuito). +### 1.4.1 Casos de uso confirmados (Sprint 1) + +1. **Análisis de costos operativos**: el consultor de InQuality releva el proceso del cliente, lo modela en BPMN, configura costos/tiempos/recursos y entrega un reporte cuantitativo del costo operativo. + +2. **Pre-venta de automatización con ROI**: el consultor identifica actividades automatizables, define costos automatizados estimados y el costo de inversión del proyecto. El sistema calcula payback, ahorro anual y ROI %, generando un reporte ejecutivo que sirve como propuesta comercial cuantificada. + ### 1.5 Lo que NO somos - ❌ NO somos un BPMS (motor de ejecución de procesos). @@ -164,9 +174,11 @@ Las consultoras, gerentes de operaciones y profesionales de eficiencia operativa --- -## 4. Fase 0 — MVP "Noche Cero" +## 4. Fase 0 — MVP "Noche Cero" ✅ COMPLETADA -### 4.1 Hipótesis a validar +> **Estado**: ✅ Entregada el 13 de mayo de 2026. Tag `v0.1.0-mvp`. Deployada en https://process-cost-platform.pages.dev. **268 tests unit/integration + 5 E2E + 4/4 validación con gradiente real**. Bundle inicial 59.75 KB gzip. 0 vulnerabilidades. + +### 4.1 Hipótesis validada > Un consultor de procesos puede transformar un archivo `.bpmn` en un reporte visualmente deslumbrante de costos operativos en menos de 15 minutos, y usarlo al día siguiente en una reunión real con un cliente. @@ -264,43 +276,193 @@ Las consultoras, gerentes de operaciones y profesionales de eficiencia operativa --- -## 5. Roadmap de Evolución +## 5. Fase 1 — Sprint 1: ROI y Escenarios de Automatización + +> **Estado**: en construcción. +> **Audiencia primaria**: equipo de InQuality (consultora de procesos). +> **Caso de uso estrella**: pre-venta de proyectos de automatización con ROI cuantificado. + +### 5.1 Hipótesis a validar + +> Un consultor de InQuality puede modelar un proceso, identificar las actividades automatizables, configurar costos del escenario actual vs automatizado, y obtener en minutos un reporte ejecutivo de ROI (payback, ahorro anual, ROI %) que sirve como propuesta comercial cuantificada para vender un proyecto de automatización. + +### 5.2 Alcance del Sprint 1 + +| # | Capacidad | Detalle | +|---|---|---| +| S1.1 | **Volumetría del proceso** | Frecuencia anual de ejecución + horizonte de análisis (años) configurables por proceso | +| S1.2 | **Marcado de actividades automatizables** | Toggle por actividad + campos de costo y tiempo automatizados | +| S1.3 | **Inversión en automatización** | Campo único agregado a nivel proceso (sin desglose) | +| S1.4 | **Motor dual de simulación** | Mismo motor recibe `scenario: 'actual' \| 'automated'` y aplica los campos correspondientes | +| S1.5 | **Sección de ROI en reporte** | Tabs en el reporte: Actual / Automatizado / Comparación + ROI | +| S1.6 | **5 KPIs de ROI** | Ahorro por ejecución · Ahorro anual · Payback (meses) · Ahorro acumulado a N años · ROI % anualizado | +| S1.7 | **Tabla comparativa** | Actividad por actividad: costos actual vs automatizado, ahorro $ y % | +| S1.8 | **Gráficos de ROI** | Ahorro acumulado en el tiempo + Top 5 actividades con mayor ahorro | +| S1.9 | **Mecanismo de transparencia** | Detecta valores cero/inversión cero y los expone en sección visible pero discreta | +| S1.10 | **Migración Dexie v1 → v2** | Preserva datos existentes, agrega los nuevos campos con defaults | +| S1.11 | **Export PDF/CSV ampliado** | El PDF incluye páginas de ROI; el CSV de ROI exporta comparación completa | +| S1.12 | **Documento metodológico** | Anexo en el repo: cómo calcular correctamente el costo automatizado por ejecución | + +### 5.3 Decisiones arquitectónicas del Sprint 1 + +#### Modelo de escenarios — Modelo A (dos campos por actividad) + +`Activity` gana 3 campos: +- `automatable: boolean` (default false) +- `automatedCostFixed: number` (default 0) +- `automatedTimeMinutes: number` (default 0) + +`Process` gana 3 campos: +- `annualFrequency: number` (default 1000) +- `analysisHorizonYears: number` (default 3) +- `automationInvestment: number` (default 0) + +**Justificación de Modelo A**: +- Trazabilidad actividad-por-actividad sin sincronización entre diagramas +- Un solo BPMN simplifica el flujo del consultor +- Migración a Modelo B (escenarios como entidad) queda pendiente para Sprint 3-4 si InQuality lo demanda + +#### Volumetría — Multiplicador en el reporte + +El motor sigue siendo determinístico ("costo de una ejecución"). La volumetría se aplica en el reporte: +``` +costoAnual = costoUnitario × annualFrequency +costoHorizonte = costoAnual × analysisHorizonYears +``` + +No se introduce VPN, TIR ni Monte Carlo en este sprint. **Razón estratégica**: el cliente promedio de InQuality entiende payback nominal; el VPN abre discusiones sobre la tasa que distraen. + +#### Fórmulas de ROI (en `domain/roi.ts`, función pura testeable) + +```typescript +savingsPerExecution = costPerExecutionActual - costPerExecutionAutomated +savingsPerExecutionPercent = (savingsPerExecution / costPerExecutionActual) * 100 +annualSavings = savingsPerExecution × annualFrequency +paybackMonths = (automationInvestment / annualSavings) × 12 +paybackYears = paybackMonths / 12 +cumulativeSavingsHorizon = (annualSavings × horizonYears) - automationInvestment +breaksEvenInHorizon = paybackYears <= horizonYears +roiAnnualPercent = (annualSavings / automationInvestment) * 100 +``` + +**Edge cases manejados explícitamente**: +- `annualSavings <= 0`: `paybackMonths = Infinity`, `breaksEvenInHorizon = false` +- `automationInvestment === 0 && annualSavings > 0`: `paybackMonths = 0`, `roiAnnualPercent = Infinity` (display "N/A" o "∞") +- `costPerExecutionActual === 0`: `savingsPerExecutionPercent = 0` (evitar div/0) + +#### Transparencia metodológica + +Si el reporte detecta: +- Actividades marcadas como automatizables pero con `automatedCostFixed = 0` Y `automatedTimeMinutes = 0` +- `automationInvestment = 0` con payback < 1 mes +- Otros valores sospechosos + +Muestra una sección **"Transparencia metodológica"** con: +- Lista de valores no informados +- Texto introductorio explicando el motivo del listado +- Fondo gris claro, no rojo/alarmante +- Aparece en pantalla y en PDF + +**Filosofía**: convierte una posible debilidad en señal de seriedad profesional. El cliente final entiende que el consultor fue transparente sobre los supuestos. + +### 5.4 Lo que NO entra en el Sprint 1 + +❌ Múltiples escenarios (más de 2) — viene en Sprint 3-4 si se demanda +❌ Escenarios como entidad separada (Modelo B) +❌ VPN, TIR, tasa de descuento +❌ Desglose de la inversión (licencias, dev, infra) — un único campo por ahora +❌ Análisis de sensibilidad +❌ Distribuciones probabilísticas +❌ Bots como recursos con capacidad finita +❌ Multi-tenant, login, colaboración, versionado, IA, modo oscuro, i18n, PWA + +### 5.5 Definition of Done — Sprint 1 + +- [ ] Migración Dexie v1 → v2 con preservación de datos existentes +- [ ] Workspace permite marcar actividades como automatizables y configurar costos automatizados +- [ ] Workspace permite configurar volumetría e inversión a nivel proceso +- [ ] Motor de simulación acepta `scenario` y devuelve resultados correctos para ambos casos +- [ ] Reporte tiene 3 tabs (Actual / Automatizado / Comparación + ROI) +- [ ] Sección "Comparación + ROI" muestra 5 KPIs grandes correctamente formateados +- [ ] Tabla comparativa funcional con ordenamiento +- [ ] Gráfico de ahorro acumulado con marcador de payback +- [ ] Gráfico Top 5 actividades con mayor ahorro +- [ ] Sección "Transparencia metodológica" aparece cuando corresponde +- [ ] Cálculos de `domain/roi.ts` cubiertos por tests (≥ 10 casos incluyendo edge cases) +- [ ] Test E2E del flujo completo de ROI con Playwright +- [ ] PDF de ROI incluye las páginas adicionales con KPIs y gráficos +- [ ] CSV de ROI exporta comparación completa +- [ ] Documento `METHODOLOGY_AUTOMATED_COST.md` en raíz del repo +- [ ] Bundle no crece más de 20 KB gzip respecto al MVP +- [ ] Todos los tests previos (268 unit + 5 E2E) siguen verdes +- [ ] Deploy a producción exitoso +- [ ] Smoke test post-deploy verde + +--- + +## 6. Roadmap de Evolución ``` -┌────────────┬──────────────────────────────────────────────────────┐ -│ FASE │ CAPACIDADES │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 0 │ MVP client-side: importar, configurar, simular, │ -│ (1 noche) │ reportear, exportar PDF/CSV │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 1 │ + Backend mínimo + Auth + Persistencia en la nube │ -│ (1-2 sem) │ + i18n (es/en/pt-BR) + PWA installable │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 2 │ + Editor BPMN (no solo lectura) + Validador │ -│ (1 mes) │ + Glosario integrado + Recursos avanzados │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 3 │ + Estructura organizacional + Multi-tenant │ -│ (1 mes) │ + RBAC + Versionado lineal │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 4 │ + Colaboración en tiempo real (Yjs/CRDT) │ -│ (1-2 mes) │ + Presencia + Comentarios │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 5 │ + Distribuciones probabilísticas + Riesgos │ -│ (1 mes) │ + Costeo ABC completo + Gobernanza RACI │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 6 │ + IA: detección de cuellos de botella │ -│ (1-2 mes) │ + Elementos RPA/Agente IA en paleta │ -├────────────┼──────────────────────────────────────────────────────┤ -│ Fase 7 │ + Marketplace comunitario de plantillas │ -│ (continuo) │ + Tutoriales interactivos + Modo educativo │ -└────────────┴──────────────────────────────────────────────────────┘ +┌──────────────┬──────────────────────────────────────────────────────┐ +│ FASE │ CAPACIDADES │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ Fase 0 ✅ │ MVP client-side: importar, configurar, simular, │ +│ (completa) │ reportear, exportar PDF/CSV. v0.1.0-mvp en prod. │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ Sprint 1 🔄 │ ROI + escenarios de automatización: │ +│ (en curso) │ · Volumetría del proceso │ +│ │ · Marcado de actividades automatizables │ +│ │ · Inversión de automatización │ +│ │ · Motor dual: actual vs automatizado │ +│ │ · 5 KPIs de ROI + tabla comparativa + gráficos │ +│ │ · Transparencia metodológica │ +│ │ · Migración Dexie v1 → v2 │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ Sprint 2 │ Productividad de carga: │ +│ │ · Grilla de edición masiva (TanStack Table) │ +│ │ · Pegado desde Excel │ +│ │ · Recursos con costo/hora + asignación múltiple │ +│ │ · Cálculo de costo esperado en vivo │ +│ │ · Edición inline de nombre proceso/cliente │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ Sprint 3-4 │ Multi-escenario y reportes ejecutivos: │ +│ │ · Escenarios como entidad (modelo B) si demandado │ +│ │ · Reporte ejecutivo (PDF 1-2 páginas) separado │ +│ │ · Branding InQuality │ +│ │ · Export Excel multi-hoja │ +│ │ · Comparación de simulaciones (historial) │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ Fase 2 │ Backend + colaboración básica: │ +│ (1-2 meses) │ · Backend NestJS + Postgres + Auth │ +│ │ · Multi-tenant + RBAC │ +│ │ · Versionado lineal │ +│ │ · Editor BPMN (no solo lectura) │ +│ │ · Validador + Glosario │ +│ │ · i18n (es/en/pt-BR) │ +│ │ · PWA installable │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ Fase 3 │ Colaboración avanzada y modelado fino: │ +│ (1-2 meses) │ · Colaboración en tiempo real (Yjs/CRDT) │ +│ │ · Presencia + Comentarios │ +│ │ · Distribuciones probabilísticas │ +│ │ · Riesgos │ +│ │ · Costeo ABC completo │ +│ │ · Gobernanza RACI │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ Fase 4 │ Inteligencia y comunidad: │ +│ (1-2 meses) │ · IA: detección de cuellos de botella │ +│ │ · Elementos RPA/Agente IA en paleta │ +│ │ · Marketplace comunitario de plantillas │ +│ │ · Tutoriales interactivos │ +│ │ · Modo educativo │ +└──────────────┴──────────────────────────────────────────────────────┘ ``` --- -## 6. Arquitectura Técnica +## 7. Arquitectura Técnica -### 6.1 Vista de alto nivel — MVP (Fase 0) +### 7.1 Vista de alto nivel — MVP (Fase 0) ``` ┌─────────────────────────────────────────────────────────────┐ @@ -340,7 +502,7 @@ Las consultoras, gerentes de operaciones y profesionales de eficiencia operativa (estático, gratis, global) ``` -### 6.2 Vista de alto nivel — V1.0 +### 7.2 Vista de alto nivel — V1.0 ``` ┌──────────────────┐ ┌──────────────────────────────┐ @@ -381,7 +543,7 @@ Las consultoras, gerentes de operaciones y profesionales de eficiencia operativa vía Docker Compose ``` -### 6.3 Stack tecnológico +### 7.3 Stack tecnológico #### 6.3.1 Stack MVP (Fase 0) @@ -423,7 +585,7 @@ Las consultoras, gerentes de operaciones y profesionales de eficiencia operativa | i18n | i18next + react-i18next | Estándar de facto | | E2E testing | Playwright | Estándar moderno | -### 6.4 Arquitectura de carpetas (MVP) +### 7.4 Arquitectura de carpetas (MVP) ``` process-cost-platform/ @@ -496,7 +658,7 @@ process-cost-platform/ └── e2e/ ← post-MVP ``` -### 6.5 Modelo conceptual del motor de simulación (MVP) +### 7.5 Modelo conceptual del motor de simulación (MVP + Sprint 1) El motor de simulación del MVP es **determinístico y agregado**. NO es discrete event simulation. Su contrato: @@ -556,7 +718,7 @@ interface SimulationResult { 5. Costo indirecto = `costoDirectoTotal × overheadPercentage`. 6. Agregar totales y rankings. -### 6.6 Integración bpmn-js + heatmap +### 7.6 Integración bpmn-js + heatmap `bpmn-js` expone: - Un `viewer` (read-only) ideal para MVP. @@ -571,7 +733,7 @@ El heatmap se implementa así: 3. Registrar handler `element.click` para drill-down. 4. Mostrar tooltip con detalle al hover. -### 6.7 Deployment del MVP +### 7.7 Deployment **Esta noche**: 1. `npm run build` → genera `dist/` estático. @@ -582,9 +744,9 @@ El heatmap se implementa así: --- -## 7. Modelo de Dominio +## 8. Modelo de Dominio -### 7.1 Entidades núcleo (MVP) +### 8.1 Entidades núcleo (estado al Sprint 1) **Distinción fundamental de capas:** - `ProcessGraph` (en memoria, reconstruido del XML cada vez): TODOS los nodos del diagrama incluidos gateways, eventos, flujos. Vive solo en el parser/motor, no se persiste. @@ -592,6 +754,8 @@ El heatmap se implementa así: - `GatewayConfig` (persistido en IndexedDB): probabilidades por flujo saliente de gateways divergentes (XOR/OR). Los gateways convergentes (merge) no tienen config — el motor suma probabilidades entrantes. - El heatmap **solo colorea nodos con Activity**. Los gateways conservan estilo BPMN neutro. +**Campos añadidos en Sprint 1** marcados con 🆕. + ``` ┌─────────────────────────────────────────────────────────────┐ │ Process │ @@ -602,6 +766,9 @@ El heatmap se implementa así: │ + bpmnXml: string (raw XML) │ │ + currency: string (ISO 4217) │ │ + overheadPercentage: number (0..1) │ +│ + annualFrequency: number 🆕 default 1000 │ +│ + analysisHorizonYears: number 🆕 default 3 │ +│ + automationInvestment: number 🆕 default 0 │ │ + createdAt, updatedAt │ └─────────────────────────────────────────────────────────────┘ │ 1 │ 1 @@ -622,8 +789,13 @@ El heatmap se implementa así: │ number │ │ probability: number │ │ + executionTimeMinutes: │ │ }> │ │ number │ │ (paralelo: todas 1.0, │ -└─────────────────────────┘ │ exclusivo: suma = 1.0) │ - │ N └──────────────────────────────┘ +│ + automatable: boolean │🆕 │ exclusivo: suma = 1.0) │ +│ + automatedCostFixed: │🆕 └──────────────────────────────┘ +│ number │ +│ + automatedTimeMinutes: │🆕 +│ number │ +└─────────────────────────┘ + │ N │ │ M ┌─────────────────────────────────────────────────────────────┐ @@ -657,13 +829,13 @@ El heatmap se implementa así: └─────────────────────────────────────────────────────────────┘ ``` -### 7.2 Modelo extendido (V1.0) +### 8.2 Modelo extendido (V1.0) Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `ProcessOwnership` (RACI), `Risk`, `RiskProcessLink`, `ProcessVersion`, `Comment`, `Notification`, `Template`. --- -## 8. Decisiones Arquitectónicas (ADRs) +## 9. Decisiones Arquitectónicas (ADRs) ### ADR-001 — MVP client-side sin backend - **Contexto**: tiempo de entrega = una noche, presupuesto cero. @@ -716,11 +888,48 @@ Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `P - **Decisión**: Cloudflare Pages mientras sea estático; migración a VPS al introducir backend. - **Justificación**: $0 al inicio, latencia global, sin operación. Migrar cuando haya backend. +### ADR-012 — Escenarios como dos pares de campos por actividad (Modelo A), no entidad separada +- **Contexto Sprint 1**: necesidad de modelar costo "actual" vs "automatizado" por actividad. +- **Decisión**: Modelo A — agregar `automatable`, `automatedCostFixed`, `automatedTimeMinutes` a `Activity`. El motor recibe un parámetro `scenario` y elige qué campos usar. +- **Alternativa descartada**: Modelo B (entidad `Scenario` con N configuraciones independientes) — más complejo, no necesario hasta que haya demanda real de >2 escenarios. +- **Justificación**: + - Trazabilidad actividad-a-actividad para la tabla comparativa (pieza más persuasiva del reporte). + - Un solo diagrama → consultor no mantiene 2 BPMNs sincronizados. + - Migración A→B es directa cuando llegue el momento. +- **Cuándo revisar**: Sprint 3-4 si InQuality necesita >2 escenarios o flujos distintos post-automatización. + +### ADR-013 — Volumetría aplicada en el reporte, no en el motor +- **Contexto Sprint 1**: necesidad de anualizar costos para calcular ROI. +- **Decisión**: el motor sigue siendo determinístico ("costo de una ejecución"). La volumetría (frecuencia anual + horizonte) es metadata del proceso y se aplica como multiplicador en la capa de reporte. +- **Alternativa descartada**: correr Monte Carlo o múltiples instancias en el motor. +- **Justificación**: + - El motor es determinístico → correrlo N veces da el mismo resultado × N (perder ciclos). + - Mantiene separación de concerns: motor calcula costo unitario, reporte hace análisis temporal. + - Cuando lleguen distribuciones probabilísticas (Fase 3), ahí tiene sentido Monte Carlo. + +### ADR-014 — ROI nominal sin VPN ni tasa de descuento en Sprint 1 +- **Contexto Sprint 1**: cálculo de payback y ahorro acumulado para pre-venta. +- **Decisión**: usar fórmulas nominales simples (payback = inversión / ahorro anual × 12, acumulado = ahorro × años - inversión). NO incluir VPN, TIR ni tasa de descuento. +- **Justificación**: + - El cliente promedio de InQuality entiende payback nominal. + - VPN abre discusiones sobre la tasa que distraen del mensaje principal. + - Si en el futuro un cliente sofisticado lo pide, se agrega como opción. +- **Cuándo revisar**: cuando un cliente concreto pida VPN/TIR. + +### ADR-015 — Transparencia metodológica como feature, no bug +- **Contexto Sprint 1**: riesgo de que consultores carguen valores incompletos (costos automatizados en 0, inversión en 0) generando ROIs irreales. +- **Decisión**: detectar estos casos y exponerlos en sección visible pero discreta del reporte ("Transparencia metodológica"). +- **Justificación**: + - Anticipar limitaciones es señal de seriedad profesional. + - El cliente final confía más en consultores transparentes sobre supuestos que en cifras "perfectas". + - Protege la credibilidad de InQuality y la herramienta. +- **Mecanismo**: banner amarillo informativo (no rojo de error) + lista de valores no informados. + --- -## 9. Atributos de Calidad +## 10. Atributos de Calidad -### 9.1 Performance +### 10.1 Performance | Métrica | MVP | V1.0 | |---|---|---| @@ -730,7 +939,7 @@ Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `P | Render mapa de calor | < 200ms | < 200ms | | Export PDF | < 5s | < 5s | -### 9.2 Mantenibilidad +### 10.2 Mantenibilidad - **TypeScript strict** activado. - **ESLint + Prettier** configurados. @@ -738,7 +947,7 @@ Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `P - **Dominio puro separado** de UI (en `/src/domain`) — testeable sin React. - **Sin lógica de negocio en componentes** — siempre en hooks o domain. -### 9.3 Seguridad (V1.0) +### 10.3 Seguridad (V1.0) - TLS obligatorio (Cloudflare en MVP, Caddy en VPS). - Auth con tokens cortos + refresh. @@ -747,7 +956,7 @@ Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `P - CSP estricto en producción. - Backups cifrados (V1.0). -### 9.4 Accesibilidad +### 10.4 Accesibilidad - WCAG 2.1 AA como objetivo V1.0. - Contraste mínimo 4.5:1 en texto. @@ -756,7 +965,7 @@ Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `P --- -## 10. Riesgos y Mitigaciones +## 11. Riesgos y Mitigaciones | # | Riesgo | Probabilidad | Impacto | Mitigación | |---|---|---|---|---| @@ -772,9 +981,9 @@ Añade: `Tenant`, `User`, `Role`, `OrganizationUnit` (jerárquica recursiva), `P --- -## 11. Anexos +## 12. Anexos -### 11.1 Comandos de arranque para Claude Code (MVP) +### 12.1 Comandos de arranque para Claude Code (MVP) ```bash # Inicialización @@ -798,11 +1007,11 @@ npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom npm install -D eslint prettier ``` -### 11.2 BPMN XML de prueba sugerido +### 12.2 BPMN XML de prueba sugerido Para testing inicial, usar el BPMN público de ejemplo de bpmn.io: https://github.com/bpmn-io/bpmn-js-examples -### 11.3 Recursos de referencia +### 12.3 Recursos de referencia - **bpmn-js docs**: https://bpmn.io/toolkit/bpmn-js/ - **BPMN 2.0 spec**: https://www.omg.org/spec/BPMN/2.0/ @@ -811,7 +1020,7 @@ Para testing inicial, usar el BPMN público de ejemplo de bpmn.io: https://githu - **Zustand**: https://zustand-demo.pmnd.rs/ - **Dexie.js**: https://dexie.org/ -### 11.4 Definition of Done — MVP "Noche Cero" +### 12.4 Definition of Done — MVP "Noche Cero" - [ ] El usuario puede importar un archivo `.bpmn` por drag & drop - [ ] El diagrama se renderiza correctamente en el canvas diff --git a/CLAUDE.md b/CLAUDE.md index 85c4f2a..f235e90 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ **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. +**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.* @@ -17,37 +17,83 @@ ## Estado Actual -- **Fase**: 0 — MVP "Noche Cero" +- **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) -- **Fecha objetivo MVP**: una noche -- **Deploy objetivo**: Cloudflare Pages (estático, gratis) +- **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 del MVP +## Reglas No Negociables — Sprint 1 -### ✅ Lo que SÍ hacemos esta noche +### ✅ Lo que SÍ entra en Sprint 1 -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) +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 hacemos esta noche +### ❌ Lo que NO entra en Sprint 1 -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 +- 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. +**Si dudás si una feature entra: NO ENTRA.** Defendé el alcance. Anotala en `TODO.md`. --- -## Stack Obligatorio (MVP) +## 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 | |---|---| @@ -61,16 +107,16 @@ Login · Multi-tenant · Backend · Colaboración · Edición del BPMN · Versio | Gráficos | Apache ECharts (vía echarts-for-react) | | Persistencia | IndexedDB vía Dexie | | Validación | Zod | -| Export PDF | jsPDF + html2canvas | +| Export PDF | jsPDF + jsPDF-autotable + html2canvas | | Export CSV | papaparse | -| Testing | Vitest | +| Testing | Vitest + Playwright | | Deploy | Cloudflare Pages | **No introduzcas librerías fuera de esta lista sin justificación explícita.** --- -## Arquitectura de Carpetas (obligatoria) +## Arquitectura de Carpetas ``` src/ @@ -79,22 +125,23 @@ src/ ├── router.tsx ├── domain/ ← lógica de negocio pura, sin React, testeable │ ├── types.ts -│ ├── simulation.ts ← motor de simulación +│ ├── 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 +├── persistence/ ← Dexie / IndexedDB (v2 en Sprint 1) ├── features/ ← organizado por feature, no por tipo │ ├── import/ -│ ├── workspace/ -│ ├── simulation/ -│ └── report/ +│ ├── 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**: +**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. @@ -104,7 +151,7 @@ src/ ## 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. +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**: @@ -114,18 +161,24 @@ src/ - 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 (CRÍTICO) +## Diferencial Visual (sigue siendo 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: +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 -- Cada gráfico tiene título, leyenda clara y formato de moneda apropiado - Densidad de información media-alta (audiencia: consultor profesional) --- @@ -136,20 +189,23 @@ 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 +- [ ] 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 con Vitest -npm run lint # eslint -npm run preview # previsualizar build +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) ``` --- @@ -161,13 +217,18 @@ npm run preview # previsualizar build - 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 +## Contexto del Fundador y Equipo - Consultor de automatización de procesos basado en Paraguay -- Construye esto como herramienta consultiva propia + para vender a colegas LATAM +- Construye esto como herramienta consultiva propia + del equipo de InQuality + 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 \ No newline at end of file +- 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 \ No newline at end of file diff --git a/src/features/workspace/ActivityPanel.tsx b/src/features/workspace/ActivityPanel.tsx index 2582373..2541472 100644 --- a/src/features/workspace/ActivityPanel.tsx +++ b/src/features/workspace/ActivityPanel.tsx @@ -122,7 +122,7 @@ export function ActivityPanel({ selectedElementId }: ActivityPanelProps) { type="number" min={0} step={10} - value={localActivity.directCostFixed} + value={localActivity.directCostFixed === 0 ? '' : localActivity.directCostFixed} onChange={(e) => handleChange('directCostFixed', Math.max(0, parseFloat(e.target.value) || 0))} className="font-mono h-8 text-sm" placeholder="0" @@ -147,7 +147,7 @@ export function ActivityPanel({ selectedElementId }: ActivityPanelProps) { type="number" min={0} step={5} - value={localActivity.executionTimeMinutes} + value={localActivity.executionTimeMinutes === 0 ? '' : localActivity.executionTimeMinutes} onChange={(e) => handleChange('executionTimeMinutes', Math.max(0, parseFloat(e.target.value) || 0))} className="font-mono h-8 text-sm" placeholder="0" diff --git a/tests/proceso_carga_facturas.bpmn b/tests/proceso_carga_facturas.bpmn new file mode 100644 index 0000000..5bc284b --- /dev/null +++ b/tests/proceso_carga_facturas.bpmn @@ -0,0 +1,371 @@ + + + + + + + + + + + + + + Flow_IK_1 + + + Flow_IK_1 + Flow_IK_2 + + + Flow_IK_2 + Flow_IK_3 + + + Flow_IK_3 + + + + + + + + Flow_R_1 + + + + Flow_R_1 + Flow_R_2 + + + Flow_R_2 + Flow_R_3_Si + Flow_R_3_No + + + Flow_R_3_Si + Flow_R_4 + + + Flow_R_4 + Flow_R_5 + + + Flow_R_5 + Flow_R_6_Si + Flow_R_6_No + + + Flow_R_6_Si + Flow_R_7 + + + Flow_R_7 + Flow_R_8_Si + Flow_R_8_No + + + Flow_R_8_Si + Flow_R_9_Si + Flow_R_9_No + + + Flow_R_9_No + Flow_R_10 + + SubFlow_T_1 + + + SubFlow_T_1 + SubFlow_T_2 + + + SubFlow_T_2 + SubFlow_T_3 + + + SubFlow_T_3 + + + + + + + Flow_R_9_Si + Flow_R_10 + Flow_R_11 + + + Flow_R_11 + Flow_R_12 + + + Flow_R_12 + Flow_R_13_Si + Flow_R_13_No + + + Flow_R_13_Si + Flow_R_14 + + + Flow_R_14 + Flow_R_15_Si + Flow_R_15_No + + + Flow_R_15_Si + Flow_R_16 + + + Flow_R_16 + + + Flow_R_3_No + Flow_R_6_No + Flow_R_8_No + Flow_R_13_No + Flow_R_15_No + Flow_R_17 + + + Flow_R_17 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +