workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-002-proyectos-estructura/_MAP.md

_MAP: MAI-002 - Proyectos y Estructura

Epica: MAI-002 Nombre: Proyectos y Estructura de Obra Fase: 2 - Core Business Story Points: 45 SP Estado: 100% Documentado | Pendiente de Implementacion Sprint: Sprint 3-6 (Semanas 3-10) Ultima actualizacion: 2025-12-06

---

Proposito

Sistema integral de gestion de proyectos de construccion inmobiliaria que permite:

• Gestion completa de proyectos (fraccionamientos, conjuntos habitacionales, edificios verticales)
• Estructura jerarquica flexible: Proyecto → Etapa → Manzana (opcional) → Lote → Vivienda
• Catalogo de prototipos de vivienda con versionado
• Asignacion de equipo con validacion de carga de trabajo
• Calendario de obra con hitos, fases y fechas criticas
• Sistema de alertas automaticas

Reutilizacion GAMILIT: 40% de componentes de infraestructura

---

Estructura de Archivos

MAI-002-proyectos-estructura/
├── README.md                     # (Pendiente) Descripcion del modulo
├── _MAP.md                       # Este archivo - Mapa de navegacion
├── RESUMEN-EPICA-MAI-002.md     # Resumen ejecutivo completo
│
├── requerimientos-funcionales/   # 4 Requerimientos Funcionales (100%)
│   ├── RF-PROJ-001-catalogo-proyectos.md
│   ├── RF-PROJ-002-estructura-jerarquica-obra.md
│   ├── RF-PROJ-003-prototipos-vivienda.md
│   └── RF-PROJ-004-asignacion-equipo-calendario.md
│
├── especificaciones/             # 4 Especificaciones Tecnicas (100%)
│   ├── ET-PROJ-001-implementacion-catalogo-proyectos.md
│   ├── ET-PROJ-002-implementacion-estructura-jerarquica.md
│   ├── ET-PROJ-003-implementacion-prototipos.md
│   └── ET-PROJ-004-implementacion-equipo-calendario.md
│
├── historias-usuario/            # 9 Historias de Usuario (100%)
│   ├── US-PROJ-001-catalogo-proyectos.md          # 8 SP - CRUD proyectos
│   ├── US-PROJ-002-transiciones-estado.md         # 5 SP - Workflow estados
│   ├── US-PROJ-003-estructura-fraccionamiento.md  # 8 SP - Wizard jerarquia
│   ├── US-PROJ-004-estructura-torre-vertical.md   # 6 SP - Torres/Edificios
│   ├── US-PROJ-005-gestion-prototipos.md          # 5 SP - Catalogo prototipos
│   ├── US-PROJ-006-asignacion-prototipos-lotes.md # 3 SP - Asignacion masiva
│   ├── US-PROJ-007-asignacion-equipo.md           # 4 SP - Team management
│   ├── US-PROJ-008-calendario-hitos.md            # 3 SP - Milestones
│   └── US-PROJ-009-alertas-fechas-criticas.md     # 3 SP - Sistema alertas
│
└── implementacion/               # Archivos de soporte tecnico
    ├── TRACEABILITY.yml          # Matriz de trazabilidad completa
    ├── ET-PROJ-001-rls-policies.sql  # RLS para proyectos
    └── ET-PROJ-002-rls-policies.sql  # RLS para estructura

---

Contenido

Requerimientos Funcionales (4)

ID	Archivo	Titulo	US Asociadas	Estado
RF-PROJ-001	RF-PROJ-001-catalogo-proyectos.md	Catalogo de Proyectos	US-001, US-002	Documentado
RF-PROJ-002	RF-PROJ-002-estructura-jerarquica-obra.md	Estructura Jerarquica de Obra	US-003, US-004	Documentado
RF-PROJ-003	RF-PROJ-003-prototipos-vivienda.md	Prototipos de Vivienda	US-005, US-006	Documentado
RF-PROJ-004	RF-PROJ-004-asignacion-equipo-calendario.md	Asignacion de Equipo y Calendario	US-007, US-008, US-009	Documentado

Especificaciones Tecnicas (4)

