# PLAN DE ORGANIZACIÓN DEL WORKSPACE

**Fecha:** 2025-12-08
**Versión:** 1.0.0
**Estado:** Propuesta

---

## RESUMEN EJECUTIVO

Este documento presenta un plan integral para organizar el workspace, centralizando funcionalidades compartidas en `core/`, definiendo módulos claros para cada proyecto, y eliminando duplicación de código.

### Estado Actual

| Proyecto | Estado | Backend | Frontend | BD |
|----------|--------|---------|----------|-----|
| **Gamilit** | ✅ 60% MVP | NestJS | React 19 | PostgreSQL 9 schemas |
| **Trading Platform** | 🔄 50% | Express | React 18 | PostgreSQL 8 schemas |
| **ERP Suite** | 🔄 35% | Express | React 18 | PostgreSQL 12+ schemas |
| **Marketing Content** | 📋 Inicio | Express | React | - |
| **Betting/Inmobiliaria** | 📋 Planificación | - | - | - |

### Problemas Identificados

1. **`core/modules/` vacío** - Solo carpetas sin código
2. **`core/catalog/_reference/` vacío** - Documentación sin implementación
3. **Código duplicado** entre proyectos (~5,000+ líneas)
4. **Frameworks mixtos** - NestJS vs Express
5. **Patrones inconsistentes** - Diferentes formas de hacer lo mismo

---

## PARTE 1: ESTRUCTURA DE CORE/

### 1.1 Estructura Propuesta

```
core/
├── modules/                    # CÓDIGO COMPARTIDO EJECUTABLE
│   ├── utils/                  # Utilidades universales
│   │   ├── date.util.ts
│   │   ├── string.util.ts
│   │   ├── validation.util.ts
│   │   ├── format.util.ts
│   │   ├── crypto.util.ts
│   │   └── index.ts
│   │
│   ├── auth/                   # Autenticación (adapter pattern)
│   │   ├── jwt/
│   │   │   ├── jwt.service.ts
│   │   │   ├── jwt.guard.ts
│   │   │   └── jwt.strategy.ts
│   │   ├── passport/
│   │   │   ├── google.strategy.ts
│   │   │   ├── facebook.strategy.ts
│   │   │   └── github.strategy.ts
│   │   ├── adapters/
│   │   │   ├── nestjs.adapter.ts
│   │   │   └── express.adapter.ts
│   │   └── index.ts
│   │
│   ├── database/               # Schemas y migraciones base
│   │   ├── schemas/
│   │   │   ├── auth.base.sql
│   │   │   ├── audit.base.sql
│   │   │   └── notifications.base.sql
│   │   ├── entities/
│   │   │   ├── base.entity.ts
│   │   │   └── tenant.entity.ts
│   │   └── migrations/
│   │
│   ├── api/                    # Patrones de API
│   │   ├── response.ts         # ApiResponse format
│   │   ├── pagination.ts
│   │   ├── filters.ts
│   │   └── interceptors/
│   │       ├── transform-response.interceptor.ts
│   │       └── logging.interceptor.ts
│   │
│   ├── notifications/          # Sistema de notificaciones
│   │   ├── email/
│   │   ├── push/
│   │   ├── in-app/
│   │   └── index.ts
│   │
│   ├── payments/               # Integración de pagos
│   │   ├── stripe/
│   │   ├── webhooks/
│   │   └── index.ts
│   │
│   ├── websocket/              # WebSocket patterns
│   │   ├── socket.service.ts
│   │   ├── rooms.ts
│   │   └── index.ts
│   │
│   └── multitenant/            # Multi-tenancy
│       ├── rls.interceptor.ts
│       ├── tenant.context.ts
│       └── index.ts
│
├── catalog/                    # DOCUMENTACIÓN + REFERENCIA (ya existe)
│   ├── auth/
│   │   ├── README.md
│   │   ├── IMPLEMENTATION.md
│   │   └── _reference/         # ← POBLAR CON CÓDIGO DE GAMILIT
│   ├── ...
│
├── constants/                  # CONSTANTES GLOBALES (NUEVO)
│   ├── enums.constants.ts      # Enums universales
│   ├── regex.constants.ts      # Patrones regex
│   └── index.ts
│
├── types/                      # TIPOS COMPARTIDOS (NUEVO)
│   ├── api.types.ts
│   ├── auth.types.ts
│   ├── common.types.ts
│   └── index.ts
│
├── frontend/                   # COMPONENTES FRONTEND COMPARTIDOS (NUEVO)
│   ├── components/
│   │   ├── atoms/
│   │   ├── molecules/
│   │   └── organisms/
│   ├── hooks/
│   ├── utils/
│   └── themes/
│
├── orchestration/              # Sistema de agentes (ya existe)
├── standards/                  # Estándares técnicos (ya existe)
└── package.json                # Para publicar como paquete npm
```

