Como rodar, testar e buildar¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-15

Audiência: dev que vai mexer no tradutor na própria máquina. Para entender o código antes, veja o Guia do código; para operar em produção, o runbook de implantação.

Pré-requisitos¶

JDK 25 — a versão do docs/app.json → toolchain.java. O Gradle vem do wrapper (./gradlew).
Docker no ar — os testes de integração sobem o Postgres de teste (o singleton da xadm-comum-teste, postgres:18-alpine) e o S3Mock por Testcontainers. Sem Docker, a suíte de integração falha dizendo isso.
Lib da casa ainda não publicada — publique-a no ~/.m2 a partir do xadm-commons (./gradlew publishToMavenLocal). O build lê o mavenLocal depois do registro e só para br.com.xadm: a versão que já está no registro sempre vem de lá.

Testar¶

./gradlew check

É o mesmo comando do job gate do pipeline.yml: Checkstyle da casa, testes unitários e de integração. Os @MicronautTest estendem IntegracaoComPostgres, que aponta o datasource para o Postgres de teste e zera as tabelas do app antes de cada teste. Teste travado reprova: 2 min por teste, 15 min para a task inteira.

Cobertura consolidada (relatório em build/reports/jacoco/):

./gradlew cleanTest test jacocoTestReport --rerun-tasks

O boot da imagem native tem teste próprio (@Tag("native")), fora do check porque exige a imagem pré-buildada:

./gradlew dockerBuildNative -PnativeQuick --no-configuration-cache
./gradlew nativeSmoke

Subir o app¶

./gradlew run

Precisa de um Postgres com a tabela estoque do integrador; o Flyway do tradutor cria só as suas webstorm_ecom_*, com histórico próprio (flyway_schema_history_webstorm_ecom). Variáveis mínimas:

Variável	Para quê
`DATASOURCES_DEFAULT_URL`	JDBC do `db_thoms` (ex. `jdbc:postgresql://localhost:5432/db_thoms`)
`DATASOURCES_DEFAULT_USERNAME` / `DATASOURCES_DEFAULT_PASSWORD`	credencial: lê `estoque`, escreve `webstorm_ecom_*`
`WEBSTORM_API_TOKEN`	Bearer `ROLE_API` que o integrador (poke) e o X-Adm (CSV) mandam ao tradutor
`PARCEIRO_URL` / `PARCEIRO_API_TOKEN`	API da WebStorm (`POST /sync/erp`)
`INTEGRADOR_URL` / `INTEGRADOR_API_TOKEN`	integrador, destino da ingestão do CSV
`CLIENTE`	`Thoms` (tag dos erros no GlitchTip)

Login (AUTH_*), Garage (GARAGE_*), watchdog (MONITOR_*) e o ajuste do lote ao parceiro (PARCEIRO_LOTE, PARCEIRO_PACING_MS, PARCEIRO_MAX_FALHAS) estão no runbook de implantação. O /health responde {status, versao, flavor, commit}.

Buildar¶

./gradlew shadowJar                                        # build/libs/app.jar
docker build -f Dockerfile.native -t webstorm-ecom:native .  # a imagem que vai a produção
docker build -t webstorm-ecom:jar .                          # a imagem JVM, fallback

Produção usa a imagem native buildada pelo job build_native do pipeline.yml na tag vX.Y.Z, fora do host de produção; o Coolify só puxa.

Documentação¶

mkdocs build --strict

O job docs do pipeline.yml baixa antes do build os hooks (scripts/frontmatter-cabecalho.py e scripts/visao-tecnica.py) e os fatos importados do integrador (docs/_importado/); para buildar local, baixe-os com os mesmos comandos do job.

Release¶

Pela /xadm-release: bump SemVer, CHANGELOG e tag. A tag builda o native, deploya pelo control-plane com o gate e o release-check verdes, e o smoke confere produção.