# MATRIZ DE TRAZABILIDAD COMPLETA - ERP CONSTRUCCION

**Fecha:** 2025-11-25
**Version:** 1.0.0
**Metodologia:** ADR-012 Politica de Trazabilidad Completa

---

## Resumen Ejecutivo

Esta matriz consolida toda la trazabilidad del ERP Construccion, mapeando:
- **RF** (Requerimientos Funcionales) → **ET** (Especificaciones Tecnicas) → **BD** (Tablas) → **API** (Endpoints) → **UI** (Componentes)

### Metricas Globales

| Metrica | Valor |
|---------|-------|
| Total Modulos | 13 |
| Total RFs | 52 |
| Total ETs | 35 |
| Total User Stories | 100+ |
| Total Tablas BD | 67 |
| Total Endpoints API | 150+ |
| Reutilizacion Promedio | 61% |

---

## Matriz por Modulo

### MAI-001: Fundamentos (Autenticacion y Seguridad)

**Mapeo:** MGN-001 | **Reutilizacion:** 100%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-AUTH-001 | Roles de Construccion | ET-AUTH-001 | auth.users, auth.roles, auth.permissions, auth.user_roles, auth.role_permissions | POST /auth/login, POST /auth/logout, POST /auth/refresh, GET /users, POST /users, GET /roles, POST /roles | LoginPage, UserManagement, RoleManagement, PermissionMatrix |
| RF-AUTH-002 | Estados de Cuenta | ET-AUTH-002 | auth.users, auth.sessions, auth.password_resets | POST /auth/forgot-password, POST /auth/reset-password, PATCH /users/{id}/status | ForgotPasswordPage, ResetPasswordPage, UserStatusBadge |
| RF-AUTH-003 | Multi-Tenancy | ET-AUTH-003 | auth.tenants, auth.companies, auth.user_companies | GET /tenants/current, GET /companies, POST /companies | TenantSelector, CompanySelector |

**User Stories:** US-FUND-001 a US-FUND-008 (8 total)

---

### MAI-002: Proyectos y Estructura de Obra

**Mapeo:** MGN-009 (parcial) | **Reutilizacion:** 40%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-PROJ-001 | Catalogo de Proyectos | ET-PROJ-001 | construction.fraccionamientos | GET/POST/PATCH/DELETE /fraccionamientos | FraccionamientoList, FraccionamientoForm, FraccionamientoDetail, ProjectStatusBadge |
| RF-PROJ-002 | Estructura Jerarquica | ET-PROJ-002 | construction.etapas, construction.manzanas, construction.lotes, construction.torres, construction.niveles, construction.departamentos | /etapas, /manzanas, /lotes, /torres, /niveles, /departamentos | EstructuraTree, EtapaForm, ManzanaForm, LoteForm, TorreForm, NivelForm, DepartamentoForm, LoteGrid, LoteMap |
| RF-PROJ-003 | Prototipos de Vivienda | ET-PROJ-003 | construction.prototipos | GET/POST/PATCH /prototipos, POST /lotes/{id}/assign-prototipo | PrototipoList, PrototipoForm, PrototipoCard, PrototipoSelector, PrototipoAssignModal |
| RF-PROJ-004 | Equipo y Calendario | ET-PROJ-004 | construction.fraccionamientos | GET/POST /fraccionamientos/{id}/team, PATCH /fraccionamientos/{id}/dates | TeamAssignment, ProjectCalendar, MilestoneTimeline |

**User Stories:** US-PROJ-001 a US-PROJ-009 (9 total)

---

### MAI-003: Presupuestos y Control de Costos

