workspace/SETUP.md

Setup del Workspace

Esta guía detalla cómo configurar el workspace para desarrollo.

Requisitos Previos

Software Base

Herramienta	Versión Mínima	Propósito
Git	2.30+	Control de versiones
Node.js	18.x LTS o 20.x	Runtime JavaScript/TypeScript
npm	9.x+	Gestor de paquetes Node
Python	3.10+	Backend Python (Odoo, ML)
PostgreSQL	14+	Base de datos
Docker	24.x+	Contenedores (opcional)

Herramientas Opcionales

Herramienta	Propósito
Miniconda/Conda	Gestión de ambientes Python
pnpm	Alternativa a npm (más rápido)
Docker Compose	Orquestación de contenedores
kubectl	Kubernetes CLI

Clonar el Workspace

Clon Básico (sin submodules)

git clone https://github.com/rckrdmrd/workspace.git
cd workspace

Clon con Submodules (incluye Odoo)

El workspace incluye Odoo como submodule. Para clonarlo completo:

# Clonar con submodules (recomendado)
git clone --recurse-submodules https://github.com/rckrdmrd/workspace.git
cd workspace

# Si ya clonaste sin --recurse-submodules
git submodule update --init --recursive

# Para un clone más rápido (sin historial completo de submodules)
git submodule update --init --depth 1

Estructura del Workspace

workspace/
├── core/                    # Núcleo reutilizable
│   ├── catalog/             # Catálogo de patrones
│   ├── modules/             # Módulos compartidos
│   ├── orchestration/       # Sistema de agentes
│   └── standards/           # Estándares técnicos
│
├── projects/                # Proyectos activos
│   ├── erp-suite/           # Suite ERP empresarial
│   ├── gamilit/             # Plataforma EdTech
│   ├── trading-platform/    # Plataforma Trading
│   ├── betting-analytics/   # Analytics Apuestas
│   └── inmobiliaria-analytics/
│
├── customers/               # Implementaciones por cliente
│   └── template/            # Template para nuevos clientes
│
├── knowledge-base/          # Base de conocimiento
│   ├── patterns/            # Patrones de diseño
│   ├── guides/              # Guías de integración
│   ├── lessons-learned/     # Lecciones aprendidas
│   └── reference/           # Código de referencia
│       └── odoo/            # Odoo 18.0 (submodule)
│
├── devtools/                # Herramientas de desarrollo
│   ├── scripts/             # Scripts de automatización
│   ├── templates/           # Templates de proyectos
│   └── docker/              # Configuraciones Docker
│
├── orchestration/           # Orquestación del workspace
│   ├── WORKSPACE-INDEX.md
│   └── WORKSPACE-STATUS.md
│
└── workspaces/              # Workspaces efímeros (temporal)

Setup por Proyecto

Gamilit (EdTech Platform)

cd projects/gamilit

# Instalar dependencias del monorepo
npm install

# Backend
cd apps/backend
npm install
cp .env.example .env
# Configurar variables en .env

# Frontend
cd ../frontend
npm install
cp .env.example .env

# Volver a raíz y ejecutar
cd ../..
npm run dev

Stack: NestJS + React + PostgreSQL + TypeORM

Trading Platform

cd projects/trading-platform

# Backend
cd apps/backend
npm install
cp .env.example .env

# Frontend
cd ../frontend
npm install
cp .env.example .env

# ML Engine (Python)
cd ../ml-engine
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows
pip install -r requirements.txt

Stack: Node.js + React + Python (ML) + PostgreSQL

ERP Suite - Verticales

cd projects/erp-suite/apps/verticales/construccion

# Backend
cd backend
npm install
cp .env.example .env

# Frontend
cd ../frontend
npm install

# Base de datos
cd ../database
# Ejecutar DDL en PostgreSQL
psql -U postgres -f ddl/001-schema.sql

Stack: NestJS + React + PostgreSQL

Setup con Conda (Proyectos Python)

Crear Ambiente Base

# Crear ambiente para el workspace
conda create -n workspace python=3.11
conda activate workspace

# Instalar herramientas base
pip install poetry black flake8 pytest

Ambiente para ML/Trading

conda create -n trading-ml python=3.11
conda activate trading-ml

cd projects/trading-platform/apps/ml-engine
pip install -r requirements.txt

Ambiente para Odoo

conda create -n odoo18 python=3.10
conda activate odoo18

cd knowledge-base/reference/odoo/odoo-18.0
pip install -r requirements.txt

# Dependencias adicionales de Odoo
pip install psycopg2-binary watchdog

Base de Datos

PostgreSQL Local

# Crear base de datos por proyecto
createdb gamilit_dev
createdb trading_dev
createdb erp_construccion_dev

# O usar Docker
docker run -d \
  --name postgres-workspace \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  postgres:14

Configuración .env Típica

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=proyecto_dev
DB_USER=postgres
DB_PASSWORD=postgres

# App
NODE_ENV=development
PORT=3000

# JWT (generar uno nuevo para producción)
JWT_SECRET=dev-secret-cambiar-en-produccion

Docker (Opcional)

Levantar Servicios Comunes

cd devtools/docker

# Base de datos + Redis
docker-compose -f docker-compose.common.yml up -d

# Verificar
docker ps

Proyecto Específico

cd projects/gamilit
docker-compose up -d

Verificar Instalación

Script de Verificación

# Ejecutar desde la raíz del workspace
./devtools/scripts/validate-structure.sh

Verificación Manual

# Git
git --version
git status
git submodule status

# Node.js
node --version
npm --version

# Python
python --version
pip --version

# PostgreSQL
psql --version

# Docker (opcional)
docker --version
docker-compose --version

Problemas Comunes

Submodules no inicializados

# Error: knowledge-base/reference/odoo está vacío
git submodule update --init --recursive

Permisos de scripts

# Error: Permission denied
chmod +x devtools/scripts/*.sh

Puerto en uso

# Error: EADDRINUSE
# Encontrar proceso usando el puerto
lsof -i :3000
# Matar proceso
kill -9 <PID>

node_modules corrupto

# Limpiar e reinstalar
rm -rf node_modules package-lock.json
npm install

Python ambiente incorrecto

# Verificar ambiente activo
which python
conda info --envs

# Activar ambiente correcto
conda activate workspace

IDEs Recomendados

VS Code

Extensiones recomendadas:

• ESLint
• Prettier
• TypeScript
• Python
• GitLens
• Docker

Settings compartidos en .vscode/settings.json de cada proyecto.

JetBrains (WebStorm/PyCharm)

• Abrir cada proyecto como proyecto separado
• Configurar Node.js interpreter por proyecto
• Configurar Python interpreter por proyecto

Flujo de Trabajo Diario

# 1. Actualizar workspace
cd workspace
git pull
git submodule update --remote --merge

# 2. Ir al proyecto
cd projects/gamilit

# 3. Actualizar dependencias (si hay cambios en package.json)
npm install

# 4. Iniciar desarrollo
npm run dev

# 5. Antes de commit
npm run lint
npm run test

Contacto y Soporte

• Repositorio: https://github.com/rckrdmrd/workspace
• Documentación: Ver /docs en cada proyecto
• Orquestación: Ver /orchestration para guías de agentes