rckrdmrd a9703b2727 Initial commit - erp-construccion

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

22 KiB

Raw Blame History

_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

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
Bitácora de Obra
- Entrada rápida de eventos
- Tipos: reporte diario, incidencia, orden de cambio, visita, clima
- Adjuntar fotos
- Firmas digitales (opcional)
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
Registro de Incidencias
- Nivel de severidad (bajo, medio, alto, crítico)
- Asignación de responsable
- Seguimiento de resolución
- Timeline de eventos
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:

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

Sistema ejecuta función detect_delays() cada noche
Compara avance programado (50%) vs real (35%)
Detecta retraso de 15%
Calcula impacto: 1.5 semanas de atraso proyectado
Genera alerta automática:
- Nivel: Medio
- Asigna a: Ingeniero responsable
- Notifica a: Residente, Superintendente
Ingeniero revisa causas:
- Falta de material (cable)
- Cuadrilla reducida por incidencias
Ingeniero registra acción correctiva:
- Acelerar entrega de material
- Reforzar cuadrilla con 2 electricistas adicionales
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

Integridad de datos offline: Validar que datos capturados offline sean consistentes al sincronizar
Rendimiento con fotos: Compresión automática y carga en background para no bloquear UI
Autorizaciones de avances: Workflow estricto para evitar avances inflados
Cálculo de curva S: Debe ser preciso para toma de decisiones financieras
Geolocalización: GPS puede ser impreciso en zonas con edificios altos, permitir override manual
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

22 KiB Raw Blame History Unescape Escape

_MAP: MAI-005 - Control de Obra

📋 Propósito

📁 Contenido

Requerimientos Funcionales (6)

Especificaciones Técnicas (6)

Historias de Usuario (9)

Implementación

Pruebas

🔗 Referencias

📊 Métricas

🎯 Módulos Afectados

Base de Datos

Backend

Frontend Web

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

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

Ruta de Implementación

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

Funcionalidades Principales

Pantallas de App

Validaciones en App

Sincronización

🔌 Integraciones

Internas (Módulos MAI)

Externas

💡 Casos de Uso Clave

Caso 1: Registro de Avance de Cimentación

Caso 2: Detección Automática de Retrasos

🚨 Puntos Críticos

🧪 Testing

Unit Tests (Backend)

E2E Tests (App Móvil)

Integration Tests

📋 Checklist de Implementación

Backend

App Móvil MOB-003

Frontend Web

Database

Testing

Despliegue

🎯 Siguiente Paso

22 KiB

Raw Blame History