**Mapeo:** null (100% Especifico) | **Reutilizacion:** 0%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-COST-001 | Catalogo Conceptos | ET-COST-001 | construction.conceptos | GET/POST/PATCH /conceptos, GET /conceptos/{id}/children, POST /conceptos/import | ConceptoTree, ConceptoForm, ConceptoImport, PrecioUnitarioEditor |
| RF-COST-002 | Presupuestos Maestros | ET-COST-002 | construction.presupuestos, construction.presupuesto_partidas | GET/POST/PATCH /presupuestos, GET/POST /presupuestos/{id}/partidas, POST /presupuestos/{id}/copy, POST /presupuestos/{id}/approve | PresupuestoList, PresupuestoEditor, PartidaGrid, PresupuestoCompare, PresupuestoApproval |
| RF-COST-003 | Control Costos Reales | ET-COST-003 | construction.presupuestos, construction.presupuesto_partidas, inventory.consumos_obra | GET /control-costos/{id}, GET /control-costos/{id}/comparativo, GET /control-costos/{id}/desviaciones | ControlCostosDashboard, ComparativoPresupuestal, DesviacionesChart, CostoRealCapture |
| RF-COST-004 | Analisis Rentabilidad | ET-COST-004 | construction.presupuestos, construction.presupuesto_partidas | GET /rentabilidad/{id}, GET /rentabilidad/{id}/por-prototipo, GET /rentabilidad/{id}/por-concepto | RentabilidadDashboard, RentabilidadPorPrototipo, MargenChart |

**User Stories:** US-COST-001 a US-COST-008 (8 total)

---

### MAI-004: Compras e Inventarios

**Mapeo:** MGN-005 + MGN-006 | **Reutilizacion:** 80%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-PURCH-001 | Catalogo Proveedores | ET-PURCH-001 | purchase.suppliers (G), purchase.supplier_construction (E) | GET/POST/PATCH /suppliers, POST /suppliers/{id}/evaluate | SupplierList, SupplierForm, SupplierEvaluation, SupplierRatingStars |
| RF-PURCH-002 | Requisiciones y OC | ET-PURCH-002 | inventory.requisiciones_obra (E), inventory.requisicion_lineas (E), purchase.purchase_orders (G), purchase.purchase_order_lines (G), purchase.purchase_order_construction (E), purchase.comparativo_* (E) | GET/POST /requisiciones, POST /requisiciones/{id}/approve, POST /requisiciones/{id}/generate-oc, GET/POST /purchase-orders, GET/POST /comparativos | RequisicionList, RequisicionForm, RequisicionApproval, PurchaseOrderList, PurchaseOrderForm, ComparativoGrid, ComparativoWizard |
| RF-PURCH-003 | Almacenes e Inventarios | ET-PURCH-003 | inventory.warehouses (G), inventory.almacenes_proyecto (E), inventory.products (G), inventory.stock_quants (G), inventory.stock_moves (G) | GET/POST /warehouses, GET /warehouses/{id}/stock, GET/POST /products, GET/POST /stock-moves | WarehouseList, WarehouseForm, WarehouseByProject, ProductList, ProductForm, StockGrid, StockMoveForm |
| RF-PURCH-004 | Kardex y Alertas | ET-PURCH-004 | inventory.stock_moves (G), inventory.consumos_obra (E) | GET /kardex/{product_id}, GET /kardex/{product_id}/by-warehouse, GET /alerts/low-stock, GET/POST /consumos-obra | KardexView, KardexReport, LowStockAlert, ConsumoObraForm, ConsumosPorLote |

**(G) = Generico, (E) = Extension**

**User Stories:** US-PURCH-001 a US-PURCH-008 (8 total)

---

### MAI-005: Control de Obra y Avances

**Mapeo:** null (100% Especifico) | **Reutilizacion:** 0%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-PROG-001 | Programacion y Curva S | ET-PROG-001 | construction.programa_obra, construction.programa_actividades | GET/POST /programas, GET/POST /programas/{id}/actividades, GET /programas/{id}/curva-s, POST /programas/{id}/import | ProgramaList, ProgramaEditor, GanttChart, CurvaSChart, ActividadForm, WBSTree |
| RF-PROG-002 | Captura Avances Fisicos | ET-PROG-002 | construction.avances_obra | GET/POST/PATCH /avances, POST /avances/{id}/approve, POST /avances/{id}/reject, GET /lotes/{id}/avances, GET /fraccionamientos/{id}/avances-consolidado | AvanceCapture, AvanceMobile, AvanceGrid, AvanceApproval, AvanceByLote, AvanceTimeline |
| RF-PROG-003 | Evidencias y Checklists | ET-PROG-003 | construction.fotos_avance, construction.bitacora_obra | POST/GET/DELETE /avances/{id}/fotos, GET/POST /bitacora | FotoUpload, FotoGallery, FotoGeoMap, BitacoraList, BitacoraForm, BitacoraTimeline |
| RF-PROG-004 | Dashboard y Reportes | ET-PROG-004 | construction.avances_obra, construction.programa_obra | GET /dashboard/avances/{id}, GET /reportes/avance-fisico/{id}, GET /reportes/avance-vs-programa/{id}, GET /reportes/curva-s-real/{id}, GET /reportes/semaforo-obra/{id} | DashboardDirector, DashboardResidente, AvanceFisicoChart, AvanceVsProgramaChart, CurvaSRealChart, SemaforoObra, ReporteExport |

