workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-002-proyectos-estructura/requerimientos-funcionales/RF-PROJ-004-asignacion-equipo-calendario.md

RF-PROJ-004: Asignación de Equipo y Calendario

Epic: MAI-002 - Proyectos y Estructura de Obra Tipo: Requerimiento Funcional Prioridad: Alta (P1) Estado: 📋 Pendiente Última actualización: 2025-11-17

---

📋 Descripción

El sistema debe permitir asignar personal clave al proyecto (director, residentes, ingenieros, supervisores) y gestionar el calendario general de obra con hitos, fases constructivas y fechas críticas. Esto facilita la organización del equipo de trabajo y el seguimiento de la programación del proyecto.

---

🎯 Objetivos

1. Organización: Definir equipo responsable del proyecto con roles claros
2. Trazabilidad: Registrar quién trabaja en qué proyecto y desde cuándo
3. Planificación: Programar hitos clave y fases constructivas
4. Control: Monitorear cumplimiento de fechas programadas
5. Comunicación: Notificar al equipo de cambios y eventos importantes

---

👥 Roles del Equipo de Proyecto

1. Director de Obra

Responsabilidad: Responsable general del proyecto, toma decisiones estratégicas

Rol: director
Perfil requerido:
  - Ingeniero Civil o Arquitecto
  - Mínimo 10 años de experiencia
  - Licencia de constructor (si aplica)
Responsabilidades:
  - Supervisión general del proyecto
  - Aprobación de estimaciones
  - Gestión de contratos con clientes
  - Toma de decisiones estratégicas
  - Representación ante el cliente
Límite de proyectos simultáneos: 5
Acceso en el sistema: Permisos completos en proyectos asignados

2. Residente de Obra

Responsabilidad: Supervisor en sitio, ejecución diaria de la obra

Rol: resident
Perfil requerido:
  - Ingeniero Civil, Arquitecto o afín
  - Mínimo 5 años de experiencia
  - Conocimiento de supervisión de obra
Responsabilidades:
  - Supervisión diaria en sitio
  - Control de avances físicos
  - Gestión de cuadrillas
  - Registro de asistencias
  - Supervisión de calidad
  - Gestión de incidencias
  - Requisiciones de materiales
Límite de proyectos simultáneos: 2
Acceso en el sistema: Permisos operativos en proyectos asignados

3. Ingeniero Especialista

Responsabilidad: Soporte técnico especializado (estructural, instalaciones, etc.)

Rol: engineer
Especialidades:
  - Ingeniero Estructural
  - Ingeniero en Instalaciones
  - Ingeniero Eléctrico
  - Ingeniero Hidráulico
  - Ingeniero de Costos
Responsabilidades:
  - Revisión de planos ejecutivos
  - Validación de procedimientos constructivos
  - Solución de problemas técnicos
  - Supervisión de instalaciones especializadas
Límite de proyectos simultáneos: 8 (soporte, no tiempo completo)
Acceso en el sistema: Solo lectura y comentarios técnicos

4. Supervisor de Cuadrilla

Responsabilidad: Liderazgo de cuadrilla especializada (albañilería, herrería, etc.)

Rol: supervisor_cuadrilla (no es rol del sistema, es empleado HR)
Perfil:
  - Experiencia en oficio (albañilería, plomería, etc.)
  - Capacidad de liderazgo de cuadrilla
Responsabilidades:
  - Coordinar trabajo de cuadrilla
  - Reportar avances al residente
  - Control de calidad de su especialidad
Límite de proyectos simultáneos: 1 (dedicación completa)
Acceso en el sistema: Vía app móvil (registro de avances)

5. Gerente de Compras

Responsabilidad: Gestión de requisiciones y órdenes de compra

Rol: purchases
Responsabilidades:
  - Recepción de requisiciones
  - Cotización con proveedores
  - Emisión de órdenes de compra
  - Gestión de almacén
Proyectos: Todos los de la constructora (servicio centralizado)
Acceso en el sistema: Módulo de compras de todos los proyectos

---

📋 Asignación de Equipo

1. Estructura de Asignación

# project_team_assignments
id: UUID
project_id: UUID del proyecto
user_id: UUID del usuario (de auth_management.users)
role: director | resident | engineer | purchases | finance | hr
specialty: structural | installations | electrical | costs | null
start_date: 2025-06-01
end_date: null (abierta) | 2026-05-31 (terminada)
is_active: true | false
is_primary: true | false (si es el responsable principal)
workload_percentage: 100 (tiempo completo) | 50 (medio tiempo) | 25 (soporte)

