workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-005-control-obra/_MAP.md

_MAP: MAI-005 - Control de Obra

Épica: MAI-005 Nombre: Control de Obra y Avances Fase: 1 - Alcance Inicial Presupuesto: $30,000 MXN Story Points: 55 SP Estado: 📝 A crear Sprint: Sprint 5-7 (Semanas 9-14) Última actualización: 2025-12-06 Prioridad: P0 - Crítico

---

📋 Propósito

Sistema integral de control de obra que permite supervisar y documentar el avance de construcción en tiempo real:

• Avances físicos: Registro de progreso por concepto/partida (%, cantidades, volúmenes)
• Avances financieros: Cálculo de obra ejecutada vs presupuestada
• Bitácora digital: Registro electrónico de eventos de obra con firmas digitales
• Gestión de recursos en obra: Control de personal, materiales y equipos en sitio
• Integración móvil: Captura desde app móvil MOB-003 (Supervisor de Obra) con modo offline

Justificación: Control de Obra es el corazón operativo del sistema de construcción. Sin control de avances no hay estimaciones, facturación, ni cumplimiento INFONAVIT.

Reutilización GAMILIT: 15% (conceptos de tracking y progreso, adaptados)

---

📁 Contenido

Requerimientos Funcionales (6)

ID	Archivo	Título	Estado
RF-CTL-001	RF-CTL-001-registro-avances-fisicos.md	Registro de Avances Físicos por Concepto	📝 A crear
RF-CTL-002	RF-CTL-002-avances-financieros.md	Cálculo de Avances Financieros	📝 A crear
RF-CTL-003	RF-CTL-003-bitacora-digital.md	Bitácora Digital de Obra	📝 A crear
RF-CTL-004	RF-CTL-004-gestion-recursos-obra.md	Gestión de Recursos en Obra	📝 A crear
RF-CTL-005	RF-CTL-005-comparativo-programa-real.md	Comparativo Programa vs Real	📝 A crear
RF-CTL-006	RF-CTL-006-evidencia-fotografica.md	Evidencia Fotográfica y Geolocalización	📝 A crear

Especificaciones Técnicas (6)

ID	Archivo	Título	RF	Estado
ET-CTL-001	ET-CTL-001-modelo-avances.md	Modelo de Datos de Avances	RF-CTL-001, RF-CTL-002	📝 A crear
ET-CTL-002	ET-CTL-002-calculo-avances.md	Algoritmos de Cálculo de Avances	RF-CTL-002	📝 A crear
ET-CTL-003	ET-CTL-003-bitacora-firmas.md	Implementación de Bitácora y Firmas Digitales	RF-CTL-003	📝 A crear
ET-CTL-004	ET-CTL-004-recursos-obra.md	Gestión de Recursos en Obra	RF-CTL-004	📝 A crear
ET-CTL-005	ET-CTL-005-curva-s.md	Curva S y Comparativos Visuales	RF-CTL-005	📝 A crear
ET-CTL-006	ET-CTL-006-app-movil-supervisor.md	App Móvil MOB-003 (Supervisor)	RF-CTL-001, RF-CTL-003, RF-CTL-006	📝 A crear

Historias de Usuario (9)

ID	Archivo	Título	SP	Estado
US-CTL-001	US-CTL-001-registro-avance-diario.md	Registrar Avance Diario por Concepto	8	📝 A crear
US-CTL-002	US-CTL-002-comparativo-programa-real.md	Ver Comparativo Programa vs Real	8	📝 A crear
US-CTL-003	US-CTL-003-bitacora-obra.md	Registrar Entrada en Bitácora de Obra	5	📝 A crear
US-CTL-004	US-CTL-004-evidencia-fotografica.md	Capturar Evidencia Fotográfica de Avances	5	📝 A crear
US-CTL-005	US-CTL-005-generar-estimacion.md	Generar Estimación de Periodo	8	📝 A crear
US-CTL-006	US-CTL-006-curva-s-avance.md	Visualizar Curva S de Avance	8	📝 A crear
US-CTL-007	US-CTL-007-dashboard-retrasos.md	Dashboard de Retrasos e Incidencias	5	📝 A crear
US-CTL-008	US-CTL-008-registrar-incidencias.md	Registrar Incidencias de Obra	5	📝 A crear
US-CTL-009	US-CTL-009-aprobar-avances.md	Aprobar Avances Reportados	3	📝 A crear

Total Story Points: 55 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 web
• MOBILE.yml - Especificaciones app móvil MOB-003 (Supervisor)