**User Stories:** US-PROG-001 a US-PROG-008 (8 total)

---

### MAI-006: Reportes Gerenciales

**Mapeo:** MGN-010 (parcial) | **Reutilizacion:** 40%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-RPT-001 | Reportes Ejecutivos | Por documentar | Views/Funciones | GET /reports/executive/{id}, GET /reports/kpis | ExecutiveDashboard, KPICards |
| RF-RPT-002 | Reportes Financieros | Por documentar | Views/Funciones | GET /reports/financial/{id}, GET /reports/cashflow | FinancialReport, CashflowChart |
| RF-RPT-003 | Exportacion y Formatos | Por documentar | - | GET /reports/{id}/export?format=pdf|xlsx | ExportButton, FormatSelector |

---

### MAI-007: Recursos Humanos

**Mapeo:** MGN-008 | **Reutilizacion:** 70%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-HR-001 | Empleados Obra | Por documentar | hr.employees (G), hr.employee_construction (E), hr.cuadrillas (E), hr.cuadrilla_integrantes (E) | GET/POST /employees, GET /employees/{id}/construction-info | EmployeeList, EmployeeForm, CuadrillaForm |
| RF-HR-002 | Asistencia y Geocercas | Por documentar | hr.asistencias (E), hr.geocercas (E) | GET/POST /asistencias, POST /asistencias/check-in, GET/POST /geocercas | AsistenciaCapture, GeocercaMap, CheckInMobile |
| RF-HR-003 | Destajo y Rendimiento | Por documentar | hr.destajo_asignaciones (E), hr.destajo_registro (E) | GET/POST /destajo, GET /destajo/{employee_id}/rendimiento | DestajoForm, RendimientoChart |

**(G) = Generico, (E) = Extension**

---

### MAI-008: Estimaciones y Facturacion

**Mapeo:** MGN-004 (parcial) | **Reutilizacion:** 20%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-EST-001 | Estimaciones Cliente | ET-EST-001 | estimates.estimaciones, estimates.estimacion_conceptos, estimates.generadores | GET/POST /estimaciones, GET/POST /estimaciones/{id}/conceptos | EstimacionList, EstimacionForm, GeneradorForm |
| RF-EST-002 | Estimaciones Subcontratistas | ET-EST-002 | estimates.estimaciones | POST /estimaciones/subcontratista | EstimacionSubForm |
| RF-EST-003 | Anticipos y Retenciones | ET-EST-003 | estimates.anticipos, estimates.amortizaciones, estimates.retenciones, estimates.fondo_garantia | GET/POST /anticipos, GET /retenciones, GET /fondo-garantia | AnticipoForm, RetencionGrid, FondoGarantiaReport |
| RF-EST-004 | Reportes y Documentos | ET-EST-004 | - | GET /estimaciones/{id}/report, GET /estimaciones/{id}/pdf | EstimacionReport, GeneradorReport |
| RF-EST-005 | Workflow Autorizacion | ET-EST-005 | estimates.estimacion_workflow | POST /estimaciones/{id}/submit, POST /estimaciones/{id}/approve, POST /estimaciones/{id}/reject | WorkflowTimeline, ApprovalButtons |

---

### MAI-009: Control de Calidad

**Mapeo:** null (100% Especifico) | **Reutilizacion:** 0%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-QA-001 | Checklists de Calidad | Por documentar | construction.checklists_calidad | GET/POST /checklists, GET /checklists/{id}/respuestas | ChecklistList, ChecklistForm, ChecklistCapture |
| RF-QA-002 | Inspecciones | Por documentar | construction.inspecciones | GET/POST /inspecciones, POST /inspecciones/{id}/complete | InspeccionForm, InspeccionCalendar |
| RF-QA-003 | No Conformidades | Por documentar | construction.no_conformidades | GET/POST /no-conformidades, POST /no-conformidades/{id}/resolve | NoConformidadList, NoConformidadForm, ResolucionModal |
| RF-QA-004 | Certificados | Por documentar | construction.certificados_calidad | GET/POST /certificados, GET /certificados/{lote_id} | CertificadoGenerator, CertificadoViewer |

