erp-construccion/docs/02-definicion-modulos/MAI-002-proyectos-estructura/requerimientos-funcionales/RF-PROJ-001-catalogo-proyectos.md

RF-PROJ-001: Catálogo de Proyectos

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

---

📋 Descripción

El sistema debe permitir la gestión completa de proyectos de construcción inmobiliaria, incluyendo fraccionamientos horizontales, conjuntos habitacionales y edificios verticales. Cada proyecto debe mantener información general, ubicación, datos del cliente, permisos legales y estados del ciclo de vida.

---

🎯 Objetivos

1. Centralizar información: Consolidar todos los datos del proyecto en un único registro
2. Trazabilidad: Rastrear el ciclo de vida completo desde licitación hasta cierre
3. Multi-proyecto: Permitir gestión simultánea de múltiples proyectos por constructora
4. Clasificación: Organizar proyectos por tipo, tamaño, ubicación y estado
5. Compliance: Registrar información legal y permisos requeridos

---

📐 Alcance Funcional

1. Tipos de Proyectos

El sistema debe soportar los siguientes tipos de proyectos inmobiliarios:

1.1 Fraccionamiento Horizontal

• Descripción: Desarrollo de viviendas unifamiliares en terreno extenso
• Características:
  • Dividido en etapas y manzanas
  • Lotes individuales con área de terreno
  • Viviendas independientes (casas)
  • Áreas comunes (vialidades, áreas verdes, caseta)
  • Urbanización completa (agua, luz, drenaje, pavimentación)
• Ejemplo: Fraccionamiento "Villas del Sol" con 250 viviendas en 15 hectáreas

1.2 Conjunto Habitacional

• Descripción: Desarrollo mixto con viviendas adosadas o en condominio horizontal
• Características:
  • Viviendas dúplex, tríplex o adosadas
  • Régimen de condominio
  • Amenidades compartidas (alberca, gym, salón de usos múltiples)
  • Áreas comunes más extensas que fraccionamiento
• Ejemplo: Conjunto "Residencial Alameda" con 80 dúplex y amenidades

1.3 Edificio Vertical

• Descripción: Torre o edificio multifamiliar de departamentos
• Características:
  • Múltiples niveles (pisos)
  • Departamentos por nivel
  • Elevadores y cuarto de máquinas
  • Estacionamiento (subterráneo o en niveles)
  • Amenidades en azotea o planta baja
• Ejemplo: Torre "Skyline Residences" con 15 niveles y 120 departamentos

1.4 Proyecto Mixto

• Descripción: Combinación de tipos (ej: torre + casas, comercial + residencial)
• Características:
  • Múltiples tipologías en un mismo desarrollo
  • Zonificación por uso (residencial, comercial, servicios)
  • Mayor complejidad en permisos y normativa
• Ejemplo: "Plaza Urbana" con torre de departamentos, casas dúplex y locales comerciales

2. Datos Generales del Proyecto

Cada proyecto debe registrar la siguiente información:

2.1 Información Básica

Nombre del proyecto: "Fraccionamiento Villas del Sol"
Tipo de proyecto: fraccionamiento_horizontal | conjunto_habitacional | edificio_vertical | mixto
Código interno: PROJ-2025-001 (generado automáticamente)
Descripción: Desarrollo de 250 viviendas de interés social en 15 hectáreas
Estado actual: licitacion | adjudicado | ejecucion | entregado | cerrado
Constructora: UUID de la constructora responsable

2.2 Datos del Cliente

Tipo de cliente: publico | privado | mixto
Nombre del cliente: "INFONAVIT Estatal"
RFC del cliente: INFXXXXXX123
Contacto principal:
  Nombre: "Ing. Roberto Martínez"
  Email: "rmartinez@infonavit.gob.mx"
  Teléfono: "+52 55 1234 5678"
Tipo de contrato: llave_en_mano | precio_alzado | administracion | mixto
Monto contratado: $125,000,000 MXN

2.3 Ubicación Geográfica

Dirección completa: "Carretera Federal 200 Km 45, Municipio de San Juan"
Estado: Jalisco
Municipio: San Juan del Río
Código postal: 76800
Coordenadas GPS:
  Latitud: 19.4326
  Longitud: -99.1332
