2112 lines
71 KiB
Markdown
2112 lines
71 KiB
Markdown
# PROMPT MAESTRO — APP DE GERENCIA DE PROYECTOS UNIVERSAL
|
||
## Para usar con: Claude Code
|
||
|
||
---
|
||
|
||
## ROL Y CONTEXTO
|
||
|
||
Actúa simultáneamente como:
|
||
|
||
- **Arquitecto de Software Senior** con expertise en seguridad, escalabilidad y UX
|
||
- **Project Management Professional (PMP)** con experiencia en proyectos de ingeniería, construcción, música, educación, tecnología, manufactura y cualquier industria
|
||
- **CFO / Controlador Financiero** con dominio de centros de costos, órdenes de trabajo, flujo de caja, presupuestos y detección de desvíos
|
||
- **Contador Público** experto en autorización de pagos, cotizaciones, reportes financieros y auditoría
|
||
- **Director de Operaciones** que entiende recursos humanos, equipos físicos, maquinaria, licencias, software y cualquier tipo de recurso
|
||
- **UX/UI Designer** especializado en dashboards ejecutivos de alta visibilidad y data visualization
|
||
- **Quality Manager / Inspector Técnico** con dominio de NCRs, auditorías, control de calidad ISO, y trazabilidad de evidencias
|
||
- **HSE Manager** con expertise en seguridad industrial, normativas ambientales y gestión de incidentes
|
||
- **Abogado Corporativo** con dominio de contratos, adendas, penalizaciones y gestión legal de proyectos
|
||
- **Especialista en Procurement** con expertise en homologación de proveedores, licitaciones y vendor management
|
||
- **Arquitecto de Soluciones IA** con dominio de integración multi-proveedor (Claude, GPT, Gemini, Ollama) y diseño de sistemas agnósticos
|
||
|
||
Tu misión: construir la **mejor aplicación de gerencia de proyectos del mundo**, full-stack, lista para producción, con control absoluto sobre tiempo, recursos, costos y riesgos.
|
||
|
||
---
|
||
|
||
## STACK TECNOLÓGICO
|
||
|
||
### Frontend
|
||
- **React 18** con hooks y context API
|
||
- **Tailwind CSS** para UI
|
||
- **Recharts** para KPIs, líneas de tiempo, comparativos
|
||
- **D3.js** para Gantt chart interactivo y matriz de riesgos
|
||
- **@dnd-kit** para Kanban drag & drop
|
||
- **date-fns** para manejo de fechas
|
||
|
||
### Backend
|
||
- **Node.js + Express** REST API
|
||
- **PostgreSQL** como base de datos principal
|
||
- **Prisma ORM**
|
||
- **JWT** para autenticación
|
||
- **bcrypt** para hash de contraseñas
|
||
- **express-validator** para validación de inputs
|
||
- **helmet + cors + rate-limiter** para seguridad
|
||
|
||
### Infraestructura / DevOps
|
||
- **Docker + docker-compose** para desarrollo local
|
||
- Variables de entorno con **.env** (nunca hardcodear secrets)
|
||
- **Swagger/OpenAPI** para documentar la API
|
||
- Logs con **Winston**
|
||
|
||
---
|
||
|
||
## ARQUITECTURA DE LA APLICACIÓN
|
||
|
||
### Módulo 1: AUTENTICACIÓN Y ROLES
|
||
```
|
||
Roles:
|
||
- Super Admin → acceso total
|
||
- Director → ve todos los proyectos, aprueba pagos
|
||
- Gerente → gestiona proyectos asignados
|
||
- Jefe de área → gestiona recursos y tareas de su área
|
||
- Colaborador → solo ve y actualiza sus tareas
|
||
- Financiero → acceso solo a módulos de costos y pagos
|
||
- Auditor → solo lectura, todo el sistema
|
||
```
|
||
|
||
Implementar:
|
||
- Login con JWT + refresh tokens
|
||
- 2FA opcional (TOTP)
|
||
- Sesiones con expiración configurable
|
||
- Registro de auditoría (quién hizo qué y cuándo)
|
||
- Política de contraseñas segura
|
||
|
||
---
|
||
|
||
### Módulo 2: DASHBOARD EJECUTIVO GLOBAL
|
||
|
||
Panel principal con visión de TODOS los proyectos simultáneamente:
|
||
|
||
**KPIs Globales (tarjetas animadas):**
|
||
- Total proyectos activos / pausados / completados / en riesgo
|
||
- Presupuesto total comprometido vs ejecutado (gauge chart)
|
||
- % de avance promedio ponderado
|
||
- Proyectos con desvío de costo > 10% (alerta roja)
|
||
- Proyectos con atraso en cronograma (alerta naranja)
|
||
- ROI estimado global
|
||
|
||
**Gráficas del Dashboard Global:**
|
||
- Burndown chart multi-proyecto
|
||
- Barras comparativas: presupuesto vs gasto por proyecto
|
||
- Línea de tiempo: hitos críticos próximos (30/60/90 días)
|
||
- Mapa de calor: carga de recursos por semana
|
||
- Pie chart: distribución de proyectos por tipo/estado
|
||
- Semáforo de salud: cada proyecto con RAG status (Rojo/Amarillo/Verde)
|
||
|
||
**Reglas de alarma automática:**
|
||
- Desvío de costo > 5% → alerta amarilla
|
||
- Desvío de costo > 15% → alerta roja + notificación al Director
|
||
- Tarea vencida sin actualización → alerta al responsable
|
||
- Recurso sobreasignado > 100% → alerta al Gerente
|
||
- Pago pendiente de autorización > X días → escalada automática
|
||
|
||
---
|
||
|
||
### Módulo 3: GESTIÓN DE PROYECTOS
|
||
|
||
**Creación de proyecto (agnóstico de industria):**
|
||
```
|
||
Campos:
|
||
- Nombre, descripción, tipo de proyecto (libre o de catálogo)
|
||
- Categoría: Ingeniería / Construcción / TI / Música / Educación /
|
||
Investigación / Marketing / Manufactura / Otro (personalizable)
|
||
- Cliente / sponsor interno
|
||
- Fechas: inicio, fin planeado, fin real
|
||
- Presupuesto base (con posibilidad de contingencia %)
|
||
- Moneda (USD, COP, EUR, etc.)
|
||
- Prioridad (Crítico / Alto / Medio / Bajo)
|
||
- Fase actual del proyecto
|
||
- Metodología: Waterfall / Ágil / Híbrido / Ninguna
|
||
- Equipo asignado
|
||
- Etiquetas personalizadas (tags)
|
||
```
|
||
|
||
**Vista por proyecto:**
|
||
- Resumen ejecutivo (1 página tipo briefing)
|
||
- Gantt interactivo (drag para mover tareas, dependencias visuales)
|
||
- Kanban por fase o sprint
|
||
- WBS (Work Breakdown Structure) en árbol expandible
|
||
- Cronograma con ruta crítica resaltada
|
||
- Registro de cambios (change log)
|
||
- Documentos adjuntos
|
||
- Bitácora / notas del proyecto
|
||
|
||
---
|
||
|
||
### Módulo 4: GESTIÓN DE TAREAS
|
||
|
||
```
|
||
Tarea contiene:
|
||
- Título, descripción detallada
|
||
- WBS ID (padre/hijo)
|
||
- Responsable(s)
|
||
- Recursos asignados (humanos + equipos + materiales)
|
||
- Fechas: inicio, fin, duración estimada, duración real
|
||
- % de avance (actualizable manualmente o por subtareas)
|
||
- Dependencias (FS, SS, FF, SF)
|
||
- Prioridad y etiquetas
|
||
- Costo estimado / costo real
|
||
- Estado: Pendiente / En proceso / Bloqueada / Revisión / Completada
|
||
- Comentarios y menciones (@usuario)
|
||
- Historial de cambios de estado
|
||
- Archivos adjuntos
|
||
```
|
||
|
||
**Funcionalidades:**
|
||
- Subtareas anidadas (ilimitadas)
|
||
- Checklists dentro de tareas
|
||
- Estimación por puntos de historia (si es ágil)
|
||
- Vista de tareas vencidas / próximas a vencer
|
||
- Filtros avanzados: por recurso, fecha, estado, proyecto, etiqueta
|
||
|
||
---
|
||
|
||
### Módulo 5: GESTIÓN DE RECURSOS (UNIVERSAL)
|
||
|
||
**Tipos de recursos:**
|
||
```
|
||
1. Humanos
|
||
- Nombre, rol, especialidad, tarifa/hora o tarifa fija
|
||
- Disponibilidad por calendario
|
||
- Proyectos asignados actualmente
|
||
- Carga de trabajo (% ocupación por semana)
|
||
- Habilidades/certificaciones
|
||
|
||
2. Equipos y Maquinaria
|
||
- Nombre, descripción, número de serie
|
||
- Costo por hora / día / semana
|
||
- Estado: Disponible / En uso / Mantenimiento / Fuera de servicio
|
||
- Ubicación actual
|
||
- Historial de uso por proyecto
|
||
- Fecha próximo mantenimiento
|
||
|
||
3. Materiales e Insumos
|
||
- Nombre, unidad de medida, costo unitario
|
||
- Proveedor asociado
|
||
- Stock disponible (opcional)
|
||
- Vinculado a orden de compra
|
||
|
||
4. Software / Licencias
|
||
- Nombre, versión, proveedor
|
||
- Costo (mensual/anual)
|
||
- Usuarios asignados
|
||
- Fecha de vencimiento (alerta automática)
|
||
|
||
5. Espacios / Instalaciones
|
||
- Nombre, capacidad, costo por uso
|
||
- Disponibilidad en calendario
|
||
|
||
6. Recursos Externos / Subcontratistas
|
||
- Empresa, contacto, especialidad
|
||
- Contrato asociado, valor, vigencia
|
||
```
|
||
|
||
**Vista de recursos:**
|
||
- Calendario de disponibilidad (tipo Outlook)
|
||
- Heatmap de carga semanal
|
||
- Alerta de sobreasignación
|
||
- Historial de uso y costos acumulados
|
||
- Reporte de eficiencia por recurso
|
||
|
||
---
|
||
|
||
### Módulo 6: CONTROL FINANCIERO Y CONTABLE
|
||
|
||
#### 6.1 Presupuesto
|
||
```
|
||
- Presupuesto base por proyecto (desglosado por categoría de gasto)
|
||
- Contingencia definida en %
|
||
- Presupuesto aprobado vs propuesto
|
||
- Historial de versiones de presupuesto (baseline 1, 2, 3...)
|
||
- Curva S: gasto planeado vs real en el tiempo
|
||
```
|
||
|
||
#### 6.2 Centro de Costos
|
||
```
|
||
- Cada proyecto tiene su centro de costos único
|
||
- Sub-centros por fase, área o WBS
|
||
- Categorías de gasto:
|
||
* Mano de obra (interna)
|
||
* Contratistas / Subcontratistas
|
||
* Materiales y suministros
|
||
* Equipos y herramientas
|
||
* Licencias y software
|
||
* Viáticos y transporte
|
||
* Servicios profesionales
|
||
* Imprevistos
|
||
* Otros (personalizables)
|
||
- Cada gasto registrado con: fecha, categoría, descripción,
|
||
monto, moneda, proveedor, documento soporte, estado de aprobación
|
||
```
|
||
|
||
#### 6.3 Órdenes de Trabajo (OT)
|
||
```
|
||
Flujo completo:
|
||
1. Solicitud de OT (Colaborador / Jefe)
|
||
2. Revisión técnica (Gerente de proyecto)
|
||
3. Estimación de costo (adjunta cotización)
|
||
4. Aprobación financiera (Financiero / Director según monto)
|
||
5. Ejecución
|
||
6. Cierre y registro de costo real
|
||
|
||
Campos OT:
|
||
- Número consecutivo automático
|
||
- Proyecto y WBS asociado
|
||
- Tipo: Correctiva / Preventiva / Nueva tarea / Cambio de alcance
|
||
- Descripción del trabajo
|
||
- Recursos requeridos
|
||
- Costo estimado
|
||
- Cotizaciones adjuntas (puede tener varias, se selecciona la aprobada)
|
||
- Estado: Borrador / En revisión / Aprobada / En ejecución / Cerrada / Rechazada
|
||
- Firma digital del aprobador
|
||
- Fecha de autorización
|
||
```
|
||
|
||
#### 6.4 Gestión de Cotizaciones
|
||
```
|
||
- Registro de cotizaciones por proveedor
|
||
- Comparativo de cotizaciones (tabla side-by-side)
|
||
- Selección de cotización ganadora con justificación
|
||
- Vinculación a OT o tarea
|
||
- Adjuntar PDF de cotización
|
||
- Estado: Solicitada / Recibida / Evaluada / Aprobada / Rechazada
|
||
- Historial de cotizaciones por proveedor
|
||
```
|
||
|
||
#### 6.5 Autorizaciones de Pago
|
||
```
|
||
Flujo de aprobación por niveles según monto:
|
||
- Hasta $X → Gerente de proyecto aprueba
|
||
- $X a $Y → Director aprueba
|
||
- Mayor a $Y → Comité (múltiples firmas requeridas)
|
||
|
||
Registro:
|
||
- Número de solicitud
|
||
- OT o tarea asociada
|
||
- Proveedor / beneficiario
|
||
- Monto exacto + impuestos
|
||
- Cuenta bancaria destino
|
||
- Soporte: factura / recibo adjunto
|
||
- Estado: Pendiente / En revisión / Aprobado / Pagado / Rechazado
|
||
- Registro de quién aprobó y cuándo
|
||
- Integración con historial contable del proyecto
|
||
```
|
||
|
||
#### 6.6 Sistema de Alarmas Financieras
|
||
```
|
||
ALARMAS AUTOMÁTICAS:
|
||
🔴 CRÍTICO:
|
||
- Gasto acumulado supera el 90% del presupuesto
|
||
- Pago sin autorización en el flujo
|
||
- Cotización seleccionada sin justificación documentada
|
||
- Desvío de costo > 20%
|
||
|
||
🟡 ADVERTENCIA:
|
||
- Gasto acumulado supera el 70% del presupuesto
|
||
- OT sin actualización > 5 días
|
||
- Factura recibida sin OT asociada
|
||
- Desvío de costo entre 10% y 20%
|
||
|
||
🔵 INFORMATIVO:
|
||
- Nueva cotización recibida
|
||
- Pago procesado exitosamente
|
||
- Presupuesto actualizado
|
||
```
|
||
|
||
#### 6.7 Reportes Financieros
|
||
```
|
||
- Estado de cuenta por proyecto (tipo P&L simplificado)
|
||
- Comparativo presupuesto vs real por categoría
|
||
- Curva S interactiva
|
||
- Flujo de caja proyectado
|
||
- Listado de pagos pendientes
|
||
- Listado de facturas por vencer
|
||
- Reporte de varianza (EVM: Earned Value Management)
|
||
* CPI (Cost Performance Index)
|
||
* SPI (Schedule Performance Index)
|
||
* EAC (Estimate at Completion)
|
||
* VAC (Variance at Completion)
|
||
- Exportar todo a Excel o PDF
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 7: GESTIÓN DE RIESGOS
|
||
|
||
```
|
||
Por cada riesgo:
|
||
- ID, descripción, categoría
|
||
- Probabilidad (1-5) × Impacto (1-5) = Exposición
|
||
- Tipo: Amenaza / Oportunidad
|
||
- Disparador (trigger)
|
||
- Plan de respuesta: Evitar / Transferir / Mitigar / Aceptar
|
||
- Responsable del riesgo
|
||
- Costo estimado de respuesta
|
||
- Estado: Identificado / Activo / Materializado / Cerrado
|
||
|
||
Visualización:
|
||
- Matriz 5×5 interactiva (heatmap)
|
||
- Registro histórico
|
||
- Riesgos materializados → vinculados a OT automáticamente
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 8: COMUNICACIÓN Y COLABORACIÓN
|
||
|
||
```
|
||
- Comentarios en tareas con @menciones
|
||
- Notificaciones en tiempo real (WebSocket)
|
||
- Centro de notificaciones con historial
|
||
- Emails automáticos por eventos críticos
|
||
- Log de auditoría completo (quién, qué, cuándo, desde dónde)
|
||
- Documentos del proyecto con control de versiones
|
||
- Reuniones: registro de actas, acuerdos y responsables
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 9: REPORTES Y EXPORTACIÓN
|
||
|
||
```
|
||
- Reporte ejecutivo por proyecto (PDF)
|
||
- Reporte multi-proyecto comparativo
|
||
- Exportar Gantt a imagen/PDF
|
||
- Exportar cualquier tabla a Excel
|
||
- Dashboard exportable como imagen
|
||
- Reporte de recursos (utilización, costos)
|
||
- Reporte de riesgos
|
||
- Reporte financiero completo
|
||
- Programar reportes automáticos por email (semanal/mensual)
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 10: CONTROL DE CALIDAD, AUDITORÍAS Y EVIDENCIAS
|
||
|
||
Este módulo es el que separa una app de gerencia de proyectos seria de las demás.
|
||
**Principio fundamental: ningún avance existe si no hay evidencia que lo respalde.**
|
||
|
||
#### 10.1 Definition of Done (DoD) por Tarea
|
||
```
|
||
- Al crear una tarea, el Gerente define los criterios de aceptación:
|
||
* Lista de condiciones que DEBEN cumplirse para considerarla completa
|
||
* Tipo de evidencia requerida: Foto / Video / Documento / Firma / Test report / Ninguna
|
||
* Requiere verificación por tercero: Sí / No
|
||
* Requiere inspección física: Sí / No
|
||
|
||
- El sistema BLOQUEA el cambio de estado a "Completada" si:
|
||
* No se han cumplido todos los criterios del checklist
|
||
* No se ha adjuntado la evidencia requerida
|
||
* No tiene firma del verificador (si aplica)
|
||
```
|
||
|
||
#### 10.2 Repositorio de Evidencias
|
||
```
|
||
Cada tarea tiene su propio repositorio de evidencias:
|
||
- Fotos / Videos (con timestamp y geolocalización automática si es móvil)
|
||
- Documentos: actas, test reports, certificados, planos as-built
|
||
- Firma digital del ejecutor
|
||
- Firma digital del verificador / inspector
|
||
- Firma digital del aprobador final
|
||
- Comentarios técnicos del inspector
|
||
|
||
Organización:
|
||
/proyecto
|
||
/fase
|
||
/tarea
|
||
/evidencias
|
||
- foto_001_2026-06-23_14-32.jpg (con metadata)
|
||
- reporte_prueba_hidraulica.pdf
|
||
- firma_ejecutor.json
|
||
- firma_inspector.json
|
||
|
||
Reglas:
|
||
- Evidencias son INMUTABLES una vez firmadas (no se pueden borrar ni reemplazar)
|
||
- Se puede agregar evidencia adicional pero no eliminar la existente
|
||
- Hash SHA-256 de cada archivo para detectar manipulaciones
|
||
- Almacenamiento en S3 o equivalente (nunca en BD)
|
||
```
|
||
|
||
#### 10.3 NCR — Non Conformance Reports (Reportes de No Conformidad)
|
||
```
|
||
Se genera cuando un trabajo NO cumple los criterios de aceptación:
|
||
|
||
Campos:
|
||
- Número NCR consecutivo por proyecto
|
||
- Tarea y WBS asociados
|
||
- Descripción detallada de la no conformidad
|
||
- Evidencia fotográfica de la falla
|
||
- Categoría: Calidad / Seguridad / Alcance / Técnica / Procedimental
|
||
- Severidad: Menor / Mayor / Crítica
|
||
- Responsable de la no conformidad
|
||
- Causa raíz (análisis de causa)
|
||
- Acción correctiva requerida
|
||
- Fecha límite de corrección
|
||
- Costo estimado de retrabajo → vinculado automáticamente a OT
|
||
- Estado: Abierto / En corrección / Verificado / Cerrado
|
||
|
||
Flujo NCR:
|
||
1. Inspector abre NCR con evidencia
|
||
2. Responsable recibe notificación y debe responder en X horas
|
||
3. Responsable ejecuta corrección y sube nueva evidencia
|
||
4. Inspector verifica corrección en campo
|
||
5. Si OK → cierra NCR y se registra en historial
|
||
6. Si No OK → reabre NCR con comentarios
|
||
|
||
Impacto automático:
|
||
- NCR abierto → tarea no puede avanzar al siguiente estado
|
||
- NCR Crítico → alerta al Director y al Gerente inmediatamente
|
||
- Historial de NCRs afecta score de calidad del subcontratista/recurso
|
||
```
|
||
|
||
#### 10.4 Módulo de Auditorías
|
||
```
|
||
Tipos de auditoría:
|
||
|
||
1. AUDITORÍA PROGRAMADA
|
||
- Definida en el cronograma del proyecto (hitos de control)
|
||
- Generada automáticamente al llegar a % de avance definido
|
||
- Checklist predefinido por tipo de proyecto / industria
|
||
- Asignada a auditor interno o externo
|
||
|
||
2. AUDITORÍA SORPRESA
|
||
- Creada manualmente por Director o Auditor en cualquier momento
|
||
- Sin previo aviso al equipo (el sistema no notifica al auditado)
|
||
- Registra fecha/hora exacta de inicio
|
||
|
||
3. GATE REVIEW (Revisión de Fase)
|
||
- Obligatoria para avanzar de una fase a la siguiente
|
||
- El sistema BLOQUEA el inicio de la siguiente fase hasta aprobación
|
||
- Requiere: informe de avance + evidencias + aprobación formal
|
||
|
||
Estructura de una auditoría:
|
||
- ID, tipo, proyecto, fase auditada
|
||
- Auditor asignado (puede ser externo al proyecto)
|
||
- Fecha programada vs fecha real de ejecución
|
||
- Checklist de ítems a verificar (personalizable por tipo de proyecto)
|
||
- Por cada ítem: Conforme / No Conforme / No Aplica + observación + foto
|
||
- Hallazgos: lista de NCRs generados durante la auditoría
|
||
- Calificación final: Aprobado / Aprobado con observaciones / Rechazado
|
||
- Informe de auditoría generado automáticamente en PDF
|
||
- Firma digital del auditor
|
||
- Firma de aceptación del Gerente del proyecto
|
||
- Plan de acción para hallazgos (con fechas y responsables)
|
||
```
|
||
|
||
#### 10.5 Checklist Templates por Industria
|
||
```
|
||
El sistema incluye plantillas de checklist predefinidas:
|
||
|
||
- Construcción civil: inspecciones estructurales, concreto, acero, electricidad
|
||
- Ingeniería naval/marina: sistemas eléctricos, propulsión, seguridad
|
||
- TI / Software: code review, testing, deployment, seguridad
|
||
- Manufactura: control de calidad, tolerancias, pruebas funcionales
|
||
- Educación: entrega de contenidos, evaluaciones, métricas de aprendizaje
|
||
- Música / Producción: tomas aprobadas, mezcla, masterización, entregables
|
||
|
||
Cada template es personalizable y puede guardarse como nuevo template.
|
||
```
|
||
|
||
#### 10.6 Score de Calidad
|
||
```
|
||
Métricas calculadas automáticamente:
|
||
|
||
Por proyecto:
|
||
- Tasa de NCRs (NCRs / Total tareas completadas)
|
||
- Tasa de retrabajo (%)
|
||
- Costo de no calidad (suma de OTs por retrabajo)
|
||
- Tiempo perdido por no conformidades
|
||
- Índice de calidad global (0-100)
|
||
|
||
Por recurso / subcontratista:
|
||
- Historial de NCRs generados
|
||
- Tasa de aprobación en primera inspección
|
||
- Tiempo promedio de cierre de NCRs
|
||
- Score acumulado que afecta futuras asignaciones
|
||
|
||
Dashboard de calidad:
|
||
- Semáforo de calidad por proyecto
|
||
- Trending de NCRs en el tiempo
|
||
- Top 5 causas de no conformidad
|
||
- Costo acumulado de retrabajo vs presupuesto
|
||
```
|
||
|
||
#### 10.7 Alarmas de Calidad
|
||
```
|
||
🔴 CRÍTICO:
|
||
- NCR Crítico abierto sin respuesta > 24 horas
|
||
- Gate Review rechazado
|
||
- Tarea marcada completa sin evidencia requerida (intento de bypass)
|
||
- Score de calidad del proyecto < 60
|
||
|
||
🟡 ADVERTENCIA:
|
||
- 3 o más NCRs abiertos simultáneamente en el mismo proyecto
|
||
- Auditoría programada sin ejecutar (vencida)
|
||
- Score de calidad entre 60 y 75
|
||
- Subcontratista con > 2 NCRs en el proyecto actual
|
||
|
||
🔵 INFORMATIVO:
|
||
- NCR cerrado exitosamente
|
||
- Gate Review aprobado
|
||
- Auditoría completada
|
||
- Nuevo template de checklist disponible
|
||
```
|
||
|
||
#### 10.8 Actualizaciones al Módulo de Tareas
|
||
```
|
||
Agregar a cada tarea:
|
||
- Sección "Criterios de Aceptación" (DoD) editable por Gerente
|
||
- Botón "Subir Evidencia" siempre visible
|
||
- Indicador visual de evidencias requeridas vs cargadas
|
||
- Sección "Inspecciones" con historial de verificaciones
|
||
- Badge de NCRs asociados a la tarea
|
||
- Historial de intentos de cambio de estado (incluyendo los bloqueados)
|
||
- Campo "Causa de retrabajo" si la tarea fue reabierta
|
||
```
|
||
|
||
#### 10.9 Actualización de Estructura de Carpetas
|
||
```
|
||
Agregar a /frontend/src/components:
|
||
├── /quality # NCRs, auditorías, evidencias, DoD
|
||
│ ├── NCRList.jsx
|
||
│ ├── NCRForm.jsx
|
||
│ ├── AuditModule.jsx
|
||
│ ├── ChecklistBuilder.jsx
|
||
│ ├── EvidenceRepository.jsx
|
||
│ ├── GateReview.jsx
|
||
│ └── QualityDashboard.jsx
|
||
|
||
Agregar a /backend/src:
|
||
├── /quality # Lógica de calidad
|
||
│ ├── ncr.controller.js
|
||
│ ├── audit.controller.js
|
||
│ ├── evidence.controller.js
|
||
│ └── quality-score.service.js
|
||
```
|
||
|
||
#### 10.10 Actualización de Fases de Construcción
|
||
```
|
||
Agregar a FASE 2 (Sprint 3-4):
|
||
□ Definition of Done por tarea
|
||
□ Repositorio de evidencias (upload + hash + inmutabilidad)
|
||
□ Bloqueo de avance sin evidencia
|
||
|
||
Agregar a FASE 4 (Sprint 7-8):
|
||
□ Módulo NCR completo con flujo de cierre
|
||
□ Módulo de Auditorías (programadas + sorpresa + gate reviews)
|
||
□ Checklist templates por industria
|
||
□ Score de calidad y dashboard
|
||
□ Alarmas de calidad integradas al dashboard global
|
||
□ Informe de auditoría en PDF generado automáticamente
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 11: RECEPCIÓN Y ACEPTACIÓN DE ENTREGABLES
|
||
|
||
**Principio fundamental: la separación de funciones es obligatoria.**
|
||
Quien ejecuta ≠ quien inspecciona ≠ quien aprueba ≠ quien paga.
|
||
El sistema lo impone técnicamente, no es una recomendación.
|
||
|
||
#### 11.1 Roles Ampliados
|
||
```
|
||
Agregar a los roles existentes:
|
||
|
||
- Inspector / QC → verifica trabajos en campo, genera NCRs,
|
||
firma actas de recepción técnica
|
||
NO puede ser el mismo que ejecutó la tarea
|
||
|
||
- Receptor Formal → acepta entregables a nombre del cliente
|
||
o de la organización, su firma habilita el pago
|
||
Puede ser: Gerente, Director, o cliente externo
|
||
|
||
Regla técnica: el sistema valida que el usuario firmante
|
||
NO sea el mismo asignado como ejecutor de la tarea.
|
||
Si lo intenta → error bloqueante con log de auditoría.
|
||
```
|
||
|
||
#### 11.2 Flujo Completo de Recepción
|
||
```
|
||
PASO 1 — Ejecución
|
||
└── Colaborador/Contratista ejecuta el trabajo
|
||
└── Sube evidencias (fotos, docs, pruebas)
|
||
└── Completa checklist DoD
|
||
└── Firma digital como EJECUTOR
|
||
└── Cambia estado a "En verificación"
|
||
└── Sistema notifica automáticamente al Inspector asignado
|
||
|
||
PASO 2 — Inspección Técnica (QC)
|
||
└── Inspector recibe notificación con detalle de la tarea
|
||
└── Accede al repositorio de evidencias del ejecutor
|
||
└── Realiza inspección (física o documental)
|
||
└── Completa checklist de inspección (puede ser distinto al del ejecutor)
|
||
└── Sube su propia evidencia: fotos de inspección, mediciones, pruebas
|
||
└── Registra fecha/hora/ubicación de la inspección
|
||
|
||
¿Conforme?
|
||
├── SÍ → Firma acta de recepción técnica
|
||
│ → Estado: "Aprobado técnicamente"
|
||
│ → Notifica al Receptor Formal
|
||
│
|
||
└── NO → Abre NCR con descripción de falla + evidencia
|
||
→ Estado de tarea: "No conforme - en corrección"
|
||
→ Notifica al ejecutor con detalle del NCR
|
||
→ Ejecutor corrige y vuelve al Paso 1
|
||
→ Cada ciclo de corrección queda registrado en historial
|
||
|
||
PASO 3 — Aceptación Formal
|
||
└── Receptor Formal revisa: tarea + evidencias del ejecutor
|
||
+ acta de inspección técnica + NCRs cerrados (si hubo)
|
||
└── Puede solicitar aclaraciones antes de aceptar
|
||
└── Firma digital de ACEPTACIÓN FORMAL
|
||
|
||
¿Acepta?
|
||
├── SÍ → Estado: "Aceptado formalmente"
|
||
│ → Se genera automáticamente la Solicitud de Pago
|
||
│ → Vinculada a la OT y al centro de costos del proyecto
|
||
│ → Notifica al módulo financiero
|
||
│
|
||
└── NO → Devuelve con observaciones escritas obligatorias
|
||
→ Puede generar NCR adicional o solicitar nueva inspección
|
||
→ Queda registrado en historial con justificación
|
||
|
||
PASO 4 — Liberación de Pago (Módulo Financiero)
|
||
└── Financiero recibe Solicitud de Pago con toda la cadena:
|
||
evidencia ejecutor + acta inspección + aceptación formal
|
||
└── Verifica que la cadena de firmas esté completa
|
||
└── Si falta CUALQUIER firma → sistema bloquea el pago
|
||
└── Si cadena completa → procede con flujo de autorización normal
|
||
(según montos definidos en Módulo 6.5)
|
||
```
|
||
|
||
#### 11.3 Acta de Recepción Digital
|
||
```
|
||
Generada automáticamente al completar el Paso 2 o 3:
|
||
|
||
Contenido del acta:
|
||
- Número de acta consecutivo por proyecto
|
||
- Proyecto, fase, tarea y WBS asociados
|
||
- Descripción del entregable recibido
|
||
- Fecha y hora de inspección
|
||
- Ubicación (geolocalización si es móvil)
|
||
- Inspector responsable
|
||
- Resultado: Conforme / No conforme / Conforme con observaciones
|
||
- Lista de evidencias revisadas (con hash SHA-256)
|
||
- Observaciones técnicas
|
||
- NCRs generados (si aplica)
|
||
- Firma digital del inspector
|
||
- Firma digital del receptor formal (Paso 3)
|
||
- QR code de verificación de autenticidad
|
||
|
||
El acta se genera en PDF inmutable y se almacena en el
|
||
repositorio de evidencias de la tarea.
|
||
No puede ser editada después de firmada.
|
||
```
|
||
|
||
#### 11.4 Panel del Inspector / QC
|
||
```
|
||
Vista exclusiva para el rol Inspector:
|
||
|
||
- Cola de trabajos pendientes de inspección (ordenados por urgencia)
|
||
- Mapa de ubicaciones de trabajos a inspeccionar (si aplica)
|
||
- Historial de inspecciones realizadas
|
||
- NCRs abiertos asignados a él para seguimiento
|
||
- Estadísticas personales:
|
||
* Total inspecciones realizadas
|
||
* Tasa de aprobación en primera inspección
|
||
* NCRs generados / cerrados
|
||
* Tiempo promedio de inspección
|
||
|
||
Filtros:
|
||
- Por proyecto / fase / tipo de trabajo
|
||
- Por urgencia / fecha límite
|
||
- Por subcontratista / ejecutor
|
||
```
|
||
|
||
#### 11.5 Panel del Receptor Formal
|
||
```
|
||
Vista para quien acepta formalmente:
|
||
|
||
- Entregables pendientes de aceptación (ya inspeccionados y aprobados técnicamente)
|
||
- Detalle completo de cada entregable: qué es, quién lo hizo, cuándo, evidencias, acta técnica
|
||
- Historial de aceptaciones
|
||
- Entregables rechazados con seguimiento
|
||
- Vista del impacto financiero: valor del entregable a pagar si acepta
|
||
```
|
||
|
||
#### 11.6 Trazabilidad Completa (Cadena de Custodia)
|
||
```
|
||
Para cada tarea completada, el sistema mantiene la cadena:
|
||
|
||
[Ejecutor] → [evidencia] → [Inspector QC] → [acta técnica]
|
||
→ [Receptor Formal] → [aceptación] → [Financiero] → [pago]
|
||
|
||
Esta cadena es visible en:
|
||
- El detalle de la tarea (timeline vertical)
|
||
- El acta de recepción
|
||
- El reporte financiero (justifica el pago)
|
||
- El log de auditoría general
|
||
|
||
En caso de disputa o auditoría externa:
|
||
→ Exportar cadena completa en PDF con todas las firmas y timestamps
|
||
→ Verificable por hash SHA-256 de cada documento
|
||
```
|
||
|
||
#### 11.7 Integraciones con Módulos Existentes
|
||
```
|
||
Con Módulo 4 (Tareas):
|
||
- Nuevos estados: "En verificación" / "No conforme" / "Aprobado técnicamente" / "Aceptado formalmente"
|
||
- Bloqueo técnico: pago solo si estado = "Aceptado formalmente"
|
||
|
||
Con Módulo 6 (Finanzas):
|
||
- Solicitud de pago generada automáticamente al aceptar formalmente
|
||
- Factura del proveedor debe vincularse al acta de recepción
|
||
- Sin acta → pago bloqueado en el sistema, no hay excepción
|
||
|
||
Con Módulo 10 (Calidad):
|
||
- NCR generado en inspección → mismo flujo del Módulo 10
|
||
- Score del inspector se calcula también (¿está siendo riguroso?)
|
||
- Auditorías pueden revisar aleatoriamente actas de recepción pasadas
|
||
|
||
Con Módulo 8 (Comunicación):
|
||
- Notificaciones automáticas en cada transición de estado
|
||
- El ejecutor siempre sabe en qué paso está su trabajo
|
||
- Alertas de SLA: si el inspector no actúa en X horas → escalada
|
||
```
|
||
|
||
#### 11.8 SLAs de Inspección (Tiempos Máximos)
|
||
```
|
||
Configurables por proyecto o globalmente:
|
||
|
||
- Inspector debe iniciar inspección: dentro de X horas de notificación
|
||
- Inspector debe completar inspección: dentro de Y horas de inicio
|
||
- Receptor Formal debe aceptar/rechazar: dentro de Z horas
|
||
|
||
Si se vence el SLA:
|
||
🟡 Alerta al Gerente del proyecto
|
||
🔴 Si pasa el doble del SLA → alerta al Director con escalada automática
|
||
|
||
Razón: los cuellos de botella en inspección son una de las
|
||
principales causas de atrasos en proyectos de construcción e ingeniería.
|
||
```
|
||
|
||
#### 11.9 Alarmas del Módulo de Recepción
|
||
```
|
||
🔴 CRÍTICO:
|
||
- Intento de autofirma detectado (ejecutor = inspector) → bloqueado + log
|
||
- Pago procesado sin acta de recepción (no debería ser posible, pero se audita)
|
||
- SLA de inspección vencido x2
|
||
|
||
🟡 ADVERTENCIA:
|
||
- Trabajo en estado "En verificación" sin inspector asignado
|
||
- SLA de inspección vencido x1
|
||
- Entregable devuelto por segunda vez consecutiva
|
||
|
||
🔵 INFORMATIVO:
|
||
- Nuevo trabajo listo para inspección
|
||
- Acta de recepción generada
|
||
- Entregable aceptado formalmente → pago habilitado
|
||
```
|
||
|
||
#### 11.10 Actualización Estructura de Carpetas
|
||
```
|
||
Agregar a /frontend/src/components:
|
||
├── /reception
|
||
│ ├── InspectionQueue.jsx # Cola del inspector
|
||
│ ├── InspectionForm.jsx # Formulario de inspección + checklist
|
||
│ ├── FormalAcceptance.jsx # Panel del receptor formal
|
||
│ ├── ReceptionAct.jsx # Acta digital generada
|
||
│ ├── CustodyChain.jsx # Visualización de cadena completa
|
||
│ └── ReceptionDashboard.jsx # Panel general de recepción
|
||
|
||
Agregar a /backend/src:
|
||
├── /reception
|
||
│ ├── inspection.controller.js
|
||
│ ├── acceptance.controller.js
|
||
│ ├── reception-act.service.js # Generación PDF del acta
|
||
│ ├── custody-chain.service.js # Trazabilidad completa
|
||
│ └── sla.service.js # Control de tiempos
|
||
```
|
||
|
||
#### 11.11 Actualización de Fases de Construcción
|
||
```
|
||
Agregar a FASE 3 (Sprint 5-6):
|
||
□ Flujo de inspección técnica (Paso 1 y 2)
|
||
□ Acta de recepción digital con firma
|
||
□ Bloqueo de pago sin acta firmada
|
||
□ Panel del Inspector QC
|
||
|
||
Agregar a FASE 4 (Sprint 7-8):
|
||
□ Aceptación formal con firma del Receptor
|
||
□ Cadena de custodia completa y exportable
|
||
□ SLAs de inspección con escalada automática
|
||
□ Panel del Receptor Formal
|
||
□ Integración completa con módulo financiero
|
||
□ Dashboard de recepción con métricas
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 12: HSE Y MONITOREO DE DESVIACIONES CRÍTICAS
|
||
|
||
**Principio fundamental: prevenir es más barato que corregir.**
|
||
Este módulo no espera que algo falle — monitorea continuamente
|
||
y actúa antes de que una desviación se convierta en crisis.
|
||
Cualquier persona en el proyecto puede activarlo, incluso anónimamente.
|
||
|
||
---
|
||
|
||
#### 12.1 Estructura de Desviaciones (5 Categorías)
|
||
|
||
```
|
||
CATEGORÍA 1 — HSE (Health, Safety & Environment)
|
||
Subcategorías:
|
||
- Accidente con lesión (leve / grave / fatal)
|
||
- Casi-accidente / Near Miss
|
||
- Condición insegura (física o procedimental)
|
||
- Enfermedad ocupacional
|
||
- Incidente ambiental:
|
||
* Derrame de químicos / combustibles
|
||
* Emisiones fuera de límite
|
||
* Contaminación de suelo o agua
|
||
* Manejo inadecuado de residuos peligrosos
|
||
* Afectación a flora/fauna
|
||
- Violación de EPP (equipos de protección personal)
|
||
- Permiso de trabajo vencido o ausente:
|
||
* Trabajo en altura
|
||
* Espacio confinado
|
||
* Trabajo en caliente (soldadura, llama)
|
||
* Energías peligrosas (lockout/tagout)
|
||
* Excavaciones
|
||
|
||
CATEGORÍA 2 — Desviaciones de Alcance
|
||
- Trabajo ejecutado fuera del scope aprobado
|
||
- Cambio de diseño no autorizado
|
||
- Material sustituto no aprobado
|
||
- Expansión de alcance sin orden de cambio
|
||
- Reducción de alcance sin aprobación
|
||
|
||
CATEGORÍA 3 — Desviaciones Regulatorias / Legales
|
||
- Licencia de construcción / operación vencida
|
||
- Permiso ambiental vencido o incumplido
|
||
- Certificación de equipo vencida (grúas, andamios, recipientes a presión)
|
||
- Certificación de personal vencida (soldadores, electricistas, operadores)
|
||
- Incumplimiento OSHA / EPA / normativa local aplicable
|
||
- Multa o notificación regulatoria recibida
|
||
- Contrato de seguro vencido
|
||
|
||
CATEGORÍA 4 — Desviaciones Técnicas
|
||
- Parámetro fuera de especificación:
|
||
* Temperatura / presión / voltaje / corriente / tolerancia dimensional
|
||
- Equipo operando fuera de rango seguro
|
||
- Material o componente no conforme instalado
|
||
- Prueba técnica fallida (hidrostática, eléctrica, estructural)
|
||
- Desviación de planos aprobados
|
||
- Instrumentación descalibrada o fuera de servicio
|
||
|
||
CATEGORÍA 5 — Desviaciones Contractuales
|
||
- Hito contractual incumplido
|
||
- Penalización / multa contractual activada
|
||
- Garantía en riesgo por incumplimiento técnico
|
||
- Reclamo formal del cliente recibido
|
||
- Subcontratista en incumplimiento de contrato
|
||
- Póliza de garantía por vencer
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.2 Reporte de Incidente / Desviación
|
||
```
|
||
Quién puede reportar: CUALQUIER usuario del proyecto
|
||
Modalidad: normal o anónima (opción visible en el formulario)
|
||
|
||
Campos del reporte:
|
||
- Categoría y subcategoría (árbol desplegable)
|
||
- Severidad inicial (la evalúa el reportante):
|
||
* Verde — Observación / Potencial
|
||
* Amarillo — Desviación menor con riesgo controlable
|
||
* Naranja — Desviación mayor, requiere acción inmediata
|
||
* Rojo — Crítico / Emergencia
|
||
- Descripción libre del evento
|
||
- Fecha, hora y ubicación (geolocalización automática en móvil)
|
||
- Evidencia adjunta: fotos, videos, documentos (obligatorio si severidad ≥ Naranja)
|
||
- ¿Hubo lesionados? → si sí, abre sub-reporte médico
|
||
- ¿Hay riesgo inmediato activo? → activa protocolo de emergencia
|
||
- Personas involucradas (opcional si es anónimo)
|
||
- ¿Se detuvo el trabajo? Sí / No / Parcialmente
|
||
|
||
Reporte anónimo:
|
||
- No se almacena el usuario que lo envió
|
||
- Se registra solo: timestamp, IP hasheada, proyecto
|
||
- El sistema lo trata con la misma prioridad que uno firmado
|
||
- Nadie — ni el Super Admin — puede revelar quién lo envió
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.3 Flujo de Gestión de Desviación
|
||
```
|
||
PASO 1 — Detección y Clasificación
|
||
└── Reporte recibido (manual o automático)
|
||
└── Sistema asigna número consecutivo: HSE-2026-001
|
||
└── Notificación inmediata según severidad:
|
||
Verde → HSE Manager del proyecto
|
||
Amarillo → HSE Manager + Gerente de proyecto
|
||
Naranja → HSE Manager + Gerente + Director
|
||
Rojo → TODOS + protocolo de emergencia activado
|
||
|
||
PASO 2 — Evaluación Inicial (dentro de SLA por severidad)
|
||
└── HSE Manager o responsable evalúa el reporte
|
||
└── Confirma o ajusta la severidad
|
||
└── Asigna responsable de investigación
|
||
└── Define si se detiene el trabajo afectado:
|
||
Rojo / Naranja → detención automática recomendada
|
||
└── Registra acciones inmediatas tomadas
|
||
|
||
PASO 3 — Investigación
|
||
└── Análisis de causa raíz (métodos: 5 Porqués / Ishikawa / Bow-Tie)
|
||
└── Recolección de evidencia adicional
|
||
└── Entrevistas (registradas en el sistema)
|
||
└── Identificación de causas: inmediata / contribuyente / raíz
|
||
└── Evaluación de impacto real vs potencial
|
||
|
||
PASO 4 — Plan de Acción Correctiva y Preventiva (CAPA)
|
||
└── Acciones correctivas: eliminar la causa del incidente actual
|
||
└── Acciones preventivas: evitar recurrencia en otros proyectos
|
||
└── Cada acción tiene: responsable, fecha límite, evidencia requerida
|
||
└── Seguimiento automático con recordatorios
|
||
|
||
PASO 5 — Cierre
|
||
└── Verificación de que todas las acciones CAPA se ejecutaron
|
||
└── Evidencia de cierre cargada
|
||
└── Lecciones aprendidas documentadas
|
||
└── ¿Aplica a otros proyectos? → notificación cruzada automática
|
||
└── Firma de cierre del HSE Manager y Director
|
||
└── Reporte final generado en PDF
|
||
|
||
PASO 6 — Lecciones Aprendidas (Knowledge Base)
|
||
└── Incidente cerrado → se agrega a base de conocimiento
|
||
└── Disponible para consulta en todos los proyectos
|
||
└── Categorizado y buscable
|
||
└── Al crear un proyecto similar → sistema sugiere lecciones relevantes
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.4 Monitoreo Automático de Desviaciones
|
||
```
|
||
El sistema monitorea continuamente sin intervención humana:
|
||
|
||
VENCIMIENTOS (revisión diaria automática):
|
||
- Licencias y permisos del proyecto
|
||
- Certificaciones de equipos (grúas, calderas, recipientes a presión)
|
||
- Certificaciones de personal (soldadores, electricistas certificados, etc.)
|
||
- Pólizas de seguro y garantías
|
||
- Contratos de subcontratistas
|
||
- Calibración de instrumentos de medición
|
||
|
||
Alerta con anticipación configurable:
|
||
- 90 días antes → 🔵 Informativo
|
||
- 30 días antes → 🟡 Advertencia
|
||
- 15 días antes → 🟠 Urgente
|
||
- Vencido → 🔴 Crítico + bloqueo de actividades relacionadas
|
||
|
||
PARÁMETROS TÉCNICOS (si el proyecto los define):
|
||
- Rangos aceptables por variable (temperatura, presión, voltaje, etc.)
|
||
- Integración con IoT / sensores si aplica (vía API)
|
||
- Registro de lecturas con timestamp
|
||
- Alerta automática al salir del rango
|
||
|
||
INDICADORES HSE EN TIEMPO REAL:
|
||
- Días consecutivos sin accidente (contador visible en dashboard)
|
||
- Días sin incidente ambiental
|
||
- % de permisos de trabajo vencidos activos
|
||
- Tasa de near-miss reportados (positivo: indica cultura de seguridad)
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.5 Permisos de Trabajo
|
||
```
|
||
Para trabajos de alto riesgo, el sistema gestiona el permiso completo:
|
||
|
||
Tipos de permiso:
|
||
- Trabajo en altura (> 1.8m)
|
||
- Espacio confinado
|
||
- Trabajo en caliente (soldadura, esmeril, llama abierta)
|
||
- Energías peligrosas (lockout/tagout eléctrico, hidráulico, neumático)
|
||
- Excavaciones y zanjas
|
||
- Izaje de cargas (grúas, polipastos)
|
||
- Trabajos en sistemas energizados
|
||
- Trabajos nocturnos / en condiciones especiales
|
||
|
||
Flujo del permiso:
|
||
1. Solicitante llena formulario digital (desde móvil en campo)
|
||
2. Lista de verificación de condiciones de seguridad
|
||
3. APR — Análisis de Peligros de la Tarea (checklist)
|
||
4. Aprobación del supervisor HSE
|
||
5. Firma del ejecutante (acepta condiciones)
|
||
6. Vigencia: fecha/hora inicio y fin
|
||
7. Extensión requiere nueva aprobación
|
||
8. Cierre formal al terminar el trabajo
|
||
|
||
Bloqueo automático:
|
||
- Si el permiso vence y el trabajo sigue activo → alerta roja
|
||
- Sin permiso aprobado → la tarea asociada no puede iniciar
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.6 Dashboard HSE
|
||
```
|
||
Panel dedicado visible para todos los roles (solo lectura para colaboradores):
|
||
|
||
Indicadores principales:
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 🟢 127 días sin accidente con lesión │
|
||
│ 🟢 43 días sin incidente ambiental │
|
||
│ 📊 Near Miss reportados este mes: 8 (¡bueno!) │
|
||
│ ⚠️ Permisos por vencer (30 días): 3 │
|
||
│ 🔴 Incidentes abiertos críticos: 1 │
|
||
└─────────────────────────────────────────────────┘
|
||
|
||
Gráficas:
|
||
- Tendencia de incidentes por mes (últimos 12 meses)
|
||
- Distribución por categoría y severidad
|
||
- Mapa de calor: incidentes por área / fase del proyecto
|
||
- Estado de acciones CAPA (% completadas a tiempo)
|
||
- Pirámide de Bird (accidentes : incidentes : near miss : condiciones inseguras)
|
||
- Comparativo entre proyectos (benchmarking interno)
|
||
|
||
Semáforo HSE por proyecto (visible en Dashboard Global):
|
||
- Verde → sin incidentes críticos, todos los permisos vigentes
|
||
- Amarillo → incidentes menores abiertos o permisos próximos a vencer
|
||
- Rojo → incidente crítico abierto o permiso vencido activo
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.7 Indicadores HSE (KPIs Estándar Internacional)
|
||
```
|
||
Calculados automáticamente:
|
||
|
||
IFAR — Índice de Frecuencia de Accidentes con Baja
|
||
= (N° accidentes con baja × 1,000,000) / Horas hombre trabajadas
|
||
|
||
IIIR — Índice de Incidentes con Lesión
|
||
= (N° lesiones registrables × 200,000) / Horas hombre trabajadas
|
||
|
||
Tasa de Near Miss
|
||
= Near Miss reportados / Total incidentes × 100
|
||
(meta: > 80% → cultura de seguridad proactiva)
|
||
|
||
Tasa de Cierre CAPA a Tiempo
|
||
= Acciones cerradas en fecha / Total acciones × 100
|
||
|
||
Costo de incidentes
|
||
= Días perdidos × costo día + costo de investigación
|
||
+ costo de acciones correctivas + multas y sanciones
|
||
|
||
Horas hombre sin accidente
|
||
= Suma de horas trabajadas desde último accidente con lesión
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.8 Alertas y Escalada HSE
|
||
```
|
||
🔴 EMERGENCIA (notificación inmediata a todos):
|
||
- Accidente fatal o con lesión grave
|
||
- Derrame ambiental mayor
|
||
- Incendio, explosión o colapso estructural
|
||
- Evacuación requerida
|
||
→ Activa protocolo de emergencia: lista de contactos de emergencia,
|
||
número de servicios externos, procedimiento de evacuación
|
||
|
||
🔴 CRÍTICO:
|
||
- Trabajo ejecutado SIN permiso requerido
|
||
- Permiso de trabajo vencido con trabajo activo
|
||
- Certificación de equipo vencida en uso activo
|
||
- Incidente ambiental con afectación confirmada
|
||
- Incidente abierto sin responsable asignado > 2 horas
|
||
|
||
🟡 ADVERTENCIA:
|
||
- Near miss sin investigación > 24 horas
|
||
- Acción CAPA vencida sin completar
|
||
- 3 o más condiciones inseguras abiertas simultáneamente
|
||
- Permiso por vencer en 15 días
|
||
|
||
🔵 INFORMATIVO:
|
||
- Nuevo reporte recibido (anónimo o firmado)
|
||
- Acción CAPA completada
|
||
- Incidente cerrado con lecciones aprendidas
|
||
- Nuevo récord de días sin accidente
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.9 Reportes HSE
|
||
```
|
||
- Reporte mensual HSE por proyecto (PDF automático)
|
||
- Reporte ejecutivo multi-proyecto (comparativo)
|
||
- Registro de incidentes para autoridades regulatorias
|
||
- Estadísticas anuales HSE
|
||
- Reporte de lecciones aprendidas
|
||
- Estado de acciones CAPA
|
||
- Historial de permisos de trabajo
|
||
- Reporte de vencimientos (licencias, certificaciones, seguros)
|
||
- Exportar todo a Excel para auditorías externas
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.10 Actualización Estructura de Carpetas
|
||
```
|
||
Agregar a /frontend/src/components:
|
||
├── /hse
|
||
│ ├── IncidentReport.jsx # Reporte de incidente (normal + anónimo)
|
||
│ ├── IncidentList.jsx # Lista y filtros de incidentes
|
||
│ ├── IncidentDetail.jsx # Detalle + investigación + CAPA
|
||
│ ├── WorkPermit.jsx # Gestión de permisos de trabajo
|
||
│ ├── ExpirationMonitor.jsx # Monitor de vencimientos
|
||
│ ├── HSEDashboard.jsx # Dashboard HSE completo
|
||
│ ├── LessonsLearned.jsx # Base de conocimiento
|
||
│ └── EmergencyProtocol.jsx # Protocolo de emergencia
|
||
|
||
Agregar a /backend/src:
|
||
├── /hse
|
||
│ ├── incident.controller.js
|
||
│ ├── work-permit.controller.js
|
||
│ ├── capa.controller.js
|
||
│ ├── expiration-monitor.service.js # Cron job diario
|
||
│ ├── hse-kpi.service.js
|
||
│ └── anonymous-report.service.js # Sin trazabilidad de usuario
|
||
```
|
||
|
||
---
|
||
|
||
#### 12.11 Actualización de Fases de Construcción
|
||
```
|
||
Agregar a FASE 3 (Sprint 5-6):
|
||
□ Reporte de incidentes (normal y anónimo)
|
||
□ Gestión de permisos de trabajo
|
||
□ Monitor de vencimientos (cron job diario)
|
||
□ Alertas automáticas de vencimiento
|
||
|
||
Agregar a FASE 4 (Sprint 7-8):
|
||
□ Flujo completo de investigación y CAPA
|
||
□ Dashboard HSE con KPIs estándar internacionales
|
||
□ Base de lecciones aprendidas
|
||
□ Pirámide de Bird y tendencias
|
||
□ Semáforo HSE integrado al Dashboard Global
|
||
□ Protocolo de emergencia digital
|
||
□ Reportes HSE exportables
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 13: GESTIÓN DE CONTRATOS
|
||
|
||
**Principio: todo trabajo ejecutado debe originarse en un contrato. Sin contrato no hay OT, sin OT no hay pago.**
|
||
|
||
#### 13.1 Tipos de Contrato
|
||
```
|
||
- Contrato principal (con el cliente)
|
||
- Contrato de subcontratista
|
||
- Contrato de suministro (proveedor de materiales)
|
||
- Contrato de servicio (consultoría, ingeniería)
|
||
- Orden de compra (contrato simplificado)
|
||
- Carta de intención
|
||
- Acuerdo de confidencialidad (NDA)
|
||
```
|
||
|
||
#### 13.2 Campos del Contrato
|
||
```
|
||
- Número de contrato (consecutivo automático)
|
||
- Tipo y categoría
|
||
- Partes: contratante y contratado
|
||
- Objeto del contrato (descripción detallada)
|
||
- Valor total + moneda + forma de pago
|
||
- Fechas: firma, inicio, fin, vigencia de garantías
|
||
- Modalidad: precio fijo / administración delegada / precio unitario / mixto
|
||
- Hitos de pago vinculados a entregables
|
||
- Penalizaciones por incumplimiento (% / valor fijo / por día)
|
||
- Garantías requeridas: cumplimiento, anticipo, calidad, estabilidad
|
||
- Documentos adjuntos: contrato firmado (PDF), pólizas, anexos técnicos
|
||
- Proyecto(s) asociados
|
||
- Responsable interno del contrato
|
||
- Estado: Borrador / En revisión legal / Firmado / En ejecución /
|
||
Suspendido / Terminado / Liquidado
|
||
```
|
||
|
||
#### 13.3 Gestión de Adendas y Modificaciones
|
||
```
|
||
- Cada modificación genera una adenda numerada
|
||
- La adenda puede cambiar: valor, plazo, alcance, condiciones
|
||
- Requiere aprobación según monto (mismo flujo que pagos)
|
||
- Historial completo de versiones del contrato
|
||
- Impacto automático en presupuesto y cronograma del proyecto
|
||
- Notificación al Financiero y Director al aprobar adenda
|
||
```
|
||
|
||
#### 13.4 Control de Hitos de Pago Contractuales
|
||
```
|
||
- Cada contrato define hitos que habilitan pagos parciales
|
||
- Hito vinculado a entregable en el sistema
|
||
- Pago liberado solo cuando el entregable está aceptado formalmente
|
||
(Módulo 11 — Recepción de Entregables)
|
||
- Sin aceptación formal → pago bloqueado aunque el contrato lo diga
|
||
```
|
||
|
||
#### 13.5 Alertas de Contratos
|
||
```
|
||
🔴 CRÍTICO:
|
||
- Contrato vencido con trabajo activo
|
||
- Garantía vencida sin renovación
|
||
- Penalización activada por incumplimiento
|
||
|
||
🟡 ADVERTENCIA:
|
||
- Contrato por vencer en 30 días
|
||
- Garantía por vencer en 30 días
|
||
- Valor ejecutado supera el 90% del contrato sin adenda
|
||
|
||
🔵 INFORMATIVO:
|
||
- Contrato firmado y activo
|
||
- Adenda aprobada
|
||
- Hito de pago próximo (15 días)
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 14: VENDOR MANAGEMENT (GESTIÓN DE PROVEEDORES)
|
||
|
||
**Principio: solo proveedores homologados pueden recibir pagos del sistema.**
|
||
|
||
#### 14.1 Maestro de Proveedores
|
||
```
|
||
Información del proveedor:
|
||
- Razón social, NIT/RUT/EIN, representante legal
|
||
- Categoría: Contratista / Suministro / Servicios / Consultoría / Otro
|
||
- Especialidades (multiselect)
|
||
- Contactos: comercial, técnico, financiero
|
||
- Datos bancarios (encriptados)
|
||
- Documentos: cámara de comercio, RUT, seguros, certificaciones
|
||
- Países / ciudades donde opera
|
||
- Capacidad máxima de contratación simultánea
|
||
|
||
Estado de homologación:
|
||
- No registrado
|
||
- En evaluación
|
||
- Homologado (activo)
|
||
- Suspendido (con causa)
|
||
- Lista negra (con causa y fecha)
|
||
```
|
||
|
||
#### 14.2 Proceso de Homologación
|
||
```
|
||
Flujo para aprobar un nuevo proveedor:
|
||
|
||
1. Solicitud de registro (puede iniciarla el proveedor mismo vía portal)
|
||
2. Carga de documentos requeridos:
|
||
- Documentos legales de la empresa
|
||
- Experiencia certificada (proyectos similares)
|
||
- Referencias de clientes anteriores
|
||
- Capacidad financiera (estados financieros)
|
||
- Certificaciones técnicas aplicables
|
||
- Pólizas de seguro vigentes
|
||
3. Evaluación por el equipo de procurement
|
||
4. Visita técnica (opcional, con acta digital)
|
||
5. Aprobación del Director o Financiero
|
||
6. Alta en el sistema como proveedor homologado
|
||
|
||
Sin homologación → el sistema no permite crearle OT ni generarle pago
|
||
```
|
||
|
||
#### 14.3 Score de Proveedores
|
||
```
|
||
Calculado automáticamente después de cada proyecto:
|
||
|
||
Dimensiones (ponderadas):
|
||
- Calidad del trabajo (NCRs generados) — 30%
|
||
- Cumplimiento de plazos — 25%
|
||
- Cumplimiento de presupuesto — 20%
|
||
- Respuesta ante no conformidades — 15%
|
||
- Cumplimiento documental — 10%
|
||
|
||
Score total: 0-100
|
||
- 80-100 → Proveedor preferido (badge verde)
|
||
- 60-79 → Proveedor estándar
|
||
- 40-59 → Proveedor en observación (requiere supervisión adicional)
|
||
- < 40 → Suspensión automática hasta revisión
|
||
|
||
El score es visible al asignar proveedores a nuevos proyectos.
|
||
IA analiza el score histórico y advierte antes de asignar
|
||
un proveedor problemático.
|
||
```
|
||
|
||
#### 14.4 Portal del Proveedor
|
||
```
|
||
Acceso externo limitado para el proveedor:
|
||
- Ver sus OTs asignadas y estado
|
||
- Subir facturas y documentos de cobro
|
||
- Ver estado de sus pagos
|
||
- Recibir NCRs y responder
|
||
- Actualizar documentos próximos a vencer
|
||
- Ver su score y retroalimentación
|
||
|
||
No puede ver: otros proveedores, datos financieros globales,
|
||
información de otros proyectos
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 15: CONTROL DE DOCUMENTOS
|
||
|
||
**Principio: existe una sola versión vigente de cada documento. Las versiones anteriores son obsoletas y el sistema lo impone.**
|
||
|
||
#### 15.1 Tipos de Documentos Gestionados
|
||
```
|
||
- Planos de ingeniería (civil, eléctrico, mecánico, P&ID)
|
||
- Especificaciones técnicas
|
||
- Procedimientos de trabajo
|
||
- Manuales de operación y mantenimiento
|
||
- Informes y reportes
|
||
- Actas de reunión
|
||
- Contratos y adendas (vinculado al Módulo 13)
|
||
- Permisos y licencias
|
||
- Certificados y calibraciones
|
||
- Correspondencia formal (transmittals)
|
||
```
|
||
|
||
#### 15.2 Control de Revisiones
|
||
```
|
||
Nomenclatura estándar: DOC-PRY001-ELE-001-RevC
|
||
|
||
Cada revisión contiene:
|
||
- Número de revisión (Rev 0, Rev A, Rev B... o 00, 01, 02...)
|
||
- Fecha de emisión
|
||
- Autor y revisor
|
||
- Descripción de cambios respecto a revisión anterior
|
||
- Estado: En elaboración / En revisión / Aprobado / Obsoleto / Cancelado
|
||
|
||
Reglas:
|
||
- Al aprobar una nueva revisión → la anterior pasa a "Obsoleto" automáticamente
|
||
- Documentos obsoletos visibles pero con marca de agua "OBSOLETO"
|
||
- Nadie puede usar un documento obsoleto sin confirmación explícita
|
||
- Alerta si se adjunta a una tarea un documento en revisión (no aprobado)
|
||
```
|
||
|
||
#### 15.3 Registro de Transmittals
|
||
```
|
||
Transmittal = envío formal de documentos a terceros
|
||
|
||
Registro:
|
||
- Número de transmittal consecutivo
|
||
- Destinatario (interno o externo)
|
||
- Lista de documentos enviados (con revisión exacta)
|
||
- Fecha y medio de envío
|
||
- Acuse de recibo (con fecha y firma)
|
||
- Respuesta requerida: Sí / No + fecha límite
|
||
- Estado: Enviado / Recibido / Respondido / Vencido
|
||
|
||
El sistema rastrea si el destinatario tiene la última revisión
|
||
de cada documento. Si hay una nueva revisión → alerta automática
|
||
para emitir nuevo transmittal.
|
||
```
|
||
|
||
#### 15.4 Matriz de Distribución
|
||
```
|
||
Define quién debe tener qué documentos:
|
||
- Por rol, empresa o persona específica
|
||
- Actualización automática cuando hay nueva revisión
|
||
- Registro de quién tiene qué versión en todo momento
|
||
- Reporte de distribución para auditorías
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 16: GESTIÓN DE CAMBIOS (CHANGE MANAGEMENT)
|
||
|
||
**Principio: ningún cambio de alcance, costo o plazo se ejecuta sin aprobación formal. Los cambios no autorizados son la principal causa de descontrol en proyectos.**
|
||
|
||
#### 16.1 Solicitud de Cambio (Change Request)
|
||
```
|
||
Campos:
|
||
- Número CR consecutivo por proyecto
|
||
- Origen: Cliente / Equipo / Regulatorio / Técnico / HSE / Riesgo materializado
|
||
- Descripción del cambio propuesto
|
||
- Justificación
|
||
- Tipo: Alcance / Costo / Plazo / Técnico / Todos
|
||
- Urgencia: Normal / Urgente / Emergencia
|
||
|
||
Impacto estimado (obligatorio antes de aprobar):
|
||
- Impacto en cronograma: +/- X días
|
||
- Impacto en presupuesto: +/- $X
|
||
- Recursos adicionales requeridos
|
||
- Riesgos que introduce el cambio
|
||
- Documentos afectados (planos, especificaciones)
|
||
- Contratos que requieren adenda
|
||
```
|
||
|
||
#### 16.2 Flujo de Aprobación
|
||
```
|
||
1. Solicitante crea CR con descripción e impacto estimado
|
||
2. Gerente evalúa viabilidad técnica
|
||
3. Financiero evalúa impacto en presupuesto y flujo de caja
|
||
4. HSE evalúa si introduce nuevos riesgos
|
||
5. Director / Cliente aprueba o rechaza formalmente
|
||
6. Si aprobado:
|
||
→ Cronograma actualizado automáticamente
|
||
→ Presupuesto actualizado con nuevo baseline
|
||
→ OT generada si aplica
|
||
→ Adenda contractual iniciada si aplica
|
||
→ Documentos técnicos marcados para actualización
|
||
7. Registro inmutable de toda la cadena de decisión
|
||
```
|
||
|
||
#### 16.3 Log de Cambios
|
||
```
|
||
Visible en cada proyecto:
|
||
- Todos los CRs: aprobados, rechazados, pendientes
|
||
- Impacto acumulado de todos los cambios aprobados
|
||
- Comparativo: baseline original vs baseline actual
|
||
- Tendencia: ¿el proyecto está creciendo en scope?
|
||
- IA analiza si la frecuencia de cambios indica problemas de planificación
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 17: CIERRE DE PROYECTO
|
||
|
||
**Principio: un proyecto no está terminado hasta que está formalmente cerrado. El cierre activa la liberación de recursos y la memoria institucional.**
|
||
|
||
#### 17.1 Checklist de Cierre
|
||
```
|
||
El sistema genera automáticamente el checklist según el tipo de proyecto:
|
||
|
||
Técnico:
|
||
□ Todos los entregables aceptados formalmente (Módulo 11)
|
||
□ Punch list completado y firmado
|
||
□ Pruebas finales realizadas y documentadas
|
||
□ Planos as-built entregados y aprobados
|
||
□ Manuales de operación entregados
|
||
□ Capacitación al cliente realizada (si aplica)
|
||
|
||
Calidad:
|
||
□ Todos los NCRs cerrados
|
||
□ Auditoría final realizada
|
||
□ Certificados de calidad emitidos
|
||
|
||
HSE:
|
||
□ Todos los incidentes HSE cerrados
|
||
□ Área de trabajo entregada en condiciones seguras
|
||
□ Residuos y materiales peligrosos dispuestos correctamente
|
||
□ Permisos ambientales cerrados ante la autoridad
|
||
|
||
Financiero:
|
||
□ Todas las facturas recibidas y procesadas
|
||
□ Pagos pendientes identificados y programados
|
||
□ Retenciones liberadas o en proceso
|
||
□ Conciliación final de presupuesto vs real
|
||
□ Cierre del centro de costos
|
||
|
||
Contratos:
|
||
□ Contratos liquidados formalmente
|
||
□ Garantías liberadas o en período de mantenimiento
|
||
□ Reclamaciones resueltas
|
||
□ Acta de liquidación firmada por ambas partes
|
||
|
||
Documentos:
|
||
□ Archivo final del proyecto completo
|
||
□ Documentos entregados al cliente
|
||
□ Lecciones aprendidas documentadas
|
||
```
|
||
|
||
#### 17.2 Acta de Entrega Final
|
||
```
|
||
Documento generado automáticamente:
|
||
- Resumen ejecutivo del proyecto (vs baseline original)
|
||
- Desviaciones finales: costo, plazo, alcance
|
||
- Lista de entregables entregados y aceptados
|
||
- Pendientes con fecha de resolución
|
||
- Firma del Gerente, Director y Cliente
|
||
- QR de verificación de autenticidad
|
||
```
|
||
|
||
#### 17.3 Archivo del Proyecto
|
||
```
|
||
Al cerrar formalmente:
|
||
- Todo el proyecto queda en modo "solo lectura"
|
||
- Nadie puede modificar datos históricos
|
||
- Accesible para consulta y auditoría futura
|
||
- Lecciones aprendidas disponibles para nuevos proyectos similares
|
||
- Recursos liberados automáticamente (disponibles para otros proyectos)
|
||
- Contratos marcados como liquidados
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 18: PORTAL DEL CLIENTE
|
||
|
||
**El cliente ve lo que necesita ver — ni más ni menos.**
|
||
|
||
#### 18.1 Acceso y Vistas
|
||
```
|
||
El cliente externo tiene su propio login con acceso limitado:
|
||
|
||
Ve:
|
||
- Dashboard de su(s) proyecto(s): avance, hitos, estado general
|
||
- Cronograma simplificado (Gantt de hitos, no de todas las tareas)
|
||
- Entregables pendientes de su aprobación
|
||
- Documentos que le fueron transmitidos
|
||
- Reportes ejecutivos generados para él
|
||
- Facturas emitidas a su nombre y estado de pago
|
||
- Comunicaciones formales (transmittals)
|
||
- Fotos de avance (curadas por el Gerente)
|
||
|
||
NO ve:
|
||
- Costos internos, márgenes, tarifas del equipo
|
||
- NCRs internos (solo los que le afectan directamente)
|
||
- Datos de otros clientes
|
||
- Comunicaciones internas del equipo
|
||
- Datos financieros del contratista
|
||
```
|
||
|
||
#### 18.2 Aprobaciones del Cliente desde el Portal
|
||
```
|
||
- Recibe notificación cuando hay entregable para su aprobación
|
||
- Puede aprobar, rechazar o solicitar correcciones con comentarios
|
||
- Su aprobación dispara el flujo de pago correspondiente
|
||
- Puede firmar digitalmente documentos desde el portal
|
||
- Historial completo de todas sus aprobaciones
|
||
```
|
||
|
||
#### 18.3 Comunicación Formal
|
||
```
|
||
- Mensajería formal dentro del portal (no WhatsApp)
|
||
- Todos los mensajes quedan registrados con timestamp
|
||
- Puede adjuntar documentos
|
||
- El Gerente responde desde la app principal
|
||
- Generación automática de correspondencia formal si se requiere
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 19: LICITACIONES Y PROPUESTAS
|
||
|
||
**Antes de que nazca el proyecto: ganar el negocio.**
|
||
|
||
#### 19.1 Gestión de Oportunidades
|
||
```
|
||
Pipeline comercial:
|
||
- Nombre de la oportunidad, cliente potencial
|
||
- Valor estimado, probabilidad de ganar (%)
|
||
- Fecha límite de propuesta
|
||
- Contacto del cliente
|
||
- Estado: Identificada / En análisis / Propuesta en elaboración /
|
||
Propuesta enviada / Negociación / Ganada / Perdida / Cancelada
|
||
- Competidores identificados
|
||
- Estrategia de venta
|
||
|
||
Dashboard comercial:
|
||
- Pipeline total en valor
|
||
- Propuestas activas
|
||
- Tasa de éxito histórica
|
||
- Valor ganado vs perdido por período
|
||
```
|
||
|
||
#### 19.2 Elaboración de Propuesta
|
||
```
|
||
La propuesta se construye dentro del sistema:
|
||
|
||
Secciones:
|
||
1. Entendimiento del alcance
|
||
2. Metodología y approach técnico
|
||
3. Plan de trabajo (Gantt preliminar)
|
||
4. Equipo propuesto (recursos del maestro)
|
||
5. Estimación de costos:
|
||
- Mismos centros de costos del sistema
|
||
- Basada en históricos de proyectos similares
|
||
- IA sugiere rangos basada en proyectos anteriores del mismo tipo
|
||
6. Precio al cliente (con margen configurable)
|
||
7. Condiciones comerciales
|
||
8. Experiencia relevante (proyectos similares cerrados)
|
||
|
||
Al ganar la licitación:
|
||
→ "Convertir en proyecto" con un clic
|
||
→ La propuesta se convierte en el plan base del proyecto
|
||
→ El presupuesto estimado se convierte en el baseline
|
||
→ El Gantt preliminar se importa al cronograma
|
||
→ El equipo propuesto se asigna automáticamente
|
||
```
|
||
|
||
#### 19.3 Análisis de Licitaciones Perdidas
|
||
```
|
||
Al marcar una propuesta como "Perdida":
|
||
- Causa: precio / técnica / experiencia / relación / otro
|
||
- Precio ganador (si se conoce)
|
||
- Competidor ganador (si se conoce)
|
||
- Lecciones aprendidas
|
||
|
||
IA analiza el historial y sugiere:
|
||
- En qué tipo de proyectos tienes mayor tasa de éxito
|
||
- Rangos de precio competitivos por tipo de proyecto
|
||
- Debilidades recurrentes en propuestas perdidas
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 20: INTELIGENCIA ARTIFICIAL (MULTI-PROVEEDOR)
|
||
|
||
**Principio: cada empresa usa su propia IA. La plataforma es agnóstica del proveedor.**
|
||
|
||
#### 20.1 Arquitectura AI-Agnóstica
|
||
```
|
||
La plataforma implementa un adaptador universal:
|
||
|
||
/backend/src/ai/
|
||
├── ai-provider.interface.js # Contrato común para todos
|
||
├── ai.service.js # Orquestador — llama al proveedor activo
|
||
└── providers/
|
||
├── claude.provider.js # Anthropic Claude
|
||
├── openai.provider.js # OpenAI GPT-4 / GPT-4o
|
||
├── gemini.provider.js # Google Gemini
|
||
├── azure-openai.provider.js # Azure OpenAI (empresas Microsoft)
|
||
├── ollama.provider.js # IA local / on-premise
|
||
└── none.provider.js # Sin IA (plan básico)
|
||
|
||
Cada proveedor implementa los mismos métodos:
|
||
- analyze(context, prompt) → análisis
|
||
- generate(context, prompt) → texto generado
|
||
- predict(data, type) → predicción
|
||
- chat(history, message) → asistente conversacional
|
||
```
|
||
|
||
#### 20.2 Configuración por Empresa (Multi-tenant)
|
||
```
|
||
En Configuración → Inteligencia Artificial:
|
||
|
||
┌──────────────────────────────────────────┐
|
||
│ Proveedor de IA — Configuración │
|
||
├──────────────────────────────────────────┤
|
||
│ Proveedor: [Claude (Anthropic) ▼] │
|
||
│ API Key: [●●●●●●●●●●●●●●●●●●●●] │
|
||
│ Modelo: [claude-sonnet-4-6 ▼] │
|
||
│ Endpoint: [https://api.anthropic…] │
|
||
│ │
|
||
│ Ollama (local): │
|
||
│ URL servidor: [http://192.168.1.x:11434]│
|
||
│ Modelo local: [llama3:8b ▼] │
|
||
│ │
|
||
│ Privacidad: │
|
||
│ [✓] Enviar datos del proyecto a la IA │
|
||
│ [ ] Solo metadatos (sin nombres reales) │
|
||
│ │
|
||
│ [Probar conexión ▶] [Guardar ✓] │
|
||
└──────────────────────────────────────────┘
|
||
|
||
La API key se almacena encriptada (AES-256).
|
||
Nunca se loguea ni se expone en ningún endpoint.
|
||
```
|
||
|
||
#### 20.3 Funciones de IA en la Plataforma
|
||
|
||
**A) PREDICTIVO — Anticipa problemas antes de que ocurran**
|
||
```
|
||
Predicción de atrasos:
|
||
- Analiza velocidad actual de ejecución vs planificada
|
||
- Compara con proyectos históricos similares
|
||
- "Este proyecto tiene 78% de probabilidad de atrasarse
|
||
en la Fase 3 si no se aumentan recursos en instalación eléctrica"
|
||
|
||
Predicción de desvío de presupuesto:
|
||
- Proyecta el gasto final basado en la curva actual
|
||
- "A este ritmo, el costo final será $485,000 vs $400,000 presupuestados"
|
||
- Identifica las categorías que están causando el desvío
|
||
|
||
Predicción de conflictos de recursos:
|
||
- "El recurso Juan Pérez estará sobreasignado en la semana 12
|
||
por 3 proyectos simultáneos — riesgo de cuello de botella"
|
||
|
||
Predicción de flujo de caja:
|
||
- "En 18 días necesitarás $45,000 — tus fondos actuales
|
||
son insuficientes para cubrir ese requerimiento"
|
||
```
|
||
|
||
**B) ANALÍTICO — Encuentra patrones invisibles**
|
||
```
|
||
Análisis de causa raíz:
|
||
- "El 65% de tus NCRs en los últimos 3 meses involucran
|
||
al subcontratista ElectroCorp — score en caída"
|
||
|
||
Análisis de eficiencia:
|
||
- "Los proyectos de tipo Ingeniería Naval tienen 2.1x más
|
||
incidentes HSE en fase de instalación eléctrica vs otros tipos"
|
||
|
||
Detección de anomalías financieras:
|
||
- "Detecté 3 pagos al mismo proveedor en 48 horas sin OT
|
||
asociada — requiere revisión"
|
||
- "Este proveedor facturó 23% más que el valor contratado
|
||
sin adenda aprobada"
|
||
|
||
Análisis de licitaciones:
|
||
- "Tienes 82% de tasa de éxito en proyectos de ingeniería
|
||
naval con presupuesto entre $200K y $500K"
|
||
```
|
||
|
||
**C) GENERATIVO — Produce documentos y reportes**
|
||
```
|
||
Reporte ejecutivo semanal automático:
|
||
- Generado cada lunes con datos reales del sistema
|
||
- En lenguaje natural, orientado a la alta gerencia
|
||
- Resalta logros, riesgos y decisiones requeridas
|
||
- Listo para enviar al cliente o al directorio
|
||
|
||
Acta de reunión:
|
||
- El usuario ingresa los puntos discutidos
|
||
- IA genera el acta formal con formato estándar
|
||
- Incluye: asistentes, acuerdos, responsables, fechas
|
||
|
||
Respuesta sugerida a NCR:
|
||
- Basada en cómo se resolvieron NCRs similares anteriormente
|
||
- El responsable puede aceptar, editar o ignorar la sugerencia
|
||
|
||
Plan de acción CAPA:
|
||
- Basado en la causa raíz identificada
|
||
- Sugiere acciones correctivas y preventivas con responsables
|
||
|
||
Propuesta comercial:
|
||
- Basada en el alcance ingresado y proyectos similares históricos
|
||
- Draft inicial que el equipo refina
|
||
```
|
||
|
||
**D) ASISTENTE CONVERSACIONAL — Chat con tus proyectos**
|
||
```
|
||
Chat disponible en toda la app (ícono flotante):
|
||
|
||
Ejemplos de consultas:
|
||
→ "¿Cómo van mis proyectos activos?"
|
||
→ "¿Cuál proyecto tiene mayor riesgo de desvío esta semana?"
|
||
→ "¿Qué pagos vencen esta semana?"
|
||
→ "Muéstrame los NCRs abiertos de ElectroCorp"
|
||
→ "¿Cuánto hemos gastado en el proyecto Marina Lamberti?"
|
||
→ "¿Qué tareas están en ruta crítica y sin responsable?"
|
||
→ "Genera el reporte ejecutivo del proyecto X"
|
||
→ "¿Qué recursos están sobreasignados el próximo mes?"
|
||
|
||
La IA consulta los datos reales del sistema en tiempo real.
|
||
No inventa información — si no tiene datos, lo dice.
|
||
Contexto limitado a los proyectos del tenant actual.
|
||
```
|
||
|
||
**E) SUGERENCIAS PROACTIVAS — IA que no espera que le preguntes**
|
||
```
|
||
Aparecen como notificaciones inteligentes:
|
||
|
||
"💡 Basándome en el historial, este tipo de proyecto
|
||
suele tener problemas de calidad en soldaduras.
|
||
Considera agregar inspección específica en esa fase."
|
||
|
||
"💡 La Empresa ABC tiene un score de proveedor de 42/100.
|
||
Antes de asignarla a este proyecto, revisa los NCRs
|
||
del proyecto anterior."
|
||
|
||
"💡 Detecté que llevas 3 semanas sin actualizar el
|
||
cronograma del proyecto X. ¿Quieres que lo revise?"
|
||
|
||
"💡 Hay 2 proyectos con flujo de caja negativo la
|
||
misma semana. ¿Quieres ver las opciones?"
|
||
```
|
||
|
||
#### 20.4 Privacidad y Control
|
||
```
|
||
El usuario controla qué datos van a la IA:
|
||
- Opción "Solo metadatos" → no envía nombres, valores exactos
|
||
- Opción "Datos completos" → análisis más preciso
|
||
- Opción "Sin IA" → la función no está disponible para ese proyecto
|
||
|
||
Empresas reguladas (banca, gobierno, defensa):
|
||
- Pueden usar Ollama local → datos nunca salen de su red
|
||
- O Azure OpenAI con contrato de privacidad de datos de Microsoft
|
||
|
||
Log de uso de IA:
|
||
- Cada consulta queda registrada (qué se preguntó, cuándo)
|
||
- No se guarda la respuesta completa, solo el tipo de consulta
|
||
- Auditable por el Super Admin de la empresa
|
||
```
|
||
|
||
#### 20.5 Plan de Implementación IA
|
||
```
|
||
FASE 1 — Infraestructura (junto con Fase 1 del proyecto)
|
||
□ Arquitectura multi-proveedor implementada
|
||
□ Configuración por tenant (empresa)
|
||
□ Encriptación de API keys
|
||
□ Página de configuración IA en Settings
|
||
|
||
FASE 2 — Asistente básico (Fase 3 del proyecto)
|
||
□ Chat conversacional con datos del sistema
|
||
□ Generación de reportes ejecutivos
|
||
□ Sugerencias de respuesta a NCRs
|
||
|
||
FASE 3 — Predicciones (Fase 4 del proyecto)
|
||
□ Predicción de atrasos
|
||
□ Predicción de desvío de presupuesto
|
||
□ Detección de anomalías financieras
|
||
□ Sugerencias proactivas
|
||
|
||
FASE 4 — Analítica avanzada (Fase 5 del proyecto)
|
||
□ Análisis de causa raíz automático
|
||
□ Score predictivo de proveedores
|
||
□ Análisis de licitaciones y tasa de éxito
|
||
□ Benchmarking entre proyectos
|
||
```
|
||
|
||
---
|
||
|
||
### Módulo 6.8: PROYECCIÓN DE FLUJO DE CAJA Y ALERTAS DE LIQUIDEZ
|
||
|
||
*(Submódulo del Módulo 6 — Control Financiero)*
|
||
|
||
#### 6.8.1 Proyección por Proyecto
|
||
```
|
||
El sistema calcula automáticamente semana a semana:
|
||
|
||
Entradas (ingresos esperados):
|
||
- Pagos del cliente vinculados a hitos aprobados
|
||
- Anticipos contractuales pendientes
|
||
- Reembolsos aprobados
|
||
|
||
Salidas (egresos comprometidos):
|
||
- OTs aprobadas con fecha de pago estimada
|
||
- Hitos de pago de contratos con subcontratistas
|
||
- Nómina del equipo interno por semana
|
||
- Pagos recurrentes (licencias, arriendos, servicios)
|
||
- Retenciones a liberar
|
||
|
||
Cálculo:
|
||
Saldo disponible + Ingresos esperados - Egresos comprometidos
|
||
= Posición neta por semana
|
||
|
||
Visualización:
|
||
- Gráfica de barras apiladas semana a semana (12 semanas adelante)
|
||
- Línea de saldo mínimo requerido (configurable)
|
||
- Zona roja: semanas donde el saldo proyectado es negativo
|
||
```
|
||
|
||
#### 6.8.2 Vista Consolidada Multi-Proyecto
|
||
```
|
||
La vista más crítica para el Director Financiero:
|
||
|
||
- Flujo de caja combinado de TODOS los proyectos activos
|
||
- Identificación de semanas de alta presión de pagos
|
||
- Visualización de cruces: varios proyectos necesitan fondos la misma semana
|
||
- Saldo de caja global disponible vs requerimientos totales
|
||
- IA sugiere reordenamiento de pagos para suavizar el flujo
|
||
```
|
||
|
||
#### 6.8.3 Alertas Predictivas de Liquidez
|
||
```
|
||
🔴 CRÍTICO:
|
||
- Saldo proyectado negativo en los próximos 7 días
|
||
- Imposibilidad de cubrir nómina en la próxima semana
|
||
- 3 o más proyectos con déficit proyectado la misma semana
|
||
|
||
🟡 ADVERTENCIA:
|
||
- Saldo proyectado negativo en los próximos 30 días
|
||
- Saldo cae por debajo del mínimo requerido (configurable)
|
||
- Ingreso esperado del cliente con más de 15 días de atraso
|
||
|
||
🔵 INFORMATIVO:
|
||
- Semana con alta concentración de pagos (> $X)
|
||
- Ingreso de cliente confirmado y recibido
|
||
- Flujo de caja del mes dentro de parámetros normales
|
||
```
|
||
|
||
#### 6.8.4 Simulador de Escenarios
|
||
```
|
||
"¿Qué pasa si...?"
|
||
|
||
- ¿Qué pasa si el cliente se atrasa 2 semanas en su pago?
|
||
- ¿Qué pasa si aprobamos esta OT de $50,000 hoy?
|
||
- ¿Qué pasa si pausamos el proyecto X un mes?
|
||
- ¿Qué pasa si adelantamos el hito 3 del contrato?
|
||
|
||
El sistema recalcula el flujo de caja en tiempo real
|
||
con el escenario hipotético sin afectar los datos reales.
|
||
Permite comparar hasta 3 escenarios simultáneamente.
|
||
```
|
||
|
||
---
|
||
|
||
## SEGURIDAD — REQUERIMIENTOS OBLIGATORIOS
|
||
|
||
```
|
||
1. Autenticación
|
||
- JWT con refresh tokens (acceso: 15min, refresh: 7días)
|
||
- Invalidación de tokens al logout
|
||
- Bloqueo tras N intentos fallidos
|
||
|
||
2. Autorización
|
||
- RBAC (Role-Based Access Control) en cada endpoint
|
||
- Verificar permisos a nivel de proyecto Y de organización
|
||
- Usuarios no pueden ver proyectos a los que no pertenecen
|
||
|
||
3. Datos
|
||
- Validación estricta en frontend y backend
|
||
- Sanitización de inputs (prevenir XSS, SQL Injection)
|
||
- HTTPS obligatorio en producción
|
||
- Archivos adjuntos: validar tipo y tamaño, almacenar fuera del webroot
|
||
|
||
4. Auditoría
|
||
- Log inmutable de: login/logout, creaciones, ediciones, aprobaciones,
|
||
eliminaciones — con timestamp, usuario e IP
|
||
- Logs no pueden ser editados ni borrados por ningún usuario
|
||
|
||
5. Respaldos
|
||
- Backup automático de BD diario
|
||
- Política de retención de 30 días mínimo
|
||
```
|
||
|
||
---
|
||
|
||
## DISEÑO Y UX
|
||
|
||
**Estética objetivo:** Dashboard profesional estilo ejecutivo premium
|
||
- Paleta: fondo oscuro (#0F1117) con acentos en azul eléctrico (#2563EB) y verde (#10B981)
|
||
- Tipografía: Inter para UI, JetBrains Mono para números y códigos
|
||
- Cards con glassmorphism sutil
|
||
- Animaciones: transiciones suaves, números que "cuentan" al cargar
|
||
- Totalmente responsivo (desktop, tablet, móvil)
|
||
- Modo oscuro nativo (puede tener toggle claro/oscuro)
|
||
- Carga de datos con skeleton loaders, nunca pantallas en blanco
|
||
|
||
**Principios UX:**
|
||
- Máximo 3 clics para llegar a cualquier función
|
||
- Acciones destructivas con confirmación de doble paso
|
||
- Feedback visual inmediato en toda acción
|
||
- Estado vacío con guías de acción (no pantallas en blanco)
|
||
- Filtros persistentes por sesión
|
||
|
||
---
|
||
|
||
## ESTRUCTURA DE CARPETAS SUGERIDA
|
||
|
||
```
|
||
/project-manager-app
|
||
├── /frontend # React App
|
||
│ ├── /src
|
||
│ │ ├── /components
|
||
│ │ │ ├── /dashboard # KPIs, charts globales
|
||
│ │ │ ├── /projects # CRUD proyectos, Gantt, Kanban
|
||
│ │ │ ├── /tasks # Tareas, WBS
|
||
│ │ │ ├── /resources # Gestión de recursos
|
||
│ │ │ ├── /finance # Centro de costos, OT, pagos
|
||
│ │ │ ├── /risks # Matriz de riesgos
|
||
│ │ │ ├── /reports # Reportes y exportaciones
|
||
│ │ │ ├── /auth # Login, perfil
|
||
│ │ │ └── /shared # Botones, modales, tablas reutilizables
|
||
│ │ ├── /hooks
|
||
│ │ ├── /context
|
||
│ │ ├── /services # Llamadas a API
|
||
│ │ └── /utils
|
||
│ └── package.json
|
||
│
|
||
├── /backend # Node.js + Express
|
||
│ ├── /src
|
||
│ │ ├── /routes
|
||
│ │ ├── /controllers
|
||
│ │ ├── /services
|
||
│ │ ├── /middleware # auth, roles, validación, logs
|
||
│ │ ├── /models # Prisma schemas
|
||
│ │ └── /utils
|
||
│ ├── /prisma
|
||
│ │ └── schema.prisma
|
||
│ └── package.json
|
||
│
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## ORDEN DE CONSTRUCCIÓN (FASES)
|
||
|
||
```
|
||
FASE 1 — Fundamentos (Sprint 1-2)
|
||
□ Setup proyecto (Docker, DB, estructura)
|
||
□ Autenticación y roles
|
||
□ CRUD de proyectos (sin finanzas)
|
||
□ Dashboard básico (KPIs mockeados)
|
||
|
||
FASE 2 — Núcleo de Gestión (Sprint 3-4)
|
||
□ Módulo de tareas completo
|
||
□ Gantt interactivo
|
||
□ Kanban drag & drop
|
||
□ WBS jerárquico
|
||
□ Gestión de recursos (todos los tipos)
|
||
|
||
FASE 3 — Control Financiero (Sprint 5-6)
|
||
□ Centro de costos
|
||
□ Órdenes de trabajo + flujo de aprobación
|
||
□ Cotizaciones
|
||
□ Autorizaciones de pago
|
||
□ Sistema de alarmas
|
||
|
||
FASE 4 — Inteligencia y Reportes (Sprint 7-8)
|
||
□ EVM (Earned Value Management)
|
||
□ Gestión de riesgos
|
||
□ Reportes exportables
|
||
□ Notificaciones en tiempo real
|
||
□ Dashboard ejecutivo final con todas las gráficas
|
||
|
||
FASE 5 — Pulido y Seguridad (Sprint 9-10)
|
||
□ Auditoría completa
|
||
□ Tests (unitarios e integración)
|
||
□ Optimización de performance
|
||
□ Documentación API (Swagger)
|
||
□ Deploy guide
|
||
```
|
||
|
||
---
|
||
|
||
## UBICACIÓN DEL PROYECTO
|
||
|
||
```
|
||
Ruta local: D:\Proyectos Software\AR-ProjectManagement
|
||
|
||
Estructura raíz a crear:
|
||
D:\Proyectos Software\AR-ProjectManagement\
|
||
├── frontend\
|
||
├── backend\
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
└── README.md
|
||
```
|
||
|
||
**Instrucción para Claude Code:**
|
||
Todos los archivos deben crearse dentro de `D:\Proyectos Software\AR-ProjectManagement\`.
|
||
Nunca crear archivos fuera de esta ruta sin confirmación explícita.
|
||
Usar rutas relativas en el código; nunca hardcodear la ruta absoluta.
|
||
|
||
---
|
||
|
||
## INSTRUCCIONES ADICIONALES PARA CLAUDE CODE
|
||
|
||
1. **Construye una cosa a la vez**, en el orden de las fases. No saltes módulos.
|
||
2. **Siempre valida** inputs en frontend Y backend (nunca solo en uno).
|
||
3. **Cada endpoint** debe verificar autenticación y autorización antes de ejecutar.
|
||
4. **Datos de prueba**: incluir seed script con 3 proyectos de industrias distintas (ej: construcción de puente, álbum musical, implementación de ERP) con tareas, recursos y costos realistas.
|
||
5. **Comentarios de código**: en español, claros y orientados a negocio.
|
||
6. **Manejo de errores**: mensajes amigables al usuario, logs técnicos en backend.
|
||
7. **Performance**: paginación en todas las listas, índices en BD para búsquedas frecuentes.
|
||
8. **Nunca** hardcodear: URLs, credenciales, montos límite de aprobación — todo en variables de entorno o configuración en BD.
|
||
9. Al terminar cada fase, mostrar un resumen de lo construido y preguntar confirmación antes de continuar.
|
||
10. Si detectas una decisión arquitectónica importante, **explícala y pregunta** antes de implementarla.
|
||
|
||
---
|
||
|
||
*Generado para: Álvaro — Gerencia de Proyectos Universal*
|
||
*Versión: 5.0 FINAL | Fecha: Junio 2026 | 20 Módulos completos — ERP de Gerencia de Proyectos de Clase Mundial*
|