71 KiB
71 KiB
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
- Construye una cosa a la vez, en el orden de las fases. No saltes módulos.
- Siempre valida inputs en frontend Y backend (nunca solo en uno).
- Cada endpoint debe verificar autenticación y autorización antes de ejecutar.
- 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.
- Comentarios de código: en español, claros y orientados a negocio.
- Manejo de errores: mensajes amigables al usuario, logs técnicos en backend.
- Performance: paginación en todas las listas, índices en BD para búsquedas frecuentes.
- Nunca hardcodear: URLs, credenciales, montos límite de aprobación — todo en variables de entorno o configuración en BD.
- Al terminar cada fase, mostrar un resumen de lo construido y preguntar confirmación antes de continuar.
- 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