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

482 lines
21 KiB
Markdown
Raw Permalink Blame History

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