# TRACEABILITY - MAI-005: Control de Obra
metadata:
  modulo: MAI-005
  nombre: Control de Obra
  version: 1.0.0
  fecha: 2025-12-06
  reutilizacion_core: 0%
  descripcion: Trazabilidad completa del módulo de Control de Obra
  app_movil: MOB-003
  app_movil_nombre: Supervisor

requerimientos:
  - id: RF-OBRA-001
    titulo: Registro de Avances Físicos
    descripcion: Sistema para registrar y controlar el progreso físico de las obras
    especificaciones:
      - ET-OBRA-database
      - ET-OBRA-backend
      - ET-OBRA-frontend
      - ET-OBRA-mobile
    historias_usuario:
      - HU-OBRA-001: Como supervisor, quiero registrar el avance físico de las partidas
      - HU-OBRA-002: Como jefe de obra, quiero visualizar el progreso de las actividades
      - HU-OBRA-003: Como director, quiero generar reportes de avance físico
      - HU-OBRA-004: Como supervisor, quiero adjuntar fotografías del avance
    tablas:
      - construction_management.avances
      - construction_management.avance_fotos
      - construction_management.avance_partidas
      - construction_management.avance_actividades
      - construction_management.avance_historial
    endpoints:
      - POST /api/v1/obras/{obraId}/avances
      - GET /api/v1/obras/{obraId}/avances
      - GET /api/v1/obras/{obraId}/avances/{avanceId}
      - PUT /api/v1/obras/{obraId}/avances/{avanceId}
      - DELETE /api/v1/obras/{obraId}/avances/{avanceId}
      - POST /api/v1/obras/{obraId}/avances/{avanceId}/fotos
      - GET /api/v1/obras/{obraId}/avances/reporte
      - GET /api/v1/obras/{obraId}/avances/progreso
    componentes_ui:
      - AvanceForm
      - ProgressBar
      - AvancesList
      - AvanceDetail
      - FotoGallery
      - ProgressChart
      - AvanceReportGenerator
    app_movil: MOB-003
    funcionalidad_movil:
      - Registro de avances en campo
      - Captura de fotografías
      - Firma digital del supervisor
      - Sincronización offline
    estado: pendiente
    prioridad: alta
    dependencias:
      - MAI-001 # Gestión de Proyectos
      - MAI-002 # Planificación de Obras

  - id: RF-OBRA-002
    titulo: Control de Avances Financieros
    descripcion: Sistema para controlar el progreso financiero y facturación de las obras
    especificaciones:
      - ET-OBRA-database
      - ET-OBRA-backend
      - ET-OBRA-frontend
      - ET-OBRA-mobile
    historias_usuario:
      - HU-OBRA-005: Como administrador de obra, quiero registrar el avance financiero
      - HU-OBRA-006: Como director financiero, quiero visualizar el flujo de efectivo
      - HU-OBRA-007: Como contador, quiero generar estimaciones de obra
      - HU-OBRA-008: Como gerente, quiero comparar avance físico vs financiero
    tablas:
      - construction_management.avances_financieros
      - construction_management.estimaciones
      - construction_management.estimacion_partidas
      - construction_management.facturacion_obra
      - construction_management.pagos_estimaciones
      - construction_management.retenciones
    endpoints:
      - POST /api/v1/obras/{obraId}/avances-financieros
      - GET /api/v1/obras/{obraId}/avances-financieros
      - GET /api/v1/obras/{obraId}/avances-financieros/{avanceId}
      - PUT /api/v1/obras/{obraId}/avances-financieros/{avanceId}
      - POST /api/v1/obras/{obraId}/estimaciones
      - GET /api/v1/obras/{obraId}/estimaciones
      - GET /api/v1/obras/{obraId}/estimaciones/{estimacionId}
      - POST /api/v1/obras/{obraId}/estimaciones/{estimacionId}/generar-pdf
      - GET /api/v1/obras/{obraId}/flujo-efectivo
      - GET /api/v1/obras/{obraId}/comparativa-fisico-financiero
    componentes_ui:
      - AvanceFinancieroForm
      - EstimacionGenerator
      - EstimacionList
      - EstimacionDetail
      - FlujoCajaChart
      - ComparativaChart
      - FacturacionPanel
      - RetencionesTable
    app_movil: MOB-003
    funcionalidad_movil:
      - Consulta de avances financieros
      - Visualización de estimaciones
      - Aprobación de estimaciones
    estado: pendiente
    prioridad: alta
    dependencias:
      - MAI-001 # Gestión de Proyectos
      - MAI-002 # Planificación de Obras
      - RF-OBRA-001 # Avances Físicos

  - id: RF-OBRA-003
    titulo: Gestión de Recursos en Obra
    descripcion: Sistema para controlar el uso de recursos humanos, materiales y equipos
    especificaciones:
      - ET-OBRA-database
      - ET-OBRA-backend
      - ET-OBRA-frontend
      - ET-OBRA-mobile
    historias_usuario:
      - HU-OBRA-009: Como supervisor, quiero registrar el personal asignado diariamente
      - HU-OBRA-010: Como almacenista, quiero controlar el consumo de materiales
      - HU-OBRA-011: Como jefe de maquinaria, quiero registrar el uso de equipos
      - HU-OBRA-012: Como administrador, quiero optimizar la asignación de recursos
    tablas:
      - construction_management.recursos_obra
      - construction_management.asignacion_personal
      - construction_management.asistencia_personal
      - construction_management.consumo_materiales
      - construction_management.uso_equipos
      - construction_management.control_inventario_obra
      - construction_management.solicitudes_material
    endpoints:
      - POST /api/v1/obras/{obraId}/recursos/personal
      - GET /api/v1/obras/{obraId}/recursos/personal
      - POST /api/v1/obras/{obraId}/recursos/asistencia
      - GET /api/v1/obras/{obraId}/recursos/asistencia
      - POST /api/v1/obras/{obraId}/recursos/materiales
      - GET /api/v1/obras/{obraId}/recursos/materiales
      - POST /api/v1/obras/{obraId}/recursos/equipos
      - GET /api/v1/obras/{obraId}/recursos/equipos
      - POST /api/v1/obras/{obraId}/recursos/solicitudes
      - GET /api/v1/obras/{obraId}/recursos/inventario
      - GET /api/v1/obras/{obraId}/recursos/reporte-consumo
    componentes_ui:
      - AsignacionPersonalForm
      - AsistenciaTable
      - ConsumoMaterialesForm
      - UsoEquiposForm
      - InventarioObraList
      - SolicitudMaterialForm
      - ReporteConsumoChart
      - RecursosOverview
    app_movil: MOB-003
    funcionalidad_movil:
      - Registro de asistencia de personal
      - Registro de consumo de materiales
      - Registro de uso de equipos
      - Solicitud de materiales
      - Verificación de inventario
    estado: pendiente
    prioridad: media
    dependencias:
      - MAI-001 # Gestión de Proyectos
      - MAI-003 # Gestión de Recursos

  - id: RF-OBRA-004
    titulo: Bitácora Digital de Obra
    descripcion: Sistema digital para registro diario de eventos, incidencias y actividades
    especificaciones:
      - ET-OBRA-database
      - ET-OBRA-backend
      - ET-OBRA-frontend
      - ET-OBRA-mobile
    historias_usuario:
      - HU-OBRA-013: Como supervisor, quiero registrar eventos diarios en la bitácora
      - HU-OBRA-014: Como residente, quiero documentar incidencias con fotografías
      - HU-OBRA-015: Como cliente, quiero consultar la bitácora de obra
      - HU-OBRA-016: Como director, quiero generar reportes de incidencias
    tablas:
      - construction_management.bitacora
      - construction_management.bitacora_entradas
      - construction_management.bitacora_fotos
      - construction_management.incidencias
      - construction_management.clima_diario
      - construction_management.visitas_obra
      - construction_management.bitacora_firmas
    endpoints:
      - POST /api/v1/obras/{obraId}/bitacora/entradas
      - GET /api/v1/obras/{obraId}/bitacora/entradas
      - GET /api/v1/obras/{obraId}/bitacora/entradas/{entradaId}
      - PUT /api/v1/obras/{obraId}/bitacora/entradas/{entradaId}
      - DELETE /api/v1/obras/{obraId}/bitacora/entradas/{entradaId}
      - POST /api/v1/obras/{obraId}/bitacora/entradas/{entradaId}/fotos
      - POST /api/v1/obras/{obraId}/bitacora/incidencias
      - GET /api/v1/obras/{obraId}/bitacora/incidencias
      - POST /api/v1/obras/{obraId}/bitacora/clima
      - POST /api/v1/obras/{obraId}/bitacora/visitas
      - POST /api/v1/obras/{obraId}/bitacora/entradas/{entradaId}/firmar
      - GET /api/v1/obras/{obraId}/bitacora/reporte
    componentes_ui:
      - BitacoraEntryForm
      - BitacoraTimeline
      - BitacoraDetail
      - IncidenciaForm
      - IncidenciasList
      - ClimaWidget
      - VisitaForm
      - FirmaDigital
      - BitacoraReportGenerator
      - BitacoraCalendar
    app_movil: MOB-003
    funcionalidad_movil:
      - Registro de entradas de bitácora
      - Captura de fotografías
      - Registro de incidencias
      - Registro de clima
      - Firma digital
      - Consulta de bitácora histórica
      - Modo offline con sincronización
    estado: pendiente
    prioridad: alta
    dependencias:
      - MAI-001 # Gestión de Proyectos