# Metadata
assigned_by: UUID del usuario que hizo la asignación
assigned_at: timestamp
removed_by: UUID (si se desasignó)
removed_at: timestamp
removal_reason: "Fin de proyecto" | "Reasignación" | null

2. Reglas de Asignación

Regla 1: Director Único

• Un proyecto debe tener exactamente 1 director activo
• No puede haber proyecto sin director
• Se puede cambiar de director (cierra asignación anterior, abre nueva)

Regla 2: Residente Principal

• Un proyecto debe tener al menos 1 residente marcado como is_primary: true
• Puede tener residentes adicionales de soporte
• Residente principal es el contacto principal en sitio

Regla 3: Ingenieros de Soporte

• Un proyecto puede tener 0 a N ingenieros especialistas
• No son obligatorios
• Un ingeniero puede estar en múltiples proyectos (workload_percentage distribuido)

Regla 4: Límite de Carga de Trabajo

• Director: max 500% (5 proyectos al 100%)
• Residente: max 200% (2 proyectos al 100% o 4 al 50%)
• Ingeniero: max 800% (soporte en múltiples proyectos)

3. Casos de Uso de Asignación

Caso 1: Arranque de Proyecto

Proyecto: Villas del Sol
Asignaciones iniciales:
  - Director: Ing. Roberto Martínez (100%, tiempo completo)
  - Residente Principal: Arq. Ana García (100%, tiempo completo)
  - Ingeniero Estructural: Ing. Carlos López (25%, soporte)
  - Ingeniero de Costos: Ing. María Sánchez (15%, soporte)

Caso 2: Cambio de Residente

# Situación
Residente original: Arq. Ana García (asignada desde 2025-06-01)
Motivo de cambio: Reasignación a otro proyecto

# Acciones
1. Cerrar asignación de Ana:
   - end_date: 2025-10-15
   - is_active: false
   - removal_reason: "Reasignación a Proyecto Alameda"

2. Crear nueva asignación:
   - Nuevo residente: Ing. Luis Ramírez
   - start_date: 2025-10-16
   - is_primary: true
   - workload_percentage: 100

# Resultado
Historial preservado, nuevo responsable activo

Caso 3: Proyecto con Múltiples Residentes

Proyecto grande: Torre Skyline (15 niveles)
Residentes:
  - Residente Principal: Ing. Pedro Gómez (is_primary: true, 100%)
  - Residente de Acabados: Arq. Laura Díaz (is_primary: false, 100%)
  - Residente de Instalaciones: Ing. Miguel Torres (is_primary: false, 50%)

# Justificación
Proyecto grande requiere múltiples residentes especializados

---

📅 Calendario General del Proyecto

1. Hitos del Proyecto (Milestones)

Definición: Eventos clave que marcan etapas importantes del proyecto

# project_milestones
id: UUID
project_id: UUID
milestone_type:
  - project_kickoff (arranque de proyecto)
  - permits_obtained (permisos obtenidos)
  - construction_start (inicio de construcción)
  - foundation_complete (cimentación terminada)
  - structure_complete (estructura terminada)
  - installations_complete (instalaciones terminadas)
  - finishes_start (inicio de acabados)
  - first_delivery (primera entrega)
  - urbanization_complete (urbanización terminada)
  - final_delivery (entrega final)
  - project_closure (cierre administrativo)
name: "Inicio de Construcción"
description: "Arranque oficial de obra en campo"
planned_date: 2025-06-15
actual_date: 2025-06-20 (si ya ocurrió) | null
status: pending | in_progress | completed | delayed
responsible: UUID del usuario responsable
dependencies: [milestone_id_1, milestone_id_2] (hitos previos requeridos)

Ejemplo de Hitos para Fraccionamiento

1. Arranque de Proyecto: 2025-05-01 ✅ (completado)
2. Permisos Obtenidos: 2025-05-28 ✅ (completado)
3. Inicio de Construcción: 2025-06-15 ✅ (completado 20/06)
4. Urbanización Etapa 1: 2025-08-30 🚧 (en progreso)
5. Primeras 20 Casas: 2025-10-15 📋 (pendiente)
6. Entrega Etapa 1 Completa: 2026-01-31 📋
7. Cierre del Proyecto: 2026-05-15 📋

2. Fases Constructivas

Definición: Periodos de tiempo para completar actividades específicas

