rckrdmrd a9703b2727 Initial commit - erp-construccion

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

7.6 KiB

Raw Blame History

_MAP: MAI-008 - Estimaciones y Facturación

Épica: MAI-008 Nombre: Estimaciones y Facturación Fase: 1 - Alcance Inicial Presupuesto: $25,000 MXN Story Points: 45 SP Estado: 📝 A crear Sprint: Sprint 5-6 (Semanas 9-12) Última actualización: 2025-11-17 Prioridad: P1

📋 Propósito

Gestión completa de estimaciones de obra hacia clientes (INFONAVIT/fideicomiso) y hacia subcontratistas/proveedores:

Estimaciones de obra ejecutada (volúmenes, importes)
Control de anticipos, amortizaciones y retenciones
Estimaciones a subcontratistas vinculadas a avances
Generación de reportes y documentos para revisión/firma
Control de estatus y pagos

Integración clave: Se vincula estrechamente con Control de Obra (MAI-005), Presupuestos (MAI-003), Contratos (MAI-012) y Finanzas (MAE-014).

📁 Contenido

Requerimientos Funcionales (Estimados: 5)

ID	Título	Estado
RF-EST-001	Estimaciones hacia cliente (INFONAVIT/fideicomiso)	📝 A crear
RF-EST-002	Estimaciones hacia subcontratistas y proveedores	📝 A crear
RF-EST-003	Control de anticipos, amortizaciones y retenciones	📝 A crear
RF-EST-004	Generación de documentos y exportables (PDF/Excel)	📝 A crear
RF-EST-005	Workflow de autorización y estatus de estimaciones	📝 A crear

Especificaciones Técnicas (Estimadas: 5)

ID	Título	RF	Estado
ET-EST-001	Modelo de datos de estimaciones	RF-EST-001	📝 A crear
ET-EST-002	Cálculo de volúmenes y montos	RF-EST-001, RF-EST-002	📝 A crear
ET-EST-003	Sistema de anticipos y retenciones	RF-EST-003	📝 A crear
ET-EST-004	Generación de reportes PDF/Excel	RF-EST-004	📝 A crear
ET-EST-005	Workflow de estados (borrador → autorizada → pagada)	RF-EST-005	📝 A crear

Historias de Usuario (Estimadas: 9)

ID	Título	SP	Estado
US-EST-001	Crear estimación hacia cliente desde avances	5	📝 A crear
US-EST-002	Crear estimación a subcontratista	5	📝 A crear
US-EST-003	Aplicar anticipos y amortizaciones	5	📝 A crear
US-EST-004	Aplicar retenciones y garantías	3	📝 A crear
US-EST-005	Generar reporte de estimación en PDF	5	📝 A crear
US-EST-006	Exportar estimación a Excel	3	📝 A crear
US-EST-007	Workflow de autorización de estimación	5	📝 A crear
US-EST-008	Registrar pago de estimación	5	📝 A crear
US-EST-009	Dashboard de estimaciones y pagos	5	📝 A crear

Total Story Points: 45 SP

Implementación

📊 Inventarios de trazabilidad:

TRACEABILITY.yml - Matriz completa de trazabilidad
DATABASE.yml - Objetos de base de datos
BACKEND.yml - Módulos backend
FRONTEND.yml - Componentes frontend

Pruebas

📋 Documentación de testing:

TEST-PLAN.md - Plan de pruebas
TEST-CASES.md - Casos de prueba

🔗 Referencias

README: README.md - Descripción detallada de la épica
Fase 1: ../README.md - Información de la fase completa
Módulo relacionado MVP: Módulo 7 - Estimaciones y Facturación (MVP-APP.md)

📊 Métricas

Métrica	Valor
Presupuesto estimado	$25,000 MXN
Story Points estimados	45 SP
Duración estimada	9 días
Reutilización GAMILIT	5% (funcionalidad nueva)
RF a implementar	5/5
ET a implementar	5/5
US a completar	9/9

🎯 Módulos Afectados

Base de Datos

Schema: estimations
Tablas principales:
- estimations - Estimaciones (hacia cliente y hacia subcontratistas)
- estimation_items - Detalle de partidas por estimación
- estimation_payments - Pagos de estimaciones
- retentions - Retenciones por estimación
- advances - Anticipos y amortizaciones
ENUMs:
- estimation_type (to_client, to_subcontractor)
- estimation_status (draft, submitted, reviewed, authorized, paid, rejected)
- retention_type (performance_bond, warranty, tax, other)

Backend

Módulo: estimations
Path: apps/backend/src/modules/estimations/
Services: EstimationService, EstimationCalculator, RetentionService, AdvanceService
Controllers: EstimationController, EstimationReportController
Middlewares: EstimationAuthGuard, ProjectAccessGuard

Frontend

Features: estimations, estimation-reports
Path: apps/frontend/src/features/estimations/
Componentes:
- EstimationList
- EstimationForm (create/edit)
- EstimationDetail
- AdvancesManager
- RetentionsManager
- EstimationWorkflow
- EstimationReportViewer
- EstimationDashboard
Stores: estimationStore, advanceStore, retentionStore

🔄 Flujo de Trabajo de Estimaciones

Hacia Cliente (INFONAVIT/Fideicomiso)

Captura de avances → Control de Obra registra avances físicos
Generación de estimación → Se crea borrador desde avances acumulados
Revisión interna → Ingeniero revisa volúmenes y montos
Aplicación de retenciones → Se aplican retenciones (5%, fondo de garantía, etc.)
Amortización de anticipos → Se amortiza anticipo si aplica
Autorización → Director/Finanzas autoriza
Envío a cliente → Se genera PDF/Excel y se envía
Pago → Se registra pago recibido

Hacia Subcontratista/Proveedor

Avance de subcontrato → Residente verifica avance en campo
Generación de estimación → Subcontratista genera o se crea desde avances
Revisión → Residente/Ingeniero verifica volúmenes
Retenciones → Se aplica retención (10% típico)
Autorización → Finanzas autoriza pago
Programación de pago → Se agenda pago según calendario
Pago → Se ejecuta pago

💡 Casos de Uso Clave

Estimación a INFONAVIT

Contexto: Constructora con contrato de 100 viviendas a $500K c/u = $50M

Anticipo: 20% = $10M (recibido al inicio)
Amortización: 25% por estimación
Retención: 5% fondo de garantía

Flujo:

Se completan 25 viviendas (25% avance)
Monto bruto estimación: 25 × $500K = $12.5M
Menos amortización anticipo (25% × $10M): -$2.5M
Menos retención 5%: -$0.625M
Pago neto: $9.375M

Estimación a Subcontratista de Plomería

Contexto: Subcontrato de plomería por $2M en 100 viviendas

Anticipo: 10% = $200K (ya pagado)
Retención: 10%