Pruebas

📋 Documentación de testing:

• TEST-PLAN.md - Plan de pruebas
• TEST-CASES.md - Casos de prueba
• MOBILE-TESTS.md - Tests de app móvil y modo offline

---

🔗 Referencias

• README: README.md - Descripción detallada de la épica
• Épica: ../../08-epicas/EPIC-MAI-005-control-obra.md
• Fase 1: ../README.md - Información de la fase completa
• Módulos relacionados:
  • MAI-002: Proyectos (dependencia - define obras)
  • MAI-003: Presupuestos (dependencia - define conceptos)
  • MAI-008: Estimaciones (bloqueado por este módulo)
  • MAI-011: INFONAVIT (bloqueado por este módulo)

---

📊 Métricas

Métrica	Valor
Presupuesto estimado	$30,000 MXN
Presupuesto target	$30,000 MXN ±5%
Story Points estimados	55 SP
Duración estimada	3 semanas (15 días)
Reutilización GAMILIT	15%
Componentes móviles	1 app (MOB-003 Supervisor)
RF a implementar	6/6
ET a implementar	6/6
US a completar	9/9

---

🎯 Módulos Afectados

Base de Datos

• Schema: progress_management
• Tablas principales: (~8 tablas)
  • progress_records - Registros de avance físico
  • progress_approvals - Autorizaciones de avances
  • schedules - Programas de obra (Gantt)
  • schedule_items - Partidas programadas
  • logbook - Bitácoras de obra
  • logbook_entries - Entradas de bitácora
  • progress_photos - Evidencia fotográfica
  • incidents - Incidencias de obra
• Funciones:
  • calculate_physical_progress() - Cálculo de avance físico
  • calculate_financial_progress() - Cálculo de avance financiero
  • get_s_curve_data() - Datos para curva S
  • detect_delays() - Detección automática de retrasos
• ENUMs:
  • progress_unit (percentage, quantity, volume, area, linear_meter)
  • progress_status (draft, submitted, approved, rejected)
  • logbook_entry_type (daily_report, incident, change_order, visitor, weather)
  • incident_severity (low, medium, high, critical)
  • incident_status (open, in_progress, resolved, closed)

Backend

• Módulo: progress
• Path: apps/backend/src/modules/progress/
• Services:
  • ProgressService - CRUD de avances
  • ProgressCalculatorService - Cálculo de avances físicos/financieros
  • ScheduleService - Gestión de programas de obra
  • LogbookService - Bitácora digital
  • IncidentService - Gestión de incidencias
  • PhotoService - Manejo de evidencia fotográfica
  • CurveSService - Generación de curva S
  • ApprovalService - Workflow de autorizaciones
• Controllers:
  • ProgressController - Endpoints de avances
  • LogbookController - Endpoints de bitácora
  • IncidentController - Endpoints de incidencias
  • ReportController - Generación de reportes
• Middlewares:
  • ProgressAuthGuard - Validación de permisos
  • ProjectAccessGuard - Validación de acceso a obra

Frontend Web

• Features: progress, logbook, reports
• Path: apps/frontend/src/features/
• Páginas:
  • /progress - Lista de avances
  • /progress/new - Captura de avance
  • /progress/compare - Comparativo programa vs real
  • /logbook - Bitácora de obra
  • /photos - Galería fotográfica
  • /reports/s-curve - Curva S
  • /reports/delays - Dashboard de retrasos
• Componentes:
  • ProgressForm - Formulario de captura de avance
  • ProgressList - Tabla de avances
  • GanttChart - Diagrama de Gantt (programa de obra)
  • CurveSChart - Gráfica de curva S
  • LogbookEditor - Editor de bitácora con rich text
  • PhotoGallery - Galería de fotos con filtros
  • IncidentCard - Tarjeta de incidencia
  • ApprovalWorkflow - Flujo de aprobaciones
  • ProgressDashboard - Dashboard de avances
• Stores:
  • progressStore - Estado de avances
  • logbookStore - Estado de bitácora
  • incidentStore - Estado de incidencias

App Móvil MOB-003 (Supervisor de Obra)

• Features: progress-capture, logbook-mobile, photo-capture
• Path: apps/mobile-supervisor/src/features/
• Pantallas:
  • Login de supervisor
  • Selector de obra/proyecto
  • Captura de avance por concepto
  • Registro de bitácora
  • Captura de fotos con geolocalización
  • Registro de incidencias
  • Sincronización de datos