ID	Archivo	Titulo	RF	Tablas	Endpoints	Estado
ET-PROJ-001	ET-PROJ-001-implementacion-catalogo-proyectos.md	Implementacion Catalogo Proyectos	RF-PROJ-001	3	9	Documentado
ET-PROJ-002	ET-PROJ-002-implementacion-estructura-jerarquica.md	Implementacion Estructura Jerarquica	RF-PROJ-002	5	15	Documentado
ET-PROJ-003	ET-PROJ-003-implementacion-prototipos.md	Implementacion Prototipos	RF-PROJ-003	4	9	Documentado
ET-PROJ-004	ET-PROJ-004-implementacion-equipo-calendario.md	Implementacion Equipo y Calendario	RF-PROJ-004	5	11	Documentado

Historias de Usuario (9)

ID	Archivo	Titulo	SP	Prioridad	Estado
US-PROJ-001	US-PROJ-001-catalogo-proyectos.md	Catalogo de Proyectos	8	P0	Documentado
US-PROJ-002	US-PROJ-002-transiciones-estado.md	Transiciones de Estado	5	P0	Documentado
US-PROJ-003	US-PROJ-003-estructura-fraccionamiento.md	Estructura de Fraccionamiento	8	P0	Documentado
US-PROJ-004	US-PROJ-004-estructura-torre-vertical.md	Estructura de Torre Vertical	6	P1	Documentado
US-PROJ-005	US-PROJ-005-gestion-prototipos.md	Gestion de Prototipos	5	P1	Documentado
US-PROJ-006	US-PROJ-006-asignacion-prototipos-lotes.md	Asignacion de Prototipos a Lotes	3	P1	Documentado
US-PROJ-007	US-PROJ-007-asignacion-equipo.md	Asignacion de Equipo	4	P1	Documentado
US-PROJ-008	US-PROJ-008-calendario-hitos.md	Calendario de Hitos	3	P1	Documentado
US-PROJ-009	US-PROJ-009-alertas-fechas-criticas.md	Alertas de Fechas Criticas	3	P1	Documentado

Total Story Points: 45 SP

Implementacion

Inventarios de trazabilidad:

• TRACEABILITY.yml - Matriz completa de trazabilidad
• ET-PROJ-001-rls-policies.sql - RLS para proyectos
• ET-PROJ-002-rls-policies.sql - RLS para estructura jerarquica

---

Flujo de Documentacion

┌─────────────────────────────────────────────────────────────────────┐
│                    FLUJO MAI-002: PROYECTOS Y ESTRUCTURA            │
└─────────────────────────────────────────────────────────────────────┘

1. CATALOGO DE PROYECTOS
   RF-PROJ-001 (Requerimiento)
      ↓
   ET-PROJ-001 (Especificacion Tecnica)
      ↓
   ├─→ US-PROJ-001 (Catalogo CRUD) → Backend API + Frontend UI
   └─→ US-PROJ-002 (Transiciones Estado) → State Machine + Notificaciones

2. ESTRUCTURA JERARQUICA
   RF-PROJ-002 (Requerimiento)
      ↓
   ET-PROJ-002 (Especificacion Tecnica)
      ↓
   ├─→ US-PROJ-003 (Fraccionamiento) → Wizard + TreeView
   └─→ US-PROJ-004 (Torre Vertical) → Adaptacion para edificios

3. PROTOTIPOS DE VIVIENDA
   RF-PROJ-003 (Requerimiento)
      ↓
   ET-PROJ-003 (Especificacion Tecnica)
      ↓
   ├─→ US-PROJ-005 (Gestion Prototipos) → Catalogo + Versionado
   └─→ US-PROJ-006 (Asignacion a Lotes) → Asignacion masiva

4. EQUIPO Y CALENDARIO
   RF-PROJ-004 (Requerimiento)
      ↓
   ET-PROJ-004 (Especificacion Tecnica)
      ↓
   ├─→ US-PROJ-007 (Asignacion Equipo) → Workload validation
   ├─→ US-PROJ-008 (Calendario Hitos) → Timeline + Dependencies
   └─→ US-PROJ-009 (Alertas Criticas) → Cron jobs + Notificaciones