### 1.2 Prioridad de Implementación

| Prioridad | Módulo | Origen | Impacto |
|-----------|--------|--------|---------|
| **P0** | `utils/` | Gamilit | Todos los proyectos |
| **P0** | `constants/` | Gamilit | Todos los proyectos |
| **P0** | `types/` | Nuevo | Todos los proyectos |
| **P1** | `auth/` | Gamilit + Trading | Backend |
| **P1** | `api/interceptors/` | Gamilit | Backend |
| **P2** | `database/schemas/` | ERP + Gamilit | Base de datos |
| **P2** | `notifications/` | Gamilit | Backend |
| **P3** | `payments/` | Trading | Backend |
| **P3** | `websocket/` | Trading + Gamilit | Backend |
| **P3** | `frontend/` | Gamilit | Frontend |

---

## PARTE 2: ORGANIZACIÓN DE TRADING PLATFORM

### 2.1 Estado Actual

```
trading-platform/apps/
├── backend/          # Express.js - 55 archivos, 15K+ líneas ✅
├── frontend/         # React 18 - 49 archivos ✅
├── ml-engine/        # Python FastAPI - 27 archivos ✅
├── llm-agent/        # Python FastAPI - 18 archivos ✅
├── trading-agents/   # Python FastAPI - 19 archivos ✅
├── data-service/     # Python FastAPI - 8 archivos ⚠️ INCOMPLETO
└── database/         # PostgreSQL - 98 archivos DDL ✅
```

### 2.2 Problemas Identificados

1. **data-service incompleto** - Solo 20% implementado
2. **Sin tests** - Framework configurado pero sin tests reales
3. **URLs hardcodeadas** entre servicios
4. **Sin retry/circuit breaker** en comunicación inter-servicios
5. **Documentación API incompleta**

### 2.3 Reorganización Propuesta

```
trading-platform/
├── apps/
│   ├── backend/                 # API principal (mantener)
│   │   └── src/
│   │       ├── modules/
│   │       │   ├── auth/        # ← Usar @core/auth adapter
│   │       │   ├── users/
│   │       │   ├── trading/
│   │       │   ├── portfolio/
│   │       │   ├── education/
│   │       │   ├── payments/    # ← Usar @core/payments
│   │       │   └── admin/
│   │       └── shared/
│   │           ├── clients/     # Clientes para otros servicios
│   │           ├── middleware/
│   │           └── utils/       # ← Usar @core/utils
│   │
│   ├── frontend/                # UI (mantener)
│   │
│   ├── ml-services/             # RENOMBRAR: Agrupa ML
│   │   ├── prediction-engine/   # Ex ml-engine
│   │   └── signal-generator/    # Nuevo: extraer de ml-engine
│   │
│   ├── ai-services/             # RENOMBRAR: Agrupa IA
│   │   ├── copilot/             # Ex llm-agent
│   │   └── market-analyst/      # Nuevo: análisis de mercado
│   │
│   ├── trading-services/        # RENOMBRAR: Agrupa trading
│   │   ├── agents/              # Ex trading-agents
│   │   └── order-executor/      # Nuevo: ejecución de órdenes
│   │
│   ├── data-services/           # COMPLETAR
│   │   ├── market-data/         # Datos de mercado en tiempo real
│   │   ├── historical/          # Datos históricos
│   │   └── providers/           # Integraciones (Binance, etc.)
│   │
│   └── database/                # Mantener
│
├── packages/                    # NUEVO: Código compartido interno
│   ├── sdk-typescript/          # Cliente para frontend/backend
│   ├── sdk-python/              # Cliente para servicios Python
│   ├── config/                  # Configuración centralizada
│   └── types/                   # Tipos compartidos
│
└── docker/
    ├── docker-compose.yml
    └── docker-compose.dev.yml
```

