282 lines
16 KiB
Markdown
282 lines
16 KiB
Markdown
# US-PROG-004: Aprobar Avances con Flujo de Validación
|
|
|
|
**Épica:** MAI-005 - Control de Obra y Avances
|
|
**Sprint:** 16
|
|
**Story Points:** 5
|
|
**Prioridad:** Alta
|
|
**Asignado a:** Backend + Frontend
|
|
|
|
---
|
|
|
|
## Historia de Usuario
|
|
|
|
**Como** Jefe de Proyecto
|
|
**Quiero** revisar y aprobar los avances reportados por los residentes de obra
|
|
**Para** asegurar que los datos reflejen el estado real del proyecto antes de actualizar la Curva S
|
|
|
|
---
|
|
|
|
## Criterios de Aceptación
|
|
|
|
### 1. Panel de Aprobaciones Pendientes ✅
|
|
- [ ] Puedo ver lista de registros de avance pendientes de aprobación
|
|
- [ ] Para cada registro veo:
|
|
- Código: AVN-2025-00123
|
|
- Fecha de registro
|
|
- Actividad: ACT-025 - Cimentación
|
|
- Registrado por: Juan Pérez (Residente)
|
|
- % Anterior → % Actual: 45% → 70% (+25%)
|
|
- Cantidad: 225 m³ → 350 m³ (+125 m³)
|
|
- Cuadrilla: Cimiento 1
|
|
- Horas-hombre: 16 hrs
|
|
- Fotos: 3
|
|
- Ubicación: 📍 Dentro del sitio
|
|
- [ ] Puedo filtrar por:
|
|
- Proyecto
|
|
- Fecha (rango)
|
|
- Actividad
|
|
- Residente que registró
|
|
- [ ] Puedo ordenar por fecha, actividad, % de avance
|
|
|
|
### 2. Revisar Detalle del Registro ✅
|
|
- [ ] Puedo hacer clic en un registro para ver detalle completo
|
|
- [ ] Veo información ampliada:
|
|
- Comparativo visual: antes vs después
|
|
- Gráfica de barras mostrando incremento
|
|
- Mapa con ubicación GPS del registro
|
|
- Galería de fotos con zoom
|
|
- Metadatos EXIF de cada foto
|
|
- Notas y observaciones del residente
|
|
- [ ] Puedo ver historial de avances anteriores de la misma actividad
|
|
|
|
### 3. Validaciones Automáticas ✅
|
|
- [ ] El sistema muestra alertas automáticas si detecta:
|
|
- ⚠️ Incremento > 20% en un día (inusual)
|
|
- ⚠️ Avance reportado fuera del horario laboral
|
|
- ⚠️ Geolocalización fuera del radio del proyecto
|
|
- ⚠️ No hay fotos adjuntas (si son requeridas)
|
|
- ⚠️ Cantidad excede lo presupuestado
|
|
- [ ] Las alertas son advertencias, no bloqueos (puedo aprobar de todas formas)
|
|
|
|
### 4. Aprobar Registro ✅
|
|
- [ ] Puedo hacer clic en botón "Aprobar"
|
|
- [ ] Puedo agregar notas de aprobación (opcional)
|
|
- [ ] Al aprobar:
|
|
- El registro cambia de estado: submitted → approved
|
|
- Se actualiza el % de la actividad en el programa de obra
|
|
- Se actualiza el avance de la unidad (si aplica)
|
|
- Se recalcula la Curva S automáticamente
|
|
- Se genera snapshot nuevo si es necesario
|
|
- El residente recibe notificación de aprobación
|
|
- [ ] Veo confirmación: "Avance aprobado correctamente"
|
|
|
|
### 5. Rechazar Registro ✅
|
|
- [ ] Puedo hacer clic en botón "Rechazar"
|
|
- [ ] DEBO especificar motivo de rechazo (obligatorio)
|
|
```
|
|
Motivos predefinidos:
|
|
- Cantidad inconsistente con fotos
|
|
- Ubicación incorrecta
|
|
- Falta evidencia fotográfica
|
|
- Incremento poco realista
|
|
- Otro (especificar)
|
|
```
|
|
- [ ] Puedo agregar notas adicionales
|
|
- [ ] Al rechazar:
|
|
- El registro cambia de estado: submitted → rejected
|
|
- El residente recibe notificación con el motivo
|
|
- El registro NO actualiza la actividad ni la Curva S
|
|
- El residente puede corregir y reenviar
|
|
|
|
### 6. Aprobación Masiva ✅
|
|
- [ ] Puedo seleccionar múltiples registros (checkboxes)
|
|
- [ ] Puedo hacer clic en "Aprobar Seleccionados"
|
|
- [ ] Veo confirmación: "¿Aprobar 5 registros seleccionados?"
|
|
- [ ] Al confirmar, todos se aprueban en batch
|
|
- [ ] Veo resultado: "5 de 5 registros aprobados exitosamente"
|
|
- [ ] Si alguno falla, veo detalle del error
|
|
|
|
### 7. Flujo de Aprobación Multi-nivel ✅
|
|
- [ ] Si el monto del avance excede umbral ($50,000), requiere 2 aprobaciones:
|
|
- Nivel 1: Residente → Aprueba
|
|
- Nivel 2: Jefe de Proyecto → Aprueba final
|
|
- [ ] Puedo ver en qué nivel de aprobación está cada registro
|
|
- [ ] Recibo notificaciones cuando me toca aprobar un nivel
|
|
|
|
---
|
|
|
|
## Mockup / Wireframe
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────────────────┐
|
|
│ ✓ Aprobación de Avances - Fracc. Los Pinos │
|
|
├──────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Pendientes de Aprobación: 8 │
|
|
│ │
|
|
│ Filtros: [Todos ▼] [Última semana ▼] [Buscar actividad...] │
|
|
│ │
|
|
│ [□] Seleccionar todos [Aprobar Seleccionados] │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
|
│ │[□] AVN-2025-00123 │ 15/Ene/25 14:30 │ Juan Pérez (Residente) │ │
|
|
│ │ ACT-025: Cimentación Tipo 1 │ │
|
|
│ │ 45% → 70% (+25%) | 225 m³ → 350 m³ | 📷 3 fotos | 📍 OK │ │
|
|
│ │ Cuadrilla: Cimiento 1 | 16 hrs-hombre │ │
|
|
│ │ ⚠️ Incremento alto (+25% en 1 día) │ │
|
|
│ │ │ │
|
|
│ │ [Ver Detalle] [✓ Aprobar] [✗ Rechazar] │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
|
│ │[□] AVN-2025-00124 │ 15/Ene/25 16:45 │ María González │ │
|
|
│ │ ACT-027: Estructura Tipo 2 │ │
|
|
│ │ 30% → 55% (+25%) | 150 m³ → 275 m³ | 📷 5 fotos | 📍 OK │ │
|
|
│ │ Cuadrilla: Estructura 2 | 24 hrs-hombre │ │
|
|
│ │ │ │
|
|
│ │ [Ver Detalle] [✓ Aprobar] [✗ Rechazar] │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ...más registros... │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Detalle del Registro:
|
|
┌──────────────────────────────────────────────────────────────────────────┐
|
|
│ ◀ Volver Detalle de Avance AVN-2025-00123 │
|
|
├──────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─ Información General ─────────────────────────────────────────────┐ │
|
|
│ │ Actividad: ACT-025 - Cimentación Tipo 1 │ │
|
|
│ │ Partida: 02.01.03 - Cimentación con concreto f'c=250 │ │
|
|
│ │ Registrado por: Juan Pérez (Residente) │ │
|
|
│ │ Fecha: 15/Ene/2025 14:30 │ │
|
|
│ │ Vía: App Móvil (iPhone 14 Pro) │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Avance Reportado ────────────────────────────────────────────────┐ │
|
|
│ │ │ │
|
|
│ │ Anterior: 45% (225 m³) ░░░░░░░░░░ │ │
|
|
│ │ Actual: 70% (350 m³) ████████████████ │ │
|
|
│ │ Incremento: +25% (+125 m³) ████████ │ │
|
|
│ │ │ │
|
|
│ │ Presupuestado: 500 m³ Ejecutado: 70% │ │
|
|
│ │ │ │
|
|
│ │ ⚠️ Incremento de 25% en un solo día es inusualmente alto │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Recursos ────────────────────────────────────────────────────────┐ │
|
|
│ │ Cuadrilla: Cimiento 1 (8 trabajadores) │ │
|
|
│ │ Horas-Hombre: 16 hrs │ │
|
|
│ │ Productividad: 7.8 m³/hr (vs 6.5 m³/hr planificado) ✓ │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Evidencias Fotográficas (3) ─────────────────────────────────────┐ │
|
|
│ │ [🖼️ Foto 1] [🖼️ Foto 2] [🖼️ Foto 3] │ │
|
|
│ │ 14:30 14:35 14:42 │ │
|
|
│ │ GPS ✓ GPS ✓ GPS ✓ │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Geolocalización ─────────────────────────────────────────────────┐ │
|
|
│ │ 📍 19.4326, -99.1332 │ │
|
|
│ │ Precisión: 5 metros │ │
|
|
│ │ Distancia del sitio: 125 metros ✓ Dentro del radio │ │
|
|
│ │ │ │
|
|
│ │ [Ver en Mapa] │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Notas del Residente ─────────────────────────────────────────────┐ │
|
|
│ │ Se completó cimentación de lotes 23-25. Buen rendimiento de la │ │
|
|
│ │ cuadrilla. Clima favorable. │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Notas de Aprobación (opcional): │
|
|
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ _____________________________________________________________ │ │
|
|
│ │ │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ [✗ Rechazar] [✓ Aprobar] │
|
|
└──────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Flujo de Aprobación
|
|
|
|
```
|
|
1. RESIDENTE REGISTRA AVANCE
|
|
↓
|
|
Estado: submitted
|
|
↓
|
|
Notificación al Jefe de Proyecto
|
|
|
|
2. JEFE DE PROYECTO REVISA
|
|
↓
|
|
Abre panel de aprobaciones
|
|
↓
|
|
Ve lista de pendientes
|
|
|
|
3. ABRE DETALLE
|
|
↓
|
|
Revisa:
|
|
- % y cantidades
|
|
- Fotos
|
|
- Geolocalización
|
|
- Alertas del sistema
|
|
|
|
4. DECISIÓN
|
|
↓
|
|
┌─────────────┬─────────────┐
|
|
│ APROBAR │ RECHAZAR │
|
|
└─────────────┴─────────────┘
|
|
│ │
|
|
↓ ↓
|
|
Estado: Estado:
|
|
approved rejected
|
|
│ │
|
|
↓ ↓
|
|
Actualiza: Notifica:
|
|
- Actividad - Residente
|
|
- Curva S - Con motivo
|
|
- Unit Progress
|
|
│ │
|
|
↓ ↓
|
|
Notifica: Residente puede
|
|
- Residente corregir y
|
|
- Equipo reenviar
|
|
```
|
|
|
|
---
|
|
|
|
## Endpoints Necesarios
|
|
|
|
```typescript
|
|
GET /api/progress/projects/:projectId/pending-approvals
|
|
GET /api/progress/records/:id
|
|
POST /api/progress/records/:id/approve
|
|
POST /api/progress/records/:id/reject
|
|
POST /api/progress/records/batch-approve
|
|
GET /api/progress/records/:id/history
|
|
```
|
|
|
|
---
|
|
|
|
## Definición de "Done"
|
|
|
|
- [x] Panel de aprobaciones pendientes funcional
|
|
- [x] Vista de detalle con toda la información
|
|
- [x] Validaciones automáticas implementadas
|
|
- [x] Flujo de aprobación y rechazo completo
|
|
- [x] Aprobación masiva funcional
|
|
- [x] Notificaciones enviadas correctamente
|
|
- [x] Actualización de Curva S tras aprobación
|
|
- [x] Tests unitarios >80%
|
|
- [x] Aprobado por Product Owner
|
|
|
|
---
|
|
|
|
**Estimación:** 5 Story Points
|
|
**Dependencias:** US-PROG-003
|
|
**Fecha:** 2025-11-17
|