onboarding-dev

name	onboarding-dev
description	Onboarding para desarrolladores nuevos del proyecto Cobertura Docker. Use para explicar cómo levantar el proyecto, variables de entorno, estructura del repo, y flujo local.

Onboarding Desarrollador

Requisitos

• Docker instalado y corriendo
• Oracle Instant Client (copiado a docker/oracle/instantclient/)
• Node.js 20+ (para desarrollo local sin Docker)

Setup

# 1. Copiar archivos sensibles
cp .env.example .env
# Editar .env con valores reales

# 2. Oracle Instant Client
mkdir -p docker/oracle/instantclient
cp -r /opt/oracle/instantclient_21_11/* docker/oracle/instantclient/

# 3. Crear carpetas
mkdir -p docker-data/output docker-data/uploads

# 4. Levantar
docker compose up --build -d

Variables de entorno (.env)

ORACLE_USER=DIGITALIZACION
ORACLE_PASSWORD=DIGITALIZACION
ORACLE_CONNECT_STRING=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=172.16.60.21)(PORT=1521))(CONNECT_DATA=(SID=PRDSGH2)))
COBERTURA_OUTPUT_DIR=/app/output
LOCAL_UID=$(id -u)
LOCAL_GID=$(id -g)

Estructura del repo

.
├── server/app.js          # API + UI
├── scripts/
│   ├── batch_fetch_json.js   # Fase 1: Oracle + portal → JSON
│   ├── batch_render_pdf.js   # Fase 2: JSON → PDF
│   ├── query_records.js      # Consulta Oracle directo
│   ├── query_live.js         # Consulta portal MSP
│   └── generate_pdf.js       # Render PDF
├── web/batch/public/     # UI web
├── docker/                # Oracle Instant Client
└── docker-data/          # Archivos generados (fuera del contenedor)

Comandos útiles

# Levantar
docker compose up -d

# Ver logs
docker compose logs -f

# Ver estado
docker compose ps

# Detener
docker compose down

# Inside container
docker exec -it cobertura_msp sh

# Test local (sin Docker)
npm start

Flujo batch

1. /api/query-records - Consulta Oracle (lista registros)
2. /api/fetch-json - Fase 1: consulta portal, guarda JSON
3. /api/render-pdf - Fase 2: lee JSON, genera PDF
4. /output/ - Archivos generados

Errores comunes

1. EACCES en /app/output - Verificar LOCAL_UID/LOCAL_GID en .env
2. Oracle DPI-1047 - Instant Client no encontrado o mal montado
3. Portal MSP 503 - Rate limiting, esperar entre consultas