┌─────────────────────────────────────────────────────────────────────┐
│                           COMPONENTES TRANSVERSALES                  │
├─────────────────────────────────────────────────────────────────────┤
│ • RLS Policies (Multi-tenancy por constructora)                     │
│ • Event Emitters (Notificaciones de cambios)                        │
│ • Validaciones de negocio (Estado, jerarquia, workload)             │
│ • Triggers SQL (Contadores automaticos, calculos)                   │
│ • Cron Jobs (Alertas automaticas)                                   │
└─────────────────────────────────────────────────────────────────────┘

---

Relacion entre Componentes

1. Dependencias Jerarquicas

Project (Proyecto)
    ├── Stage (Etapa)
    │   └── Block (Manzana) [OPCIONAL - solo fraccionamientos]
    │       └── Lot (Lote)
    │           └── HousingUnit (Vivienda)
    │
    ├── HousingPrototype (Prototipos) [CATALOGO]
    │   ├── Versions (Versionado)
    │   └── Assigned to → Lots
    │
    ├── ProjectTeamAssignment (Equipo)
    │   ├── Director (unico)
    │   ├── Residents (multiples)
    │   └── Engineers/Supervisors (compartidos)
    │
    └── Calendar
        ├── Milestones (Hitos con dependencias)
        ├── ConstructionPhases (Fases)
        └── CriticalDates (Fechas criticas + Alertas)

2. Flujo de Estados

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

3. Integraciones con Otros Modulos

Modulo	Relacion	Campos Clave
MAI-001 (Fundamentos)	constructoraId, userId	Multi-tenancy, Auth
MAI-003 (Presupuestos)	Project.contractAmount	Presupuesto maestro por proyecto
MAI-004 (Compras)	Project.id	Requisiciones filtradas por proyecto
MAI-005 (Control de Obra)	HousingUnit.id	Avances fisicos por vivienda
MAI-007 (RRHH)	TeamAssignment	Asistencias de cuadrillas en proyecto

---

Quick Links

Documentos Principales

• RESUMEN-EPICA-MAI-002.md - Resumen ejecutivo completo (830+ lineas)
• TRACEABILITY.yml - Matriz de trazabilidad (307 lineas)

Por Tipo de Proyecto

Fraccionamiento Horizontal:

• RF-PROJ-002 (Estructura con manzanas)
• US-PROJ-003 (Wizard de fraccionamiento)

Edificio Vertical:

• RF-PROJ-002 (Estructura sin manzanas)
• US-PROJ-004 (Wizard de torre vertical)

Conjunto Habitacional Mixto:

• RF-PROJ-002 (Estructura flexible)
• US-PROJ-003 + US-PROJ-004 (Combinacion)

Por Funcionalidad

Gestion de Proyectos:

• RF-PROJ-001 → ET-PROJ-001 → US-PROJ-001, US-PROJ-002

Estructura de Obra:

• RF-PROJ-002 → ET-PROJ-002 → US-PROJ-003, US-PROJ-004

Prototipos:

• RF-PROJ-003 → ET-PROJ-003 → US-PROJ-005, US-PROJ-006

Equipo y Calendario:

• RF-PROJ-004 → ET-PROJ-004 → US-PROJ-007, US-PROJ-008, US-PROJ-009

Archivos SQL

• ET-PROJ-001-rls-policies.sql - Row Level Security para proyectos
• ET-PROJ-002-rls-policies.sql - Row Level Security para estructura

---

Modulos Afectados

Base de Datos

• Schema: project_management
• Tablas: 17 tablas principales
  • Proyectos: projects, project_documents, project_metrics
  • Estructura: stages, blocks, lots, housing_units, unit_progress
  • Prototipos: housing_prototypes, prototype_versions, prototype_documents, prototype_costs
  • Equipo: project_team_assignments
  • Calendario: project_milestones, construction_phases, critical_dates, milestone_dependencies
• ENUMs:
  • ProjectType (fraccionamiento_horizontal, conjunto_habitacional, edificio_vertical, mixto)
  • ProjectStatus (licitacion, adjudicado, ejecucion, entregado, cerrado)
  • PrototypeCategory (unifamiliar, departamento, duplex)
  • ProjectRole (director, resident, engineer, supervisor, purchases_manager)
  • MilestoneType (11 tipos: arranque, permisos, cimentacion, etc.)
• Funciones SQL:
  • get_user_total_workload() - Calculo de carga de trabajo
  • get_role_workload_limit() - Limites por rol
  • Triggers para contadores automaticos

