# MAI-005: Control de Obra

**ID:** MAI-005
**Fase:** 1 - Alcance Inicial
**Presupuesto:** $35,000 MXN
**Story Points:** 52 SP
**Sprint:** Sprint 15-18 (Semanas 29-36)
**Prioridad:** P0
**Estado:** En documentación

---

## Resumen Ejecutivo

Este módulo gestiona el control integral de avances físicos y financieros en obra, desde la programación con ruta crítica hasta la captura de evidencias fotográficas geolocalizadas. Incluye herramientas avanzadas de seguimiento con Curva S, Earned Value Management (EVM), bitácora digital, checklists de calidad con firma digital y reportes oficiales para INFONAVIT.

### Problema que Resuelve

Las constructoras enfrentan desafíos críticos en el control de obra:
- Falta de visibilidad en tiempo real del avance físico vs programado
- Desviaciones no detectadas a tiempo en costo y tiempo
- Registro manual de avances propenso a errores y fraudes
- Evidencias fotográficas sin validación de ubicación o fecha
- Reportes tardíos o incompletos para clientes y INFONAVIT
- Falta de trazabilidad en inspecciones de calidad

**Sin este módulo:** Control en Excel desactualizado, avances reportados sin evidencia, desviaciones detectadas muy tarde, problemas en auditorías INFONAVIT.

**Con este módulo:** Seguimiento en tiempo real con métricas EVM, captura móvil geolocalizada, evidencias inmutables con hash SHA256, trazabilidad completa, reportes oficiales automatizados.

---

## Objetivos

1. **Programación con CPM:** Crear cronogramas con cálculo automático de ruta crítica
2. **Seguimiento EVM:** Medir desempeño con SPI/CPI y proyecciones de costo
3. **Captura móvil eficiente:** Registro de avances desde obra con geolocalización
4. **Documentación robusta:** Evidencias fotográficas verificables con marca de agua
5. **Control de calidad:** Checklists digitales con firma y gestión de No Conformidades
6. **Visibilidad ejecutiva:** Dashboard en tiempo real con KPIs y alertas automáticas
7. **Reportes oficiales:** Generación automática para INFONAVIT y clientes

---

## Alcance Funcional

### 1. Programación de Obra con Ruta Crítica

- Creación de cronogramas con actividades y dependencias
- Algoritmo Critical Path Method (CPM) para identificar actividades críticas
- Cálculo de holguras totales y libres
- Diagramas de Gantt interactivos
- Milestones con triggers de pago
- Reprogramaciones con control de versiones
- Baseline inmutable para comparación

### 2. Curva S y Earned Value Management

- Generación automática de snapshots diarios (CRON 23:00)
- Gráficas de líneas: Programado vs Real
- Cálculo de métricas EVM:
  - **PV** (Planned Value): Valor planificado
  - **EV** (Earned Value): Valor ganado
  - **AC** (Actual Cost): Costo real
  - **SPI** (Schedule Performance Index): Desempeño de tiempo
  - **CPI** (Cost Performance Index): Desempeño de costo
  - **EAC** (Estimate at Completion): Proyección de costo final
  - **VAC** (Variance at Completion): Varianza al completar
- Alertas si varianza >5% del presupuesto

### 3. Captura de Avances Físicos

- **Tres modos de registro:**
  - Por porcentaje: 45% → 70% (+25%)
  - Por cantidad: 225 m³ → 350 m³ (+125 m³)
  - Por unidad: Seleccionar lotes/viviendas individuales
- **App móvil React Native:**
  - Captura desde obra con interfaz intuitiva
  - Geolocalización automática con PostGIS
  - Validación de distancia del sitio (umbral 500m)
  - Fotos asociadas al avance
- **Modo offline robusto:**
  - Almacenamiento local en SQLite
  - Sincronización automática al recuperar conexión
  - Cola de sincronización con reintentos
  - Resolución de conflictos
- **Workflow de aprobación:**
  - Estados: Pendiente → Revisado → Aprobado/Rechazado
  - Validaciones automáticas de coherencia
  - Notificaciones a supervisores

