rckrdmrd/erp-construccion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7f422e51db
erp-construccion/docs/02-definicion-modulos/ANALISIS-REUTILIZACION-GAMILIT.md

18 KiB
Raw Blame History

Análisis de Reutilización de Componentes GAMILIT para MVP Inmobiliario

Proyecto Origen: GAMILIT (Plataforma Educativa) Proyecto Destino: Sistema de Administración de Obra e INFONAVIT Fecha Análisis: 2025-11-17 Stack Tecnológico: Node.js + Express + TypeScript | React + Vite | PostgreSQL

Resumen Ejecutivo

Este documento analiza qué componentes del proyecto GAMILIT pueden ser reutilizados en el desarrollo del MVP inmobiliario, estimando el ahorro de tiempo y esfuerzo.

Resultado estimado:

  • Reducción de tiempo de desarrollo: 30-40% (similar a lo estimado en el MVP-APP.md)
  • Código ya probado en producción: ~60% de la infraestructura base
  • Ahorro estimado: ~6-8 semanas de desarrollo

1. Componentes Reutilizables de GAMILIT

1.1 Infraestructura Base (Reutilización: 90%)

Backend (Node.js + Express + TypeScript)

Componente Archivo Origen GAMILIT Aplicación Inmobiliaria Adaptación Requerida
Sistema de Autenticación JWT apps/backend/src/modules/auth/ Autenticación de usuarios (Dirección, Ingeniería, Residentes, etc.) Mínima - Ajustar roles
RBAC (Roles y Permisos) apps/backend/src/shared/guards/roles.guard.ts Sistema de permisos por perfil (7 roles del MVP) Media - Adaptar roles específicos
Multi-tenancy apps/database/ddl/schemas/auth_management/ Soporte de múltiples constructoras Mínima - Ya implementado
Row Level Security (RLS) Políticas RLS en PostgreSQL Seguridad a nivel de datos por proyecto/obra Media - Adaptar políticas
Sistema de Auditoría apps/database/ddl/schemas/audit_logging/ Bitácora de actividades y cambios críticos Mínima - Reutilización directa
Middleware de Validación apps/backend/src/shared/middleware/ Validación de entrada en endpoints Mínima - Reutilización directa
Manejo de Errores apps/backend/src/shared/filters/ Gestión centralizada de errores Ninguna - Reutilización directa
Logging Estructurado Winston/Pino config Logs estructurados con niveles Ninguna - Reutilización directa
Gestión de Archivos Sistema de uploads Gestión de documentos, planos, fotos Baja - Adaptación de categorías

Ahorro estimado Backend: 3-4 semanas

Frontend Web (React + Vite + TypeScript)

Componente Archivo Origen GAMILIT Aplicación Inmobiliaria Adaptación Requerida
Componentes UI Base apps/frontend/src/components/ui/ Botones, Inputs, Modales, Alerts Ninguna - Reutilización directa
Sistema de Formularios React Hook Form + Zod Formularios de captura (avances, compras, etc.) Baja - Adaptación de esquemas
Tablas con Paginación apps/frontend/src/components/tables/ Listados de obras, presupuestos, compras Baja - Adaptación de columnas
Dashboards y Gráficos Chart.js / Recharts Dashboards de obra, desviaciones, KPIs Media - Nuevas métricas
Layouts Responsivos apps/frontend/src/layouts/ Layout principal admin + móvil Baja - Adaptación de menús
Autenticación y Rutas Protegidas apps/frontend/src/guards/ Protección de rutas por rol Mínima - Ajustar roles
Hooks Personalizados apps/frontend/src/hooks/ useApi, useAuth, useForm Ninguna - Reutilización directa
Sistema de Notificaciones Toast/Alerts Notificaciones de sistema Ninguna - Reutilización directa
State Management (Zustand) Stores de autenticación, perfiles Stores para obras, presupuestos, etc. Media - Nuevos stores

Ahorro estimado Frontend: 2-3 semanas

Base de Datos (PostgreSQL 15+)

Componente Archivo Origen GAMILIT Aplicación Inmobiliaria Adaptación Requerida
Schemas Modulares Organización por dominios Schemas por módulo (projects, budgets, purchases, etc.) Media - Nueva organización
Políticas RLS Row Level Security Políticas por proyecto/obra Media - Adaptación de políticas
Triggers de Auditoría Triggers automáticos Auditoría de cambios críticos Baja - Reutilización con ajustes
Funciones Comunes gamilit.now_mexico(), gamilit.get_current_user_id() Funciones de utilidad Ninguna - Reutilización directa
Sistema de Migraciones Control de versiones DDL Gestión de cambios en BD Ninguna - Reutilización directa
ENUMs para Estados Estados de cuenta, tipos Estados de obra, estimaciones, etc. Alta - Nuevos ENUMs específicos

