579 lines
22 KiB
Markdown
579 lines
22 KiB
Markdown
# _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](./requerimientos/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](./requerimientos/RF-CTL-002-avances-financieros.md) | Cálculo de Avances Financieros | 📝 A crear |
|
||
| RF-CTL-003 | [RF-CTL-003-bitacora-digital.md](./requerimientos/RF-CTL-003-bitacora-digital.md) | Bitácora Digital de Obra | 📝 A crear |
|
||
| RF-CTL-004 | [RF-CTL-004-gestion-recursos-obra.md](./requerimientos/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](./requerimientos/RF-CTL-005-comparativo-programa-real.md) | Comparativo Programa vs Real | 📝 A crear |
|
||
| RF-CTL-006 | [RF-CTL-006-evidencia-fotografica.md](./requerimientos/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](./especificaciones/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](./especificaciones/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](./especificaciones/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](./especificaciones/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](./especificaciones/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](./especificaciones/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](./historias-usuario/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](./historias-usuario/US-CTL-002-comparativo-programa-real.md) | Ver Comparativo Programa vs Real | 8 | 📝 A crear |
|
||
| US-CTL-003 | [US-CTL-003-bitacora-obra.md](./historias-usuario/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](./historias-usuario/US-CTL-004-evidencia-fotografica.md) | Capturar Evidencia Fotográfica de Avances | 5 | 📝 A crear |
|
||
| US-CTL-005 | [US-CTL-005-generar-estimacion.md](./historias-usuario/US-CTL-005-generar-estimacion.md) | Generar Estimación de Periodo | 8 | 📝 A crear |
|
||
| US-CTL-006 | [US-CTL-006-curva-s-avance.md](./historias-usuario/US-CTL-006-curva-s-avance.md) | Visualizar Curva S de Avance | 8 | 📝 A crear |
|
||
| US-CTL-007 | [US-CTL-007-dashboard-retrasos.md](./historias-usuario/US-CTL-007-dashboard-retrasos.md) | Dashboard de Retrasos e Incidencias | 5 | 📝 A crear |
|
||
| US-CTL-008 | [US-CTL-008-registrar-incidencias.md](./historias-usuario/US-CTL-008-registrar-incidencias.md) | Registrar Incidencias de Obra | 5 | 📝 A crear |
|
||
| US-CTL-009 | [US-CTL-009-aprobar-avances.md](./historias-usuario/US-CTL-009-aprobar-avances.md) | Aprobar Avances Reportados | 3 | 📝 A crear |
|
||
|
||
**Total Story Points:** 55 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 web
|
||
- [MOBILE.yml](./implementacion/MOBILE.yml) - Especificaciones app móvil MOB-003 (Supervisor)
|
||
|
||
### 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
|
||
- [MOBILE-TESTS.md](./pruebas/MOBILE-TESTS.md) - Tests de app móvil y modo offline
|
||
|
||
---
|
||
|
||
## 🔗 Referencias
|
||
|
||
- **README:** [README.md](./README.md) - Descripción detallada de la épica
|
||
- **Épica:** [../../08-epicas/EPIC-MAI-005-control-obra.md](../../08-epicas/EPIC-MAI-005-control-obra.md)
|
||
- **Fase 1:** [../README.md](../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
|
||
|
||
```mermaid
|
||
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)
|
||
|
||
```typescript
|
||
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)
|
||
|
||
```typescript
|
||
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
|
||
|
||
```typescript
|
||
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
|