---

### MAI-010: CRM y Ventas

**Mapeo:** MGN-003 | **Reutilizacion:** 80%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-CRM-001 | Prospectos y Leads | Por documentar | crm.leads (G), crm.contacts (G) | GET/POST /leads, PATCH /leads/{id}/status | LeadList, LeadForm, LeadKanban |
| RF-CRM-002 | Asignacion Vivienda | Por documentar | crm.sales (G), construction.lotes | POST /sales/{id}/assign-vivienda, GET /lotes/disponibles | ViviendaSelector, AsignacionModal |
| RF-CRM-003 | Seguimiento Postventa | Por documentar | crm.post_venta | GET/POST /post-venta, PATCH /post-venta/{id}/resolve | PostVentaList, PostVentaForm, SeguimientoTimeline |

**(G) = Generico**

---

### MAI-011: INFONAVIT

**Mapeo:** null (100% Especifico) | **Reutilizacion:** 0%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-INFO-001 | Registro ROC/RUV | Por documentar | infonavit.registro_roc, infonavit.registro_ruv | GET/POST /infonavit/roc, GET/POST /infonavit/ruv | ROCForm, RUVForm, RegistroTimeline |
| RF-INFO-002 | Ofertas INFONAVIT | Por documentar | infonavit.ofertas, infonavit.oferta_viviendas | GET/POST /infonavit/ofertas, POST /infonavit/ofertas/{id}/viviendas | OfertaWizard, ViviendaOfertaGrid |
| RF-INFO-003 | Derechohabientes | Por documentar | infonavit.derechohabientes, infonavit.creditos | GET/POST /infonavit/derechohabientes, GET /infonavit/creditos | DerechohabienteList, DerechohabienteForm, CreditoStatus |
| RF-INFO-004 | Actas y Entregas | Por documentar | infonavit.actas_entrega | GET/POST /infonavit/actas, POST /infonavit/actas/{id}/firma | ActaEntregaForm, FirmaDigital, ActaPDF |
| RF-INFO-005 | Reportes INFONAVIT | Por documentar | infonavit.reportes_avance | GET /infonavit/reportes/{periodo}, POST /infonavit/reportes/generar | ReporteINFONAVIT, CIIGenerator |

---

### MAI-012: Contratos y Subcontratos

**Mapeo:** null (Mayormente Especifico) | **Reutilizacion:** 20%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-CONT-001 | Catalogo Subcontratistas | Por documentar | construction.subcontratistas | GET/POST/PATCH /subcontratistas, POST /subcontratistas/{id}/evaluate | SubcontratistaList, SubcontratistaForm, SubcontratistaCard, SubcontratistaRating |
| RF-CONT-002 | Gestion de Contratos | Por documentar | construction.contratos, construction.contrato_partidas | GET/POST/PATCH /contratos, GET/POST /contratos/{id}/partidas, POST /contratos/{id}/activate, POST /contratos/{id}/terminate | ContratoList, ContratoForm, ContratoDetail, PartidaGrid, ContratoWorkflow |
| RF-CONT-003 | Workflow Aprobacion | Por documentar | construction.contratos | POST /contratos/{id}/submit-approval, POST /contratos/{id}/approve, POST /contratos/{id}/reject | ContratoApproval, ApprovalHistory |
| RF-CONT-004 | Penalizaciones | Por documentar | construction.contratos | POST /contratos/{id}/penalties, GET /contratos/{id}/penalties | PenaltyForm, PenaltyList |

---

### MAI-013: Administracion y Seguridad

**Mapeo:** MGN-001 + MGN-012 | **Reutilizacion:** 80%