Ahorro estimado Database: 1-2 semanas

1.2 Patrones Arquitectónicos (Reutilización: 100%)

Estos patrones se copian directamente sin modificación:

Patrón Descripción Beneficio
Repository/Service Separación de lógica de negocio y acceso a datos Código limpio y testeable
Modularización por Dominio Organización /modules/{domain} Escalabilidad y mantenibilidad
DTOs con Validación class-validator + class-transformer Validación robusta de entrada
Guards y Decorators @Roles(), @Public(), @CurrentUser() Seguridad declarativa
Error Handling Centralizado Exception filters personalizados Respuestas consistentes
Testing Patterns Unit + E2E tests con Jest Cobertura de tests

2. Mapeo de Funcionalidades GAMILIT → Inmobiliario

2.1 Equivalencias Directas

GAMILIT Inmobiliario Reutilización
students tabla employees / beneficiaries 70% - Cambio de nombres
courses tabla projects 60% - Similar estructura jerárquica
modules tabla stages (etapas de obra) 50% - Concepto similar
activities tabla tasks / checklists 70% - Similar tracking
progress_tracking schema progress_tracking (avances de obra) 80% - Muy similar
user_stats tabla project_stats 70% - Métricas similares
achievements tabla milestones (hitos de proyecto) 50% - Concepto adaptable
Sistema de notificaciones Alertas de desviaciones/hitos 90% - Reutilización directa

2.2 Adaptaciones Conceptuales

GAMILIT: Sistema de "Aulas" con profesores y estudiantes Inmobiliario: Sistema de "Proyectos/Obras" con equipo asignado

GAMILIT: Tracking de "Progreso en Ejercicios" Inmobiliario: Tracking de "Avances Físicos de Obra"

GAMILIT: Sistema de "ML Coins" (monedas lectoras) Inmobiliario: Sistema de "Presupuesto vs Costo Real"

GAMILIT: "Rangos Maya" de progreso Inmobiliario: "Estados de Obra" (Licitación, Ejecución, Entrega, etc.)

3. Mapeo de Módulos a Épicas

Fase 1: Alcance Inicial (14 semanas) - 6 Épicas

Presupuesto Estimado: $150,000 MXN Story Points: ~280 SP

Épica Nombre Módulos MVP Relacionados Reutilización GAMILIT Presupuesto SP
MAI-001 Fundamentos Módulo 13 (Admin & Seguridad) EAI-001 (90%) $25,000 50
MAI-002 Proyectos y Estructura de Obra Módulo 1 (Proyectos, Obras, Viviendas) EAI-002 (40%) $25,000 45
MAI-003 Presupuestos y Control de Costos Módulo 2 (Presupuestos y Costos) Nuevo (10%) $25,000 50
MAI-004 Compras e Inventarios Módulo 3, 4 (Compras, Inventarios) Nuevo (15%) $25,000 50
MAI-005 Control de Obra y Avances Módulo 6 (Control de Obra y Avances) EAI-002 (60%) $25,000 45
MAI-006 Reportes y Analytics Base Módulo 12 (Reportes & BI) EAI-004 (70%) $25,000 40

Total Fase 1: $150,000 MXN | 280 SP | ~14 semanas

Fase 2: Gestión Avanzada (10 semanas) - 5 Épicas

Presupuesto Estimado: $125,000 MXN Story Points: ~220 SP

Épica Nombre Módulos MVP Relacionados Reutilización GAMILIT Presupuesto SP
MAI-007 Contratos y Estimaciones Módulo 5, 7 (Contratos, Estimaciones) Nuevo (20%) $25,000 45
MAI-008 RRHH y Nómina de Obra Módulo 8 (RRHH, Asistencias) EAI-005 (30%) $25,000 45
MAI-009 Calidad y Postventa Módulo 9 (Calidad, Garantías) Nuevo (25%) $25,000 45
MAI-010 CRM Derechohabientes Módulo 10 (CRM) Nuevo (30%) $25,000 40
MAI-011 INFONAVIT & Cumplimiento Módulo 11 (INFONAVIT) Nuevo (10%) $25,000 45

Total Fase 2: $125,000 MXN | 220 SP | ~10 semanas

Fase 3: IA y Extensiones (6 semanas) - 2 Épicas

Presupuesto Estimado: $75,000 MXN Story Points: ~140 SP

Épica Nombre Módulos MVP Relacionados Reutilización GAMILIT Presupuesto SP
MAI-012 Admin y Configuración Avanzada Módulo 13 (Admin completo) EAI-005, EAI-006 (60%) $25,000 50
MAI-013 IA, WhatsApp Business y App Móvil Agente IA, WhatsApp, App React Native Nuevo (20%) $50,000 90