### 4. Evidencias Fotográficas

- **Procesamiento automático:**
  - Marca de agua inmutable: "Proyecto | Lote | Fecha Hora"
  - Thumbnail 300x225 px para performance
  - Compresión JPEG calidad 85%
  - Hash SHA256 para verificación de integridad
- **Metadatos EXIF extraídos:**
  - Dispositivo, fecha original, coordenadas GPS
  - Altitud, orientación, flash, ISO, exposición
- **Georreferenciación PostGIS:**
  - Almacenamiento de coordenadas GPS
  - Mapa visual con pins por ubicación
  - Validación de ubicación en el sitio
- **Álbumes organizados:**
  - Por proyecto, etapa, fecha o tema
  - Exportación a PDF con galería
  - Exportación ZIP de fotos seleccionadas

### 5. Bitácora Digital de Obra

- Registro diario de eventos en obra
- Categorías: Avance, Incidencia, Clima, Visita
- Multimedia: Fotos, videos, grabaciones de voz
- Geolocalización automática
- Timeline visual por proyecto
- Exportación a PDF para reportes oficiales

### 6. Checklists de Calidad

- **Templates configurables:**
  - Items de tipo: Boolean, Numérico, Texto, Foto obligatoria
  - Tolerancias para mediciones (10 ± 1 cm)
  - Valores de referencia normativos
- **Registro de No Conformidades (NC):**
  - Severidad: Menor, Mayor, Crítica
  - Acción correctiva propuesta
  - Responsable y fecha límite
  - Seguimiento de cierre con fotos de verificación
- **Firma digital:**
  - Canvas para dibujar firma con dedo/mouse
  - Timestamp y hash del documento
  - PDF generado con firma visible
- **Cálculo de compliance:**
  - % = (Items conformes / Total items) × 100
  - Semáforos: Verde ≥95%, Amarillo 80-94%, Rojo <80%

### 7. Dashboard en Tiempo Real

- **KPIs principales:**
  - Avance físico, financiero, tiempo transcurrido
  - SPI, CPI con colores según umbral
  - Varianzas de costo y tiempo
- **Curva S interactiva:** Chart.js con zoom y tooltips
- **Mapa de calor de unidades:**
  - Bloques por unidad con gradiente de color
  - Verde (100%), Amarillo (50-99%), Rojo (0-49%)
- **Panel de alertas:**
  - Críticas, Advertencias, Informativas
  - Acciones sugeridas
- **Widgets configurables:** Drag & drop con react-grid-layout
- **Actualización WebSocket:** Push en tiempo real

### 8. Reportes Oficiales

**Tipos de reportes:**
- **INFONAVIT:** Formato oficial con secciones obligatorias
- **Ejecutivo:** Resumen para dirección (5-10 páginas)
- **Calidad:** Checklists, NCs, inspecciones
- **Financiero:** Avance financiero vs presupuesto
- **Productividad:** Análisis de cuadrillas y rendimientos
- **Fotográfico:** Álbum de evidencias

**Características:**
- Firma digital con canvas
- Hash del documento para verificación
- Generación a PDF con PDFKit
- Exportación a Excel con ExcelJS
- Envío automático programado (diario, semanal, mensual)
- Historial con tracking de descargas

---

## Reutilización del Core ERP

**Nivel de Reutilización:** 0% - Módulo vertical 100% específico de construcción

Este módulo es completamente específico de la industria de la construcción y no reutiliza componentes del core ERP genérico. Sin embargo, se integra con los módulos base del vertical:

**Dependencias internas:**
- Utiliza autenticación y autorización de MAI-001
- Consume estructura de proyectos de MAI-002
- Lee presupuestos y partidas de MAI-003
- Provee datos para MAI-004 (Compras) en consumo de materiales

**Justificación:**
Los requerimientos de control de obra con CPM, EVM, geolocalización GPS, evidencias fotográficas con hash SHA256, checklists de calidad con firma digital y reportes INFONAVIT son únicos del sector construcción y no aplican a otros verticales.

---

## Requerimientos Funcionales

