erp-construccion/docs/02-definicion-modulos/MAI-002-proyectos-estructura

MAI-002: Proyectos y Estructura de Obra

Vertical: Construccion Modulo: MAI-002 Nombre: Proyectos y Estructura Fase: Fase 2 - Core Business Prioridad: P0 (Critica) Estado: Completo Story Points: 45 SP Ultima actualizacion: 2025-11-17

---

Descripcion

El modulo MAI-002 - Proyectos y Estructura es el nucleo central del sistema de construccion, permitiendo la gestion completa de proyectos inmobiliarios con una jerarquia flexible que se adapta a diferentes tipos de desarrollos:

• Fraccionamiento Horizontal: Proyecto → Etapa → Manzana → Lote → Vivienda
• Conjunto Habitacional: Proyecto → Etapa → Lote → Vivienda (sin manzanas)
• Edificio Vertical: Proyecto → Torre → Nivel → Departamento
• Proyecto Mixto: Combinacion de estructuras anteriores

Este modulo gestiona desde el catalogo de proyectos hasta la estructura jerarquica detallada de cada desarrollo, incluyendo prototipos de vivienda, asignacion de equipos de trabajo y calendario de hitos del proyecto.

Caracteristicas Clave

• Gestion de multiples proyectos simultaneos por constructora
• Jerarquia de 5 niveles: Proyecto → Etapa → Manzana → Lote → Vivienda
• Catalogo de prototipos de vivienda con versionado
• Asignacion de equipo con validacion de workload
• Calendario de hitos con dependencias y alertas automaticas
• Soporte para creacion masiva de lotes (hasta 500 por operacion)
• Estados del ciclo de vida: Licitacion → Adjudicado → Ejecucion → Entregado → Cerrado

---

Alcance Funcional

El modulo MAI-002 cubre las siguientes areas funcionales:

1. Catalogo de Proyectos (RF-PROJ-001)

• CRUD completo de proyectos inmobiliarios
• 4 tipos de proyectos: Fraccionamiento horizontal, Conjunto habitacional, Edificio vertical, Mixto
• 5 estados del ciclo de vida: Licitacion → Adjudicado → Ejecucion → Entregado → Cerrado
• Datos completos: Ubicacion geografica, cliente, contrato, permisos legales
• Metricas automaticas: Fisicas (viviendas, m2), financieras (presupuesto, avance), temporales (fechas clave)
• Codigo auto-generado: PROJ-2025-001, PROJ-2025-002, etc.

2. Estructura Jerarquica de Obra (RF-PROJ-002)

• Jerarquia de 5 niveles: Proyecto → Etapa → Manzana → Lote → Vivienda
• Estructuras flexibles:
  • Fraccionamiento: Con manzanas y lotes
  • Conjunto: Sin manzanas (solo lotes directos)
  • Torre vertical: Niveles y departamentos
• Estados de lote: Disponible → Vendido → En construccion → Terminado → Entregado
• Avance fisico por vivienda: Cimentacion, Estructura, Muros, Instalaciones, Acabados
• Creacion masiva: Hasta 500 lotes en una operacion (< 3 segundos)
• Vista de arbol jerarquico: Navegacion recursiva con expandir/colapsar

3. Prototipos de Vivienda (RF-PROJ-003)

• Catalogo de prototipos por constructora
• 3 tipos principales: Casa unifamiliar, Departamento, Duplex/Triplex
• Segmentos: Interes social, Interes medio, Residencial medio/alto, Premium
• Datos completos: Areas (construccion, terreno, vendible), distribucion (recamaras, banos), acabados, costos
• Versionado automatico: v1, v2, v3... con historial de cambios
• Asignacion a lotes: Individual o masiva (hasta 500 lotes)
• Herencia de caracteristicas: Snapshot de prototipo al momento de asignacion
• Control de uso: Impedir eliminacion si el prototipo esta asignado a viviendas

4. Asignacion de Equipo y Calendario (RF-PROJ-004)

• 5 roles de equipo: Director, Residente, Ingeniero, Supervisor, Gerente de Compras
• Validacion de workload: Limites por rol (Director 500%, Residente 200%, Ingeniero 800%)
• Reglas de asignacion: Solo un Director/Residente principal por proyecto
• Hitos del proyecto: 11 tipos desde arranque hasta cierre administrativo
• Fases constructivas: 9 fases (preliminares, cimentacion, estructura, albanileria, instalaciones, acabados, exteriores, urbanizacion, entrega)
• Fechas criticas: Contractuales, regulatorias, financieras con alertas automaticas
• Alertas configurables: 30, 15, 7, 3, 2, 1 dia(s) antes
• Dashboard de equipo: Visualizacion de carga de trabajo por rol

---

Reutilizacion del Core ERP

