# 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](./requerimientos-funcionales/RF-PROJ-001-catalogo-proyectos.md) | P0 | Completo |
| RF-PROJ-002 | Estructura Jerarquica de Obra | [RF-PROJ-002-estructura-jerarquica-obra.md](./requerimientos-funcionales/RF-PROJ-002-estructura-jerarquica-obra.md) | P0 | Completo |
| RF-PROJ-003 | Prototipos de Vivienda | [RF-PROJ-003-prototipos-vivienda.md](./requerimientos-funcionales/RF-PROJ-003-prototipos-vivienda.md) | P0 | Completo |
| RF-PROJ-004 | Asignacion de Equipo y Calendario | [RF-PROJ-004-asignacion-equipo-calendario.md](./requerimientos-funcionales/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](./especificaciones/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](./especificaciones/ET-PROJ-002-implementacion-estructura-jerarquica.md) | RF-PROJ-002 | Completo |
| ET-PROJ-003 | Implementacion de Prototipos | [ET-PROJ-003-implementacion-prototipos.md](./especificaciones/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](./especificaciones/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](./historias-usuario/US-PROJ-001-catalogo-proyectos.md) | 8 | Completo |
| US-PROJ-002 | Transiciones de Estado | [US-PROJ-002-transiciones-estado.md](./historias-usuario/US-PROJ-002-transiciones-estado.md) | 5 | Completo |
| US-PROJ-003 | Crear Estructura de Fraccionamiento | [US-PROJ-003-estructura-fraccionamiento.md](./historias-usuario/US-PROJ-003-estructura-fraccionamiento.md) | 8 | Completo |
| US-PROJ-004 | Crear Estructura de Torre Vertical | [US-PROJ-004-estructura-torre-vertical.md](./historias-usuario/US-PROJ-004-estructura-torre-vertical.md) | 6 | Completo |
| US-PROJ-005 | Gestion de Prototipos | [US-PROJ-005-gestion-prototipos.md](./historias-usuario/US-PROJ-005-gestion-prototipos.md) | 5 | Completo |
| US-PROJ-006 | Asignacion de Prototipos a Lotes | [US-PROJ-006-asignacion-prototipos-lotes.md](./historias-usuario/US-PROJ-006-asignacion-prototipos-lotes.md) | 3 | Completo |
| US-PROJ-007 | Asignacion de Equipo | [US-PROJ-007-asignacion-equipo.md](./historias-usuario/US-PROJ-007-asignacion-equipo.md) | 4 | Completo |
| US-PROJ-008 | Calendario de Hitos | [US-PROJ-008-calendario-hitos.md](./historias-usuario/US-PROJ-008-calendario-hitos.md) | 3 | Completo |
| US-PROJ-009 | Alertas de Fechas Criticas | [US-PROJ-009-alertas-fechas-criticas.md](./historias-usuario/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

```yaml
# 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

```sql
-- 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:

```sql
-- 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):

```sql
-- 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-EPICA-MAI-002.md) - Resumen completo de la epica con estado de completitud

### Implementacion
- [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](/home/isem/workspace/projects/erp-suite/apps/verticales/construccion/docs/GUIA-USO-REFERENCIAS-ODOO.md)
- [Mapeo MAI to MGN](/home/isem/workspace/projects/erp-suite/apps/verticales/construccion/docs/01-analisis-referencias/MAPEO-MAI-TO-MGN.md)
- [Analisis de Reutilizacion GAMILIT](../ANALISIS-REUTILIZACION-GAMILIT.md)

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