# Esquema de Puertos - ERP Suite

**Version:** 1.0.0
**Fecha:** 2025-12-06
**Proposito:** Asignacion centralizada de puertos para evitar conflictos entre proyectos

---

## Principios de Asignacion

1. **Rango base por proyecto:** Cada proyecto tiene un offset de 100 puertos
2. **Consistencia interna:** Misma estructura de servicios en cada proyecto
3. **Evitar puertos reservados:** No usar puertos < 1024
4. **Documentar cambios:** Actualizar este archivo al agregar proyectos

---

## Mapa de Puertos por Proyecto

### Rango Base Asignado

| Proyecto | Rango Base | Backend | Frontend | Database | Redis | MinIO | pgAdmin |
|----------|------------|---------|----------|----------|-------|-------|---------|
| **erp-core** | 3000 | 3000 | 5173 | 5432 | 6379 | 9000/9001 | 5050 |
| **construccion** | 3100 | 3100 | 5174 | 5433 | 6380 | 9100/9101 | 5051 |
| **vidrio-templado** | 3200 | 3200 | 5175 | 5434 | 6381 | 9200/9201 | 5052 |
| **mecanicas-diesel** | 3300 | 3300 | 5176 | 5435 | 6382 | 9300/9301 | 5053 |
| **retail** | 3400 | 3400 | 5177 | 5436 | 6383 | 9400/9401 | 5054 |
| **clinicas** | 3500 | 3500 | 5178 | 5437 | 6384 | 9500/9501 | 5055 |
| **trading-platform** | 3600 | 3600 | 5179 | 5438 | 6385 | 9600/9601 | 5056 |
| **orbiquantia** | 3700 | 3700 | 5180 | 5439 | 6386 | 9700/9701 | 5057 |

---

## Detalle por Proyecto

### ERP Core (Base)

```yaml
proyecto: erp-core
rango_base: 3000
servicios:
  backend:
    puerto: 3000
    protocolo: HTTP
    descripcion: API REST principal

  frontend_web:
    puerto: 5173
    protocolo: HTTP
    descripcion: Vite dev server (React)

  database:
    puerto: 5432
    protocolo: TCP
    descripcion: PostgreSQL 15+
    container: erp_core_db

  redis:
    puerto: 6379
    protocolo: TCP
    descripcion: Cache y colas
    container: erp_core_redis

  minio_api:
    puerto: 9000
    protocolo: HTTP
    descripcion: S3-compatible storage API

  minio_console:
    puerto: 9001
    protocolo: HTTP
    descripcion: MinIO Web Console

  pgadmin:
    puerto: 5050
    protocolo: HTTP
    descripcion: Database admin UI (opcional)
```

### Construccion (Vertical)

```yaml
proyecto: construccion
rango_base: 3100
servicios:
  backend:
    puerto: 3100
    protocolo: HTTP
    descripcion: API REST construccion

  frontend_web:
    puerto: 5174
    protocolo: HTTP
    descripcion: Vite dev server (React)

  database:
    puerto: 5433
    protocolo: TCP
    descripcion: PostgreSQL 15+ con PostGIS
    container: erp_construccion_db

  redis:
    puerto: 6380
    protocolo: TCP
    descripcion: Cache y colas
    container: erp_construccion_redis

  minio_api:
    puerto: 9100
    protocolo: HTTP
    descripcion: S3-compatible storage API

  minio_console:
    puerto: 9101
    protocolo: HTTP
    descripcion: MinIO Web Console

  pgadmin:
    puerto: 5051
    protocolo: HTTP
    descripcion: Database admin UI (opcional)
```

---

## Variables de Entorno Estandar

### Template .env para cada proyecto