El modulo MAI-002 reutiliza aproximadamente 40% de componentes del ERP generico (GAMILIT):

Componentes Reutilizados del Core

Componente Core	Reutilizacion	Adaptacion Requerida
Sistema de autenticacion (JWT)	95%	Roles de construccion
Multi-tenancy (por constructora)	90%	RLS policies por proyecto
Sistema de auditoria	85%	Eventos especificos de proyectos
Gestion de catalogos	70%	Jerarquia de 5 niveles
Sistema de notificaciones	80%	Alertas de fechas criticas
Dashboard base	60%	Metricas especificas de obra
Componentes UI	85%	TreeView, Forms, Cards
API RESTful	90%	Endpoints especificos

Componentes Nuevos (No Reutilizables)

Los siguientes componentes son especificos del dominio de construccion:

• Jerarquia de 5 niveles: Proyecto → Etapa → Manzana → Lote → Vivienda
• Prototipos de vivienda: Catalogo con versionado y herencia
• Estructuras flexibles: Soporte para horizontal, vertical y mixto
• Creacion masiva de lotes: Bulk operations hasta 500 elementos
• Workload por rol: Validacion de limites por tipo de ingeniero/residente
• Hitos con dependencias: Graph validation de milestones
• Avance fisico ponderado: Calculo automatico por etapas constructivas

---

Requerimientos Funcionales (RF)

El modulo MAI-002 incluye 4 requerimientos funcionales completos:

ID	Titulo	Archivo	Prioridad	Estado
RF-PROJ-001	Catalogo de Proyectos	RF-PROJ-001-catalogo-proyectos.md	P0	Completo
RF-PROJ-002	Estructura Jerarquica de Obra	RF-PROJ-002-estructura-jerarquica-obra.md	P0	Completo
RF-PROJ-003	Prototipos de Vivienda	RF-PROJ-003-prototipos-vivienda.md	P0	Completo
RF-PROJ-004	Asignacion de Equipo y Calendario	RF-PROJ-004-asignacion-equipo-calendario.md	P0	Completo

Total: 4 RFs (~104 KB de documentacion)

---

Especificaciones Tecnicas (ET)

ID	Titulo	Archivo	RF Base	Estado
ET-PROJ-001	Implementacion de Catalogo de Proyectos	ET-PROJ-001-implementacion-catalogo-proyectos.md	RF-PROJ-001	Completo
ET-PROJ-002	Implementacion de Estructura Jerarquica	ET-PROJ-002-implementacion-estructura-jerarquica.md	RF-PROJ-002	Completo
ET-PROJ-003	Implementacion de Prototipos	ET-PROJ-003-implementacion-prototipos.md	RF-PROJ-003	Completo
ET-PROJ-004	Implementacion de Equipo y Calendario	ET-PROJ-004-implementacion-equipo-calendario.md	RF-PROJ-004	Completo

Total: 4 ETs (~164 KB de documentacion)

---

Historias de Usuario (US)

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

Total: 9 USs | 45 Story Points (~92 KB de documentacion)

---

Dependencias con Otros Modulos

Modulos Prerequisitos (Bloqueantes)

Modulo	Relacion	Detalles
MAI-001: Fundamentos	BLOQUEANTE	Sistema de autenticacion, RBAC, multi-tenancy por constructora

Modulos Dependientes (Consumen MAI-002)

Modulo	Relacion	Uso de MAI-002
MAI-003: Presupuestos y Costos	DEPENDIENTE	Presupuestos maestros por proyecto, costos por prototipo
MAI-004: Compras e Inventarios	DEPENDIENTE	Requisiciones filtradas por proyecto
MAI-005: Control de Obra y Avances	DEPENDIENTE	Avances fisicos por vivienda, checklists por etapa
MAI-007: RRHH y Asistencias	DEPENDIENTE	Asistencias de cuadrillas asignadas al proyecto
MAI-008: Estimaciones y Facturacion	DEPENDIENTE	Estimaciones por avance de proyecto
MAI-009: Calidad y Postventa	DEPENDIENTE	Incidencias por lote/vivienda
MAI-010: CRM Derechohabientes	DEPENDIENTE	Clientes asignados a lotes

Integraciones Clave

# Ejemplo de flujo de datos
MAI-002 (Proyecto) → MAI-003 (Presupuesto Maestro)
MAI-002 (Prototipo) → MAI-003 (Presupuesto por Prototipo)
MAI-002 (Lote) → MAI-010 (Cliente/Derechohabiente)
MAI-002 (Vivienda) → MAI-005 (Avance Fisico)
MAI-002 (Equipo) → MAI-007 (Asistencias Cuadrillas)

---

Diagrama de Arquitectura

Vista Jerarquica de Datos