Total Fase 3: $75,000 MXN | 140 SP | ~6 semanas

4. Desglose de Reutilización por Componente

4.1 Infraestructura y Base (Sprint 0)

Componente Origen GAMILIT Tiempo sin Reutilización Tiempo con Reutilización Ahorro
Sistema de Autenticación 2 semanas 3 días 65%
RBAC 1.5 semanas 2 días 70%
Configuración Base de Datos 1 semana 3 días 60%
UI Base y Layouts 3 semanas 1 semana 67%
Dashboards Base 2 semanas 1 semana 50%
Sistema de Formularios 1.5 semanas 3 días 60%
TOTAL Sprint 0 11 semanas 3.8 semanas ~65%

4.2 Módulos de Negocio

Módulo MVP Complejidad Reutilización GAMILIT Tiempo Estimado (sin/con)
1. Proyectos y Obras Media 40% 3 sem / 2 sem
2. Presupuestos Alta 10% 4 sem / 3.5 sem
3. Compras Media 15% 3 sem / 2.5 sem
4. Inventarios Media 20% 3 sem / 2.5 sem
5. Contratos Alta 20% 4 sem / 3 sem
6. Control de Obra Alta 60% 4 sem / 2 sem
7. Estimaciones Alta 25% 4 sem / 3 sem
8. RRHH Media 30% 3 sem / 2 sem
9. Calidad/Postventa Media 25% 3 sem / 2.5 sem
10. CRM Media 30% 3 sem / 2 sem
11. INFONAVIT Alta 10% 4 sem / 3.5 sem
12. Reportes/BI Media 70% 3 sem / 1.5 sem
13. Admin Baja 80% 2 sem / 0.5 sem

5. Plan de Migración de Componentes

Sprint 0: Migración de Base (1 semana)

Componentes a migrar:

  1. Sistema de autenticación JWT
  2. Middleware de autenticación y autorización
  3. Sistema de logging estructurado
  4. Componentes UI base (Buttons, Inputs, Modales)
  5. Layouts principales
  6. Setup de base de datos con schemas modulares

Actividades:

  • Crear repositorio con estructura base de GAMILIT
  • Migrar sistema de autenticación completo
  • Setup de base de datos con schemas modulares
  • Migrar componentes UI base
  • Configurar sistema de logging y error handling

Sprint 1-2: Fundamentos (2 semanas)

Componentes a adaptar:

  1. Sistema de roles específicos de construcción:

    • student → resident (Residente de obra)
    • admin_teacher → engineer (Ingeniero)
    • super_admin → director (Director de obra)
    • Nuevos: purchases, finance, hr, post_sales

  2. Layouts y navegación:

    • Adaptar menú principal
    • Crear dashboards por rol

  3. Sistema de permisos:

    • Adaptar RLS policies para obras/proyectos
    • Definir permisos por módulo

Sprint 3+: Módulos de Negocio

Estrategia:

  1. Reutilizar patrones de tracking de GAMILIT para "Control de Obra"
  2. Adaptar sistema de "Aulas" a "Proyectos/Obras"
  3. Crear nuevos módulos específicos (Presupuestos, Compras, Contratos)
  4. Reutilizar componentes de dashboards y gráficos

6. Consideraciones Técnicas

6.1 Diferencias de Dominio

Aspecto GAMILIT MVP Inmobiliario Impacto
Modelo de Datos Educativo (cursos, módulos, ejercicios) Constructivo (obras, etapas, conceptos) Alto - Nuevas entidades
Flujos de Trabajo Lineal (progreso en curso) Complejo (múltiples frentes paralelos) Alto - Nueva lógica
Roles de Usuario Estudiante, Profesor, Admin 7 roles específicos de construcción Medio - Adaptación de RBAC
Métricas Educativas (XP, progreso, logros) Financieras (presupuesto, costo, avance) Alto - Nuevas métricas
Integraciones OAuth social WhatsApp Business, INFONAVIT Alto - Nuevas integraciones

6.2 Términos a Adaptar

GAMILIT MVP Inmobiliario
students employees / beneficiaries
teachers engineers / residents
courses projects
modules stages (etapas)
activities tasks / work_items
progress physical_progress / financial_progress
achievements milestones
classrooms construction_sites / work_fronts
xp_points progress_percentage
ml_coins budget_balance

7. Estrategia de Mantenimiento del Código Compartido

7.1 Componentes Compartidos

Opción 1: Copiar y Divergir

  • Copiar componentes de GAMILIT al proyecto inmobiliario
  • Evolucionar independientemente
  • Ventaja: Independencia total
  • Desventaja: Duplicación de código