### 2.4 Módulos por Funcionalidad

| Funcionalidad | App | Responsabilidad |
|---------------|-----|-----------------|
| **Autenticación** | backend | Login, OAuth, JWT, 2FA |
| **Usuarios** | backend | Perfiles, preferencias |
| **Trading** | backend + trading-services | Watchlists, órdenes, posiciones |
| **Portafolio** | backend | Gestión de inversiones |
| **Educación** | backend + frontend | Cursos, lecciones, certificados |
| **Pagos** | backend | Stripe, suscripciones |
| **Predicciones** | ml-services | Modelos ML, señales |
| **Copiloto IA** | ai-services | Chat, análisis, recomendaciones |
| **Agentes** | trading-services | Ejecución automática |
| **Datos** | data-services | Market data, históricos |

### 2.5 Tareas Pendientes Trading Platform

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Completar data-service | P0 | Alto |
| Agregar tests unitarios | P0 | Alto |
| Implementar retry/circuit breaker | P1 | Medio |
| Crear SDK compartido | P1 | Medio |
| Documentar APIs (OpenAPI) | P1 | Medio |
| Implementar métricas Prometheus | P2 | Bajo |
| Centralizar logging | P2 | Bajo |
| Migrar auth a @core/auth | P2 | Medio |

---

## PARTE 3: ORGANIZACIÓN DE ERP-SUITE

### 3.1 Estado Actual

```
erp-suite/apps/
├── erp-core/                    # Base 60% ✅
│   ├── backend/                 # 14 módulos, 100+ archivos
│   ├── frontend/                # 165 archivos
│   └── database/                # 12 schemas, 130+ tablas
│
├── verticales/
│   ├── construccion/            # 35% - DDL parcial ⚠️
│   ├── vidrio-templado/         # 25% - Solo docs 📋
│   ├── mecanicas-diesel/        # 95% - DDL completo ✅
│   ├── retail/                  # 25% - Solo docs 📋
│   └── clinicas/                # 25% - Solo docs 📋
│
├── products/
│   ├── pos-micro/               # 80% MVP ✅
│   └── erp-basico/              # 0% ❌
│
├── saas/                        # Billing layer
└── shared-libs/                 # VACÍO ❌
```

### 3.2 Problemas Identificados

1. **shared-libs vacío** - Sin código compartido entre verticales
2. **Verticales sin código** - Solo documentación en la mayoría
3. **Inconsistencia de stack** - Express en core, NestJS en POS
4. **Sin herencia clara** - Verticales no extienden erp-core

### 3.3 Arquitectura de Herencia Propuesta

```
                    ┌─────────────────┐
                    │   @core/        │
                    │   (workspace)   │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   erp-core      │
                    │   (60-70%)      │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼───────┐   ┌───────▼───────┐   ┌───────▼───────┐
│  Construcción │   │    Retail     │   │   Clínicas    │
│  (+30% custom)│   │  (+40% custom)│   │  (+50% custom)│
└───────────────┘   └───────────────┘   └───────────────┘
```

### 3.4 Reorganización Propuesta

