workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-002-proyectos-estructura/implementacion/TRACEABILITY.yml

# TRACEABILITY - MAI-002: Proyectos y Estructura de Obra
metadata:
  modulo: MAI-002
  nombre: Proyectos y Estructura de Obra
  version: 1.0.0
  fecha: 2025-12-06
  reutilizacion_core: 40%
  descripcion: >
    Sistema de gestión de proyectos de construcción inmobiliaria con estructura jerárquica
    (Fraccionamiento → Etapa → Manzana → Lote → Vivienda), prototipos de vivienda,
    asignación de equipo y calendario de obra.    

requerimientos:
  - id: RF-PROJ-001
    titulo: Catálogo de Proyectos
    descripcion: >
      Gestión completa de proyectos de construcción inmobiliaria incluyendo
      fraccionamientos, conjuntos habitacionales y edificios verticales con
      información general, ubicación, datos del cliente, permisos legales y
      estados del ciclo de vida.      
    especificaciones:
      - ET-PROJ-001-implementacion-catalogo-proyectos
      - ET-PROJ-001-rls-policies
    historias_usuario:
      - US-PROJ-001-catalogo-proyectos
      - US-PROJ-002-transiciones-estado
    tablas:
      - project_management.projects
      - project_management.project_documents
      - project_management.project_metrics
    endpoints:
      - POST /api/v1/projects
      - GET /api/v1/projects
      - GET /api/v1/projects/:id
      - PATCH /api/v1/projects/:id
      - POST /api/v1/projects/:id/change-status
      - GET /api/v1/projects/:id/metrics
      - GET /api/v1/projects/:id/dashboard
      - POST /api/v1/projects/:id/documents
      - GET /api/v1/projects/:id/documents
    componentes_ui:
      - ProjectList
      - ProjectCard
      - ProjectForm
      - ProjectDetail
      - ProjectDashboard
      - ProjectMetrics
      - ProjectStatusBadge
      - ProjectDocuments
    estado: pendiente
    prioridad: P0
    dependencias:
      - RF-AUTH-002 (Roles y permisos)
      - RF-AUTH-003 (Multi-tenancy por constructora)
    validaciones:
      - Nombre único por constructora
      - Transiciones de estado válidas
      - Monto contratado > 0
      - Fecha inicio < fecha fin
      - RFC válido (12-13 caracteres)

  - id: RF-PROJ-002
    titulo: Estructura Jerárquica de Obra
    descripcion: >
      Definición y gestión de la estructura jerárquica de proyectos de construcción
      organizando el desarrollo en Etapas → Manzanas (opcional) → Lotes → Viviendas.
      Permite rastrear avances físicos, asignar presupuestos y gestionar entregas
      de forma granular.      
    especificaciones:
      - ET-PROJ-002-implementacion-estructura-jerarquica
      - ET-PROJ-002-rls-policies
    historias_usuario:
      - US-PROJ-003-estructura-fraccionamiento
      - US-PROJ-004-estructura-torre-vertical
    tablas:
      - project_management.stages
      - project_management.blocks
      - project_management.lots
      - project_management.housing_units
      - project_management.unit_progress
    endpoints:
      - POST /api/v1/projects/:projectId/stages
      - GET /api/v1/projects/:projectId/stages
      - GET /api/v1/stages/:id
      - PATCH /api/v1/stages/:id
      - DELETE /api/v1/stages/:id
      - POST /api/v1/stages/:stageId/blocks
      - GET /api/v1/stages/:stageId/blocks
      - POST /api/v1/blocks/:blockId/lots
      - GET /api/v1/blocks/:blockId/lots
      - PATCH /api/v1/lots/:id
      - POST /api/v1/lots/:lotId/housing
      - GET /api/v1/housing-units/:id
      - PATCH /api/v1/housing-units/:id/status
      - GET /api/v1/projects/:id/hierarchy
    componentes_ui:
      - StageList
      - StageForm
      - BlockList
      - BlockForm
      - LotList
      - LotForm
      - HousingUnitCard
      - HousingUnitDetail
      - ProjectHierarchyTree
      - ProgressTracker
    estado: pendiente
    prioridad: P0
    dependencias:
      - RF-PROJ-001 (Catálogo de proyectos)
      - RF-PROJ-003 (Prototipos - para asignación)
    validaciones:
      - Códigos únicos dentro del proyecto
      - Jerarquía válida (lote → manzana → etapa)
      - Suma de lotes = total declarado en etapa
      - Área de lote > 0
      - Estado secuencial (no saltar estados)

  - id: RF-PROJ-003
    titulo: Prototipos de Vivienda
    descripcion: >
      Creación y gestión de prototipos de vivienda estandarizados (casas, departamentos,
      dúplex) que sirven como plantillas para asignación a lotes. Define características
      arquitectónicas, áreas, distribución, acabados estándar y costos estimados.      
    especificaciones:
      - ET-PROJ-003-implementacion-prototipos
    historias_usuario:
      - US-PROJ-005-gestion-prototipos
      - US-PROJ-006-asignacion-prototipos-lotes
    tablas:
      - project_management.housing_prototypes
      - project_management.prototype_versions
      - project_management.prototype_documents
      - project_management.prototype_costs
    endpoints:
      - POST /api/v1/prototypes
      - GET /api/v1/prototypes
      - GET /api/v1/prototypes/:id
      - PATCH /api/v1/prototypes/:id
      - DELETE /api/v1/prototypes/:id
      - POST /api/v1/prototypes/:id/versions
      - GET /api/v1/prototypes/:id/versions
      - POST /api/v1/prototypes/:id/documents
      - POST /api/v1/lots/bulk-assign-prototypes
    componentes_ui:
      - PrototypeList
      - PrototypeCard
      - PrototypeForm
      - PrototypeDetail
      - PrototypeVersionHistory
      - PrototypeCostCalculator
      - BulkPrototypeAssignment
      - PrototypeComparison
    estado: pendiente
    prioridad: P1
    dependencias:
      - RF-PROJ-002 (Para asignación a lotes)
    validaciones:
      - Código único por constructora
      - Área construida > 0
      - Costo por m² > 0
      - Versiones secuenciales
      - Archivos válidos (PDF, JPG, PNG, DWG)

  - id: RF-PROJ-004
    titulo: Asignación de Equipo y Calendario
    descripcion: >
      Asignación de personal clave al proyecto (director, residentes, ingenieros,
      supervisores) y gestión del calendario general de obra con hitos, fases
      constructivas y fechas críticas para facilitar organización y seguimiento.      
    especificaciones:
      - ET-PROJ-004-implementacion-equipo-calendario
    historias_usuario:
      - US-PROJ-007-asignacion-equipo
      - US-PROJ-008-calendario-hitos
      - US-PROJ-009-alertas-fechas-criticas
    tablas:
      - project_management.project_team_assignments
      - project_management.project_milestones
      - project_management.construction_phases
      - project_management.critical_dates
      - project_management.milestone_dependencies
    endpoints:
      - POST /api/v1/projects/:id/team-assignments
      - GET /api/v1/projects/:id/team-assignments
      - PATCH /api/v1/team-assignments/:id
      - DELETE /api/v1/team-assignments/:id
      - GET /api/v1/users/:userId/workload
      - POST /api/v1/projects/:id/milestones
      - GET /api/v1/projects/:id/milestones
      - PATCH /api/v1/milestones/:id/complete
      - POST /api/v1/projects/:id/phases
      - GET /api/v1/projects/:id/phases
      - POST /api/v1/projects/:id/critical-dates
      - GET /api/v1/projects/:id/critical-dates
      - GET /api/v1/projects/:id/calendar
    componentes_ui:
      - TeamAssignmentList
      - TeamAssignmentForm
      - WorkloadChart
      - MilestoneList
      - MilestoneForm
      - MilestoneTimeline
      - PhaseList
      - PhaseGantt
      - CriticalDatesList
      - ProjectCalendar
      - AlertsPanel
    estado: pendiente
    prioridad: P1
    dependencias:
      - RF-AUTH-002 (Usuarios y roles)
      - RF-HR-001 (Empleados - para cuadrillas)
    validaciones:
      - Director único por proyecto
      - Residente obligatorio en ejecución
      - Límite de carga de trabajo por rol
      - Fechas lógicas (inicio < fin)
      - Dependencias de hitos válidas