### RF-OBRA-001: Programación de Obra y Curva S
**Descripción:** Sistema de programación con Critical Path Method (CPM) y seguimiento con Curva S y Earned Value Management (EVM).

**Funcionalidades:**
- CRUD de cronogramas con actividades y dependencias
- Algoritmo CPM para cálculo de ruta crítica
- Generación automática de snapshots de Curva S
- Métricas EVM (PV, EV, AC, SPI, CPI, EAC, VAC)
- Diagramas de Gantt interactivos
- Reprogramaciones con control de versiones

**Documento:** [RF-OBRA-001](./requerimientos/RF-OBRA-001-programacion-curva-s.md)

### RF-OBRA-002: Captura de Avances Físicos
**Descripción:** Captura de avances desde app móvil con geolocalización, modo offline y workflow de aprobación.

**Funcionalidades:**
- Captura por porcentaje, cantidad o unidad
- App React Native con SQLite offline
- Geolocalización PostGIS con validación de radio
- Sincronización automática con cola de reintentos
- Workflow de aprobación multinivel
- Actualización automática de métricas

**Documento:** [RF-OBRA-002](./requerimientos/RF-OBRA-002-captura-avances-fisicos.md)

### RF-OBRA-003: Evidencias Fotográficas y Checklists
**Descripción:** Gestión de evidencias fotográficas geolocalizadas con marca de agua inmutable y checklists de calidad con firma digital.

**Funcionalidades:**
- Procesamiento automático con marca de agua
- Hash SHA256 para integridad
- Metadatos EXIF y georreferenciación PostGIS
- Templates de checklists configurables
- Gestión de No Conformidades (NC)
- Firma digital con canvas
- Exportación a PDF y ZIP

**Documento:** [RF-OBRA-003](./requerimientos/RF-OBRA-003-evidencias-checklists.md)

### RF-OBRA-004: Dashboard y Reportes de Avances
**Descripción:** Dashboard ejecutivo en tiempo real con WebSocket y generación de reportes oficiales con firma digital.

**Funcionalidades:**
- KPIs en tiempo real (físico, financiero, SPI, CPI)
- Curva S interactiva con Chart.js
- Mapa de calor de unidades
- Panel de alertas categorizadas
- Widgets configurables drag & drop
- Generación de reportes PDF/Excel
- Firma digital y hash de documentos
- Envío automático programado

**Documento:** [RF-OBRA-004](./requerimientos/RF-OBRA-004-dashboard-reportes-avances.md)

---

## Integración con App Móvil

### MOB-003: App Supervisor de Obra

Este módulo se integra completamente con la aplicación móvil **MOB-003: App Supervisor de Obra**, diseñada para residentes y supervisores de obra.

**Funcionalidades móviles:**
- **F-MOB003-01:** Captura de avances (8 SP)
  - Registro de % avance por concepto
  - Tres modos: Porcentaje, Cantidad, Por unidad
  - Asociación automática a actividades del cronograma

- **F-MOB003-02:** Fotos geoetiquetadas (5 SP)
  - Evidencia con GPS embebido (PostGIS)
  - Marca de agua automática
  - Hash SHA256 para integridad

- **F-MOB003-03:** Checklist de inspección (4 SP)
  - Listas de verificación configurables
  - Firma digital en dispositivo móvil
  - Registro de No Conformidades

- **F-MOB003-04:** Bitácora digital (4 SP)
  - Registro de notas diarias
  - Multimedia: Fotos, videos, voz
  - Categorización de eventos

- **F-MOB003-05:** Modo offline (4 SP)
  - Trabajo sin conexión con SQLite
  - Sincronización automática
  - Resolución de conflictos

**Stack tecnológico móvil:**
- React Native 0.73+ con Expo 50
- TypeScript 5.3+
- WatermelonDB para almacenamiento offline
- expo-camera para fotos con EXIF
- expo-location para GPS
- Zustand para state management

**Documento de referencia:** [EPIC-MAI-019: Apps Móviles](../../08-epicas/EPIC-MAI-019-mobile-apps.md)

---

## Dependencias con Otros Módulos

