Saltar a contenido

Setup del entorno

Guía para levantar TiFacturaOnlineNext en local de punta a punta: requisitos, build, perfiles, scripts y un primer arranque verde. Si recién entrás, hacé este recorrido una vez completo antes de tocar código.

Antes de empezar

Leé Arquitectura del sistema y El ciclo de facturación. Vas a entender qué estás levantando: un backend headless que emite CAE/CAEA contra AFIP, expone SOAP y REST, y corre jobs con Quartz contra SQL Server.

1. Requisitos

  • JDK 17 (Eclipse Adoptium / Temurin). Es lo que usan los scripts .bat del repo (JAVA_HOME=…\jdk-17.0.19.10-hotspot).
  • Maven en el PATH (mvn -version).
  • SQL Server local (o accesible) con la base tifacturaonline restaurada. Sin DB podés compilar y correr la suite (que usa H2), pero no el runtime completo.
  • Certificado AFIP (.p12) para los flujos que pegan contra AFIP. El cert no vive en application.yml: sale de EntesFacturadores (certP12Path/certP12Password/certP12Alias), por comercio.

No uses JDK 25 (default del sistema)

El proyecto NO compila con JDK 25. Los scripts .bat fuerzan JAVA_HOME a un JDK 17 justamente por eso. Si ves errores raros de compilación o de stubs JAXB/JAX-WS/CXF, lo primero que revisás es qué JDK está activo (java -version). Para el build nativo, en cambio, se usa otro toolchain (ver paso 7).

2. Build y suite de tests

Lo más rápido para confirmar que todo arranca verde:

:: Compila + corre la suite + arma el JAR (equivale al CI)
ci-local.bat

ci-local.bat fija el JDK 17, valida que estén java y mvn, corre mvn clean package y, si queda verde, sella una copia del JAR en releases\tifactura-spring-<fecha>-<commit>.jar (equivalente al artifact de GitHub Actions). El JAR queda en target\tifactura-spring.jar.

Si preferís ir directo con Maven:

mvn clean test     :: solo compila + corre la suite
mvn clean package  :: lo anterior + arma el JAR ejecutable

La suite corre sobre H2

Los tests usan H2 en memoria (src/test/resources/application.yml pisa al base). Los tests que necesitan infra real —realdb y afipsmoke— se saltean solos salvo que los habilites por flag (ver Cómo se hace). Por eso mvn test no necesita ni SQL Server ni cert.

3. Configurar la base de datos (perfil dev)

El perfil por defecto es dev, que apunta a SQL Server local. La URL y credenciales están en application-dev.yml:

spring:
  datasource:
    url: jdbc:sqlserver://localhost:1433;databaseName=tifacturaonline;encrypt=true;trustServerCertificate=true
    username: ${DB_USER:sa}
    password: ${DB_PASS:}

El esquema lo administra el cliente: ddl-auto=none (la app no genera ni migra tablas). Necesitás la base tifacturaonline ya restaurada.

Secretos siempre por variable de entorno

La clave de DB (DB_PASS), el CUIT (AFIP_CUIT) y el secret del ABM (COCKPIT_ADMIN_SECRET) nunca van en el repo. Se pasan por env var. El application.yml lo deja escrito: "Secretos (DB, cert AFIP) SIEMPRE por variable de entorno, nunca en el repo."

4. Levantar el backend

Con el JAR ya compilado:

run.bat

run.bat está gitignoreado (no lo commitees con claves). Setea las env vars y arranca el JAR:

set "DB_PASS=<tu-clave-de-SQL-Server>"
set "COCKPIT_ADMIN_SECRET=<tu-secret-del-ABM>"
java -jar target\tifactura-spring.jar

El backend queda en :8080. Al arrancar vas a ver, en el log, al TareaScheduler agendando los jobs desde la tabla Tareas (ver Jobs Quartz).

Si querés correr sin JAR (iterando código):

mvn spring-boot:run

5. Compilar solo el JAR (rápido, sin tests)

Cuando solo querés el ejecutable y no la suite:

compilar-jar.bat

Hace mvn clean package -DskipTests con el JDK 17 y deja target\tifactura-spring.jar. Para correrlo: java -jar target\tifactura-spring.jar.

Atajos .bat de la raíz

Script Qué hace
ci-local.bat CI completo: mvn clean package + copia sellada a releases\.
compilar-jar.bat mvn clean package -DskipTests (JAR rápido).
run.bat Arranca el JAR con las env vars (DB + cockpit secret). Gitignoreado.
co.bat mvn -o compile y luego mvn -o package (offline).
t.bat mvn test (con JDK 17).
tt.bat Smoke contra AFIP homologación (-Dtest=AfipHomologacionSmokeTest -Dafipsmoke=true). Ver Cómo se hace.

Todos fijan JAVA_HOME al JDK 17 antes de invocar Maven.

6. Healthcheck

Con el backend arriba, comprobá que el enlace con AFIP responde desde el Cockpit:

curl http://localhost:8080/api/cockpit/afip-status
curl http://localhost:8080/api/cockpit/summary

afip-status te dice si el ping FEDummy está online, si hay TA vigente y el CUIT del facturador. summary te da las métricas por operación. La superficie completa está en Cockpit.

Perfiles de un vistazo

  • dev (default): SQL Server local, AFIP en HOMOLOGACION (heredado del base). Logging DEBUG.
  • prod: SQL Server del cliente y AFIP PRODUCCION; todos los hosts/secretos por env var (DB_HOST, DB_NAME, DB_USER, DB_PASS, …).

El default es homologación a propósito (seguro). Para activar prod: --spring.profiles.active=prod. Detalle en Configuración y perfiles.

7. (Opcional) Build nativo Windows

El proyecto también compila a un EXE nativo con GraalVM/Liberica NIK + MSVC. El estado y el camino reproducible están documentados en handoff.md de la raíz del repo. Resumen del flujo que funcionó:

:: Desde "x64 Native Tools Command Prompt for VS"
set "JAVA_HOME=C:\Program Files\BellSoft\LibericaNIK-25-OpenJDK-25"
set "PATH=%JAVA_HOME%\bin;%PATH%"

mvn -DskipTests package
mvn -Pnative -DskipTests native:compile

El build nativo usa otro JDK y tiene un workaround pendiente

A diferencia del build JVM (JDK 17), el nativo usa Liberica NIK 25. Con GraalVM 25 el análisis puede fallar por Password$ConsoleHolder; el workaround verificado es correr native-image directo con --initialize-at-run-time=sun.security.util.Password$ConsoleHolder sobre el args-file generado por Maven. El EXE final (target\tifactura-spring.exe) arranca en perfil prod, conecta a SQL Server, publica SOAP y agenda los jobs. Para el detalle completo (troubleshooting, scripts\package-dist.cmd, YAML externo al lado del EXE), leé handoff.md.

Por dónde seguir