Opción 2: Librería Compartida (Futuro)

  • Extraer componentes comunes a librería npm privada
  • Compartir entre GAMILIT e Inmobiliario
  • Ventaja: Reutilización real, fixes compartidos
  • Desventaja: Complejidad adicional

Recomendación: Opción 1 para MVP, Opción 2 en Fase 2

7.2 Documentación de Componentes Reutilizados

Todos los componentes reutilizados deben documentarse con:

/**
 * @reused-from GAMILIT
 * @original-file apps/backend/src/shared/guards/roles.guard.ts
 * @adaptations
 * - Roles específicos de construcción
 * - Permisos por proyecto/obra
 * @last-sync 2025-11-17
 */

8. Estimación de Ahorro

8.1 Resumen por Fase

Fase Sin Reutilización Con Reutilización Ahorro
Fase 1 20 semanas 14 semanas 30%
Fase 2 14 semanas 10 semanas 29%
Fase 3 8 semanas 6 semanas 25%
TOTAL 42 semanas 30 semanas ~29%

Ahorro total estimado: 12 semanas (~3 meses)

8.2 Resumen por Componente

Componente Ahorro Estimado
Autenticación 65%
UI Base 67%
Dashboards 50%
Formularios 60%
BD Setup 60%
Logging/Auditoría 90%
Middleware 85%
PROMEDIO ~65%

9. Riesgos y Mitigaciones

9.1 Riesgos Identificados

Riesgo Probabilidad Impacto Mitigación
Incompatibilidad de versiones Media Alto Documentar versiones exactas de dependencias
Over-engineering Media Medio Simplificar componentes no necesarios
Divergencia de arquitectura Baja Alto Mantener patrones consistentes
Deuda técnica Media Medio Code reviews rigurosos

9.2 Plan de Mitigación

  1. Sprint 0 obligatorio: No saltar directo a módulos de negocio
  2. Code reviews cruzados: Team GAMILIT revisa código inmobiliario
  3. Documentación exhaustiva: Cada adaptación debe documentarse
  4. Tests rigurosos: Mantener >80% coverage como en GAMILIT

10. Conclusiones y Recomendaciones

10.1 Componentes Prioritarios a Reutilizar

Alta Prioridad (Reutilizar tal cual):

  • Sistema de autenticación JWT
  • RBAC y guards
  • Logging y auditoría
  • Componentes UI base
  • Middleware de validación
  • Error handling

Media Prioridad (Adaptar):

  • Sistema de tracking de progreso → Avances de obra
  • Dashboards y gráficos → Dashboards de obra
  • Sistema de notificaciones
  • Gestión de archivos

Baja Prioridad (Inspiración):

  • Sistema de gamificación → No aplica
  • Achievements → Hitos de proyecto (concepto adaptado)

10.2 Roadmap Recomendado

Semanas 1-2: Sprint 0 (Migración de Base)

  • Configurar repositorio
  • Migrar infraestructura base
  • Adaptar sistema de autenticación

Semanas 3-6: Fase 1A (Fundamentos + Proyectos)

  • MAI-001: Fundamentos
  • MAI-002: Proyectos y Estructura

Semanas 7-14: Fase 1B (Core de Obra)

  • MAI-003: Presupuestos
  • MAI-004: Compras e Inventarios
  • MAI-005: Control de Obra
  • MAI-006: Reportes Base

Semanas 15-24: Fase 2 (Gestión Avanzada)

  • MAI-007 a MAI-011

Semanas 25-30: Fase 3 (IA y Extensiones)

  • MAI-012 y MAI-013

10.3 KPIs de Éxito

KPI Target
Tiempo de desarrollo ≤ 30 semanas
Reducción vs desarrollo desde cero ≥ 25%
Código reutilizado ≥ 50% de infraestructura
Coverage de tests ≥ 80%
Bugs críticos en producción 0

Apéndice A: Checklist de Migración

Infraestructura Base

  • Sistema de autenticación JWT
  • Guards y decorators
  • Middleware de validación
  • Error handlers
  • Logging estructurado
  • Sistema de auditoría
  • Gestión de archivos
  • RLS policies base

Frontend

  • Componentes UI base
  • Layouts principales
  • Sistema de formularios
  • Tablas con paginación
  • Dashboards base
  • Hooks personalizados
  • Guards de routing
  • State management

Database

  • Schemas modulares
  • Funciones comunes
  • Triggers de auditoría
  • Sistema de migraciones
  • Seeds de datos de prueba

Documento generado: 2025-11-17 Autor: Análisis Técnico Versión: 1.0 Próxima revisión: Post Sprint 0