### MAI-001: Fundamentos (Autenticación y Autorización)
**Relación:** Consume servicios de autenticación
**Datos compartidos:**
- Usuarios con roles (Residente, Jefe de Proyecto, Director)
- Sesiones JWT para API y WebSocket
- Permisos por acción (crear, aprobar, firmar)

### MAI-002: Proyectos y Estructura
**Relación:** Consume estructura de proyectos
**Datos compartidos:**
- Proyectos activos con ubicación GPS
- Unidades/lotes con identificadores únicos
- Etapas de construcción
- Cuadrillas y personal asignado

### MAI-003: Presupuestos y Costos
**Relación:** Lee presupuestos y actualiza costos reales
**Datos compartidos:**
- Catálogo de partidas presupuestales
- Cantidades y precios unitarios
- Presupuesto total por proyecto (BAC para EVM)
- Costos reales ejecutados (AC para EVM)

### MAI-004: Compras e Inventarios (Opcional)
**Relación:** Compara materiales consumidos vs presupuesto
**Datos compartidos:**
- Consumo de materiales por actividad
- Validación de órdenes vs avances
- Alertas de desviaciones de costo

### MAE-014: Finanzas (Indirecto)
**Relación:** Provee métricas financieras
**Datos compartidos:**
- Flujo de caja por proyecto
- Proyecciones de costos (EAC)
- Varianzas financieras (VAC)

---

## Arquitectura del Módulo

### Diagrama de Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                        FRONTEND WEB                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Dashboard   │  │  Programación│  │   Reportes   │          │
│  │   React +    │  │   CPM/Gantt  │  │   PDF/Excel  │          │
│  │  Chart.js    │  │  react-gantt │  │    jsPDF     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│         ▲                  ▲                  ▲                  │
│         │                  │                  │                  │
│         └──────────────────┴──────────────────┘                 │
│                            │                                     │
│                     WebSocket (Socket.io)                        │
│                            │                                     │
└────────────────────────────┼─────────────────────────────────────┘
                             │
┌────────────────────────────┼─────────────────────────────────────┐
│                        BACKEND NESTJS                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Schedule    │  │   Progress   │  │   Evidence   │          │
│  │   Service    │  │    Service   │  │    Service   │          │
│  │   (CPM/EVM)  │  │  (Approval)  │  │  (Photos/QC) │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│         │                  │                  │                  │
│         ├──────────────────┼──────────────────┤                 │
│         │                  │                  │                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ CPM Algorithm│  │  Sync Queue  │  │  Image Proc  │          │
│  │  Calculator  │  │   (BullMQ)   │  │   (Sharp)    │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│         │                  │                  │                  │
│         ▼                  ▼                  ▼                  │
└─────────────────────────────────────────────────────────────────┘
                             │
┌────────────────────────────┼─────────────────────────────────────┐
│                     POSTGRESQL 15+                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   schedules  │  │   progress   │  │   evidence   │          │
│  │  (CPM, S-    │  │  (Records,   │  │  (Photos,    │          │
│  │   Curve)     │  │   Approval)  │  │  Checklists) │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│         │                  │                  │                  │
│         │         PostGIS Extension          │                  │
│         │         (Geolocation)               │                  │
│         │                                     │                  │
│  ┌──────────────────────────────────────────────────┐          │
│  │            analytics (KPIs, Alerts)              │          │
│  └──────────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                             │
┌────────────────────────────┼─────────────────────────────────────┐
│                  MOBILE APP (React Native)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Progress    │  │  Camera +    │  │  Checklist   │          │
│  │  Capture     │  │  GPS Geo     │  │  + Signature │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│         │                  │                  │                  │
│         ▼                  ▼                  ▼                  │
│  ┌────────────────────────────────────────────────┐            │
│  │          SQLite (Offline Storage)              │            │
│  │          + Sync Queue (WatermelonDB)           │            │
│  └────────────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────────────┘
                             │