• Componentes:
  • ProgressCaptureForm - Formulario móvil de avance
  • PhotoCamera - Captura de foto con GPS
  • LogbookQuickEntry - Entrada rápida de bitácora
  • OfflineIndicator - Indicador de estado de conexión
  • SyncQueue - Cola de sincronización
• Offline:
  • SQLite local para almacenamiento temporal
  • Cola de sincronización automática
  • Indicadores visuales de registros pendientes
• Sensores:
  • GPS para geolocalización de fotos
  • Cámara para evidencia fotográfica
  • Timestamp automático
• Librerías:
  • react-native-camera - Captura de fotos
  • @react-native-community/geolocation - GPS
  • expo-sqlite - Base de datos local
  • react-native-queue - Cola de sincronización

---

🔄 Flujo de Trabajo: RF→ET→US→Código

Ruta de Implementación

flowchart TD
    RF1[RF-CTL-001: Registro Avances Físicos] --> ET1[ET-CTL-001: Modelo de Datos]
    RF2[RF-CTL-002: Avances Financieros] --> ET1
    RF2 --> ET2[ET-CTL-002: Algoritmos Cálculo]
    RF3[RF-CTL-003: Bitácora Digital] --> ET3[ET-CTL-003: Bitácora y Firmas]
    RF4[RF-CTL-004: Recursos en Obra] --> ET4[ET-CTL-004: Recursos]
    RF5[RF-CTL-005: Comparativo] --> ET5[ET-CTL-005: Curva S]
    RF6[RF-CTL-006: Evidencia Fotográfica] --> ET6[ET-CTL-006: App Móvil]
    RF1 --> ET6
    RF3 --> ET6

    ET1 --> US1[US-CTL-001: Registro Avance Diario]
    ET5 --> US2[US-CTL-002: Comparativo]
    ET3 --> US3[US-CTL-003: Bitácora]
    ET6 --> US4[US-CTL-004: Evidencia Fotográfica]
    ET2 --> US5[US-CTL-005: Generar Estimación]
    ET5 --> US6[US-CTL-006: Curva S]
    ET2 --> US7[US-CTL-007: Dashboard Retrasos]
    ET4 --> US8[US-CTL-008: Incidencias]
    ET1 --> US9[US-CTL-009: Aprobar Avances]

    US1 --> CODE1[Código: ProgressService + ProgressForm]
    US2 --> CODE2[Código: GanttChart + Comparativo]
    US3 --> CODE3[Código: LogbookService + Editor]
    US4 --> CODE4[Código: PhotoService + Gallery]
    US5 --> CODE5[Código: EstimationGenerator]
    US6 --> CODE6[Código: CurveSChart + Analytics]
    US7 --> CODE7[Código: DelayDetector + Dashboard]
    US8 --> CODE8[Código: IncidentService + Form]
    US9 --> CODE9[Código: ApprovalWorkflow]

    CODE1 --> TEST1[Tests E2E: Registro completo]
    CODE6 --> TEST1
    CODE3 --> TEST2[Tests: Bitácora + Firmas]
    CODE4 --> TEST3[Tests: Offline + Sync]

---

📱 App Móvil MOB-003: Supervisor de Obra

Funcionalidades Principales

1. Captura de Avances en Campo

   • Selector de concepto/partida
   • Entrada de cantidad/porcentaje
   • Selección de cuadrilla/responsable
   • Notas y observaciones
   • Timestamp y GPS automáticos

2. Bitácora de Obra

   • Entrada rápida de eventos
   • Tipos: reporte diario, incidencia, orden de cambio, visita, clima
   • Adjuntar fotos
   • Firmas digitales (opcional)

3. Evidencia Fotográfica

   • Captura con geolocalización automática
   • Etiquetado por concepto/vivienda/zona
   • Modo galería con filtros
   • Compresión automática para sync

4. Registro de Incidencias

   • Nivel de severidad (bajo, medio, alto, crítico)
   • Asignación de responsable
   • Seguimiento de resolución
   • Timeline de eventos

5. Modo Offline

   • Almacenamiento local en SQLite
   • Cola de sincronización automática
   • Indicadores de registros pendientes
   • Resolución de conflictos (último gana)

Pantallas de App

Login
  ↓