Superficie total: 150,000 m² (15 hectáreas)
Superficie construible: 120,000 m² (80%)

2.4 Fechas Clave

Fecha de licitación: 2024-03-15
Fecha de adjudicación: 2024-04-30
Fecha de inicio contractual: 2024-05-15
Fecha de inicio real: 2024-05-20
Plazo contractual: 24 meses
Fecha de terminación programada: 2026-05-15
Fecha de terminación real: null (aún no concluye)
Fecha de entrega: null
Fecha de cierre administrativo: null

2.5 Información Legal y Permisos

Número de licencia de construcción: LIC-2024-SJR-0456
Fecha de emisión licencia: 2024-04-15
Vigencia de licencia: 2026-04-14
Número de manifestación de impacto ambiental: MIA-2024-045
Uso de suelo aprobado: H4 (Habitacional densidad media)
Número de plano autorizado: PLANO-SJR-2024-145
Número INFONAVIT (si aplica): INF-2024-JL-0123
Número FOVISSSTE (si aplica): null

3. Estados del Proyecto

El proyecto debe transitar por los siguientes estados:

3.1 Licitación 📋

• Descripción: Proyecto en proceso de concurso o licitación
• Acciones permitidas:
  • Crear proyecto
  • Editar información general
  • Subir documentación de licitación
  • Calcular presupuesto preliminar
• Transición: → Adjudicado (cuando se gana la licitación)

3.2 Adjudicado ✅

• Descripción: Proyecto ganado, pendiente de inicio de obra
• Acciones permitidas:
  • Asignar equipo de obra (residente, ingeniero, supervisores)
  • Crear estructura jerárquica (etapas, manzanas, lotes)
  • Cargar presupuesto definitivo
  • Registrar contrato firmado
  • Tramitar permisos y licencias
• Transición: → Ejecución (cuando se arranca obra)

3.3 Ejecución 🚧

• Descripción: Obra en construcción activa
• Acciones permitidas:
  • Registrar avances físicos
  • Generar estimaciones
  • Gestionar compras e inventarios
  • Registrar asistencias de personal
  • Subir evidencias fotográficas
  • Gestionar incidencias
  • Modificar presupuesto (con aprobación)
• Transición: → Entregado (cuando obra finaliza y se entrega al cliente)

3.4 Entregado 📦

• Descripción: Obra terminada y entregada al cliente, periodo de garantía
• Acciones permitidas:
  • Registrar acta de entrega
  • Gestionar postventa (garantías, defectos, bitácora)
  • Generar finiquito
  • Cerrar presupuesto final
• Transición: → Cerrado (cuando se cierra administrativamente)

3.5 Cerrado 🔒

• Descripción: Proyecto cerrado administrativamente, solo consulta
• Acciones permitidas:
  • Solo lectura de información histórica
  • Exportar reportes finales
  • Consultar lecciones aprendidas
• Transición: No hay (estado final)

4. Métricas y KPIs por Proyecto

Cada proyecto debe calcular y mostrar las siguientes métricas:

4.1 Métricas Físicas

Total de viviendas: 250
Viviendas entregadas: 187 (74.8%)
Viviendas en proceso: 63 (25.2%)
Superficie total construida: 18,750 m² (75 m² × 250)
Avance físico general: 78.5%

4.2 Métricas Financieras

Presupuesto total: $125,000,000
Costo ejercido: $97,125,000 (77.7%)
Disponible: $27,875,000 (22.3%)
Desviación presupuestal: +2.5% (sobre presupuesto)
Estimaciones cobradas: $95,000,000 (76%)

4.3 Métricas de Tiempo

Plazo contractual: 24 meses
Tiempo transcurrido: 18 meses (75%)
Avance programado (curva S): 80%
Desviación temporal: -1.5% (atrasado)
Días hábiles restantes: 120

4.4 Métricas de Recursos

Personal asignado: 85 empleados
Equipos asignados: 12 (excavadoras, revolvedoras, etc.)
Proveedores activos: 32
Órdenes de compra emitidas: 287