┌────────────────────────────┼─────────────────────────────────────┐
│                    STORAGE (AWS S3 / GCS)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Original   │  │  Thumbnails  │  │    PDFs      │          │
│  │    Photos    │  │  (300x225)   │  │  (Reports)   │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
```

### Schema de Base de Datos

**Schemas principales:**
- `schedules` - Programación, actividades, Curva S, milestones
- `progress` - Registros de avance, aprobaciones, batch updates, offline sync
- `evidence` - Fotos, checklists, templates, álbumes, NCs
- `analytics` - KPIs, alertas, productividad, widgets, reportes

**Tablas clave:**
```sql
schedules
  → schedule_activities (CPM: ES, EF, LS, LF, total_float, is_critical_path)
  → milestones (payment_trigger, planned_date, actual_date)
  → s_curve_snapshots (planned_pct, actual_pct, spi, cpi, eac, vac)

progress_records
  → unit_progress (percent_complete, start_date, completion_date)
  → offline_sync_queue (device_id, local_id, payload JSONB, sync_status)
  → approval_workflows (levels JSONB, applies_to_activities[])

photos (sha256_hash, geolocation POINT, exif_data JSONB, has_watermark)
quality_checklists (items JSONB, compliance_percent, signature_data, pdf_path)

kpi_metrics (physical_progress, spi, cpi, eac, etc, vac, critical_alerts)
alerts (severity, related_entity_type, actions_taken JSONB)
```

**Features de PostgreSQL:**
- PostGIS POINT para coordenadas GPS
- JSONB para items flexibles (actividades, checklists)
- Triggers para actualización automática de estados
- Stored procedures para cálculo de CPM, EVM, compliance
- Materialized views para performance (dashboard summary)
- Full-text search en descripciones y notas

---

## Stack Tecnológico

### Backend
```yaml
framework: NestJS 10+
language: TypeScript 5+
database: PostgreSQL 15+ (schemas: schedules, progress, evidence, analytics)
extensions: PostGIS para geolocalización
orm: TypeORM con migraciones
async_processing: Bull/BullMQ para batch updates y sync offline
scheduler: node-cron para snapshots diarios (23:00)
image_processing: Sharp para compresión y watermark
metadata: ExifReader para metadatos EXIF
hashing: crypto (SHA256) para integridad
pdf_generation: PDFKit
excel_export: ExcelJS
email: SendGrid / AWS SES
real_time: WebSocket (Socket.io)
storage: AWS S3 / Google Cloud Storage
```

### Frontend Web
```yaml
framework: React 18
language: TypeScript
state: Zustand
data_fetching: React Query (cache y sincronización)
charts: Chart.js / Recharts para Curva S y KPIs
gantt: react-gantt-chart para diagramas
maps: Leaflet para geolocalización
file_upload: react-dropzone
signature: react-signature-canvas
grid: react-grid-layout para widgets drag&drop
websocket: Socket.io-client
dates: date-fns
pdf_client: jsPDF
```

### Mobile App
```yaml
framework: React Native 0.73+
platform: Expo 50
language: TypeScript
offline_db: SQLite con WatermelonDB
sync: Background fetch + Queue
network_detection: NetInfo
camera: expo-camera con EXIF
geolocation: expo-location
file_system: expo-file-system / react-native-fs
local_storage: AsyncStorage
state: Zustand
```

### Infraestructura
```yaml
containers: Docker + Docker Compose
orchestration: Kubernetes (producción)
storage: AWS S3 / Google Cloud Storage
cdn: CloudFront / Cloud CDN
monitoring: Prometheus + Grafana
logging: Winston + ELK Stack
ci_cd: GitHub Actions / GitLab CI
```

---

## Flujos de Trabajo

### Flujo 1: Creación de Programa de Obra

```
1. [Director] Crea cronograma nuevo
2. [Director] Agrega actividades con duración, dependencias y lag
3. [Sistema] Ejecuta algoritmo CPM:
   - Forward Pass: Calcula ES (Earliest Start), EF (Earliest Finish)
   - Backward Pass: Calcula LS (Latest Start), LF (Latest Finish)
   - Float Calculation: TF = LF - EF, FF = min(ES[successors]) - EF
   - Identifica Critical Path: actividades donde TF == 0