```bash
# ===========================================
# PROYECTO: {NOMBRE_PROYECTO}
# RANGO BASE: {RANGO}
# ===========================================

# Application
NODE_ENV=development
APP_PORT={BACKEND_PORT}
APP_HOST=0.0.0.0
API_VERSION=v1
API_PREFIX=/api/v1

# Database
DB_HOST=localhost
DB_PORT={DB_PORT}
DB_NAME={db_name}
DB_USER={db_user}
DB_PASSWORD={db_password}
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}

# Redis
REDIS_HOST=localhost
REDIS_PORT={REDIS_PORT}
REDIS_URL=redis://${REDIS_HOST}:${REDIS_PORT}

# MinIO (S3)
S3_ENDPOINT=http://localhost:{MINIO_API_PORT}
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET={bucket_name}

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRATION=24h
JWT_REFRESH_EXPIRATION=7d

# CORS
CORS_ORIGIN=http://localhost:{FRONTEND_PORT}
CORS_CREDENTIALS=true

# Frontend (para Vite)
VITE_API_URL=http://localhost:${APP_PORT}
VITE_WS_URL=ws://localhost:${APP_PORT}
```

---

## Valores Especificos por Proyecto

### erp-core

```bash
APP_PORT=3000
DB_PORT=5432
DB_NAME=erp_core
REDIS_PORT=6379
S3_ENDPOINT=http://localhost:9000
CORS_ORIGIN=http://localhost:5173
VITE_API_URL=http://localhost:3000
```

### construccion

```bash
APP_PORT=3100
DB_PORT=5433
DB_NAME=erp_construccion
REDIS_PORT=6380
S3_ENDPOINT=http://localhost:9100
CORS_ORIGIN=http://localhost:5174
VITE_API_URL=http://localhost:3100
```

---

## Docker Compose Networking

### Red compartida vs aislada

**Opcion 1: Redes aisladas (RECOMENDADO para desarrollo)**
- Cada proyecto tiene su propia red
- No hay conflictos de nombres de contenedor
- Facilita pruebas independientes

```yaml
# Ejemplo para construccion
networks:
  erp_construccion_network:
    driver: bridge
    name: erp_construccion_network
```

**Opcion 2: Red compartida (para integracion)**
- Todos los proyectos en una red
- Comunicacion directa entre servicios
- Requiere nombres de contenedor unicos

```yaml
networks:
  erp_suite_network:
    external: true
    name: erp_suite_network
```

---

## Validacion de Puertos

### Script de verificacion

```bash
#!/bin/bash
# validate-ports.sh
# Verifica que los puertos asignados esten disponibles

PORTS=(
  3000 3100 3200 3300 3400 3500 3600 3700  # Backend
  5173 5174 5175 5176 5177 5178 5179 5180  # Frontend
  5432 5433 5434 5435 5436 5437 5438 5439  # Database
  6379 6380 6381 6382 6383 6384 6385 6386  # Redis
)

echo "Verificando disponibilidad de puertos..."

for port in "${PORTS[@]}"; do
  if lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
    echo "OCUPADO: Puerto $port en uso"
  else
    echo "OK: Puerto $port disponible"
  fi
done
```

---

## Reglas de Asignacion

### Al agregar nuevo proyecto

1. Asignar siguiente rango base disponible (incremento de 100)
2. Actualizar tabla de puertos en este documento
3. Crear docker-compose.yml con puertos correctos
4. Crear .env.example con variables correctas
5. Ejecutar script de validacion

### Puertos reservados (NO USAR)

| Puerto | Razon |
|--------|-------|
| 22 | SSH |
| 80 | HTTP standard |
| 443 | HTTPS standard |
| 3306 | MySQL (evitar confusion) |
| 5000 | Flask default |
| 8080 | Tomcat/proxies |
| 8443 | HTTPS alternativo |

---

## Troubleshooting

### Puerto ocupado

```bash
# Encontrar proceso usando puerto
lsof -i :3000

# Matar proceso por PID
kill -9 <PID>

# O usando fuser
fuser -k 3000/tcp
```

### Verificar contenedores Docker

```bash
# Ver puertos mapeados
docker ps --format "table {{.Names}}\t{{.Ports}}"

# Detener todos los contenedores de un proyecto
docker-compose -f docker-compose.yml down
```

---

## Changelog

### v1.0.0 (2025-12-06)
- Definicion inicial de esquema de puertos
- Asignacion para 8 proyectos
- Templates de .env y docker-compose
- Script de validacion

---

**Mantenido por:** DevEnv-Agent
**Ultima actualizacion:** 2025-12-06