Backend (NestJS)

• Modulo: project-management
• Path: apps/backend/src/modules/project-management/
• Entities: 11 entities principales
  • Project, Stage, Block, Lot, HousingUnit
  • HousingPrototype, PrototypeVersion
  • ProjectTeamAssignment, Milestone, CriticalDate, ConstructionPhase
• Services: 8+ services
  • ProjectsService, StagesService, LotsService, HousingUnitsService
  • PrototypesService, TeamAssignmentsService, MilestonesService, AlertsService
• Controllers: 6+ controllers RESTful
• Total Endpoints: 52 endpoints

Frontend (React + TypeScript)

• Features: projects
• Path: apps/frontend/src/features/projects/
• Pages:
  • ProjectsListPage, ProjectDetailPage, CreateProjectPage
  • StructurePage, PrototypesPage, CalendarPage
• Components: 43+ componentes
  • ProjectForm, ProjectCard, ProjectStatusBadge
  • StructureTreeView, BulkLotCreationForm, HousingUnitProgressCard
  • PrototypeGallery, PrototypeForm
  • TeamRoster, MilestoneTimeline, CriticalDatesCalendar
• Stores: projectStore, structureStore, prototypeStore
• Services: projects.api.ts

---

Metricas

Metrica	Valor
Story Points estimados	45 SP
Duracion estimada	8 semanas (4 sprints de 2 semanas)
Desarrolladores requeridos	2 full-stack
Reutilizacion GAMILIT	40%
RF completados	4/4 (100%)
ET completadas	4/4 (100%)
US completadas	9/9 (100%)
Documentacion generada	~230 KB
Tablas DB	17 tablas
Endpoints API	52 endpoints
Componentes UI	43 componentes
Validaciones de negocio	20+ reglas

---

Caracteristicas Clave

1. Jerarquia Flexible

• Soporta 3 estructuras: Fraccionamiento (con manzanas), Conjunto (sin manzanas), Torre vertical (niveles)
• Navegacion de arbol recursivo con expand/collapse
• Creacion masiva: hasta 500 lotes en <3 segundos
• Codigos unicos auto-generados

2. Prototipos con Versionado

• Catalogo centralizado de prototipos
• Versionado automatico (v1, v2, v3...)
• Depreciacion de versiones antiguas
• Asignacion masiva a lotes
• Snapshot de version al momento de asignacion
• Herencia de caracteristicas a viviendas

3. Gestion de Equipo Inteligente

• Validacion de limites de workload por rol:
  • Director: 500% (5 proyectos)
  • Residente: 200% (2 proyectos)
  • Ingeniero: 800% (8 proyectos)
• Solo un Director principal por proyecto
• Dashboard de disponibilidad de equipo
• Historial de asignaciones

4. Calendario Inteligente

• Hitos con dependencias (validacion de grafo)
• 11 tipos de hitos predefinidos
• Fases constructivas (9 fases)
• Fechas criticas con alertas automaticas
• Cron jobs para notificaciones diarias (9:00 AM)
• Sistema de notificaciones por email + in-app

5. Multi-tenancy Robusto

• Row Level Security (RLS) en todas las tablas
• Aislamiento total por constructoraId
• Imposible ver datos de otras constructoras
• Validaciones a nivel DB + Backend

---

Configuracion SaaS Multi-tenant

Activacion del Modulo

MAI-002 es un modulo core incluido en los 3 planes de suscripcion:

Plan	Modulo MAI-002	Limites
Basico	Incluido	5 proyectos activos simultaneos
Profesional	Incluido	15 proyectos activos simultaneos
Enterprise	Incluido	Proyectos ilimitados

Activacion automatica: Este modulo se activa durante el onboarding de un nuevo tenant (constructora).

Feature Flags Configurables

• projects.bulk_lot_creation - Creacion masiva de hasta 500 lotes
• projects.housing_prototypes - Catalogo de prototipos de vivienda
• projects.team_workload_validation - Validacion de limites de carga por rol
• projects.ai_schedule_optimization - Optimizacion de calendario con IA (Beta)

---

Stack Tecnologico

Backend

• Framework: NestJS + TypeORM
• Base de Datos: PostgreSQL 15+
• Arquitectura: Event-driven (Event Emitters)
• Seguridad: Row Level Security (RLS), JWT
• Jobs: Cron jobs para alertas automaticas