┌─────────────────────────────────────────────────────────────────┐
│                        CONSTRUCTORA                             │
│                    (Multi-tenant: RLS)                          │
└───────────────────────┬─────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│                       PROYECTO                                  │
│  Tipo: Fraccionamiento | Conjunto | Torre | Mixto              │
│  Estado: Licitacion → Adjudicado → Ejecucion → Entregado       │
│  Codigo: PROJ-2025-001                                          │
└───────────┬────────────────────┬───────────────┬────────────────┘
            │                    │               │
            ▼                    ▼               ▼
    ┌──────────────┐   ┌──────────────┐  ┌──────────────┐
    │   ETAPA 1    │   │   ETAPA 2    │  │  PROTOTIPO   │
    │ (Fase del    │   │ (Fase del    │  │  (Modelo de  │
    │  proyecto)   │   │  proyecto)   │  │  vivienda)   │
    └──────┬───────┘   └──────┬───────┘  └──────────────┘
           │                  │                   │
           ▼                  ▼                   │ (asignado a)
    ┌──────────────┐   ┌──────────────┐          │
    │   MANZANA A  │   │   MANZANA B  │          │
    │ (Solo en     │   │ (Solo en     │          │
    │ Fraccionam.) │   │ Fraccionam.) │          │
    └──────┬───────┘   └──────┬───────┘          │
           │                  │                   │
           ▼                  ▼                   │
    ┌──────────────┐   ┌──────────────┐          │
    │   LOTE 1     │   │   LOTE 2     │◄─────────┘
    │ (Terreno     │   │ (Terreno     │
    │  individual) │   │  individual) │
    └──────┬───────┘   └──────┬───────┘
           │                  │
           ▼                  ▼
    ┌──────────────┐   ┌──────────────┐
    │  VIVIENDA    │   │  VIVIENDA    │
    │ (Casa/Depto  │   │ (Casa/Depto  │
    │  construido) │   │  construido) │
    └──────────────┘   └──────────────┘

Vista de Modulos Backend

apps/backend/src/modules/projects/
├── entities/
│   ├── project.entity.ts         (Proyecto principal)
│   ├── stage.entity.ts           (Etapa del proyecto)
│   ├── block.entity.ts           (Manzana)
│   ├── lot.entity.ts             (Lote/Terreno)
│   ├── housing-unit.entity.ts    (Vivienda construida)
│   ├── housing-prototype.entity.ts (Prototipo)
│   ├── team-assignment.entity.ts (Equipo)
│   ├── milestone.entity.ts       (Hitos)
│   └── critical-date.entity.ts   (Fechas criticas)
├── dto/
│   ├── create-project.dto.ts
│   ├── update-project.dto.ts
│   ├── bulk-lot-creation.dto.ts
│   └── ...
├── services/
│   ├── projects.service.ts       (CRUD + metricas)
│   ├── stages.service.ts         (Jerarquia)
│   ├── lots.service.ts           (Creacion masiva)
│   ├── housing-units.service.ts  (Avances)
│   ├── prototypes.service.ts     (Versionado)
│   ├── team.service.ts           (Workload)
│   ├── milestones.service.ts     (Dependencias)
│   └── alerts.service.ts         (Cron jobs)
├── controllers/
│   ├── projects.controller.ts
│   ├── stages.controller.ts
│   ├── prototypes.controller.ts
│   └── ...
└── projects.module.ts

Vista de Base de Datos

-- Schema: projects
CREATE SCHEMA IF NOT EXISTS projects;

-- Tablas principales (11 tablas)
projects.projects              -- Proyectos
projects.stages                -- Etapas
projects.blocks                -- Manzanas
projects.lots                  -- Lotes
projects.housing_units         -- Viviendas
projects.housing_prototypes    -- Prototipos
projects.project_team_assignments -- Equipo
projects.project_milestones    -- Hitos
projects.critical_dates        -- Fechas criticas
projects.construction_phases   -- Fases constructivas
projects.project_documents     -- Documentos

-- ENUMs
CREATE TYPE project_type AS ENUM (
  'fraccionamiento_horizontal',
  'conjunto_habitacional',
  'edificio_vertical',
  'mixto'
);

CREATE TYPE project_status AS ENUM (
  'licitacion',
  'adjudicado',
  'ejecucion',
  'entregado',
  'cerrado'
);

-- Row Level Security (RLS)
ALTER TABLE projects.projects ENABLE ROW LEVEL SECURITY;

CREATE POLICY projects_tenant_isolation ON projects.projects
  FOR ALL
  USING (constructora_id = current_setting('app.current_constructora_id')::UUID);

---

Stack Tecnologico

Backend