5. Documentación del Proyecto

El sistema debe permitir gestionar los siguientes documentos:

5.1 Documentos Contractuales

• Contrato firmado (PDF)
• Anexos técnicos
• Convenios modificatorios
• Fianzas (anticipo, cumplimiento, vicios ocultos)

5.2 Documentos Técnicos

• Proyecto ejecutivo (planos arquitectónicos, estructurales, instalaciones)
• Especificaciones técnicas
• Catálogo de conceptos
• Estudios de mecánica de suelos

5.3 Documentos Legales

• Licencia de construcción
• Manifestación de impacto ambiental
• Uso de suelo
• Permisos de CONAGUA, CFE, etc.
• Escrituras del terreno

5.4 Documentos de Cierre

• Actas de entrega-recepción
• Finiquito
• Planos as-built (como quedó construido)
• Manuales de operación y mantenimiento

6. Relaciones del Proyecto

Un proyecto se relaciona con las siguientes entidades:

6.1 Estructura Jerárquica (RF-PROJ-002)

• Etapas: Proyecto dividido en fases constructivas
• Manzanas: Agrupación de lotes (solo fraccionamientos)
• Lotes: Terrenos individuales con viviendas
• Viviendas: Unidades habitacionales (basadas en prototipos)

6.2 Equipo Asignado (RF-PROJ-004)

• Director de Obra: Responsable general del proyecto
• Residente de Obra: Supervisor en sitio
• Ingenieros: Especialistas (estructural, instalaciones, etc.)
• Personal RRHH: Cuadrillas asignadas al proyecto

6.3 Presupuesto (MAI-003)

• Presupuesto maestro: Costo total del proyecto
• Presupuestos por etapa: Desglose por fase
• Precios unitarios: Matriz de insumos por concepto

6.4 Compras e Inventarios (MAI-004)

• Almacén del proyecto: Inventario en obra
• Requisiciones: Solicitudes de materiales
• Órdenes de compra: Compras autorizadas

6.5 Control de Obra (MAI-005)

• Avances físicos: Progreso de actividades
• Estimaciones: Generación de cobros
• Incidencias: Problemas registrados

---

🔄 Flujo de Vida del Proyecto

stateDiagram-v2
    [*] --> Licitacion: Crear proyecto
    Licitacion --> Adjudicado: Ganar licitación
    Licitacion --> [*]: Perder licitación (eliminar)
    Adjudicado --> Ejecucion: Arrancar obra
    Ejecucion --> Entregado: Finalizar y entregar
    Entregado --> Cerrado: Cierre administrativo
    Cerrado --> [*]

---

💼 Casos de Uso

CU-PROJ-001: Crear Proyecto de Fraccionamiento

Actor: Director de Constructora

Precondiciones:

• Usuario autenticado con rol director
• Constructora activa en el sistema

Flujo Principal:

1. Usuario accede a "Proyectos" > "Nuevo Proyecto"
2. Selecciona tipo: "Fraccionamiento Horizontal"
3. Ingresa datos generales:
   • Nombre: "Villas del Sol Etapa 2"
   • Cliente: INFONAVIT Estatal
   • Ubicación: Jalisco, San Juan del Río
   • Superficie: 10 hectáreas
4. Carga documentos contractuales:
   • Contrato firmado (PDF, 2.5 MB)
   • Licencia de construcción
5. Define fechas clave:
   • Inicio: 2025-06-01
   • Plazo: 18 meses
   • Fin programado: 2026-11-30
6. Asigna monto contratado: $85,000,000 MXN
7. Guarda proyecto con estado: "Adjudicado"
8. Sistema genera código: PROJ-2025-002
9. Usuario recibe confirmación: "Proyecto creado exitosamente"

Resultado: Proyecto creado, visible en catálogo, listo para configuración de estructura jerárquica

CU-PROJ-002: Transitar Proyecto a Ejecución

Actor: Residente de Obra

Precondiciones:

• Proyecto en estado "Adjudicado"
• Equipo de obra asignado
• Presupuesto cargado
• Permisos completos

Flujo Principal:

1. Usuario accede a proyecto "Villas del Sol Etapa 2"
2. Verifica checklist de pre-arranque:
   • ✅ Equipo asignado
   • ✅ Presupuesto aprobado
   • ✅ Licencia vigente
   • ✅ Estructura jerárquica definida
   • ✅ Contrato firmado
3. Hace clic en "Iniciar Obra"
4. Sistema solicita confirmación con fecha de inicio real
5. Usuario confirma: 2025-06-15 (5 días después del contractual)
6. Sistema cambia estado a "Ejecución"
7. Activa módulos de obra:
   • Control de avances
   • Compras e inventarios
   • Asistencias de personal
8. Genera primera estimación: #001

Resultado: Proyecto en ejecución, módulos activos, listo para operación diaria

CU-PROJ-003: Consultar Dashboard del Proyecto

Actor: Ingeniero Residente

Precondiciones:

• Proyecto en estado "Ejecución"
• Avances registrados

Flujo Principal:

1. Usuario accede a proyecto
2. Ve dashboard con:
   • Avance físico: 78.5% (curva S vs plan)
   • Avance financiero: 77.7% ejercido
   • Personal: 85 empleados activos
   • Alertas:
     • 🔴 3 partidas con desviación > 15%
     • 🟡 5 materiales con stock bajo
     • 🟢 Estimación #12 cobrada
3. Hace clic en "Curva S"
4. Ve gráfica comparativa:
   • Línea azul: Programado (80%)
   • Línea verde: Real (78.5%)
   • Línea roja: Proyección (97% al cierre)
5. Identifica retraso de -1.5%
6. Genera reporte semanal en PDF

Resultado: Información clave del proyecto visualizada, reporte generado

CU-PROJ-004: Cerrar Proyecto Administrativamente

Actor: Director de Constructora

Precondiciones:

• Proyecto en estado "Entregado"
• Acta de entrega firmada
• Finiquito generado
• Sin pendientes legales o financieros

Flujo Principal:

1. Usuario accede a proyecto "Villas del Sol Etapa 2"
2. Verifica checklist de cierre:
   • ✅ Todas las viviendas entregadas (250/250)
   • ✅ Acta de entrega firmada
   • ✅ Finiquito generado y firmado
   • ✅ Garantías activadas (12 meses)
   • ✅ Sin adeudos con proveedores
   • ✅ Personal desasignado
3. Hace clic en "Cerrar Proyecto"
4. Sistema solicita confirmación
5. Usuario confirma con contraseña
6. Sistema:
   • Cambia estado a "Cerrado"
   • Congela todos los datos (no editables)
   • Genera reporte final automático
   • Archiva documentos en storage
   • Libera recursos (almacén, equipo)
7. Envía notificación a equipo de proyecto

Resultado: Proyecto cerrado, datos históricos preservados, recursos liberados

---

🧪 Casos de Prueba

TC-PROJ-001: Crear Proyecto de Fraccionamiento ✅

Entrada:

{
  "name": "Fraccionamiento Jardines del Norte",
  "projectType": "fraccionamiento_horizontal",
  "clientName": "INFONAVIT Jalisco",
  "clientRFC": "INF850101ABC",
  "contractAmount": 95000000,
  "surfaceArea": 120000,
  "address": "Carretera a Tesistán Km 12",
  "state": "Jalisco",
  "municipality": "Zapopan",
  "startDate": "2025-07-01",
  "contractDuration": 20
}

Salida Esperada:

{
  "id": "uuid-generated",
  "projectCode": "PROJ-2025-003",
  "status": "adjudicado",
  "createdAt": "2025-11-17T10:30:00Z",
  "message": "Proyecto creado exitosamente"
}

TC-PROJ-002: Validar Transición de Estados ✅

Escenario 1: Licitación → Adjudicado

• Input: Estado actual = "licitacion", Acción = "adjudicar"
• Output: Estado = "adjudicado" ✅

Escenario 2: Adjudicado → Licitación (inválido)

• Input: Estado actual = "adjudicado", Acción = "regresar a licitacion"
• Output: Error 400 "Transición no permitida" ❌

Escenario 3: Ejecución → Cerrado (inválido, falta estado Entregado)