Frontend

• Framework: React + TypeScript
• Formularios: React Hook Form + Zod validation
• Estado: React Query (TanStack) + Zustand
• UI: Shadcn/UI components
• Routing: React Router v6

Storage

• Documentos: S3-compatible (planos, permisos, renders)
• Geoespacial: PostGIS (coordenadas de proyectos) - Opcional

---

Patrones de Implementacion

1. Jerarquia Recursiva

// Navegacion de arbol recursivo
interface TreeNode {
  id: string;
  type: 'project' | 'stage' | 'block' | 'lot' | 'housing';
  children?: TreeNode[];
}

2. Event-Driven Notifications

// Event emitters para notificaciones
this.eventEmitter.emit('project.status_changed', {
  projectId,
  oldStatus,
  newStatus,
  changedBy
});

3. Codigo Auto-generado

// Patron: PROJ-{YEAR}-{SEQUENCE}
generateProjectCode(): string {
  const year = new Date().getFullYear();
  const sequence = await this.getNextSequence(year);
  return `PROJ-${year}-${sequence.toString().padStart(3, '0')}`;
}

4. Validacion de Estado

// Maquina de estados para transiciones
const validTransitions = {
  licitacion: ['adjudicado'],
  adjudicado: ['ejecucion'],
  ejecucion: ['entregado'],
  entregado: ['cerrado']
};

5. Row Level Security (RLS)

-- Politica RLS para multi-tenancy
CREATE POLICY projects_select_policy ON project_management.projects
FOR SELECT
USING (constructora_id = current_setting('app.current_constructora_id')::UUID);

---

Plan de Implementacion

Sprint 3 (Semana 3-4) - 13 SP

• US-PROJ-001: Catalogo de Proyectos (8 SP)
• US-PROJ-002: Transiciones de Estado (5 SP)

Entregables:

• CRUD completo de proyectos
• Workflow de estados con validaciones
• RLS policies implementadas

Sprint 4 (Semana 5-6) - 14 SP

• US-PROJ-003: Estructura de Fraccionamiento (8 SP)
• US-PROJ-004: Estructura de Torre Vertical (6 SP)

Entregables:

• Wizard de creacion de estructura
• TreeView jerarquico
• Creacion masiva de lotes

Sprint 5 (Semana 7-8) - 8 SP

• US-PROJ-005: Gestion de Prototipos (5 SP)
• US-PROJ-006: Asignacion de Prototipos a Lotes (3 SP)

Entregables:

• Catalogo de prototipos con versionado
• Asignacion masiva a lotes
• Herencia de caracteristicas

Sprint 6 (Semana 9-10) - 10 SP

• US-PROJ-007: Asignacion de Equipo (4 SP)
• US-PROJ-008: Calendario de Hitos (3 SP)
• US-PROJ-009: Alertas de Fechas Criticas (3 SP)

Entregables:

• Gestion de equipo con workload
• Timeline de hitos
• Sistema de alertas automaticas

---

Siguientes Pasos

Opcion 1: Iniciar Implementacion de MAI-002 (RECOMENDADO)

Razon: Documentacion 100% completa, equipo puede empezar desarrollo inmediato

Estimacion: 4 sprints de 2 semanas = 8 semanas

Opcion 2: Continuar con Siguiente Epica

Opciones:

• MAI-003: Presupuestos y Control de Costos (50 SP)
• MAI-004: Compras e Inventarios (50 SP)
• MAI-005: Control de Obra y Avances (45 SP)

Beneficio: Cobertura completa del sistema antes de implementar

Opcion 3: Enfoque Paralelo

• Equipo A: Implementa MAI-002
• Equipo B: Documenta MAI-003 o MAI-005

Beneficio: Velocidad maxima, trabajo paralelo

---

Referencias

• Resumen Ejecutivo: RESUMEN-EPICA-MAI-002.md
• Trazabilidad: TRACEABILITY.yml
• Proyecto GAMILIT: Reutilizacion de componentes base de infraestructura

---

Generado: 2025-12-06 Mantenedores: @tech-lead @backend-team @frontend-team @database-team Estado: Documentado (Pendiente de Implementacion)