Setup del entorno de desarrollo¶

Bienvenido al ecosistema WorkDone Sanitarios (LubecaTech). Esta guía te lleva, paso a paso, desde un Windows limpio hasta tener los tres proyectos corriendo en tu máquina:

Backend Spring Boot (la fuente de verdad de todo el ecosistema).
App móvil Android para operarios de limpieza.
Terminal Smiley (kiosk) Android de opinión del público.

Al terminar vas a poder: levantar el backend en local y entrar a Swagger, compilar e instalar la app móvil en un device/emulador, y compilar el kiosk corriendo su suite de tests.

Orden recomendado

Arrancá siempre por el backend. Tanto la app móvil como el kiosk son clientes del backend: consumen sus endpoints REST y comparten sus contratos (SYNC_PROTOCOL.md, API.md). Sin el backend levantado no vas a poder probar el flujo de punta a punta.

Prerequisitos¶

Estas son las versiones exactas que el ecosistema espera. Las sacamos de los CLAUDE.md de cada repo: respetalas, sobre todo las del backend (Java 25) y las de los proyectos Android (JDK 24 para compilar).

Backend¶

Herramienta	Versión	Notas
Java (JDK)	25	LTS-track. Mínimo Java 21 si bajás por algún motivo.
Spring Boot	4.0.6	Lo trae el proyecto, no lo instalás aparte.
Maven	3.9.16+	No Gradle. El repo trae wrapper (`./mvnw`).
Node	24+	Requerido para el CLI de JHipster (Node 25 también funciona).
JHipster CLI	9.1.0	Scaffolder inicial.
Base de datos (dev)	H2 con disco	En `./target/h2db/`, sin instalar nada.
Base de datos (prod/local opcional)	MSSQL Server 2019+	SQL Server nativo en Windows, no necesita Docker.

JDK 21 también instalado

El backend documenta correr PIT (mutation testing) con un JDK ≤ 24 porque PIT 1.19.1 no corre sobre JVM Java 25. Si vas a hacer mutation testing, tené un JDK 21 a mano. Para el día a día alcanza con Java 25.

App móvil Android y Kiosk Smiley¶

Ambos proyectos Android comparten stack y convenciones (el kiosk usa "las mismas versiones/convenciones que workdone-mobile salvo justificación").

Herramienta	Versión	Notas
JDK (toolchain)	24	Compila con bytecode target Java 21. JDK 25 dispara un warning falso de Kotlin 2.2.10.
Kotlin	2.2.10+	Compose Compiler Plugin nativo, sin kapt.
Android Gradle Plugin (AGP)	9.2.1+
Gradle	9.4.1+	Via wrapper (`./gradlew`).
Android Studio	Quail 1 (stable, junio 2026) o superior	Panda 4 también sirve, sin diferencia funcional.
Min SDK	26 (Android 8.0)	Por estabilidad NFC.
Target / Compile SDK	36 (Android 16)	Compile SDK con `minorApiLevel = 1`.

Una sola instalación de Android Studio para los dos repos Android

Tanto la app móvil como el kiosk son proyectos Gradle estándar de Android. El SDK que instala Android Studio (Compile SDK 36) y el JDK 24 te sirven para los dos.

1. Backend (Spring Boot)¶

Empezá por acá. Es la fuente de verdad del ecosistema.

Clonar e instalar dependencias¶

git clone <url-del-repo> workdone_backend
cd workdone_backend

El proyecto trae el Maven Wrapper, así que no necesitás instalar Maven globalmente: ./mvnw resuelve y baja las dependencias en el primer build.

Levantar en dev (H2, sin base de datos externa)¶

La forma más rápida de arrancar es con el perfil dev, que usa H2 en disco y DevTools:

./mvnw

Deberías ver...

El arranque de Spring Boot en consola y, una vez levantado, podés entrar a Swagger UI en:

Swagger UI: http://localhost:8080/swagger-ui/index.html
OpenAPI JSON: http://localhost:8080/v3/api-docs

El perfil dev incluye los api-docs, así que si Swagger carga, el backend está sano.

(Opcional) Levantar contra MSSQL local¶

Si querés probar contra SQL Server nativo en Windows (no necesita Docker):

# Prerequisito, 1 sola vez: CREATE DATABASE workdone; + un login SQL con db_owner.
# Liquibase crea el schema y los seeds al levantar.

# Credenciales por variables de entorno:
$env:MSSQL_USER='sa'
$env:MSSQL_PASSWORD='...'   # ver application-mssql.yml

./mvnw -Pdev,-webapp -Dspring.profiles.active=dev,mssql

Verificar¶

# Tests unitarios (surefire — EXCLUYE los *IT)
./mvnw test

[ ] El backend levanta con ./mvnw y Swagger UI responde en http://localhost:8080/swagger-ui/index.html
[ ] ./mvnw test pasa en verde

Credenciales de desarrollo (seed dev)

Hay dos mundos de auth distintos en dev:

BackOffice web (/api/authenticate): admin / admin (SOLO dev).
App móvil (/api/v1/app/auth/*, tabla operario): por ejemplo jperez / PIN 1234 / password Pa$$w0rd! (rol ADMIN). El usuario admin NO sirve para la app móvil.

Guardá estas credenciales: las vas a usar cuando pruebes la app móvil contra tu backend local.

2. App móvil Android (operarios)¶

Es un cliente del backend: lee tags NFC, registra trabajos, opera 100% offline-first y sincroniza. Repo separado.

Clonar y abrir¶

git clone <url-del-repo> workdone_mobile
cd workdone_mobile

Abrí el proyecto con Android Studio Quail 1 (o superior). El proyecto trae el Gradle Wrapper, así que las dependencias se resuelven en el primer build/sync de Gradle. Asegurate de que el JDK toolchain sea 24 (la config del proyecto ya lo fija; Android Studio lo respeta).

A qué backend apunta

El build debug apunta por defecto a https://workdone-dev.lubeca.tech/api/v1/ (definido en buildConfigField API_BASE_URL). Si querés que pegue contra tu backend local, vas a tener que ajustar esa URL — pero eso ya es trabajo de desarrollo, no de setup inicial.

Compilar e instalar en device/emulador¶

# Build debug + instalar en el device conectado
./gradlew installDebug

Verificar¶

# Tests unitarios
./gradlew test

# Lint
./gradlew lint

# Ver logs filtrados de la app
adb logcat -s WorkDone:*

[ ] ./gradlew installDebug instala la app en un device/emulador
[ ] ./gradlew test y ./gradlew lint pasan en verde

Problemas comunes (documentados en el repo)

El emulador de Android Studio NO soporta NFC nativamente. Es una limitación de larga data. Para el desarrollo cotidiano usá el modo dev de la app: en build debug, tap 5 veces sobre el logo de la pantalla principal abre un panel oculto que simula taps con UUIDs de prueba. Es la herramienta de uso diario (10x más rápido que cualquier emulación NFC).
Para validar el flujo NFC real, hace falta un device físico (el del proyecto es un Ulefone RugKing 2 Pro, Android 15) y tags NTAG215/213 grabables. Una tarjeta contactless de pago/acceso NO sirve: no tiene la URL WorkDone en NDEF, el reader la ignora.
Room 2.6.x falla con KSP2 + Kotlin 2.2 ("unexpected jvm signature V"): usá Room 2.8.4+.
Hilt < 2.59 NO soporta AGP 9: usá Hilt 2.59.2+.

3. Terminal Smiley (kiosk)¶

App Android en modo kiosko para la terminal de opinión del público. No tiene backend propio: es otro cliente del workdone-backend, con los mismos patrones que la app móvil.

Clonar y abrir¶

git clone <url-del-repo> workdone-smiley-kiosk
cd workdone-smiley-kiosk

Es un proyecto Gradle de Android igual que la app móvil; abrilo con Android Studio y dejá que Gradle sincronice. Usa Kotlin + Jetpack Compose con las mismas versiones/convenciones que workdone-mobile (mismo JDK toolchain 24, mismo Compile SDK 36).

Este repo NO documenta un comando de build/run de la app

El CLAUDE.md del kiosk solo documenta la suite de tests JVM (ver abajo). No hay un comando de "levantar/instalar" la app documentado en las fuentes consultadas, ni un equivalente a installDebug. Para correr la terminal en una tablet real interviene el modo kiosko (Lock Task / dedicated launcher, autoarranque al boot) y un flujo de vinculación que se hace con un código generado en el BackOffice — eso es instalación de campo, no setup de dev. Si necesitás levantar la app más allá de los tests, confirmá el procedimiento con AndresM en vez de asumirlo.

Verificar¶

# Tests JVM
./gradlew test

[ ] ./gradlew test pasa en verde

Hook pre-push (red de seguridad local)

El repo trae un hook pre-push que corre los tests JVM antes de dejarte pushear. Activalo una vez por clon:

git config core.hooksPath scripts/git-hooks

Para saltearlo puntualmente: git push --no-verify.

Cómo se instala una terminal en el lugar (contexto, no es setup de dev)

La puesta en marcha de una terminal física (montaje, "Probar conexión" contra GET /api/v1/smiley/ping, ingreso del código de vinculación, menú técnico con 10 toques sobre el logo) está documentada en la guía de instalación de terminal Smiley. La terminal no se configura en el lugar: textos, sonido, logo y reglas se administran remoto desde el BackOffice y bajan en el próximo sync.

Checklist final¶

Cuando los tres tildes estén verdes, tenés el entorno listo:

[ ] Backend levanta con ./mvnw y Swagger responde en http://localhost:8080/swagger-ui/index.html
[ ] App móvil instala con ./gradlew installDebug y sus tests/lint pasan
[ ] Kiosk compila y ./gradlew test pasa en verde

A partir de acá, para entender los contratos entre backend y clientes, seguí por la referencia del backend.