4. [Director] Envía para aprobación
5. [Jefe] Aprueba → Estado: Active, isBaseline: true (v1)
6. [Sistema] Genera snapshot inicial de Curva S
```

### Flujo 2: Captura y Aprobación de Avances

```
1. [Residente] (App Móvil):
   - Selecciona proyecto y actividad
   - Captura % avance o cantidad
   - Toma fotos con GPS automático
   - Envía (online) o guarda en SQLite (offline)

2. [Sistema] (Sincronización si offline):
   - Al recuperar conexión, detecta registros pendientes
   - Cola BullMQ procesa registros
   - Sube fotos a S3/GCS
   - Marca como synced

3. [Jefe de Proyecto] (Web):
   - Recibe notificación de avance pendiente
   - Abre detalle con validaciones automáticas:
     * Incremento de % coherente
     * Fotos geolocalizadas en el sitio
     * Sin duplicados
   - Aprueba o Rechaza con motivo

4. [Sistema] (Al aprobar):
   - Actualiza schedule_activity.percent_complete
   - Actualiza unit_progress.percent_complete
   - Recalcula KPIs (físico, SPI, CPI, EAC)
   - Genera snapshot de Curva S (si aplica)
   - Emite evento WebSocket → Dashboard se actualiza en vivo
```

### Flujo 3: Inspección con Checklist de Calidad

```
1. [Residente] Selecciona template de checklist (ej: "Acabados Vivienda")
2. [Residente] Completa items uno por uno:
   - Boolean: ¿Pintura uniforme? ✅
   - Numérico: Espesor de piso = 10.2 cm (tolerancia: 10 ± 1) ✅
   - Foto: Toma foto de evidencia
3. [Residente] Registra No Conformidades (NC) si encuentra:
   - Severidad: Mayor
   - Descripción: "Grietas en muro norte"
   - Acción correctiva: "Resanar y repintar"
   - Responsable: Juan Pérez
   - Fecha límite: 2025-12-10
4. [Residente] Dibuja firma digital en canvas
5. [Sistema]:
   - Calcula compliance_percent = (conformes / total) × 100
   - Genera timestamp y hash del documento
   - Genera PDF con firma visible
   - Almacena en S3/GCS
6. [Jefe] Recibe notificación de NC y da seguimiento
```

### Flujo 4: Generación de Reporte Oficial INFONAVIT

```
1. [Director] Selecciona "Generar Reporte INFONAVIT"
2. [Director] Configura:
   - Período: 2025-12-01 a 2025-12-31
   - Formato: PDF
   - Secciones: Carátula, Resumen, Avance por Etapa, Curva S, Fotos
   - Requiere firma: Sí
3. [Sistema] (Background job):
   - Ejecuta queries SQL para recopilar datos
   - Calcula KPIs y métricas EVM
   - Genera gráficas (Chart.js server-side con node-canvas)
   - Procesa fotografías seleccionadas
   - Compila PDF con PDFKit
4. [Director] Recibe notificación "Reporte listo para firma"
5. [Director] Dibuja firma digital en canvas
6. [Sistema]:
   - Captura firma Base64 + timestamp
   - Calcula hash SHA256 del documento completo
   - Inserta firma en PDF
   - Sube a S3/GCS
