rckrdmrd a9703b2727 Initial commit - erp-construccion

2026-01-04 06:12:06 -06:00

9.1 KiB

Raw Permalink Blame History

RF-EST-001: Estimaciones hacia Cliente

ID: RF-EST-001
Módulo: MAI-008
Prioridad: Alta
Story Points: 13 SP

📋 Descripción

Sistema para generar estimaciones de obra ejecutada hacia clientes institucionales (INFONAVIT, fideicomisos, Gobierno) basadas en avances físicos verificados, con cálculo automático de amortizaciones de anticipo y retenciones.

🎯 Objetivos

Generar estimaciones desde avances de obra validados
Calcular automáticamente anticipos, amortizaciones y retenciones según contrato
Mantener trazabilidad completa entre avances físicos y cobros
Workflow de autorización multinivel
Generación de documentos oficiales para cliente

📐 Reglas de Negocio

RN-EST-001: Cálculo de Monto Bruto

montoBruto = Σ (conceptos_ejecutados × precio_unitario)

// Ejemplo para viviendas:
montoBruto = viviendas_terminadas × precio_por_vivienda

Validaciones:

Solo conceptos con avance >= umbral_estimacion (default 100%)
Precios del catálogo vigente del contrato
Validar que no exceda monto contratado

RN-EST-002: Amortización de Anticipo

// Si hay anticipo pendiente:
porcentaje_amortizacion = configurado_en_contrato  // Ejemplo: 25%
saldo_anticipo = anticipo_inicial - Σ(amortizaciones_previas)

amortizacion_actual = min(
  saldo_anticipo,
  (monto_bruto - acumulado_estimaciones_anteriores) × (porcentaje_amortizacion / 100)
)

Ejemplo:

Contrato: $50M, Anticipo 20% = $10M
Amortización: 25% por estimación
Estimación 1: $12.5M bruto → Amortiza $2.5M (25% × $10M)
Estimación 2: $10M bruto → Amortiza $2.5M
Etc hasta agotar $10M

RN-EST-003: Retenciones

base_retenciones = monto_bruto - amortizacion

retenciones = {
  fondo_garantia: base_retenciones × 0.05,  // 5% típico
  isr: base_retenciones × (tasa_isr / 100) || 0,
  iva_retenido: base_retenciones × (tasa_iva_ret / 100) || 0,
  otras: monto_fijo || 0
}

total_retenciones = Σ(retenciones)

Reglas:

Fondo de garantía: Configurable por contrato (típico 5-10%)
ISR retenido: Solo si aplica según contrato
IVA retenido: Casos específicos
Se acumulan hasta finiquito/liberación

RN-EST-004: Cálculo de Monto Neto

monto_neto = monto_bruto - amortizacion_anticipo - total_retenciones

Validaciones:

monto_neto >= 0
Si monto_neto < 0 → Alerta, revisar cálculos

RN-EST-005: Numeración Consecutiva

EST-[PROYECTO]-[TIPO]-[AÑO]-[CONSECUTIVO]

Ejemplos:
- EST-PRJ001-CLI-2025-001  (Primera estimación a cliente)
- EST-PRJ001-CLI-2025-002  (Segunda estimación a cliente)

Reglas:

Consecutivo reinicia cada año
No se saltan números
Único por proyecto

RN-EST-006: Validaciones de Negocio

No duplicar conceptos:
- Un concepto/vivienda no puede estimarse 2 veces al mismo cliente
- Validar vs estimaciones anteriores

Límite del contrato:

acumulado_estimaciones + monto_actual <= monto_contrato_total

Avances verificados:
- Solo incluir conceptos con avance validado por residente/supervisor
- Estado del avance: "verificado" o "autorizado"
Periodo de estimación:
- Típico: Mensual, Quincenal
- No solapar periodos
- No generar 2 estimaciones del mismo periodo

🏛️ Estructura de Datos

Estimación hacia Cliente

interface EstimacionCliente {
  id: string;
  numero: string;  // EST-PRJ001-CLI-2025-001
  
  // Relaciones
  proyectoId: string;
  contratoId: string;
  clienteId: string;
  
  // Periodo
  periodoInicio: Date;
  periodoFin: Date;
  numeroEstimacion: number;  // 1, 2, 3...
  
  // Montos
  montoBruto: number;
  amortizacionAnticipo: number;
  totalRetenciones: number;
  montoNeto: number;
  
  // Desglose retenciones
  retencionFondoGarantia: number;
  retencionISR: number;
  retencionIVA: number;
  otrasRetenciones: number;
  
  // Estado
  status: EstimationStatus;  // draft, submitted, authorized, paid
  
  // Fechas
  fechaCreacion: Date;
  fechaEnvio: Date;
  fechaAutorizacion: Date;
  fechaCobro: Date;
  fechaCobroEstimada: Date;
  
  // Workflow
  creadoPor: string;
  autorizadoPor: string;
  observaciones: string;
  
  // Metadata
  documentosPDF: string[];  // URLs
  documentosExcel: string[];
}

Detalle de Partidas

interface EstimacionItem {
  id: string;
  estimacionId: string;
  
  // Concepto
  conceptoCatalogoId: string;
  descripcion: string;
  unidad: string;
  precioUnitario: number;
  
  // Cantidades
  cantidadContratada: number;
  cantidadEstimadaAnterior: number;
  cantidadEstimadaActual: number;
  cantidadAcumulada: number;
  porcentajeAvance: number;
  
  // Importes
  importeActual: number;  // cantidad_actual × precio
  importeAcumulado: number;
  
  // Trazabilidad
  avanceObraId: string;  // Link a MAI-005
  verificadoPor: string;
  fechaVerificacion: Date;
}

🔄 Estados del Workflow

stateDiagram-v2
    [*] --> Borrador
    Borrador --> Enviada: Ingeniero envía
    Enviada --> Revisada: Finanzas revisa
    Revisada --> Autorizada: Director autoriza
    Autorizada --> Cobrada: Se registra pago
    
    Enviada --> Borrador: Rechazada (volver a editar)
    Revisada --> Enviada: Correcciones requeridas
    
    Cobrada --> [*]

Transiciones:

draft → submitted: Ingeniero valida y envía
submitted → reviewed: Finanzas valida cálculos
reviewed → authorized: Director autoriza (si >$100K)
authorized → paid: Se registra cobro de cliente

📊 Casos de Uso

CU-001: Generar Estimación Mensual de Viviendas

Actor: Ingeniero de Proyecto

Precondiciones:

Existe proyecto con contrato vigente
Hay avances de obra verificados del periodo
No existe estimación para el mismo periodo

Flujo:

Ingeniero selecciona proyecto y periodo
Sistema carga avances verificados del periodo
Sistema identifica viviendas 100% terminadas en el periodo
Sistema calcula monto bruto (viviendas × precio)
Sistema calcula amortización de anticipo
Sistema calcula retenciones
Sistema muestra resumen y desglose
Ingeniero revisa y confirma
Sistema genera estimación en estado "Borrador"

Postcondiciones:

Estimación creada vinculada a avances
Disponible para revisión

CU-002: Estimar por Avance de Partidas

Actor: Ingeniero