```
erp-suite/
├── apps/
│   ├── erp-core/                    # BASE GENÉRICA
│   │   ├── backend/
│   │   │   └── src/
│   │   │       ├── modules/
│   │   │       │   ├── auth/        # Autenticación base
│   │   │       │   ├── core/        # Catálogos maestros
│   │   │       │   ├── partners/    # Clientes/Proveedores
│   │   │       │   ├── inventory/   # Inventario base
│   │   │       │   ├── sales/       # Ventas base
│   │   │       │   ├── purchases/   # Compras base
│   │   │       │   ├── financial/   # Contabilidad base
│   │   │       │   ├── hr/          # RRHH base
│   │   │       │   ├── projects/    # Proyectos base
│   │   │       │   ├── crm/         # CRM base
│   │   │       │   └── system/      # Sistema
│   │   │       └── shared/          # Compartido dentro de core
│   │   ├── frontend/
│   │   └── database/
│   │
│   ├── verticales/
│   │   ├── construccion/
│   │   │   ├── backend/
│   │   │   │   └── src/
│   │   │   │       ├── modules/
│   │   │   │       │   ├── construction/  # Proyectos de obra
│   │   │   │       │   ├── hse/           # Seguridad e higiene
│   │   │   │       │   ├── budgets/       # Presupuestos
│   │   │   │       │   ├── progress/      # Avances de obra
│   │   │   │       │   └── infonavit/     # Integración INFONAVIT
│   │   │   │       └── extends/           # EXTENSIONES de erp-core
│   │   │   │           ├── hr.extension.ts
│   │   │   │           └── projects.extension.ts
│   │   │   ├── frontend/
│   │   │   └── database/
│   │   │
│   │   ├── mecanicas-diesel/
│   │   │   ├── backend/
│   │   │   │   └── src/modules/
│   │   │   │       ├── service-orders/    # Órdenes de servicio
│   │   │   │       ├── diagnostics/       # Diagnósticos
│   │   │   │       ├── vehicles/          # Vehículos
│   │   │   │       └── parts/             # Refacciones
│   │   │   └── ...
│   │   │
│   │   ├── vidrio-templado/
│   │   │   └── ... (por definir)
│   │   │
│   │   ├── retail/
│   │   │   ├── backend/
│   │   │   │   └── src/modules/
│   │   │   │       ├── pos/               # Punto de venta
│   │   │   │       ├── cash/              # Caja
│   │   │   │       ├── pricing/           # Precios
│   │   │   │       └── ecommerce/         # E-commerce
│   │   │   └── ...
│   │   │
│   │   └── clinicas/
│   │       ├── backend/
│   │       │   └── src/modules/
│   │       │       ├── patients/          # Pacientes
│   │       │       ├── appointments/      # Citas
│   │       │       ├── consultations/     # Consultas
│   │       │       ├── prescriptions/     # Recetas
│   │       │       ├── laboratory/        # Laboratorio
│   │       │       └── pharmacy/          # Farmacia
│   │       └── ...
│   │
│   └── products/
│       ├── pos-micro/                     # POS standalone
│       └── erp-basico/                    # ERP simplificado
│
├── packages/                              # NUEVO: Shared interno
│   ├── erp-sdk/                           # SDK para verticales
│   ├── erp-types/                         # Tipos compartidos
│   ├── erp-components/                    # Componentes UI
│   └── erp-utils/                         # Utilidades
│
└── docker/
```

### 3.5 Módulos por Vertical

| Módulo | Core | Construcción | Mecánicas | Retail | Clínicas |
|--------|:----:|:------------:|:---------:|:------:|:--------:|
| Auth | ✅ | Hereda | Hereda | Hereda | Hereda |
| Partners | ✅ | Hereda | Hereda | Hereda | Hereda |
| Inventory | ✅ | Extiende | Extiende | Extiende | Extiende |
| Sales | ✅ | - | - | Extiende | - |
| Purchases | ✅ | Extiende | Extiende | Extiende | Extiende |
| Financial | ✅ | Extiende | Hereda | Hereda | Hereda |
| HR | ✅ | Extiende | Hereda | Hereda | Hereda |
| Projects | ✅ | Extiende | - | - | - |
| Construction | - | ✅ | - | - | - |
| HSE | - | ✅ | - | - | - |
| Service Orders | - | - | ✅ | - | - |
| Diagnostics | - | - | ✅ | - | - |
| POS | - | - | - | ✅ | - |
| Cash | - | - | - | ✅ | - |
| Patients | - | - | - | - | ✅ |
| Appointments | - | - | - | - | ✅ |
| Medical Records | - | - | - | - | ✅ |

### 3.6 Tareas Pendientes ERP-Suite