# construction_phases
id: UUID
project_id: UUID
phase_type:
  - preliminary_work (trabajos preliminares)
  - foundation (cimentación)
  - structure (estructura)
  - walls (muros)
  - roof (techos)
  - installations (instalaciones)
  - finishes (acabados)
  - urbanization (urbanización)
  - cleanup (limpieza y entrega)
name: "Fase de Cimentación Etapa 1"
start_date: 2025-06-15
end_date: 2025-07-30
status: planned | active | completed | paused
progress_percentage: 65.5 (calculado de avances físicos)
assigned_team: [user_id_1, user_id_2]
budget_assigned: 2500000.00 MXN

3. Fechas Críticas (Deadlines)

Definición: Fechas límite que no se pueden retrasar sin consecuencias

# critical_dates
id: UUID
project_id: UUID
date: 2025-12-15
description: "Entrega comprometida con INFONAVIT"
category: client_commitment | permit_expiration | contract_deadline | financing
alert_days_before: 30 (notificar 30 días antes)
is_hard_deadline: true (no movible) | false (puede negociarse)
consequences_if_missed: "Multa de $500,000 MXN + intereses"
responsible: UUID del director
status: upcoming | at_risk | missed | met

---

📊 Dashboard del Equipo y Calendario

Vista del Equipo

┌─────────────────────────────────────────┐
│ Equipo del Proyecto: Villas del Sol    │
├─────────────────────────────────────────┤
│ 👔 Director                             │
│    Ing. Roberto Martínez                │
│    Desde: 01/05/2025                    │
│    Proyectos adicionales: 3             │
│                                         │
│ 👷 Residente Principal                  │
│    Arq. Ana García                      │
│    Desde: 01/06/2025                    │
│    Carga: 100% (tiempo completo)        │
│                                         │
│ 🔧 Ingenieros de Soporte                │
│    Ing. Carlos López (Estructural) 25%  │
│    Ing. María Sánchez (Costos) 15%      │
│                                         │
│ 📦 Almacenista                          │
│    Sr. Juan Pérez                       │
└─────────────────────────────────────────┘

Vista del Calendario

Línea de Tiempo (2025-2026)

May Jun Jul Ago Sep Oct Nov Dic Ene Feb Mar Abr May
 |───|───|───|───|───|───|───|───|───|───|───|───|
 ✓   ✓   🚧  📋  📋  📋  📋  📋  📋  📋  📋  📋  📋
Inicio  Cim Muro Inst Acab Urb Ent1     Ent2    Cierre

Hitos Críticos:
✓ Permisos: 28/05
✓ Inicio construcción: 15/06
🚧 Primera entrega: 15/10 (EN PROGRESO)
📋 Entrega Etapa 1: 31/01/2026
📋 Cierre: 15/05/2026

---

💼 Casos de Uso

CU-PROJ-011: Asignar Equipo al Proyecto

Actor: Director de Constructora

Precondiciones:

• Proyecto en estado "Adjudicado"
• Usuarios registrados en el sistema

Flujo Principal:

1. Usuario accede a proyecto "Villas del Sol"
2. Entra a pestaña "Equipo"
3. Hace clic en "Asignar Director"
4. Busca y selecciona: Ing. Roberto Martínez
5. Define:
   • Fecha inicio: 2025-05-01
   • Workload: 100%
   • Es principal: Sí
6. Guarda asignación
7. Sistema valida:
   • ✅ Roberto no excede límite de carga (tiene 3/5 proyectos)
   • ✅ Proyecto no tiene otro director activo
8. Crea asignación exitosamente
9. Envía notificación a Roberto: "Has sido asignado como Director de 'Villas del Sol'"

Resultado: Roberto es ahora director del proyecto, tiene acceso completo

CU-PROJ-012: Registrar Hito Completado

Actor: Residente de Obra

Precondiciones:

• Hito "Cimentación Completa" programado para 30/07/2025
• Fecha actual: 28/07/2025

Flujo Principal:

1. Residente verifica que cimentación de 80 viviendas está terminada
2. Accede a "Calendario" > "Hitos"
3. Selecciona hito "Cimentación Completa"
4. Hace clic en "Marcar como Completado"
5. Ingresa:
   • Fecha real: 28/07/2025 (2 días antes de lo programado)
   • Comentarios: "Terminado 2 días antes gracias a buen clima"
   • Evidencia: Foto general (5 MB JPG)
6. Confirma
7. Sistema:
   • Cambia estado a "completed"
   • Registra actual_date: 28/07/2025
   • Calcula desviación: -2 días (adelanto)
   • Marca como 🟢 verde (dentro de tiempo)
8. Notifica al equipo del proyecto

