reformix-hackaton/docs/superpowers/specs/2026-05-30-motor-presupuesto-design.md

Motor de presupuesto Reformix — Diseño

Fecha: 2026-05-30 · Estado: aprobado (brainstorming) · Owner dominio: Goyo · Coord: Carlos Alcance: F2 (en sprint actual). El configurador multi-tenant real sigue siendo F1.5.

Objetivo

Producir un presupuesto orientativo desglosado por partidas a partir de datos que escalan "de menos a más": con el mínimo (tipo de reforma + calidad) ya sale un número, y cada etapa del funnel (medidas, material exacto, llamada) lo afina. El reformista define los precios en el panel; el catálogo se puede sembrar y actualizar por CSV.

Requisitos cubiertos: RF-C-21 (desglose por partidas + factor zona), RF-C-22 (licencia si hay cambios estructurales), RF-D-07 (tabla de precios editable), RF-B-07 (DIN-A4 como input de medidas, fallback stubbeable), RF-B-09 (disclaimer orientativo), RNF-MAINT-01 (≥70% cobertura en src/budget/*).

Decisiones de diseño (validadas con el usuario)

1. Modelo híbrido partidas ← precios unitarios. El reformista configura precios unitarios (€/m² suelo por calidad, €/m² pared, €/m² pintura, €/ml mobiliario, mano de obra). El motor calcula cantidades desde las medidas y agrupa el resultado en las partidas de RF-C-21.
2. Medidas mínimas = m² de suelo + supuestos. El resto se deriva: perímetro ≈ 4·√(m²), m² pared = perímetro × altura (2,5 m por defecto). Si no hay m², mediana por tipo. El refinamiento con dimensiones reales (largo×ancho×alto) o DIN-A4 es posterior/opcional.
3. Calidad = columna de precio por material (B/M/P) más un catálogo de materiales con precio e identidad propia, importable por CSV. El cliente elige una calidad global por defecto; puede personalizar material exacto si quiere.
4. Progressive disclosure. Se fomenta lo básico (solo calidad). La personalización (material exacto del catálogo) aparece sutil y opcional en el funnel, y el agente la afina en la llamada. El material elegido alimenta el prompt del render para que la imagen refleje exactamente lo presupuestado.

Arquitectura

   PANEL (CRUD)        pricing_config + catalog_items (por tenant)
   reformista          · precios unitarios B/M/P por material
   + CSV import        · mano de obra, factor zona, partidas
        │ (lee de DB)
        ▼
   FUNNEL (cliente)
   inputs por etapa ─► computeBudget(config, catalog, inputs) ─► BudgetResult
   · m² suelo, calidad      [ función PURA en src/budget/ ]       · partidas[]
   · (opc.) material exacto                                       · subtotal, total
   · (llamada) estructural                                       · rango + confianza
                                                                 · materiales→render

• src/budget/ (núcleo puro): tipos, computeBudget(), derivación de cantidades, agrupación en partidas, partida condicional de licencia, cálculo de rango+confianza. Sin imports de DB ni de red. Es el módulo con cobertura ≥70% (RNF-MAINT-01).
• DB (Drizzle): extiende el schema existente (src/db/schema.ts).
• Panel: CRUD sobre config/catálogo + importador CSV. Tenant único "Reformas Ejemplo".
• Funnel: recoge inputs mínimos, llama al engine, persiste snapshot por etapa.

Flujo de cálculo computeBudget(config, catalog, inputs)

1. Cantidades (con degradación):
   • m² suelo aportado; si no, mediana por tipo (cocina 10, baño 5, salón 20, integral 70).
   • perímetro ≈ 4·√(m² suelo); m² pared = perímetro × alturaTecho (default 2,5 m).
   • ml mobiliario ≈ perímetro × factor_tipo (solo cocina/baño).
2. Precio unitario por material: ítem exacto elegido del catálogo si existe; si no, ítem esDefault de la calidad global.
3. Partidas (RF-C-21): cada partida = Σ(cantidad × precio unitario material) + mano de obra. Categorías: demolición, alicatado, fontanería, electricidad, carpintería, mano de obra, extras.
4. Factor zona: multiplicador por provincia (configurable) sobre el subtotal.
5. Licencia (RF-C-22): si inputs.estructural = true, partida "Licencia + Proyecto técnico" con rango 300–1.500 €.
6. Rango + confianza: total como { min, max, confianza }. Menos datos → banda más ancha (≈ ±25% solo con calidad; ≈ ±10% tras llamada con material exacto + estructural confirmado).

Modelo de datos (extensión Drizzle)

pricing_config (1 por tenant)
  tenantId, alturaTechoDefault, factorZona (jsonb provincia→mult),
  manoObra (jsonb partida→€), updatedAt

catalog_items (N por tenant)
  id, tenantId, categoria (suelo|pared|pintura|mobiliario|...),
  nombre, calidad (basica|media|premium), precioUnit (cents),
  unidad (m2|ml|ud), descriptorRender (text), esDefault (bool), sku

leads (campos nuevos)
  m2Suelo, alturaTecho, calidadGlobal, estructural,
  materialSelections (jsonb categoria→catalogItemId),
  desgloseSnapshot (jsonb: partidas+rango por pipeline_stage)

• Dinero en enteros (cents), consistente con el schema actual.
• desgloseSnapshot guarda el resultado en cada pipeline_stage → permite analizar cómo evoluciona la estimación lead a lead.
• descriptorRender de cada material se inyecta en el prompt del render.

Panel del reformista (/panel/precios)

• Catálogo editable: tabla de catalog_items por categoría, precio por calidad inline; crear/editar/borrar; marcar esDefault por calidad.
• Importar CSV: subida → parse con zod → preview filas válidas/erróneas → confirmar. Cabeceras: categoria,nombre,calidad,precio,unidad,descriptor_render,sku. Upsert por sku. Si hay errores de validación, se escriben cero filas.
• Config general: factor zona por provincia, mano de obra por partida, altura techo.

Funnel (cliente) — progressive disclosure

• Por defecto: tipo de reforma + calidad (B/M/P) y, opcional, m² de suelo → estimación
  • render genérico de la calidad.
• Afordance sutil "Personalizar materiales" (colapsado): galería del catálogo para elegir ítems exactos. Quien no la toca, usa el default.
• La llamada enriquece inputs (material exacto, estructural, medidas finas) → recálculo
  • render exacto.

Seed (demo 11-jun-2026)

Sembrar pricing_config + un catálogo demo (suelos, alicatados, pinturas, mobiliario en B/M/P con descriptorRender) para que la demo funcione sin cargar CSV.

Fuera de alcance (ahora)

• Recálculo retroactivo de presupuestos ya guardados (los snapshots no se tocan).
• Calidad por elemento mezclada como input por defecto (refinamiento F1.5; el catálogo ya lo permite a nivel de selección manual).
• Extracción real de medidas por visión/DIN-A4: se deja stub (has_din_a4 flag + hook de medidas) y se usa la degradación por medianas mientras tanto.
• Multi-tenant real (F1.5): todo opera sobre "Reformas Ejemplo".
• Dimensiones largo×ancho×alto como input mínimo (queda como refinamiento opcional).

Verificación

• Tests unitarios de computeBudget con inputs conocidos: desglose ±1 € vs cálculo manual (RF-C-21), partida de licencia presente con estructural=true (RF-C-22), degradación sin m², estrechamiento del rango al añadir datos. Cobertura src/budget/* ≥70% (RNF-MAINT-01).
• Test de parser CSV: filas válidas/erróneas, upsert por sku, cero escrituras si hay error.