# 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*