Home (Selector de Obra)
  ├── Captura de Avance
  │     ├── Seleccionar Concepto
  │     ├── Ingresar Cantidad/Porcentaje
  │     ├── Agregar Notas
  │     └── Adjuntar Fotos
  ├── Bitácora
  │     ├── Nueva Entrada
  │     ├── Seleccionar Tipo
  │     ├── Capturar Contenido
  │     └── Firmas (opcional)
  ├── Galería de Fotos
  │     ├── Capturar Foto
  │     ├── Etiquetar
  │     └── Geolocalizar
  ├── Incidencias
  │     ├── Registrar Incidencia
  │     ├── Asignar Severidad
  │     └── Seguimiento
  └── Sincronización
        ├── Estado de Sync
        ├── Registros Pendientes
        └── Sincronizar Ahora

Validaciones en App

Validación	Descripción	Acción si falla
GPS	Verificar que la captura sea dentro del polígono de la obra	Advertencia, permitir override
Concepto válido	Concepto debe existir en presupuesto de la obra	Bloquear captura
Cantidad válida	No exceder cantidad total presupuestada	Advertencia
Fechas	Avance debe estar en rango de vigencia del proyecto	Bloquear captura
Duplicados	No permitir doble registro del mismo concepto en el mismo día	Advertencia, permitir override

Sincronización

Estrategia:

• Automática al detectar conexión estable
• Manual por botón "Sincronizar ahora"
• Prioridad: incidencias críticas > avances > fotos > bitácora
• Reintentos automáticos con backoff exponencial

Manejo de Conflictos:

• Regla: Último gana (last-write-wins)
• Excepciones: Incidencias críticas siempre se sincronizan, nunca se descartan
• Logs: Registrar conflictos en tabla sync_conflicts para auditoría

---

🔌 Integraciones

Internas (Módulos MAI)

Módulo	Integración	Dirección
MAI-002: Proyectos	Obtener obras activas	Consume
MAI-003: Presupuestos	Obtener conceptos/partidas presupuestadas	Consume
MAI-008: Estimaciones	Proveer avances para generar estimaciones	Provee
MAI-011: INFONAVIT	Proveer avance para reportes a INFONAVIT	Provee
MAI-007: RRHH	Obtener cuadrillas disponibles	Consume

Externas

Sistema	Integración	Propósito
Servicios de Mapas	Google Maps API / OpenStreetMap	Visualización de ubicaciones de obra
Almacenamiento Cloud	AWS S3 / Azure Blob Storage	Almacenamiento de fotos de alta resolución
Servicios de Firma Digital	DocuSign / Adobe Sign (opcional)	Firmas legales en bitácora

---

💡 Casos de Uso Clave

Caso 1: Registro de Avance de Cimentación

Contexto: Fraccionamiento de 100 viviendas. Concepto: "Plantilla de cimentación"

• Presupuesto: 100 viviendas × 50 m² = 5,000 m²
• Costo unitario: $150/m² = $750,000 total
• Programa: 20 viviendas/semana (5 semanas)

Flujo:

1. Residente abre app MOB-003
2. Selecciona obra "Fraccionamiento Los Pinos"
3. Selecciona concepto "Plantilla de cimentación"
4. Semana 1: Registra 25 viviendas completadas (1,250 m²)
   • Avance físico: 25% (1,250/5,000)
   • Avance financiero: $187,500
5. Toma 10 fotos de evidencia con GPS
6. Registra en bitácora: "Completadas viviendas 1-25. Clima favorable. Sin incidencias"
7. Datos se guardan en SQLite local (offline)
8. Al llegar a oficina, app sincroniza automáticamente
9. Superintendente aprueba avance desde web
10. Ingeniero genera estimación del periodo

Resultado:

• Avance físico acumulado: 25%
• Avance financiero: $187,500
• Variación vs programa: +5% (adelantado, se esperaban 20 viviendas)
• Estatus: Verde (dentro de presupuesto y tiempo)

---

Caso 2: Detección Automática de Retrasos

Contexto: Concepto "Instalación eléctrica" programado al 50% a la semana 10

Flujo:

1. Sistema ejecuta función detect_delays() cada noche
2. Compara avance programado (50%) vs real (35%)
3. Detecta retraso de 15%
4. Calcula impacto: 1.5 semanas de atraso proyectado
5. Genera alerta automática:
   • Nivel: Medio
   • Asigna a: Ingeniero responsable
   • Notifica a: Residente, Superintendente
6. Ingeniero revisa causas:
   • Falta de material (cable)
   • Cuadrilla reducida por incidencias
7. Ingeniero registra acción correctiva:
   • Acelerar entrega de material
   • Reforzar cuadrilla con 2 electricistas adicionales