• Input: Estado actual = "ejecucion", Acción = "cerrar"
• Output: Error 400 "Debe entregar el proyecto antes de cerrar" ❌

TC-PROJ-003: Validar Campos Obligatorios ❌

Entrada:

{
  "name": "",
  "projectType": "fraccionamiento_horizontal",
  "contractAmount": -5000
}

Salida Esperada:

{
  "errors": [
    {
      "field": "name",
      "message": "El nombre del proyecto es obligatorio"
    },
    {
      "field": "contractAmount",
      "message": "El monto contratado debe ser mayor a 0"
    },
    {
      "field": "clientName",
      "message": "El nombre del cliente es obligatorio"
    }
  ]
}

TC-PROJ-004: Cálculo de Métricas ✅

Entrada:

• Viviendas totales: 200
• Viviendas entregadas: 150
• Presupuesto: $100,000,000
• Costo ejercido: $78,000,000

Salida Esperada:

{
  "metrics": {
    "physicalProgress": 75.0,
    "financialProgress": 78.0,
    "budgetDeviation": 4.0,
    "status": "green"
  }
}

---

🔐 Seguridad y Permisos

Permisos por Rol

Acción	Director	Engineer	Resident	Purchases	Finance	HR
Crear proyecto	✅	✅	❌	❌	❌	❌
Editar info general	✅	✅	✅	❌	❌	❌
Ver dashboard	✅	✅	✅	✅	✅	✅
Transitar estados	✅	✅	✅	❌	❌	❌
Subir documentos	✅	✅	✅	❌	❌	❌
Eliminar proyecto	✅	❌	❌	❌	❌	❌
Cerrar proyecto	✅	❌	❌	❌	❌	❌

Row Level Security (RLS)

Todos los proyectos deben estar filtrados por constructoraId:

CREATE POLICY project_isolation ON projects.projects
  USING (constructora_id = current_setting('app.current_constructora_id')::uuid);

---

📊 Reportes Requeridos

1. Catálogo General de Proyectos

• Lista paginada con filtros
• Ordenable por fecha, estado, monto
• Exportable a Excel

2. Dashboard Ejecutivo por Proyecto

• Resumen de avances físico/financiero
• Curva S (plan vs real)
• Alertas críticas

3. Reporte de Cierre de Proyecto

• Datos finales consolidados
• Lecciones aprendidas
• Comparativo presupuesto vs real

---

📋 Validaciones

Validaciones de Negocio

1. Nombre único por constructora: No puede haber dos proyectos con el mismo nombre en la misma constructora
2. Fecha inicio < fecha fin: La fecha de inicio debe ser anterior a la fecha programada de terminación
3. Monto > 0: El monto contratado debe ser mayor a cero
4. Superficie > 0: La superficie total debe ser mayor a cero
5. Transiciones válidas: Solo se permiten transiciones de estado según el diagrama de estados

Validaciones Técnicas

1. RFC válido: El RFC del cliente debe tener formato válido (12-13 caracteres)
2. Coordenadas GPS: Latitud entre -90 y 90, Longitud entre -180 y 180
3. Código postal: 5 dígitos numéricos
4. Archivos: PDF, JPG, PNG, DWG permitidos, máximo 10 MB por archivo

---

🔗 Dependencias

Dependencias de Otros RFs

• RF-AUTH-002: Sistema de roles y permisos (MAI-001)
• RF-AUTH-003: Multi-tenancy por constructora (MAI-001)
• RF-PROJ-002: Estructura jerárquica de obra (siguiente RF)
• RF-BUD-001: Presupuesto maestro (MAI-003)

Dependencias Técnicas

• PostgreSQL 15+ con soporte de JSONB para metadata
• S3-compatible storage para documentos
• PostGIS para coordenadas geográficas (opcional)

---

📈 Métricas de Éxito

• ✅ 100% de proyectos con información completa (0 campos nulos en obligatorios)
• ✅ Tiempo promedio de creación de proyecto: < 10 minutos
• ✅ 95% de transiciones de estado exitosas en primer intento
• ✅ 0 proyectos con datos inconsistentes (validaciones activas)

---

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