7. [Sistema] Envía por email a contactos de INFONAVIT (si configurado)
8. [Sistema] Guarda registro en reports_generated con tracking
```

---

## Roles y Permisos

| Rol | Permisos |
|-----|----------|
| **Residente de Obra** | Capturar avances móvil, tomar fotos, crear checklists, bitácora |
| **Jefe de Proyecto** | Crear cronogramas, aprobar avances, ver dashboard, generar reportes ejecutivos |
| **Director de Proyecto** | Aprobar programas, autorizar reprogramaciones, firmar reportes oficiales |
| **Inspector de Calidad** | Crear templates de checklists, registrar NCs, dar seguimiento |
| **Finanzas** | Ver métricas EVM (AC, EAC, VAC), exportar datos financieros |
| **Cliente/INFONAVIT** | Consultar reportes oficiales, ver galería de fotos (solo lectura) |

---

## Indicadores Clave (KPIs)

### KPIs del Sistema

1. **Eficiencia en Programación**
   - Tiempo promedio para aprobar programa: <48h
   - % Programas con ruta crítica identificada: 100%
   - Precisión de proyecciones de término: ±5 días

2. **Adopción de Captura Móvil**
   - % Avances registrados desde app: >90%
   - % Registros con geolocalización: >95%
   - % Sincronizaciones exitosas (offline): >98%

3. **Calidad de Evidencias**
   - % Fotos con metadatos EXIF completos: >95%
   - % Fotos georreferenciadas: >90%
   - % Checklists completados con firma: 100%

4. **Exactitud de Seguimiento**
   - Diferencia Curva S proyectada vs real: <5%
   - % Avances aprobados en <24h: >80%
   - % Alertas críticas atendidas en <48h: >90%

5. **Generación de Reportes**
   - Tiempo de generación de reporte: <60s
   - % Reportes entregados a tiempo: >95%
   - % Reportes con firma digital: 100% (oficiales)

### Métricas EVM

- **SPI** (Schedule Performance Index): >0.95 (verde), 0.85-0.95 (amarillo), <0.85 (rojo)
- **CPI** (Cost Performance Index): >0.95 (verde), 0.85-0.95 (amarillo), <0.85 (rojo)
- **VAC** (Variance at Completion): Alerta si >5% del presupuesto

---

## Puntos Críticos

1. **Complejidad del algoritmo CPM**
   - Riesgo: Cálculos incorrectos de ruta crítica
   - Mitigación: Algoritmo probado con tests extensivos, casos edge documentados

2. **Sincronización offline**
   - Riesgo: Pérdida de datos o duplicados
   - Mitigación: Cola robusta con reintentos, resolución de conflictos, SQLite transaccional

3. **Performance con miles de fotos**
   - Riesgo: Lentitud en carga de galería
   - Mitigación: Thumbnails, lazy loading, paginación, CDN

4. **Validación de geolocalización**
   - Riesgo: Registros falsos desde fuera del sitio
   - Mitigación: Validación PostGIS de radio, alertas de ubicaciones sospechosas

5. **Integridad de evidencias**
   - Riesgo: Manipulación de fotos o documentos
   - Mitigación: Hash SHA256, marca de agua inmutable, firma digital con timestamp

---

## Documentos Relacionados

### Requerimientos Funcionales
- [RF-OBRA-001: Programación de Obra y Curva S](./requerimientos/RF-OBRA-001-programacion-curva-s.md)
- [RF-OBRA-002: Captura de Avances Físicos](./requerimientos/RF-OBRA-002-captura-avances-fisicos.md)
- [RF-OBRA-003: Evidencias Fotográficas y Checklists](./requerimientos/RF-OBRA-003-evidencias-checklists.md)
- [RF-OBRA-004: Dashboard y Reportes de Avances](./requerimientos/RF-OBRA-004-dashboard-reportes-avances.md)

### Especificaciones Técnicas
- [ET-OBRA-001: Implementación de Programación y Curva S](./especificaciones/ET-OBRA-001-implementacion-programacion-curva-s.md)
- [ET-OBRA-002: Implementación de Captura de Avances](./especificaciones/ET-OBRA-002-implementacion-captura-avances.md)
- [ET-OBRA-003: Implementación de Evidencias y Checklists](./especificaciones/ET-OBRA-003-implementacion-evidencias-checklists.md)
- [ET-OBRA-004: Implementación de Dashboard y Reportes](./especificaciones/ET-OBRA-004-implementacion-dashboard-reportes.md)

### Historias de Usuario
- [US-OBRA-001: Crear Programa de Obra con Ruta Crítica](./historias-usuario/US-OBRA-001-crear-programa-obra.md) - 8 SP
- [US-OBRA-002: Seguimiento con Curva S y Earned Value](./historias-usuario/US-OBRA-002-seguimiento-curva-s.md) - 5 SP
- [US-OBRA-003: Capturar Avances desde Obra](./historias-usuario/US-OBRA-003-capturar-avances-obra.md) - 8 SP
- [US-OBRA-004: Aprobar Avances con Flujo de Validación](./historias-usuario/US-OBRA-004-aprobar-avances.md) - 5 SP
- [US-OBRA-005: Gestión de Evidencias Fotográficas](./historias-usuario/US-OBRA-005-evidencias-fotograficas.md) - 8 SP
- [US-OBRA-006: Checklists de Calidad](./historias-usuario/US-OBRA-006-checklists-calidad.md) - 5 SP
- [US-OBRA-007: Dashboard Ejecutivo en Tiempo Real](./historias-usuario/US-OBRA-007-dashboard-ejecutivo.md) - 8 SP
- [US-OBRA-008: Generación de Reportes Oficiales](./historias-usuario/US-OBRA-008-reportes-oficiales.md) - 5 SP

### Referencias Técnicas
- [RESUMEN ÉPICA MAI-005](../../02-definicion-modulos/MAI-005-control-obra-avances/RESUMEN-EPICA-MAI-005.md)
- [EPIC-MAI-019: Apps Móviles](../../08-epicas/EPIC-MAI-019-mobile-apps.md)
- [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml)

---

## Estimación y Planificación

### Distribución por Sprint

**Sprint 15 (13 SP):** Programación CPM + Curva S + EVM
- US-OBRA-001: Crear Programa de Obra (8 SP)
- US-OBRA-002: Seguimiento con Curva S (5 SP)

**Sprint 16 (13 SP):** Captura móvil + Aprobaciones
- US-OBRA-003: Capturar Avances desde Obra (8 SP)
- US-OBRA-004: Aprobar Avances (5 SP)

**Sprint 17 (13 SP):** Evidencias fotográficas + Checklists QC
- US-OBRA-005: Evidencias Fotográficas (8 SP)
- US-OBRA-006: Checklists de Calidad (5 SP)

**Sprint 18 (13 SP):** Dashboard + Reportes oficiales
- US-OBRA-007: Dashboard Ejecutivo (8 SP)
- US-OBRA-008: Reportes Oficiales (5 SP)

**Total:** 52 Story Points en 4 sprints (8 semanas)

### Equipo Sugerido

- 2 Backend developers (NestJS + PostgreSQL + PostGIS)
- 1 Mobile developer (React Native + SQLite)
- 2 Frontend developers (React + Chart.js + WebSocket)
- 1 QA engineer
- 1 Product Owner (medio tiempo)

---

## Riesgos y Mitigaciones

| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|--------------|---------|------------|
| Complejidad del algoritmo CPM | Media | Alto | Algoritmo probado, tests extensivos con casos edge |
| Sincronización offline | Media | Medio | Cola con reintentos, SQLite robusto, WatermelonDB |
| Performance con miles de fotos | Media | Medio | Thumbnails, lazy loading, paginación, CDN |
| Cálculo de EVM incorrecto | Baja | Alto | Validación con experto PMI, tests unitarios |
| WebSocket desconexiones | Media | Bajo | Reconexión automática, fallback a polling |
| Manipulación de evidencias | Baja | Alto | Hash SHA256, marca de agua, firma digital |

---

## Próximos Pasos

### Implementación
1. ✅ Documentación completa
2. Sprint Planning con equipo
3. Setup de infraestructura (BD con PostGIS, storage S3/GCS)
4. Sprint 15: Programación CPM y Curva S
5. Sprint 16: Captura móvil y aprobaciones
6. Sprint 17: Evidencias fotográficas y checklists
7. Sprint 18: Dashboard y reportes
8. Testing integral y UAT
9. Capacitación a usuarios (residentes, jefes, directores)
10. Go-live escalonado (1 proyecto piloto)

### Integraciones Futuras
- BI avanzado con Power BI / Tableau
- Integración con drones para fotogrametría aérea
- Machine learning para predicción de retrasos
- App móvil nativa (Swift/Kotlin) para mejor performance
- Integración con BIM (Building Information Modeling)
- Exportación a MS Project / Primavera P6

---

**Generado:** 2025-12-06
**Estado:** Documentado
**Mantenedores:** @tech-lead @backend-team @frontend-team @mobile-team
