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