217 lines
7.6 KiB
Markdown
217 lines
7.6 KiB
Markdown
# _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](./implementacion/TRACEABILITY.yml) - Matriz completa de trazabilidad
|
||
- [DATABASE.yml](./implementacion/DATABASE.yml) - Objetos de base de datos
|
||
- [BACKEND.yml](./implementacion/BACKEND.yml) - Módulos backend
|
||
- [FRONTEND.yml](./implementacion/FRONTEND.yml) - Componentes frontend
|
||
|
||
### Pruebas
|
||
|
||
📋 Documentación de testing:
|
||
- [TEST-PLAN.md](./pruebas/TEST-PLAN.md) - Plan de pruebas
|
||
- [TEST-CASES.md](./pruebas/TEST-CASES.md) - Casos de prueba
|
||
|
||
---
|
||
|
||
## 🔗 Referencias
|
||
|
||
- **README:** [README.md](./README.md) - Descripción detallada de la épica
|
||
- **Fase 1:** [../README.md](../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)
|
||
|
||
1. **Captura de avances** → Control de Obra registra avances físicos
|
||
2. **Generación de estimación** → Se crea borrador desde avances acumulados
|
||
3. **Revisión interna** → Ingeniero revisa volúmenes y montos
|
||
4. **Aplicación de retenciones** → Se aplican retenciones (5%, fondo de garantía, etc.)
|
||
5. **Amortización de anticipos** → Se amortiza anticipo si aplica
|
||
6. **Autorización** → Director/Finanzas autoriza
|
||
7. **Envío a cliente** → Se genera PDF/Excel y se envía
|
||
8. **Pago** → Se registra pago recibido
|
||
|
||
### Hacia Subcontratista/Proveedor
|
||
|
||
1. **Avance de subcontrato** → Residente verifica avance en campo
|
||
2. **Generación de estimación** → Subcontratista genera o se crea desde avances
|
||
3. **Revisión** → Residente/Ingeniero verifica volúmenes
|
||
4. **Retenciones** → Se aplica retención (10% típico)
|
||
5. **Autorización** → Finanzas autoriza pago
|
||
6. **Programación de pago** → Se agenda pago según calendario
|
||
7. **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:**
|
||
1. Se completan 25 viviendas (25% avance)
|
||
2. Monto bruto estimación: 25 × $500K = $12.5M
|
||
3. **Menos** amortización anticipo (25% × $10M): -$2.5M
|
||
4. **Menos** retención 5%: -$0.625M
|
||
5. **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%
|
||
|
||
**Flujo:**
|
||
1. Subcontratista completa 30 viviendas (30% avance)
|
||
2. Monto bruto: 30% × $2M = $600K
|
||
3. **Menos** amortización anticipo (30% × $200K): -$60K
|
||
4. **Menos** retención 10%: -$60K
|
||
5. **Pago neto:** $480K
|
||
|
||
---
|
||
|
||
## 🚨 Puntos Críticos
|
||
|
||
1. **Cálculo preciso:** Errores en cálculo de amortizaciones/retenciones → problemas de flujo de caja
|
||
2. **Trazabilidad:** Cada estimación debe estar respaldada por avances verificados
|
||
3. **Workflow estricto:** No se puede pagar sin autorización
|
||
4. **Integración con finanzas:** Módulo MAE-014 consumirá estos datos para cuentas por cobrar/pagar
|
||
5. **Reportes auditables:** INFONAVIT y auditores piden trazabilidad completa
|
||
|
||
---
|
||
|
||
## 🎯 Siguiente Paso
|
||
|
||
Crear documentación de requerimientos y especificaciones técnicas del módulo.
|
||
|
||
---
|
||
|
||
**Generado:** 2025-11-17
|
||
**Mantenedores:** @tech-lead @backend-team @frontend-team @database-team
|
||
**Estado:** 📝 A crear
|