Resultado: Hito marcado como completado, equipo notificado

CU-PROJ-013: Alertar de Fecha Crítica Próxima

Actor: Sistema (automatizado)

Precondiciones:

• Fecha crítica: "Entrega INFONAVIT" el 15/12/2025
• Configurado: Alertar 30 días antes
• Fecha actual: 15/11/2025

Flujo Automático:

1. Cron job ejecuta diariamente a las 8:00 AM
2. Detecta fecha crítica en 30 días
3. Genera alerta automática:

   ⚠️ Fecha Crítica Próxima
   Proyecto: Villas del Sol
   Evento: Entrega comprometida con INFONAVIT
   Fecha límite: 15/12/2025 (30 días)
   Consecuencias si se incumple: Multa $500,000 + intereses
   Avance actual: 75% (requiere acelerar 10%)
   

4. Envía notificación a:
   • Director: Ing. Roberto Martínez
   • Residente: Arq. Ana García
   • Cliente (opcional): INFONAVIT
5. Crea alerta en dashboard visible

Resultado: Equipo alertado con anticipación, pueden tomar acciones

---

🧪 Casos de Prueba

TC-PROJ-012: Asignar Director ✅

Entrada:

{
  "projectId": "uuid-villas-del-sol",
  "userId": "uuid-roberto",
  "role": "director",
  "startDate": "2025-05-01",
  "workload": 100,
  "isPrimary": true
}

Salida Esperada:

{
  "assignmentId": "uuid-generated",
  "message": "Director asignado exitosamente",
  "notification_sent": true
}

TC-PROJ-013: Validar Límite de Carga ❌

Entrada:

{
  "userId": "uuid-director-saturado",  // Ya tiene 500% workload
  "projectId": "nuevo-proyecto",
  "workload": 100
}

Salida Esperada:

{
  "error": "El usuario excede su límite de carga (500% actual + 100% nuevo = 600%). Máximo permitido: 500%",
  "code": "WORKLOAD_EXCEEDED"
}

TC-PROJ-014: Crear Hito con Dependencias ✅

Entrada:

{
  "milestoneType": "construction_start",
  "plannedDate": "2025-06-15",
  "dependencies": ["milestone-permits-id"]  // Requiere permisos primero
}

Validación:

• Si "milestone-permits" no está completado → Error
• Si está completado → Crear hito ✅

---

🔐 Seguridad y Permisos

Permisos por Rol

Acción	Director	Engineer	Resident	Purchases
Asignar equipo	✅	❌	❌	❌
Desasignar equipo	✅	❌	❌	❌
Ver equipo	✅	✅	✅	✅
Crear hitos	✅	✅	❌	❌
Marcar hito como completado	✅	✅	✅	❌
Crear fechas críticas	✅	✅	❌	❌

---

📊 Reportes Requeridos

1. Resumen del Equipo

Director: Ing. Roberto Martínez (3 proyectos activos)
Residente: Arq. Ana García (1 proyecto, dedicación completa)
Ingenieros: 2 de soporte
Personal total: 5 personas

2. Calendario de Hitos

Completados: 3/10 (30%)
En progreso: 2/10 (20%)
Pendientes: 5/10 (50%)
Desviación promedio: -1.5 días (adelantados)

3. Alertas Activas

🔴 Críticas: 1 (Entrega INFONAVIT en 30 días)
🟡 Advertencias: 3 (Hitos con 5% de retraso)
🟢 Ok: 6

---

📋 Validaciones

1. Director único: Solo 1 director activo por proyecto
2. Residente obligatorio: Proyecto en ejecución requiere al menos 1 residente
3. Carga de trabajo: Validar que usuario no exceda límite de su rol
4. Fechas lógicas: start_date < end_date en asignaciones
5. Dependencias de hitos: Hitos dependientes no pueden completarse antes que sus requisitos

---

🔗 Dependencias

• RF-AUTH-002: Sistema de usuarios y roles (MAI-001)
• RF-HR-001: Empleados (cuadrillas de construcción) - MAI-007
• RF-PROG-001: Avances de obra (cálculo de progreso) - MAI-005

---

📈 Métricas de Éxito

• ✅ 100% de proyectos con director y residente asignados
• ✅ 90% de hitos completados dentro de ±5 días de lo programado
• ✅ 0 fechas críticas incumplidas sin notificación previa
• ✅ Tiempo de asignación de equipo: < 5 minutos

---

Fecha de creación: 2025-11-17 Versión: 1.0 Autor: Equipo de Producto Revisado por: Arquitecto de Software