833 lines
31 KiB
Markdown
833 lines
31 KiB
Markdown
# Resumen Ejecutivo: MAI-002 - Proyectos y Estructura de Obra
|
|
|
|
**Fecha de generación:** 2025-11-17
|
|
**Estado:** ✅ COMPLETO (100%)
|
|
**Story Points:** 45 SP
|
|
**Prioridad:** P0 (Crítica)
|
|
|
|
---
|
|
|
|
## 📊 Estado de Completitud
|
|
|
|
| Tipo de Documento | Completados | Total | % |
|
|
|-------------------|-------------|-------|---|
|
|
| Requerimientos Funcionales (RF) | 4 | 4 | 100% ✅ |
|
|
| Especificaciones Técnicas (ET) | 4 | 4 | 100% ✅ |
|
|
| Historias de Usuario (US) | 9 | 9 | 100% ✅ |
|
|
| **Total Documentos** | **17** | **17** | **100%** ✅ |
|
|
|
|
**Tamaño total generado:** ~230 KB
|
|
|
|
---
|
|
|
|
## ✅ Documentos Completados
|
|
|
|
### Requerimientos Funcionales (4/4 - 100%)
|
|
|
|
#### 1. RF-PROJ-001: Catálogo de Proyectos (~25 KB)
|
|
**Contenido clave:**
|
|
- 4 tipos de proyectos: Fraccionamiento Horizontal, Conjunto Habitacional, Edificio Vertical, Mixto
|
|
- 5 estados: Licitación → Adjudicado → Ejecución → Entregado → Cerrado
|
|
- Datos completos: ubicación, cliente, contrato, fechas, permisos
|
|
- Métricas: físicas, financieras, temporales, recursos
|
|
- 4 casos de uso detallados
|
|
- Validaciones de negocio y técnicas
|
|
- Permisos por rol
|
|
|
|
#### 2. RF-PROJ-002: Estructura Jerárquica de Obra (~28 KB)
|
|
**Contenido clave:**
|
|
- Jerarquía de 5 niveles: Proyecto → Etapa → Manzana → Lote → Vivienda
|
|
- Estructuras por tipo: Fraccionamiento (con manzanas), Conjunto (sin manzanas), Torre vertical (niveles)
|
|
- Estados de lote: Disponible → Vendido → En construcción → Terminado → Entregado
|
|
- Avance físico por vivienda (cimentación, estructura, muros, instalaciones, acabados)
|
|
- 3 casos de uso: Crear estructura, Crear torre, Cambiar estado
|
|
- Reportes: Árbol jerárquico, Resumen por etapa, Listado por estado
|
|
|
|
#### 3. RF-PROJ-003: Prototipos de Vivienda (~26 KB)
|
|
**Contenido clave:**
|
|
- 3 tipos principales: Casa Unifamiliar, Departamento, Dúplex/Tríplex
|
|
- Segmentos: Interés social, Interés medio, Residencial medio/alto, Premium
|
|
- Datos: Áreas, distribución, características constructivas, acabados, costos
|
|
- Versionado de prototipos (v1, v2, etc.)
|
|
- Asignación a lotes en masa
|
|
- Herencia de características a viviendas
|
|
- Catálogo por constructora
|
|
|
|
#### 4. RF-PROJ-004: Asignación de Equipo y Calendario (~25 KB)
|
|
**Contenido clave:**
|
|
- 5 roles de equipo: Director, Residente, Ingeniero, Supervisor, Gerente de Compras
|
|
- Reglas de asignación: Director único, Residente principal, Límites de carga
|
|
- Hitos del proyecto (milestones): 11 tipos desde arranque hasta cierre
|
|
- Fases constructivas: 9 fases (preliminares, cimentación, estructura, etc.)
|
|
- Fechas críticas con alertas automáticas
|
|
- Workload management (% de dedicación)
|
|
- Dashboard de equipo y calendario
|
|
|
|
### Especificaciones Técnicas (4/4 - 100%)
|
|
|
|
#### 1. ET-PROJ-001: Implementación de Catálogo de Proyectos (~20 KB)
|
|
**Contenido técnico:**
|
|
- **Entity:** `Project` con 45+ columnas (TypeORM)
|
|
- **ENUMs:** ProjectType, ProjectStatus, ClientType, ContractType
|
|
- **Service:** `ProjectsService` con 8 métodos:
|
|
- create, findAll (con filtros), findOne, update, changeStatus
|
|
- calculateMetrics, generateProjectCode, validateStatusTransition
|
|
- **Controller:** RESTful con 6 endpoints
|
|
- **Frontend:**
|
|
- `ProjectForm` component (React Hook Form + Zod)
|
|
- `ProjectCard` component con badges de estado
|
|
- Validaciones completas
|
|
- **Tests:** Generación de códigos, transiciones de estado
|
|
- **Features:**
|
|
- Código auto-generado: PROJ-2025-001
|
|
- Cálculo automático de scheduledEndDate
|
|
- Event emitters para status changes
|
|
- Métricas calculadas (físico, financiero, temporal)
|
|
|
|
#### 2. ET-PROJ-002: Implementación de Estructura Jerárquica (~48 KB)
|
|
**Contenido técnico:**
|
|
- **Entities:** Stage, Block, Lot, HousingUnit (4 entidades completas)
|
|
- **ENUMs:** StageStatus, BlockStatus, LotStatus, ConstructionStatus, LotShape, LotOrientation
|
|
- **Services:**
|
|
- `StagesService`: create, findAll, getTreeStructure (recursivo), changeStatus
|
|
- `LotsService`: create, bulkCreate (hasta 500 lotes), assignPrototype, bulkAssignPrototype
|
|
- `HousingUnitsService`: create con herencia de prototipos, updateProgress con cálculo ponderado
|
|
- **Controllers:** 3 controllers RESTful con 20+ endpoints
|
|
- **Frontend:**
|
|
- `StructureTreeView` component con navegación jerárquica
|
|
- `BulkLotCreationForm` para creación masiva
|
|
- `HousingUnitProgressCard` con sliders por etapa constructiva
|
|
- **Database:**
|
|
- Triggers automáticos para contadores (totalLots, totalBlocks, totalHousingUnits)
|
|
- Funciones SQL para cálculo de avances
|
|
- **Features:**
|
|
- Soporte de 3 estructuras: Fraccionamiento (con manzanas), Conjunto (sin manzanas), Torre vertical
|
|
- Árbol jerárquico recursivo con relaciones OneToMany
|
|
- Creación masiva de lotes con código secuencial
|
|
- Asignación de prototipos individual y en masa
|
|
- Cálculo automático de avance físico ponderado
|
|
|
|
#### 3. ET-PROJ-003: Implementación de Prototipos (~45 KB)
|
|
**Contenido técnico:**
|
|
- **Entity:** `HousingPrototype` con 50+ columnas
|
|
- **ENUMs:** PrototypeCategory, PrototypeSegment, PrototypeStatus, KitchenType
|
|
- **Service:** `HousingPrototypesService` con 10 métodos:
|
|
- create, createVersion (versionado), findAll, getCatalog, getVersionHistory
|
|
- deprecate, incrementUsageCount, cloneForHousingUnit
|
|
- **Controller:** RESTful con 8 endpoints
|
|
- **Frontend:**
|
|
- `PrototypeGallery` component con filtros por categoría y segmento
|
|
- `PrototypeForm` component con 60+ campos
|
|
- Visualización de costos y características
|
|
- **Database:**
|
|
- Triggers automáticos para cálculo de totalBuiltArea y totalTurnkeyCost
|
|
- Índices GIN para búsqueda por tags
|
|
- **Features:**
|
|
- Versionado automático (v1, v2, v3...)
|
|
- Depreciación de versiones anteriores
|
|
- Catálogo agrupado por categoría o segmento
|
|
- Código auto-generado: CASA-2025-001, DEPTO-2025-001
|
|
- Herencia de características a viviendas (snapshot)
|
|
- Control de usageCount para prevenir eliminaciones
|
|
|
|
#### 4. ET-PROJ-004: Implementación de Equipo y Calendario (~51 KB)
|
|
**Contenido técnico:**
|
|
- **Entities:** ProjectTeamAssignment, Milestone, CriticalDate, ConstructionPhase
|
|
- **ENUMs:** ProjectRole, Specialty, MilestoneType, MilestoneStatus, CommitmentType, CriticalDateStatus
|
|
- **Services:**
|
|
- `TeamAssignmentsService`: create con validación de workload, getUserTotalWorkload, getTeamDashboard
|
|
- `MilestonesService`: create, markComplete con validación de dependencias, getTimeline
|
|
- `CriticalDatesService`: create, updateStatus, sendAlerts
|
|
- `AlertsService`: Cron jobs para alertas automáticas (diario a las 9:00 AM)
|
|
- **Controllers:** 3 controllers RESTful con 18+ endpoints
|
|
- **Frontend:**
|
|
- `TeamRoster` component con visualización de workload por rol
|
|
- `MilestoneTimeline` component con línea de tiempo visual
|
|
- `CriticalDatesCalendar` component con alertas
|
|
- **Database:**
|
|
- Funciones SQL: get_user_total_workload(), get_role_workload_limit()
|
|
- Límites por rol: Director 500%, Residente 200%, Ingeniero 800%
|
|
- **Features:**
|
|
- Validación de límites de workload por rol
|
|
- Solo un Director principal por proyecto
|
|
- Milestones con dependencias (graph validation)
|
|
- Alertas automáticas con cron jobs
|
|
- Sistema de notificaciones por correo/webhook
|
|
- Dashboard de disponibilidad de equipo
|
|
|
|
---
|
|
|
|
## 📋 Documentos Pendientes
|
|
|
|
### Especificaciones Técnicas (0 pendientes - 100% ✅)
|
|
|
|
Todas las especificaciones técnicas han sido completadas.
|
|
|
|
### Historias de Usuario (9/9 - 100%)
|
|
|
|
#### 1. US-PROJ-001: Catálogo de Proyectos (8 SP) - ~17 KB
|
|
**Contenido clave:**
|
|
- CRUD completo de proyectos con formulario de 6 secciones
|
|
- Filtros por tipo, estado, cliente, año + búsqueda de texto libre
|
|
- Vista de detalle con 5 tabs: General, Métricas, Estructura, Equipo, Calendario
|
|
- Permisos por rol (Director/Admin: crear/editar, todos: ver)
|
|
- Eliminación con confirmación "ELIMINAR"
|
|
- Código auto-generado secuencial por año (PROJ-2025-001)
|
|
- 8 criterios de aceptación detallados
|
|
- 5 escenarios de prueba
|
|
|
|
#### 2. US-PROJ-002: Transiciones de Estado (5 SP) - ~15 KB
|
|
**Contenido clave:**
|
|
- Flujo validado: Licitación → Adjudicado → Ejecución → Entregado → Cerrado
|
|
- Checklist de condiciones por transición
|
|
- Actualización automática de fechas (awardDate, actualStartDate, deliveryDate, closureDate)
|
|
- Timeline de historial con auditoría completa
|
|
- Notificaciones a equipo y cliente
|
|
- Solo Director/Admin pueden cambiar estados
|
|
- Regresión solo para Admin con justificación
|
|
- 5 escenarios de prueba
|
|
|
|
#### 3. US-PROJ-003: Crear Estructura de Fraccionamiento (8 SP) - ~11 KB
|
|
**Contenido clave:**
|
|
- Wizard de 4 pasos: Etapas → Manzanas → Lotes → Resumen
|
|
- Creación masiva de lotes (hasta 500 por operación)
|
|
- Vista de árbol jerárquico con expandir/colapsar
|
|
- Códigos únicos validados (Etapa, Manzana, Lote)
|
|
- Calculadora de áreas y lotes
|
|
- Edición y eliminación con validación de dependencias
|
|
- Transacción atómica (todo o nada)
|
|
- Performance: 500 lotes en <3 segundos
|
|
|
|
#### 4. US-PROJ-004: Crear Estructura de Torre Vertical (6 SP) - ~7 KB
|
|
**Contenido clave:**
|
|
- Wizard adaptado para edificios verticales
|
|
- Terminología: Torre → Niveles → Departamentos
|
|
- Códigos departamento: DEPTO-101, DEPTO-201 (piso-número)
|
|
- Plantilla de niveles repetitivos (N niveles iguales)
|
|
- Orientación de departamentos (Norte/Sur/Este/Oeste)
|
|
- TreeView adaptado para torres
|
|
- Creación masiva por nivel
|
|
|
|
#### 5. US-PROJ-005: Gestión de Prototipos (5 SP) - ~9 KB
|
|
**Contenido clave:**
|
|
- Catálogo con galería visual (filtros por categoría, segmento, precio)
|
|
- Formulario de 6 secciones: Básica, Características, Áreas, Distribución, Acabados, Costos
|
|
- Versionado automático (v1, v2, v3...)
|
|
- Depreciación de versiones anteriores
|
|
- Auto-código: CASA-2025-001, DEPTO-2025-001
|
|
- Control de usageCount (no eliminar si >0)
|
|
- Historial de versiones con cambios documentados
|
|
|
|
#### 6. US-PROJ-006: Asignación de Prototipos a Lotes (3 SP) - ~8 KB
|
|
**Contenido clave:**
|
|
- Asignación individual desde modal con catálogo
|
|
- Asignación en masa (hasta 500 lotes)
|
|
- Validación de área requerida vs disponible
|
|
- No permitir si lote tiene vivienda construida
|
|
- Incremento/decremento de usageCount
|
|
- Reasignación con confirmación
|
|
- Filtros en TreeView: "Sin prototipo", "Con prototipo X"
|
|
- Snapshot de versión al momento de asignación
|
|
|
|
#### 7. US-PROJ-007: Asignación de Equipo (4 SP) - ~9 KB
|
|
**Contenido clave:**
|
|
- Dashboard de equipo por roles: Director, Residentes, Ingenieros, Supervisores
|
|
- Validación de workload por rol (Director: 500%, Residente: 200%, Ingeniero: 800%)
|
|
- Solo un Director/Residente principal por proyecto
|
|
- Cálculo en tiempo real de carga total
|
|
- Indicadores visuales: 🟢 Verde (0-70%), 🟡 Amarillo (70-90%), 🔴 Rojo (90-100%)
|
|
- Edición de dedicación y responsabilidades
|
|
- Desactivación de asignaciones con fecha fin
|
|
- Función SQL: get_user_total_workload()
|
|
|
|
#### 8. US-PROJ-008: Calendario de Hitos (3 SP) - ~8 KB
|
|
**Contenido clave:**
|
|
- Timeline visual con 11 tipos de hitos predefinidos
|
|
- Estados: Completado, En progreso, Próximo, Pendiente, Retrasado
|
|
- Validación de dependencias entre hitos
|
|
- Marcar como completado con fecha real y notas
|
|
- Cálculo de días de retraso/adelanto
|
|
- Alertas automáticas configurables (7 días antes por defecto)
|
|
- Cron job diario a las 9:00 AM
|
|
- Notificaciones por email e in-app
|
|
|
|
#### 9. US-PROJ-009: Alertas de Fechas Críticas (3 SP) - ~8 KB
|
|
**Contenido clave:**
|
|
- Registro de fechas contractuales, regulatorias, financieras
|
|
- Marcado de fechas inamovibles con consecuencias si se incumplen
|
|
- Sistema de alertas múltiples: 30, 15, 7, 3, 2, 1 día(s) antes
|
|
- Widget en dashboard: "⚠️ Fechas Críticas Próximas"
|
|
- Colores: 🔴 <7 días, 🟡 7-30 días, 🟢 >30 días
|
|
- Marcar como cumplida o incumplida con notas
|
|
- Cron job diario para envío de alertas
|
|
- Email template completo con botones de acción
|
|
|
|
**Total USs:** 45 SP | ~90 KB de documentación
|
|
|
|
---
|
|
|
|
## 📋 Documentos Pendientes
|
|
|
|
**Ninguno - Épica 100% Completa** ✅
|
|
|
|
---
|
|
|
|
## 🏗️ Arquitectura Técnica
|
|
|
|
### Base de Datos (PostgreSQL)
|
|
|
|
```sql
|
|
-- Schema: projects
|
|
CREATE SCHEMA IF NOT EXISTS projects;
|
|
|
|
-- Tablas principales
|
|
projects.projects (proyecto)
|
|
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 críticas)
|
|
projects.construction_phases (fases)
|
|
projects.project_documents (documentos)
|
|
|
|
-- Total: 11 tablas
|
|
```
|
|
|
|
### Backend (NestJS)
|
|
|
|
```
|
|
apps/backend/src/modules/projects/
|
|
├── entities/
|
|
│ ├── project.entity.ts
|
|
│ ├── stage.entity.ts
|
|
│ ├── block.entity.ts
|
|
│ ├── lot.entity.ts
|
|
│ ├── housing-unit.entity.ts
|
|
│ ├── housing-prototype.entity.ts
|
|
│ ├── team-assignment.entity.ts
|
|
│ └── milestone.entity.ts
|
|
├── dto/
|
|
│ ├── create-project.dto.ts
|
|
│ ├── update-project.dto.ts
|
|
│ └── ...
|
|
├── services/
|
|
│ ├── projects.service.ts
|
|
│ ├── stages.service.ts
|
|
│ ├── housing-units.service.ts
|
|
│ ├── prototypes.service.ts
|
|
│ └── team.service.ts
|
|
├── controllers/
|
|
│ ├── projects.controller.ts
|
|
│ ├── stages.controller.ts
|
|
│ └── ...
|
|
└── projects.module.ts
|
|
```
|
|
|
|
### Frontend (React + TypeScript)
|
|
|
|
```
|
|
apps/frontend/src/features/projects/
|
|
├── pages/
|
|
│ ├── ProjectsListPage.tsx
|
|
│ ├── ProjectDetailPage.tsx
|
|
│ ├── CreateProjectPage.tsx
|
|
│ └── PrototypesPage.tsx
|
|
├── components/
|
|
│ ├── ProjectForm.tsx
|
|
│ ├── ProjectCard.tsx
|
|
│ ├── StructureTreeView.tsx
|
|
│ ├── HousingUnitCard.tsx
|
|
│ ├── PrototypeBuilder.tsx
|
|
│ ├── TeamRoster.tsx
|
|
│ └── MilestoneTimeline.tsx
|
|
├── stores/
|
|
│ └── projectStore.ts
|
|
└── services/
|
|
└── projects.api.ts
|
|
```
|
|
|
|
---
|
|
|
|
## 📈 Características Clave Implementadas
|
|
|
|
### 1. Multi-Proyecto
|
|
✅ Una constructora gestiona múltiples proyectos simultáneos
|
|
✅ Aislamiento por `constructoraId` (RLS)
|
|
✅ Código único auto-generado por año
|
|
|
|
### 2. Jerarquía Flexible
|
|
✅ Soporta fraccionamientos (con manzanas)
|
|
✅ Soporta conjuntos (sin manzanas)
|
|
✅ Soporta torres verticales (niveles)
|
|
✅ Navegación de árbol recursivo
|
|
|
|
### 3. Gestión de Equipo
|
|
✅ Múltiples residentes por proyecto
|
|
✅ Ingenieros compartidos (workload distribuido)
|
|
✅ Validación de límites de carga
|
|
✅ Historial de asignaciones
|
|
|
|
### 4. Calendario Inteligente
|
|
✅ Hitos con dependencias
|
|
✅ Fases constructivas
|
|
✅ Fechas críticas con alertas
|
|
✅ Cálculo de desviaciones temporales
|
|
|
|
---
|
|
|
|
## ⚙️ Configuración SaaS Multi-tenant
|
|
|
|
### Activación del Módulo
|
|
|
|
MAI-002 es un **módulo core** incluido en los 3 planes de suscripción:
|
|
|
|
| Plan | Módulo MAI-002 | Límites |
|
|
|------|----------------|---------|
|
|
| **Básico** | ✅ Incluido | 5 proyectos activos simultáneos |
|
|
| **Profesional** | ✅ Incluido | 15 proyectos activos simultáneos |
|
|
| **Enterprise** | ✅ Incluido | Proyectos ilimitados |
|
|
|
|
**Activación automática:** Este módulo se activa automáticamente durante el onboarding de un nuevo tenant (constructora).
|
|
|
|
### Portal de Administración SaaS
|
|
|
|
#### Para Super Admin (Equipo Interno)
|
|
|
|
**Panel de gestión del módulo:**
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Módulo MAI-002: Proyectos y Estructura │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ 📊 Uso Global (Todos los Tenants) │
|
|
│ ──────────────────────────────────────── │
|
|
│ Tenants con módulo activo: 234/234 (100%) │
|
|
│ Proyectos totales creados: 2,847 │
|
|
│ Viviendas gestionadas: 128,456 │
|
|
│ Proyectos activos: 1,234 │
|
|
│ │
|
|
│ 🔧 Feature Flags │
|
|
│ ──────────────────────────────────────── │
|
|
│ ☑️ projects.bulk_lot_creation (ENABLED) │
|
|
│ Permite creación masiva de hasta 500 lotes │
|
|
│ │
|
|
│ ☑️ projects.housing_prototypes (ENABLED) │
|
|
│ Catálogo de prototipos de vivienda │
|
|
│ │
|
|
│ ☑️ projects.team_workload_validation (ENABLED) │
|
|
│ Validación de límites de carga por rol │
|
|
│ │
|
|
│ ☐ projects.ai_schedule_optimization (BETA) │
|
|
│ Optimización de calendario con IA (Beta) │
|
|
│ │
|
|
│ 📈 Métricas de Rendimiento │
|
|
│ ──────────────────────────────────────── │
|
|
│ API response time (p95): 145 ms ✅ │
|
|
│ Database query time (p95): 78 ms ✅ │
|
|
│ Bulk lot creation (500 lotes): 2.3 s ✅ │
|
|
│ TreeView render (200 nodos): 1.2 s ✅ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
#### Para Tenant Admin (Cliente/Constructora)
|
|
|
|
**Panel de configuración del módulo:**
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Configuración: Módulo de Proyectos │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ 📊 Uso Actual (Constructora ABC) │
|
|
│ ──────────────────────────────────────── │
|
|
│ Plan: Profesional ($799/mes) │
|
|
│ Proyectos activos: 8 / 15 (53%) │
|
|
│ Viviendas gestionadas: 342 │
|
|
│ Usuarios usando módulo: 12 / 25 │
|
|
│ │
|
|
│ ⚙️ Configuraciones Personalizadas │
|
|
│ ──────────────────────────────────────── │
|
|
│ ☑️ Generar código de proyecto automáticamente │
|
|
│ Formato: PROJ-{año}-{secuencial} │
|
|
│ │
|
|
│ ☑️ Requerir aprobación para eliminar proyectos │
|
|
│ Solo Director/Admin pueden eliminar │
|
|
│ │
|
|
│ ☐ Notificar equipo en cambios de estado │
|
|
│ Email + In-app notification │
|
|
│ │
|
|
│ ☑️ Validar límites de workload │
|
|
│ Director: 500%, Resident: 200%, Engineer: 800% │
|
|
│ │
|
|
│ 📂 Catálogos Personalizados │
|
|
│ ──────────────────────────────────────── │
|
|
│ Prototipos de vivienda: 15 activos │
|
|
│ Plantillas de milestones: 3 plantillas │
|
|
│ │
|
|
│ [Gestionar Prototipos] [Configurar Workflows] │
|
|
│ │
|
|
│ ⚠️ Límites del Plan │
|
|
│ ──────────────────────────────────────── │
|
|
│ Estás usando 8 de 15 proyectos permitidos. │
|
|
│ ¿Necesitas más proyectos? │
|
|
│ [Actualizar a Plan Enterprise] (100 proyectos) │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Provisioning Automático
|
|
|
|
Durante el onboarding de un nuevo tenant (constructora), el sistema ejecuta:
|
|
|
|
```bash
|
|
# 1. Validar que tenant existe
|
|
SELECT id FROM constructoras.constructoras WHERE id = $constructora_id;
|
|
|
|
# 2. Activar módulo MAI-002
|
|
INSERT INTO constructoras.constructora_modules (
|
|
constructora_id,
|
|
module_code,
|
|
is_active,
|
|
plan_included
|
|
) VALUES (
|
|
$constructora_id,
|
|
'MAI-002',
|
|
true,
|
|
true -- Incluido en todos los planes
|
|
);
|
|
|
|
# 3. Crear catálogos seed (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', ...);
|
|
|
|
# 4. Configurar feature flags por plan
|
|
INSERT INTO constructoras.constructora_feature_flags (
|
|
constructora_id,
|
|
flag_key,
|
|
is_enabled
|
|
) VALUES
|
|
($constructora_id, 'projects.bulk_lot_creation', true),
|
|
($constructora_id, 'projects.housing_prototypes', true),
|
|
($constructora_id, 'projects.team_workload_validation', true);
|
|
|
|
# 5. Configurar límites por plan
|
|
INSERT INTO constructoras.constructora_limits (
|
|
constructora_id,
|
|
limit_key,
|
|
limit_value
|
|
) VALUES
|
|
($constructora_id, 'max_active_projects', 15), -- Plan Profesional
|
|
($constructora_id, 'max_housing_units', 5000),
|
|
($constructora_id, 'max_team_assignments', 100);
|
|
```
|
|
|
|
### Aislamiento de Datos (RLS)
|
|
|
|
**Garantía de seguridad multi-tenant:**
|
|
|
|
Cada consulta a tablas del módulo MAI-002 está protegida por Row-Level Security (RLS):
|
|
|
|
```sql
|
|
-- Configuración de contexto por sesión
|
|
SET app.current_constructora_id = 'uuid-de-constructora-abc';
|
|
SET app.current_user_id = 'uuid-de-usuario';
|
|
SET app.current_user_role = 'director';
|
|
|
|
-- Toda query SELECT automáticamente filtra por constructora
|
|
SELECT * FROM projects.projects;
|
|
-- Internamente ejecuta:
|
|
-- SELECT * FROM projects.projects
|
|
-- WHERE constructora_id = current_setting('app.current_constructora_id')::UUID;
|
|
|
|
-- Imposible ver datos de otras constructoras
|
|
SELECT * FROM projects.projects WHERE constructora_id = 'otra-constructora-uuid';
|
|
-- Retorna: 0 rows (bloqueado por RLS policy)
|
|
```
|
|
|
|
**Políticas RLS completas:** Ver `implementacion/ET-PROJ-001-rls-policies.sql` y `ET-PROJ-002-rls-policies.sql`
|
|
|
|
### Migraciones Multi-tenant
|
|
|
|
Cuando se despliega una nueva versión con cambios en schema:
|
|
|
|
```typescript
|
|
// Migration ejemplo: Agregar columna nueva
|
|
export class AddProjectTypeToProjects1700000000 implements MigrationInterface {
|
|
public async up(queryRunner: QueryRunner): Promise<void> {
|
|
// Se ejecuta una sola vez, afecta a todos los tenants
|
|
await queryRunner.addColumn(
|
|
'projects',
|
|
new TableColumn({
|
|
name: 'project_subtype',
|
|
type: 'varchar',
|
|
length: '50',
|
|
isNullable: true,
|
|
})
|
|
);
|
|
|
|
// Los datos de cada tenant están aislados por constructora_id
|
|
// No hay riesgo de cross-contamination
|
|
}
|
|
|
|
public async down(queryRunner: QueryRunner): Promise<void> {
|
|
await queryRunner.dropColumn('projects', 'project_subtype');
|
|
}
|
|
}
|
|
```
|
|
|
|
**Proceso de deployment:**
|
|
1. **Pre-deployment checks**: Validar que migration no rompe RLS policies
|
|
2. **Staging deployment**: Ejecutar en tenant de prueba
|
|
3. **Production rollout**: Blue-green deployment sin downtime
|
|
4. **Post-deployment validation**: Verificar que RLS sigue activo
|
|
|
|
### Monitoreo por Tenant
|
|
|
|
**Métricas capturadas por constructora:**
|
|
|
|
```javascript
|
|
// Ejemplo de evento de auditoría
|
|
{
|
|
"event": "project.created",
|
|
"timestamp": "2025-11-17T10:30:00Z",
|
|
"constructora_id": "uuid-constructora-abc",
|
|
"user_id": "uuid-user-123",
|
|
"project_id": "uuid-project-456",
|
|
"metadata": {
|
|
"project_code": "PROJ-2025-015",
|
|
"project_type": "fraccionamiento_horizontal",
|
|
"contract_amount": 25000000
|
|
}
|
|
}
|
|
```
|
|
|
|
**Dashboard de métricas por tenant:**
|
|
- Proyectos creados por mes
|
|
- Viviendas gestionadas
|
|
- Usuarios activos en módulo
|
|
- API calls por día
|
|
- Errores y warnings
|
|
|
|
### Upgrade de Plan
|
|
|
|
Cuando un tenant actualiza su plan (ej: Básico → Profesional):
|
|
|
|
```typescript
|
|
// Auto-desbloqueo de límites
|
|
UPDATE constructoras.constructora_limits
|
|
SET limit_value = 15 -- Era 5 en plan Básico
|
|
WHERE constructora_id = $tenant_id
|
|
AND limit_key = 'max_active_projects';
|
|
|
|
// Activar features adicionales (si aplica)
|
|
UPDATE constructoras.constructora_feature_flags
|
|
SET is_enabled = true
|
|
WHERE constructora_id = $tenant_id
|
|
AND flag_key = 'projects.ai_schedule_optimization';
|
|
|
|
// Audit log
|
|
INSERT INTO audit.plan_changes (
|
|
constructora_id,
|
|
old_plan,
|
|
new_plan,
|
|
changed_at,
|
|
changed_by
|
|
) VALUES (
|
|
$tenant_id,
|
|
'basico',
|
|
'profesional',
|
|
NOW(),
|
|
$admin_user_id
|
|
);
|
|
```
|
|
|
|
**Efectos inmediatos:**
|
|
- ✅ Límites actualizados (sin reinicio)
|
|
- ✅ Features nuevos disponibles
|
|
- ✅ Facturación ajustada pro-rata
|
|
- ✅ Notificación al tenant admin
|
|
|
|
### Soporte y Troubleshooting
|
|
|
|
**Herramientas de soporte para equipo interno:**
|
|
|
|
```sql
|
|
-- Ver estado de módulo para un tenant específico
|
|
SELECT
|
|
c.name AS constructora,
|
|
cm.is_active,
|
|
cm.activated_at,
|
|
c.plan,
|
|
cl.limit_value AS max_projects,
|
|
(SELECT COUNT(*) FROM projects.projects WHERE constructora_id = c.id) AS projects_count
|
|
FROM constructoras.constructoras c
|
|
JOIN constructoras.constructora_modules cm ON cm.constructora_id = c.id
|
|
LEFT JOIN constructoras.constructora_limits cl ON cl.constructora_id = c.id
|
|
AND cl.limit_key = 'max_active_projects'
|
|
WHERE c.subdomain = 'constructora-abc'
|
|
AND cm.module_code = 'MAI-002';
|
|
|
|
-- Diagnóstico de performance para un tenant
|
|
SELECT
|
|
constructora_id,
|
|
AVG(response_time_ms) AS avg_response_time,
|
|
MAX(response_time_ms) AS max_response_time,
|
|
COUNT(*) AS total_requests,
|
|
COUNT(*) FILTER (WHERE status_code >= 500) AS errors
|
|
FROM api_logs
|
|
WHERE module = 'MAI-002'
|
|
AND constructora_id = $tenant_id
|
|
AND created_at > NOW() - INTERVAL '24 hours'
|
|
GROUP BY constructora_id;
|
|
```
|
|
|
|
---
|
|
|
|
## 🔗 Integraciones con Otras Épicas
|
|
|
|
| Épica | Relación | 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 físicos por vivienda |
|
|
| MAI-007 (RRHH) | `TeamAssignment` | Asistencias de cuadrillas en proyecto |
|
|
|
|
---
|
|
|
|
## 📊 Métricas de Progreso
|
|
|
|
| Métrica | Planificado | Actual | % |
|
|
|---------|-------------|--------|---|
|
|
| **RFs** | 4 | 4 | 100% ✅ |
|
|
| **ETs** | 4 | 4 | 100% ✅ |
|
|
| **USs** | 9 | 9 | 100% ✅ |
|
|
| **Story Points** | 45 SP | 45 SP | 100% ✅ |
|
|
| **Tamaño Documentación** | ~315 KB | ~230 KB | 73% |
|
|
| **Tiempo invertido** | - | ~8 horas | - |
|
|
|
|
---
|
|
|
|
## 🎉 MAI-002: ÉPICA COMPLETA
|
|
|
|
### ✅ Logros Alcanzados
|
|
|
|
**Documentación Generada:**
|
|
- ✅ 4 Requerimientos Funcionales (~104 KB)
|
|
- ✅ 4 Especificaciones Técnicas (~164 KB)
|
|
- ✅ 9 Historias de Usuario (~92 KB)
|
|
- ✅ 1 Resumen Ejecutivo
|
|
- **Total:** 18 documentos | ~230 KB
|
|
|
|
**Cobertura Técnica:**
|
|
- ✅ 11 tablas de base de datos especificadas
|
|
- ✅ 8 entities TypeORM completas
|
|
- ✅ 12+ services con lógica de negocio
|
|
- ✅ 15+ controllers RESTful
|
|
- ✅ 20+ componentes React
|
|
- ✅ Validaciones Zod completas
|
|
- ✅ Tests unitarios especificados
|
|
- ✅ Cron jobs para alertas
|
|
- ✅ Sistema de eventos completo
|
|
|
|
**Story Points Cubiertos:**
|
|
- RFs: ~16 SP (estimado)
|
|
- ETs: ~24 SP (estimado)
|
|
- USs: 45 SP (exacto)
|
|
- **Total:** 45+ SP de trabajo especificado
|
|
|
|
### 📦 Entregables Listos para Implementación
|
|
|
|
**Backend (NestJS + PostgreSQL):**
|
|
- Schema completo de 11 tablas
|
|
- Migrations especificadas
|
|
- Entities, DTOs, Services, Controllers
|
|
- Validaciones de negocio
|
|
- Event emitters
|
|
- Triggers y funciones SQL
|
|
- Row Level Security (RLS)
|
|
|
|
**Frontend (React + TypeScript):**
|
|
- 20+ componentes especificados
|
|
- Formularios con React Hook Form + Zod
|
|
- State management (Zustand)
|
|
- API service layer
|
|
- Mockups/wireframes
|
|
- Responsive design
|
|
|
|
**Features Completas:**
|
|
- ✅ Multi-proyecto con multi-tenancy
|
|
- ✅ Jerarquía flexible (horizontal/vertical/mixto)
|
|
- ✅ Prototipos con versionado
|
|
- ✅ Gestión de equipo con workload
|
|
- ✅ Calendario de hitos con dependencias
|
|
- ✅ Alertas automáticas
|
|
|
|
---
|
|
|
|
## 🎯 Próximos Pasos Recomendados
|
|
|
|
### Opción 1: Iniciar Implementación de MAI-002 ⭐ RECOMENDADO
|
|
**Razón:** Documentación 100% completa, equipo puede empezar desarrollo inmediato
|
|
|
|
**Sprint Planning:**
|
|
- Sprint 3: US-PROJ-001 + US-PROJ-002 (13 SP)
|
|
- Sprint 4: US-PROJ-003 + US-PROJ-004 (14 SP)
|
|
- Sprint 5: US-PROJ-005 + US-PROJ-006 (8 SP)
|
|
- Sprint 6: US-PROJ-007 + US-PROJ-008 + US-PROJ-009 (10 SP)
|
|
|
|
**Estimación:** 4 sprints de 2 semanas = 8 semanas
|
|
|
|
### Opción 2: Continuar con Siguiente Épica
|
|
**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
|
|
|
|
### Opción 3: Enfoque Paralelo
|
|
- Equipo A: Implementa MAI-002
|
|
- Equipo B: Documenta MAI-003 o MAI-005
|
|
**Beneficio:** Velocidad máxima, trabajo paralelo
|
|
|
|
---
|
|
|
|
## 📝 Lecciones de MAI-002
|
|
|
|
### Patrones Técnicos Exitosos
|
|
✅ Jerarquía recursiva (Proyecto → Etapa → Manzana → Lote → Vivienda)
|
|
✅ ENUMs para estados y tipos (type-safe)
|
|
✅ Event emitters para notificaciones
|
|
✅ Cálculo automático de fechas y métricas
|
|
✅ Código auto-generado secuencial por año
|
|
|
|
### Complejidad Manejada
|
|
✅ Múltiples tipos de proyectos (horizontal, vertical, mixto)
|
|
✅ Transiciones de estado validadas
|
|
✅ Gestión de equipo con workload distribuido
|
|
✅ Calendario con dependencias de hitos
|
|
|
|
### Reutilización de GAMILIT
|
|
- **Estructura jerárquica:** ~40% similar a Cursos → Módulos → Lecciones
|
|
- **Team assignments:** ~50% similar a Professor assignments
|
|
- **Prototypes:** Concepto nuevo, 0% reutilización
|
|
|
|
---
|
|
|
|
**Generado:** 2025-11-17
|
|
**Autor:** Sistema de Documentación Automática
|
|
**Próxima revisión:** Al completar ETs y USs pendientes
|