integraciones:
  core:
    - MGN-001: Gestión de Usuarios (autenticación y autorización)
    - MGN-002: RBAC (control de permisos por rol)
    - MGN-003: Multi-tenancy (aislamiento de datos por empresa)
    - MGN-005: Catálogos (tipos de incidencias, categorías, etc.)
    - MGN-007: Auditoría (registro de cambios)
    - MGN-008: Notificaciones (alertas de incidencias y aprobaciones)

  verticales:
    - MAI-001: Gestión de Proyectos (datos de proyectos)
    - MAI-002: Planificación de Obras (presupuestos y cronogramas)
    - MAI-003: Gestión de Recursos (personal, materiales, equipos)

  apps_moviles:
    - MOB-003: App Supervisor
      descripcion: Aplicación móvil para supervisores de obra
      funcionalidades:
        - Registro de avances físicos en campo
        - Control de recursos (personal, materiales, equipos)
        - Bitácora digital con captura de fotos
        - Registro de incidencias
        - Firma digital
        - Modo offline con sincronización automática

metricas:
  cobertura_pruebas: 0%
  documentacion: 0%
  endpoints_implementados: 0/42
  componentes_implementados: 0/38
  tablas_creadas: 0/21

notas_implementacion:
  - Implementar primero RF-OBRA-001 (Avances Físicos) como base
  - RF-OBRA-002 depende de RF-OBRA-001 para comparativas
  - La app móvil MOB-003 debe soportar modo offline robusto
  - Implementar sistema de sincronización de datos móvil-servidor
  - Las fotografías deben comprimirse antes de enviar desde móvil
  - Implementar firma digital con certificado de tiempo
  - Considerar geolocalización en registros móviles
  - Sistema de aprobación multinivel para estimaciones
  - Dashboard ejecutivo con KPIs de avance físico y financiero
  - Alertas automáticas por desviaciones presupuestarias