Montar el entorno de desarrollo¶

Esta guía te lleva de una máquina limpia a los tres proyectos —backend, landing y gestor— corriendo en local con hot reload, campaña de prueba cargada y un login funcionando en el gestor. Calculá unos 20-30 minutos si ya tenés el software base instalado.

El Sistema de Premios es un único backend Java que sirve dos frontends: la landing (donde el cliente final escanea su ticket y participa) y el gestor (el panel donde el equipo de Caracol administra la campaña). En desarrollo corrés los tres procesos por separado para tener hot reload; en producción, el backend empaqueta y sirve a los otros dos (ver instalación en servidor).

Orden recomendado

Arrancá siempre por la base de datos y el backend. La landing y el gestor son clientes del backend — sin él levantado, ninguno de los dos tiene con qué hablar.

Prerrequisitos¶

Necesitás	Versión	Notas
JDK	21	El bytecode del jar apunta a Java 17, así que cualquier JDK ≥17 corre el proceso — pero usá 21 para que coincida con lo que usa el equipo.
Maven	cualquiera reciente	Sin wrapper en el repo: `mvn` tiene que estar en el `PATH`.
SQL Server	2022	Con una base vacía llamada `SistemaPremios` ya creada.
Node	20	Lo pide el `frontend-maven-plugin` del build `full`; usalo también para correr landing y gestor sueltos.

1. Crear la base de datos¶

Necesitás una base vacía llamada SistemaPremios en tu instancia de SQL Server. Flyway se encarga de crear el esquema entero la primera vez que arranca el backend — vos solo creás el contenedor vacío.

CREATE DATABASE SistemaPremios;

2. Clonar el repo y preparar las variables de entorno¶

git clone <url-del-repo> SistemaPremios
cd SistemaPremios\backend

El repo trae backend/dev-env.local.ps1 (gitignoreado) con las variables SP_* que el backend necesita en dev. Antes de arrancar nada, cargalas en tu sesión de PowerShell:

. .\dev-env.local.ps1

Sin SP_GESTOR_PASSWORD el backend no arranca

No es un default silencioso: si esa variable falta, el arranque falla rápido y explícito. Si el script dev-env.local.ps1 no existe todavía en tu clon, armate uno con al menos estas variables (con tus propios valores, nunca los reales de producción):

$env:SP_DB_PASSWORD = "CAMBIAR"
$env:SP_MASTER_KEY = "CAMBIAR"          # base64 de 32 bytes
$env:SP_GESTOR_USER = "admin"
$env:SP_GESTOR_PASSWORD = "CAMBIAR"
$env:SP_MODO_PRUEBA = "true"

3. Arrancar el backend con hot reload¶

Parado en backend/:

mvn spring-boot:run

Esto levanta el backend en http://localhost:8080, corre las migraciones de Flyway y queda escuchando con reinicio automático ante cambios de código (spring-boot-devtools). La config operativa la toma de backend/config/application.yml, el archivo versionado de referencia (ver ADR-029 y el detalle completo de cada variable en Configuración).

Verificá que levantó bien:

curl.exe http://localhost:8080/api/salud

Debería responder {"estado":"ok","base_datos":"ok"}.

4. Arrancar la landing¶

En otra terminal:

cd SistemaPremios\landing
npm install
npm run dev

Queda en http://localhost:5173. El vite.config.ts de la landing ya trae un proxy de /api, /bases y /branding hacia http://localhost:8080, así que no hay CORS que configurar: la landing en dev habla con tu backend local como si fuera same-origin.

5. Arrancar el gestor¶

En una tercera terminal:

cd SistemaPremios\gestor
npm install
npm run dev

Queda en http://localhost:5174, sirviendo bajo la ruta /gestor/ (igual que en producción, donde el jar lo sirve bajo esa misma ruta dentro del mismo puerto).

6. Cargar el seed mínimo¶

Con el backend abajo (Ctrl+C), arrancalo una vez apuntando al seed de ejemplo:

mvn spring-boot:run "-Dspring-boot.run.arguments=--sp.seed.archivo=../docs/seed-minimo.ejemplo.json"

Esto carga una campaña vigente con 6 sorteos (5 semanales + cierre) y una clave de firma. Una vez que veas en el log que el seed corrió, podés volver a arrancar con mvn spring-boot:run normal — el flag solo hace falta la primera vez.

El seed es idempotente respecto al bean

Sin la property sp.seed.archivo, el bean SeedMinimo ni se registra — así que dejar el flag afuera en los arranques siguientes no vuelve a insertar nada de más.

7. Verificar que todo funciona junto¶

Backend solo: http://localhost:8080/api/salud → {"estado":"ok","base_datos":"ok"}.
Landing: abrí http://localhost:5173 — debería cargar sin errores de consola relacionados a /api.
Login del gestor: abrí http://localhost:5174/gestor/ (o directamente http://localhost:5174/ si tu router redirige) e ingresá con SP_GESTOR_USER / SP_GESTOR_PASSWORD — los mismos valores que cargaste en el paso 2.
Campaña vigente: dentro del gestor, la pantalla Panel debería mostrar la campaña "Sorteo Aniversario Caracol" con sus 6 sorteos.

Entorno listo

Si los cuatro puntos de arriba cierran, tenés el entorno de desarrollo completo: backend + landing + gestor + datos de prueba.

Iterar con los tres procesos a la vez¶

Para el día a día dejá las tres terminales abiertas en paralelo:

Terminal	Comando	Puerto
Backend	`mvn spring-boot:run` (en `backend/`)	8080
Landing	`npm run dev` (en `landing/`)	5173
Gestor	`npm run dev` (en `gestor/`)	5174

Cada una tiene su propio hot reload: tocás un .java y spring-boot:run reinicia el contexto solo; tocás un .tsx en landing o gestor y Vite actualiza el navegador sin recargar la página entera. No hace falta reiniciar nada manualmente salvo que cambies una variable de entorno del backend (esas sí requieren volver a correr . .\dev-env.local.ps1 y reiniciar spring-boot:run).

Para generar vouchers de prueba y probar el circuito de punta a punta sin depender de una impresora de ticket real, seguí con Generar vouchers de prueba (QR).