rckrdmrd a9703b2727 Initial commit - erp-construccion

2026-01-04 06:12:06 -06:00

21 KiB

Raw Permalink 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	Catalogo de Proyectos	US-001, US-002	Documentado
RF-PROJ-002	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	Prototipos de Vivienda	US-005, US-006	Documentado
RF-PROJ-004	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	Implementacion Catalogo Proyectos	RF-PROJ-001	3	9	Documentado
ET-PROJ-002	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	Implementacion Prototipos	RF-PROJ-003	4	9	Documentado
ET-PROJ-004	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	Catalogo de Proyectos	8	P0	Documentado
US-PROJ-002	US-PROJ-002-transiciones-estado.md	Transiciones de Estado	5	P0	Documentado
US-PROJ-003	US-PROJ-003-estructura-fraccionamiento.md	Estructura de Fraccionamiento	8	P0	Documentado
US-PROJ-004	US-PROJ-004-estructura-torre-vertical.md	Estructura de Torre Vertical	6	P1	Documentado
US-PROJ-005	US-PROJ-005-gestion-prototipos.md	Gestion de Prototipos	5	P1	Documentado
US-PROJ-006	US-PROJ-006-asignacion-prototipos-lotes.md	Asignacion de Prototipos a Lotes	3	P1	Documentado
US-PROJ-007	US-PROJ-007-asignacion-equipo.md	Asignacion de Equipo	4	P1	Documentado
US-PROJ-008	US-PROJ-008-calendario-hitos.md	Calendario de Hitos	3	P1	Documentado
US-PROJ-009	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 - Matriz completa de trazabilidad
ET-PROJ-001-rls-policies.sql - RLS para proyectos
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 ejecutivo completo (830+ lineas)
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 - Row Level Security para proyectos
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

// Navegacion de arbol recursivo
interface TreeNode {
  id: string;
  type: 'project' | 'stage' | 'block' | 'lot' | 'housing';
  children?: TreeNode[];
}

2. Event-Driven Notifications

// Event emitters para notificaciones
this.eventEmitter.emit('project.status_changed', {
  projectId,
  oldStatus,
  newStatus,
  changedBy
});

3. Codigo Auto-generado

// 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

// Maquina de estados para transiciones
const validTransitions = {
  licitacion: ['adjudicado'],
  adjudicado: ['ejecucion'],
  ejecucion: ['entregado'],
  entregado: ['cerrado']
};

5. Row Level Security (RLS)

-- 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
Trazabilidad: 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)

21 KiB Raw Permalink Blame History

_MAP: MAI-002 - Proyectos y Estructura

Proposito

Estructura de Archivos

Contenido

Requerimientos Funcionales (4)

Especificaciones Tecnicas (4)

Historias de Usuario (9)

Implementacion

Flujo de Documentacion

Relacion entre Componentes

1. Dependencias Jerarquicas

2. Flujo de Estados

3. Integraciones con Otros Modulos

Quick Links

Documentos Principales

Por Tipo de Proyecto

Por Funcionalidad

Archivos SQL

Modulos Afectados

Base de Datos

Backend (NestJS)

Frontend (React + TypeScript)

Metricas

Caracteristicas Clave

1. Jerarquia Flexible

2. Prototipos con Versionado

3. Gestion de Equipo Inteligente

4. Calendario Inteligente

5. Multi-tenancy Robusto

Configuracion SaaS Multi-tenant

Activacion del Modulo

Feature Flags Configurables

Stack Tecnologico

Backend

Frontend

Storage

Patrones de Implementacion

1. Jerarquia Recursiva

2. Event-Driven Notifications

3. Codigo Auto-generado

4. Validacion de Estado

5. Row Level Security (RLS)

Plan de Implementacion

Sprint 3 (Semana 3-4) - 13 SP

Sprint 4 (Semana 5-6) - 14 SP

Sprint 5 (Semana 7-8) - 8 SP

Sprint 6 (Semana 9-10) - 10 SP

Siguientes Pasos

Opcion 1: Iniciar Implementacion de MAI-002 (RECOMENDADO)

Opcion 2: Continuar con Siguiente Epica

Opcion 3: Enfoque Paralelo

Referencias

21 KiB

Raw Permalink Blame History