cobertura:
  rf_total: 4
  rf_con_et: 4
  rf_con_us: 9
  rf_implementados: 0
  porcentaje: 0%

metricas_desarrollo:
  tablas_total: 17
  endpoints_total: 52
  componentes_ui_total: 43
  validaciones_total: 20
  dependencias_externas: 4

integracion:
  modulos_core:
    - MAI-001 (Autenticación y Multi-tenancy)
  modulos_verticales:
    - MAI-003 (Presupuesto - vinculación por etapa)
    - MAI-004 (Compras e Inventarios - almacén por proyecto)
    - MAI-005 (Control de Obra - avances por vivienda)
    - MAI-007 (RRHH - cuadrillas asignadas)

stack_tecnologico:
  backend:
    - NestJS + TypeORM
    - PostgreSQL 15+
    - Event-driven architecture
  frontend:
    - React + TypeScript
    - React Query (TanStack)
    - Zod validation
    - Shadcn/UI components
  storage:
    - S3-compatible para documentos
    - PostGIS para coordenadas (opcional)

estados_entidades:
  proyecto:
    - licitacion
    - adjudicado
    - ejecucion
    - entregado
    - cerrado
  etapa:
    - planeada
    - en_proceso
    - terminada
    - entregada
  lote:
    - disponible
    - vendido
    - en_construccion
    - terminado
    - entregado
  vivienda:
    - disponible
    - en_proceso
    - terminada
    - entregada
  hito:
    - pending
    - in_progress
    - completed
    - delayed

notas_implementacion:
  - Implementar Row-Level Security (RLS) por constructoraId en todas las tablas
  - Código de proyecto autogenerado: PROJ-{YEAR}-{SEQUENCE}
  - Validar transiciones de estado con máquina de estados
  - Calcular métricas de forma asíncrona (avances, costos)
  - Emitir eventos para notificaciones (project.created, status_changed, etc.)
  - Soportar versionado de prototipos sin afectar construcciones existentes
  - Validar límites de carga de trabajo al asignar personal
  - Implementar alertas automáticas para fechas críticas (cron job)
  - Permitir estructura flexible (con/sin manzanas para edificios verticales)
  - Mantener historial de asignaciones de equipo con fechas de inicio/fin

estimaciones:
  esfuerzo_total: 8 semanas
  desarrolladores: 2 full-stack
  desglose:
    - RF-PROJ-001: 2 semanas
    - RF-PROJ-002: 3 semanas
    - RF-PROJ-003: 1.5 semanas
    - RF-PROJ-004: 1.5 semanas