| RF ID | Nombre | ET | Tablas | Endpoints | Componentes |
|-------|--------|-----|--------|-----------|-------------|
| RF-ADMIN-001 | Configuracion Tenant | Por documentar | auth.tenants, auth.companies | GET/PATCH /admin/tenant, GET/POST /admin/companies | TenantSettings, CompanySettings, BrandingConfig |
| RF-ADMIN-002 | Parametros Sistema | Por documentar | - | GET/PATCH /admin/settings, GET /admin/settings/{category} | SystemSettings, SettingsForm |
| RF-ADMIN-003 | Logs y Auditoria | Por documentar | - | GET /admin/logs, GET /admin/audit-trail, GET /admin/audit-trail/{entity}/{id} | LogViewer, AuditTrail |
| RF-ADMIN-004 | Notificaciones | Por documentar | - | GET /notifications, PATCH /notifications/{id}/read, GET/PATCH /notifications/settings | NotificationList, NotificationBell, NotificationSettings |
| RF-ADMIN-005 | Seguridad Avanzada | Por documentar | - | POST /admin/2fa/enable, POST /admin/2fa/verify, GET/DELETE /admin/sessions, PATCH /admin/password-policy | TwoFactorSetup, ActiveSessions, PasswordPolicy |

---

## Matriz de Dependencias entre Modulos

```
MAI-001 (Fundamentos)
    |
    +---> MAI-002 (Proyectos) ---> MAI-003 (Presupuestos)
    |         |                        |
    |         +---> MAI-005 (Avances) -+---> MAI-008 (Estimaciones)
    |         |         |                        |
    |         +---> MAI-004 (Compras) -----------+
    |                   |
    +---> MAI-007 (RRHH)
    |
    +---> MAI-010 (CRM) ---> MAI-011 (INFONAVIT)
    |
    +---> MAI-012 (Contratos)
    |
    +---> MAI-009 (Calidad)
    |
    +---> MAI-006 (Reportes) <--- (consume datos de todos)
    |
    +---> MAI-013 (Admin) --- (modulo transversal)
```

---

## Resumen de Reutilizacion por Modulo

| Modulo | Nombre | Reutilizacion | Origen |
|--------|--------|---------------|--------|
| MAI-001 | Fundamentos | 100% | MGN-001 |
| MAI-002 | Proyectos | 40% | MGN-009 (parcial) |
| MAI-003 | Presupuestos | 0% | Especifico |
| MAI-004 | Compras | 80% | MGN-005 + MGN-006 |
| MAI-005 | Control Obra | 0% | Especifico |
| MAI-006 | Reportes | 40% | MGN-010 (parcial) |
| MAI-007 | RRHH | 70% | MGN-008 |
| MAI-008 | Estimaciones | 20% | MGN-004 (parcial) |
| MAI-009 | Calidad | 0% | Especifico |
| MAI-010 | CRM | 80% | MGN-003 |
| MAI-011 | INFONAVIT | 0% | Especifico |
| MAI-012 | Contratos | 20% | Especifico |
| MAI-013 | Admin | 80% | MGN-001 + MGN-012 |
| **PROMEDIO** | | **61%** | |

---

## Distribucion de Tablas por Schema

| Schema | Tablas | Tipo |
|--------|--------|------|
| auth | 10 | 100% Generico |
| core | 3 | 100% Generico |
| construction | 25 | 100% Especifico |
| estimates | 8 | 100% Especifico |
| infonavit | 8 | 100% Especifico |
| inventory | 4 ext + base | Mixto |
| purchase | 5 ext + base | Mixto |
| hr | 8 ext + base | Mixto |

**Total: 67 tablas** (25 genericas + 17 extensiones + 41 especificas)

---

## Estado de Documentacion

| Fase | Completado | Pendiente |
|------|------------|-----------|
| ADRs | 12/12 | 0 |
| Requerimientos Funcionales | 52 | - |
| Especificaciones Tecnicas | 35 | 17 |
| User Stories | 100+ | - |
| Database DDL | 8 schemas | 0 |
| Test Plans | README | Detalle por modulo |
| DevOps | docker-compose | CI/CD |

---

## Proximos Pasos de Trazabilidad

1. [ ] Completar ETs faltantes para MAI-006 a MAI-013
2. [ ] Crear TEST-PLAN-MAI-XXX.md por modulo
3. [ ] Implementar codigo y actualizar estado
4. [ ] Generar cobertura de tests
5. [ ] Validar RLS policies por tabla

---

## Referencias

- [ADR-012: Politica de Trazabilidad](../adr/ADR-012-trazabilidad-completa.md)
- [INVENTARIO-OBJETOS-BD.yml](./INVENTARIO-OBJETOS-BD.yml)
- [Archivos de Trazabilidad por Modulo](./modulos/)

---

**Ultima actualizacion:** 2025-11-25
**Version:** 1.0.0
