rckrdmrd/erp-construccion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a9703b2727
erp-construccion/docs/02-definicion-modulos/MAI-002-proyectos-estructura/_MAP.md

548 lines
21 KiB
Markdown
Raw Blame History

# _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)
Reference in New Issue View Git Blame Copy Permalink