• Framework: NestJS 10.x (Node.js + TypeScript)
• ORM: TypeORM 0.3.x
• Base de Datos: PostgreSQL 15.x
• Autenticacion: JWT (passport-jwt)
• Validacion: class-validator + class-transformer
• Documentacion API: Swagger/OpenAPI 3.0
• Testing: Jest + Supertest
• Cron Jobs: @nestjs/schedule (para alertas)

Frontend

• Framework: React 18.x + TypeScript
• State Management: Zustand 4.x
• Forms: React Hook Form + Zod
• UI Components: shadcn/ui + Tailwind CSS
• Data Fetching: TanStack Query (React Query)
• Routing: React Router v6
• Testing: Vitest + React Testing Library
• Visualizacion: Recharts (graficas), react-big-calendar

Base de Datos

• RDBMS: PostgreSQL 15.x
• Features:
  • Row Level Security (RLS) para multi-tenancy
  • Triggers para calculos automaticos
  • Funciones SQL para workload y metricas
  • Indices GIN para busqueda full-text
  • Particionamiento por constructora (futuro)

DevOps

• Containerizacion: Docker + Docker Compose
• CI/CD: GitHub Actions
• Migraciones: TypeORM migrations
• Monitoreo: Prometheus + Grafana
• Logs: Winston + ELK Stack

---

Metricas del Modulo

Metrica	Valor
Story Points	45 SP
Requerimientos Funcionales	4 RFs
Especificaciones Tecnicas	4 ETs
Historias de Usuario	9 USs
Tablas de Base de Datos	11 tablas
Entities TypeORM	8 entities
Services NestJS	8+ services
Controllers RESTful	6+ controllers
Componentes React	20+ componentes
Endpoints API	40+ endpoints
Documentacion Total	~360 KB
Reutilizacion Core ERP	40%
Tiempo Estimado Desarrollo	8 semanas (4 sprints)

---

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).

Provisioning Automatico

Durante el onboarding, el sistema ejecuta:

-- 1. Activar modulo MAI-002
INSERT INTO constructoras.constructora_modules (
  constructora_id, module_code, is_active, plan_included
) VALUES (
  $constructora_id, 'MAI-002', true, true
);

-- 2. Crear prototipos seed (3 prototipos predefinidos)
INSERT INTO projects.housing_prototypes (
  constructora_id, code, name, category, segment, ...
) VALUES
  ($constructora_id, 'CASA-SEED-001', 'Casa Tipo A', 'unifamiliar', 'interes_social', ...),
  ($constructora_id, 'CASA-SEED-002', 'Casa Tipo B', 'unifamiliar', 'interes_medio', ...),
  ($constructora_id, 'DEPTO-SEED-001', 'Departamento Tipo A', 'departamento', 'interes_social', ...);

-- 3. Configurar limites por plan
INSERT INTO constructoras.constructora_limits (
  constructora_id, limit_key, limit_value
) VALUES
  ($constructora_id, 'max_active_projects', 15);  -- Plan Profesional

Aislamiento de Datos (RLS)

Todas las tablas del modulo MAI-002 estan protegidas con Row-Level Security (RLS):

-- Configuracion de contexto por sesion
SET app.current_constructora_id = 'uuid-de-constructora';

-- Toda query SELECT filtra automaticamente por constructora
SELECT * FROM projects.projects;
-- Retorna solo proyectos de la constructora actual

Politicas RLS completas: Ver archivos implementacion/ET-PROJ-*-rls-policies.sql

---

Documentacion Adicional

Resumen Ejecutivo

• RESUMEN-EPICA-MAI-002.md - Resumen completo de la epica con estado de completitud

Implementacion

• implementacion/ - Codigo fuente, migraciones, tests
  • Scripts SQL de creacion de tablas
  • Politicas RLS por tabla
  • Funciones SQL para calculos
  • Triggers automaticos
  • Seeds de datos iniciales

Documentacion de Referencia

• Guia de Uso de Referencias Odoo
• Mapeo MAI to MGN
• Analisis de Reutilizacion GAMILIT

Roadmap

• Fase 1 (Semanas 1-2): Implementacion de RF-PROJ-001 y RF-PROJ-002 (Catalogo y Jerarquia)
• Fase 2 (Semanas 3-4): Implementacion de RF-PROJ-003 (Prototipos)
• Fase 3 (Semanas 5-6): Implementacion de RF-PROJ-004 (Equipo y Calendario)
• Fase 4 (Semanas 7-8): Testing, refinamiento y deployment

---

Contacto y Soporte

Equipo responsable:

• Tech Lead: @tech-lead
• Backend Team: @backend-team
• Frontend Team: @frontend-team
• Database Team: @database-team

Documentacion generada: 2025-11-17 Estado del modulo: Completo (documentacion 100%) Proximo paso: Iniciar implementacion (Sprint 3)

---

Licencia

Copyright (c) 2025 - ERP Suite Construccion Todos los derechos reservados.