| Tarea | Vertical | Prioridad | Esfuerzo |
|-------|----------|-----------|----------|
| Implementar backend Mecánicas | mecanicas-diesel | P0 | Alto |
| Completar backend Construcción | construccion | P0 | Alto |
| Crear DDL Retail | retail | P1 | Medio |
| Crear DDL Clínicas | clinicas | P1 | Medio |
| Crear DDL Vidrio Templado | vidrio-templado | P2 | Medio |
| Crear packages/erp-sdk | global | P1 | Alto |
| Implementar herencia de módulos | global | P1 | Alto |
| Poblar shared-libs | global | P1 | Medio |

---

## PARTE 4: PATRONES A REPLICAR DE GAMILIT

### 4.1 Sistema SSOT (Single Source of Truth)

**Qué es:** Constantes centralizadas que son la única fuente de verdad.

**Archivos a crear en core/constants/:**

```typescript
// core/constants/database.constants.ts
export const DB_SCHEMAS = {
  AUTH: 'auth_management',
  CORE: 'core',
  // ... universales
};

export const getFullTableName = (schema: string, table: string) =>
  `${schema}.${table}`;
```

```typescript
// core/constants/api.constants.ts
export const API_VERSION = 'v1';
export const API_BASE = `/api/${API_VERSION}`;

export const buildApiUrl = (route: string) => `${API_BASE}${route}`;
```

### 4.2 Sincronización Backend-Frontend

**Script:** `sync-enums.ts`

```bash
# Copia enums de backend a frontend
cp backend/src/shared/constants/enums.ts frontend/src/shared/constants/enums.ts
```

**Agregar a package.json:**
```json
{
  "scripts": {
    "sync:enums": "ts-node scripts/sync-enums.ts",
    "postinstall": "npm run sync:enums"
  }
}
```

### 4.3 Estructura de Módulos Backend

```
module/
├── module.module.ts       # Decorador @Module
├── module.controller.ts   # Endpoints
├── module.service.ts      # Lógica de negocio
├── dto/                   # Data Transfer Objects
│   ├── create-x.dto.ts
│   ├── update-x.dto.ts
│   └── query-x.dto.ts
├── entities/              # Entidades TypeORM
│   └── x.entity.ts
└── __tests__/             # Tests
    ├── module.service.spec.ts
    └── module.controller.spec.ts
```

### 4.4 Estructura de Features Frontend

```
features/
└── gamification/
    ├── components/        # Componentes del feature
    ├── hooks/             # Hooks del feature
    ├── services/          # API calls
    ├── types/             # Tipos
    └── utils/             # Utilidades
```

### 4.5 Shared Components (Atomic Design)

```
shared/components/
├── atoms/                 # Button, Input, Label
├── molecules/             # FormField, Card, Alert
├── organisms/             # DataTable, Modal, Sidebar
└── templates/             # Layouts completos
```

---

## PARTE 5: ACCIONES INMEDIATAS

### Fase 1: Core Modules (Semana 1-2)

1. **Poblar `core/modules/utils/`**
   - Copiar de `/projects/gamilit/apps/backend/src/shared/utils/`
   - Adaptar para ser framework-agnostic

2. **Crear `core/constants/`**
   - Copiar enums universales de Gamilit
   - Crear regex patterns

3. **Crear `core/types/`**
   - Tipos de API response
   - Tipos de paginación
   - Tipos de auth

4. **Poblar `core/catalog/_reference/`**
   - Copiar código de referencia de Gamilit para auth, notifications, etc.

### Fase 2: Trading Platform (Semana 2-4)

1. **Completar data-service**
   - Implementar feeds de datos de mercado
   - Integrar con Binance/otros providers

2. **Crear packages/sdk-typescript**
   - Cliente HTTP compartido
   - Tipos de API

3. **Agregar tests básicos**
   - Tests unitarios para servicios críticos

### Fase 3: ERP-Suite (Semana 3-6)

1. **Implementar backend Mecánicas Diesel**
   - Basarse en DDL existente (100% completo)
   - Crear services y controllers

2. **Completar backend Construcción**
   - Implementar services para módulos existentes

3. **Crear packages/erp-sdk**
   - SDK para que verticales extiendan erp-core