8. Dashboard de retrasos muestra incidencia y acciones

Resultado:

• Detección temprana evita crecimiento del problema
• Trazabilidad de acciones correctivas
• Visibilidad para toda la cadena de mando

---

🚨 Puntos Críticos

1. Integridad de datos offline: Validar que datos capturados offline sean consistentes al sincronizar
2. Rendimiento con fotos: Compresión automática y carga en background para no bloquear UI
3. Autorizaciones de avances: Workflow estricto para evitar avances inflados
4. Cálculo de curva S: Debe ser preciso para toma de decisiones financieras
5. Geolocalización: GPS puede ser impreciso en zonas con edificios altos, permitir override manual
6. Firmas digitales: Cumplir con normativa legal mexicana (NOM-151-SCFI-2016)

---

🧪 Testing

Unit Tests (Backend)

describe('ProgressCalculatorService', () => {
  it('should calculate physical progress correctly')
  it('should calculate financial progress based on unit costs')
  it('should detect delays when actual < scheduled')
  it('should generate S-curve data points')
  it('should handle multiple units (%, m², m³, pza)')
})

describe('LogbookService', () => {
  it('should create logbook entry with timestamp')
  it('should validate digital signatures')
  it('should filter entries by date range')
  it('should export to PDF with signatures')
})

describe('PhotoService', () => {
  it('should store photo with GPS coordinates')
  it('should compress image to target size')
  it('should generate thumbnails automatically')
  it('should validate GPS within project polygon')
})

E2E Tests (App Móvil)

describe('Progress Capture E2E', () => {
  it('should complete full progress capture flow')
  it('should save progress offline when no connection')
  it('should sync pending records when connection restored')
  it('should show validation error for invalid quantity')
  it('should capture photo with GPS and attach to progress')
})

describe('Offline Mode E2E', () => {
  it('should work completely offline for 100+ records')
  it('should prioritize critical incidents in sync queue')
  it('should resolve conflicts with last-write-wins strategy')
  it('should show pending sync count in UI')
})

Integration Tests

describe('Progress Integration', () => {
  it('should integrate with MAI-003 for budget concepts')
  it('should provide data to MAI-008 for estimations')
  it('should trigger alerts when delays detected')
  it('should export logbook to PDF with signatures')
})

---

📋 Checklist de Implementación

Backend

• CRUD de avances con validaciones de negocio
• Servicio de cálculo de avance físico/financiero
• Algoritmo de detección de retrasos
• Servicio de generación de curva S
• API de bitácora con soporte de firmas digitales
• Servicio de fotos con compresión y GPS
• Workflow de autorizaciones
• Generación de reportes (PDF/Excel)

App Móvil MOB-003

• Login y autenticación
• Selector de obra/proyecto
• Formulario de captura de avance
• Editor de bitácora
• Captura de fotos con GPS
• Registro de incidencias
• Base de datos SQLite local
• Cola de sincronización
• Indicadores de estado offline/online
• Manejo de conflictos

Frontend Web

• Páginas de gestión de avances
• Componente de Gantt (programa de obra)
• Gráfica de curva S
• Dashboard de retrasos
• Editor de bitácora con rich text
• Galería fotográfica con filtros
• Workflow de autorizaciones
• Generación y descarga de reportes

Database

• Schema y tablas
• Funciones de cálculo
• Triggers de validación
• Índices optimizados
• Políticas RLS por constructora

Testing

• Unit tests >80% coverage
• E2E tests de flujo completo
• Tests de app móvil (offline, GPS, sync)
• Tests de carga (sync de 1000+ registros)
• Tests de integración con MAI-003 y MAI-008

Despliegue

• Variables de entorno
• Configuración de almacenamiento cloud (S3/Azure)
• Deploy de app a stores (TestFlight, Play Store)
• Monitoreo de sincronización
• Documentación de API

---

🎯 Siguiente Paso

Crear documentación de requerimientos funcionales y especificaciones técnicas del módulo, con especial énfasis en:

• RF-CTL-001: Especificación detallada de registro de avances (unidades, validaciones)
• RF-CTL-003: Requerimientos de bitácora digital y firmas electrónicas
• ET-CTL-002: Algoritmos de cálculo de avances y curva S
• ET-CTL-006: Arquitectura y especificaciones de app móvil MOB-003

---

Generado: 2025-12-06 Mantenedores: @tech-lead @backend-team @mobile-team @frontend-team @database-team Estado: 📝 A crear Prioridad: P0 - Crítico para operación de obra