FRASA-CAS/docs/PLAN-REGLAS-COTIZADOR.md

Plan — Nuevas reglas de negocio del Cotizador FRASA

Fuente: Reglas de negocio Cotizador FRASA .xlsx (entregado por el cliente). Alcance: aplicar estas reglas al cotizador web (apps/cotizador) y a su espejo del lado del API (api-gateway/src/services/cotizacion-esquema.service.ts).

1. Lectura de las reglas (interpretación)

Globales (todos los tipos)

Concepto	Regla
Apartado	$15,000 (cantidad fija, ya confirmada por el cliente)
Gastos de escrituración	5.5 % del precio de venta
Gastos — opción del cliente	Puede incluirlos en el pago de firma (toggle). Si los incluye, se liquidan junto con el enganche para firma de contrato
Mensualidades a diferir	Número de meses calendario completos entre la fecha de cotización y la fecha de entrega de la vivienda (ya implementado vía captura)
Mensualidad a pagar	Enganche diferido ÷ mensualidades
Enganche total	El % total que el cliente elige pagar como enganche (incluye el apartado). Tope por tipo de crédito

Tipos de crédito

Tipo	Rango enganche para firma	Tope enganche total	Aforo	Notaría
Bancario	2.5 % – 15 %	15 %	84.5 %	No aplica
Infonavit-Cofinavit	2.5 % – 15 %	15 %	89.5 %	No aplica
Semi Contado	50 % – 85 %	85 %	No aplica	Debe quedar 15 % para notaría
Contado	86 % – 95 %	95 %	No aplica	Debe quedar mínimo 5 % para notaría

Fórmulas

gastos        = 0.055 × precio
firma         = % enganche firma elegido   (dentro del rango del tipo)
totalEng      = % enganche total elegido   (≤ tope del tipo; firma ≤ totalEng)
diferido      = totalEng − firma           (lo que se difiere en mensualidades)
mensualidad   = diferido × precio ÷ N_meses
saldoPorPagar = precio + gastos − (firma% + diferido%) × precio
                (= precio + gastos − totalEng% × precio)

• Bancario / Infonavit-Cofinavit: monto a financiar = saldoPorPagar. Validación de aforo: saldoPorPagar ≤ aforo × precio; si se rebasa, la combinación elegida no es viable y hay que pedir más enganche.
• Semi Contado: no hay financiamiento. Restricción: el saldo por pagar debe dejar ≥ 15 % para el pago en notaría (saldoPorPagar ≥ 0.15 × precio, equivalente a totalEng ≤ 0.85 + gastos%). El "monto pago en notaría" = 15 %.
• Contado: sin mensualidades (diferido = 0; todo el enganche se paga a la firma). Restricción: saldo ≥ 5 % para notaría (totalEng ≤ 0.95 + gastos%).

Diferencias contra el esquema actual

Aspecto	Esquema actual (FRASA)	Nuevo
Enganche firma	fijo 2.5 %	rango por tipo (2.5–15 / 50–85 / 86–95 %)
Enganche diferible	fijo 7.5 % editable	total elegido − firma
Tope enganche	90 % global	por tipo: 15 / 15 / 85 / 95 %
Aforo	no se valida	validación 84.5 / 89.5 % (bancario/infonavit)
Gastos 5.5 %	siempre aparte	toggle: incluidos en firma u aparte
Notaría	no existe	piso 15 % (semi) / 5 % (contado)
Anticipo adicional	campo extra (decisión previa: sin espacio separado)	se absorbe en "enganche total"

2. Puntos a confirmar con el cliente (antes o durante la implementación)

1. Apartado dentro del %: se interpreta que el % de enganche total es dinero total (el apartado de $15,000 forma parte de él), según la columna K ("% de enganche elegido incluido el apartado"). Confirmar.
2. Semi Contado / Contado: ¿el "pago en notaría" (15 % / 5 %) es parte del saldo por pagar que el cliente liquida al final? Se asume que sí.
3. Aforo: si el financiamiento calculado supera el aforo, ¿bloquear la opción o mostrarla en rojo como "no viable"? Se propone mostrar no viable.
4. Rango de enganche para firma en créditos: ¿el 2.5 % mínimo sigue incluyendo el apartado como parte del pago a firma (como hoy)? Se propone que sí.

3. Plan de implementación

3.1 Motor de cálculo — esquema-frasa.ts (app) y cotizacion-esquema.service.ts (API, espejo)

1. Nuevo tipo TipoCredito = 'bancario' | 'infonavit' | 'contado' | 'semicontado' (reemplaza/usa el catálogo actual de opciones de crédito).
2. Tabla de reglas por tipo (única fuente de verdad en ambos lados, misma constante): REGLAS_TIPO con {rangoFirmaMin, rangoFirmaMax, topeTotal, aforo, pisoNotaria, permiteDiferir}.
3. Entrada del motor: {precio, apartado, tipo, pctFirma, pctTotal, incluirGastosEnFirma, meses}.
4. Salida: {gastos, montoFirma, montoDiferido, mensualidad, saldoPorPagar, montoFinanciar, pagoNotaria, viable, motivos[]} con validaciones:
   • firma dentro de rango; total ≤ tope; total ≥ firma;
   • si diferido > 0 → meses ≥ 1 (tope por fecha de entrega, ya existente);
   • aforo (bancario/infonavit): saldo ≤ aforo × precio;
   • piso notaría (semi/contado): saldo ≥ piso × precio.
5. Quitar del esquema actual lo que queda reemplazado: enganche fijo 2.5/7.5, tope global 90 %, engancheAdicional (el "total elegido" lo absorbe).

3.2 UI del cotizador (apps/cotizador)

1. Selector de tipo de crédito con las 4 opciones y sus topes visibles.
2. Slider/input de enganche total (0 → tope del tipo) y slider/input de enganche a firma (rango del tipo, ≤ total).
3. Toggle "Incluir gastos de escrituración en el pago de firma".
4. Tabla de resultados: apartado, firma, diferido, mensualidad (×N meses), gastos, saldo, monto a financiar (o pago en notaría), y badge viable / no viable con motivo (aforo excedido, piso notaría, etc.).
5. Las 4 opciones de crédito del guardado existente pasan a ser las 4 combinaciones tipo+porcentajes que el vendedor guarde, no 4 presets fijos.

3.3 Persistencia y reportes

1. Cotizacion: columnas nuevas tipoCredito, pctFirma, pctTotal, incluirGastosFirma (migración SQLite manual, estilo existente). Mantener opcionesCredito JSON para compatibilidad de lectura histórica.
2. PDF: sección de desglose según nuevo esquema (firma / diferido / notaría / financiamiento, viable o no).

3.4 Pruebas

• Unitarias del motor: casos dorados por tipo (límites de rango, tope, aforo justo arriba/abajo, pisos de notaría, toggle de gastos).
• Smoke API: POST cotización con cada tipo → verificar montos y viable.
• Regresión: cotizaciones históricas existentes siguen leyéndose.

3.5 Entrega

• Migración + build de api-gateway y apps/cotizador.
• Actualización de guía de usuario del cotizador (sección reglas).
• Resumen de cambios para el cliente con los puntos 2 resueltos.