# _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](./requerimientos-funcionales/RF-PROJ-001-catalogo-proyectos.md) | Catalogo de Proyectos | US-001, US-002 | Documentado |
| RF-PROJ-002 | [RF-PROJ-002-estructura-jerarquica-obra.md](./requerimientos-funcionales/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](./requerimientos-funcionales/RF-PROJ-003-prototipos-vivienda.md) | Prototipos de Vivienda | US-005, US-006 | Documentado |
| RF-PROJ-004 | [RF-PROJ-004-asignacion-equipo-calendario.md](./requerimientos-funcionales/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](./especificaciones/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](./especificaciones/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](./especificaciones/ET-PROJ-003-implementacion-prototipos.md) | Implementacion Prototipos | RF-PROJ-003 | 4 | 9 | Documentado |
| ET-PROJ-004 | [ET-PROJ-004-implementacion-equipo-calendario.md](./especificaciones/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](./historias-usuario/US-PROJ-001-catalogo-proyectos.md) | Catalogo de Proyectos | 8 | P0 | Documentado |
| US-PROJ-002 | [US-PROJ-002-transiciones-estado.md](./historias-usuario/US-PROJ-002-transiciones-estado.md) | Transiciones de Estado | 5 | P0 | Documentado |
| US-PROJ-003 | [US-PROJ-003-estructura-fraccionamiento.md](./historias-usuario/US-PROJ-003-estructura-fraccionamiento.md) | Estructura de Fraccionamiento | 8 | P0 | Documentado |
| US-PROJ-004 | [US-PROJ-004-estructura-torre-vertical.md](./historias-usuario/US-PROJ-004-estructura-torre-vertical.md) | Estructura de Torre Vertical | 6 | P1 | Documentado |
| US-PROJ-005 | [US-PROJ-005-gestion-prototipos.md](./historias-usuario/US-PROJ-005-gestion-prototipos.md) | Gestion de Prototipos | 5 | P1 | Documentado |
| US-PROJ-006 | [US-PROJ-006-asignacion-prototipos-lotes.md](./historias-usuario/US-PROJ-006-asignacion-prototipos-lotes.md) | Asignacion de Prototipos a Lotes | 3 | P1 | Documentado |
| US-PROJ-007 | [US-PROJ-007-asignacion-equipo.md](./historias-usuario/US-PROJ-007-asignacion-equipo.md) | Asignacion de Equipo | 4 | P1 | Documentado |
| US-PROJ-008 | [US-PROJ-008-calendario-hitos.md](./historias-usuario/US-PROJ-008-calendario-hitos.md) | Calendario de Hitos | 3 | P1 | Documentado |
| US-PROJ-009 | [US-PROJ-009-alertas-fechas-criticas.md](./historias-usuario/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](./implementacion/TRACEABILITY.yml) - Matriz completa de trazabilidad
- [ET-PROJ-001-rls-policies.sql](./implementacion/ET-PROJ-001-rls-policies.sql) - RLS para proyectos
- [ET-PROJ-002-rls-policies.sql](./implementacion/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-EPICA-MAI-002.md) - Resumen ejecutivo completo (830+ lineas)
- [TRACEABILITY.yml](./implementacion/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](./implementacion/ET-PROJ-001-rls-policies.sql) - Row Level Security para proyectos
- [ET-PROJ-002-rls-policies.sql](./implementacion/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
```typescript
// Navegacion de arbol recursivo
interface TreeNode {
  id: string;
  type: 'project' | 'stage' | 'block' | 'lot' | 'housing';
  children?: TreeNode[];
}
```

### 2. Event-Driven Notifications
```typescript
// Event emitters para notificaciones
this.eventEmitter.emit('project.status_changed', {
  projectId,
  oldStatus,
  newStatus,
  changedBy
});
```

### 3. Codigo Auto-generado
```typescript
// 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
```typescript
// Maquina de estados para transiciones
const validTransitions = {
  licitacion: ['adjudicado'],
  adjudicado: ['ejecucion'],
  ejecucion: ['entregado'],
  entregado: ['cerrado']
};
```

### 5. Row Level Security (RLS)
```sql
-- 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](./RESUMEN-EPICA-MAI-002.md)
- **Trazabilidad:** [TRACEABILITY.yml](./implementacion/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)