### Fase 4: Estandarización (Semana 6-8)

1. **Decisión de framework**
   - Opción A: Migrar todo a NestJS
   - Opción B: Mantener Express, crear adapters
   - **Recomendación:** Opción B para minimizar reescritura

2. **Implementar patrones SSOT en todos los proyectos**

3. **Configurar CI/CD con validación de contratos**

---

## PARTE 6: MATRIZ DE RESPONSABILIDADES

### Por Proyecto

| Proyecto | Responsable | Stack | Prioridad |
|----------|-------------|-------|-----------|
| core/modules | Arquitecto | Agnostic | P0 |
| Gamilit | Dev Team A | NestJS | Mantenimiento |
| Trading Platform | Dev Team B | Express/Python | P1 |
| ERP-Suite/Core | Dev Team C | Express | P1 |
| ERP/Verticales | Dev Teams | Express | P2 |

### Por Módulo Core

| Módulo | Propietario | Consumidores |
|--------|-------------|--------------|
| utils | Core Team | Todos |
| auth | Core Team | Backend |
| database | Core Team | Backend, DDL |
| api | Core Team | Backend |
| notifications | Core Team | Backend |
| payments | Trading Team | Trading, ERP |
| frontend | Core Team | Frontend |

---

## PARTE 7: MÉTRICAS DE ÉXITO

### Corto Plazo (1 mes)

- [ ] `core/modules/utils/` implementado y en uso
- [ ] `core/constants/` creado con enums universales
- [ ] data-service de Trading Platform funcional
- [ ] Backend de Mecánicas Diesel iniciado

### Mediano Plazo (3 meses)

- [ ] 70% de código duplicado eliminado
- [ ] Todos los proyectos usando `@core/utils`
- [ ] DDL completo para todas las verticales ERP
- [ ] Tests con cobertura >50% en servicios críticos

### Largo Plazo (6 meses)

- [ ] Arquitectura de herencia ERP funcionando
- [ ] CI/CD con validación de contratos API
- [ ] Documentación completa (OpenAPI) para todas las APIs
- [ ] Todos los proyectos con estructura consistente

---

## ANEXO A: DECISIONES ARQUITECTÓNICAS

### ADR-001: Mantener Múltiples Frameworks

**Contexto:** Tenemos NestJS (Gamilit) y Express (Trading, ERP).

**Decisión:** Mantener ambos frameworks, crear adapters en core/.

**Razón:**
- Reescribir Gamilit a Express sería costoso
- NestJS tiene ventajas para proyectos modulares grandes
- Adapters permiten reutilización de lógica

### ADR-002: Monorepo con Packages Compartidos

**Contexto:** Código duplicado entre proyectos.

**Decisión:** Usar estructura de packages internos.

**Razón:**
- npm workspaces para gestionar dependencias
- Cada proyecto puede importar `@core/utils`, `@erp/sdk`
- Versionado independiente si es necesario

### ADR-003: SSOT para Constantes

**Contexto:** Constantes hardcodeadas en múltiples lugares.

**Decisión:** Centralizar en `core/constants/` con sincronización automática.

**Razón:**
- Evita inconsistencias
- Facilita refactoring
- Validación automática en CI

---

## ANEXO B: ARCHIVOS CLAVE

```
# Gamilit (Referencia)
/projects/gamilit/apps/backend/src/shared/constants/enums.constants.ts
/projects/gamilit/apps/backend/src/shared/constants/database.constants.ts
/projects/gamilit/apps/backend/src/shared/constants/routes.constants.ts
/projects/gamilit/apps/backend/src/shared/utils/

# Trading Platform
/projects/trading-platform/apps/backend/src/
/projects/trading-platform/apps/ml-engine/src/
/projects/trading-platform/apps/database/ddl/

# ERP Suite
/projects/erp-suite/apps/erp-core/backend/src/modules/
/projects/erp-suite/apps/erp-core/database/ddl/
/projects/erp-suite/apps/verticales/mecanicas-diesel/database/init/

# Core (a poblar)
/core/modules/
/core/constants/
/core/types/
/core/catalog/*/reference/
```

---

**Fin del documento**