xadm-pied-cliente

Cliente Java de linha de comando que puxa produtos, clientes e pedidos da API REST da PIED, mapeia para o formato do X-Adm e grava arquivos JSON (imprimindo um resumo no stdout). Não envia nada ao X-Adm — a ingestão dos arquivos é responsabilidade da equipe X-Adm.

Cliente da Maxsul. 📖 Documentação Completa no portal X-Adm (o fonte fica em docs/); este README cobre só o essencial de build/execução.

Requisitos

• JDK 25 — o Gradle usa toolchain Java 25.
  • Windows: baixe o JDK aqui e configure JAVA_HOME + Path.
  • Linux: via SDKMAN! — sdk install java 25.0.3-graal.
• ./gradlew (wrapper versionado) — não precisa instalar Gradle.

Build e testes

./gradlew check        # compila + Checkstyle + testes (JUnit 5/WireMock) — gate de CI
./gradlew shadowJar    # gera build/libs/xadm-pied-cliente-*.jar e copia para a raiz do projeto

Execução

Crie um .env no diretório de execução (cp .env.example .env e preencha) — o app o lê automaticamente. Variáveis reais do SO têm precedência (CI/prod).

java -jar xadm-pied-cliente-*.jar               # sem flags: valida config + lista opções
java -jar xadm-pied-cliente-*.jar --dev         # amostra de 5 por entidade
java -jar xadm-pied-cliente-*.jar --mode incremental --output-dir ./saida
./gradlew run                                           # valida config + mostra help
./gradlew run --args="--dev"                            # modo DEV (amostra de 5)

Flags

Flag	Descrição
--mode incremental|reconcile|full	modo de execução (padrão: incremental)
--last-update-after AAAA-MM-DD	data inicial — só no modo reconcile
--entity produtos|clientes|pedidos	limita a execução a uma entidade
--page-limit N	itens por página (máx. 50)
--output-dir DIR	diretório de saída (padrão ./saida)
--print-json	imprime também os arrays mapeados no stdout
--dev	amostra de 5 por entidade (1 página)

Exit codes

Código	Significado
0	sucesso
1	erro parcial (itens rejeitados)
2	erro de configuração/autenticação
3	indisponibilidade externa (PIED)

Saída

Em XADM_OUTPUT_DIR (padrão ./saida), prefixados pelo timestamp <ts> da execução:

Arquivo	Conteúdo
<ts>-<entidade>.json	dados mapeados para o X-Adm
<ts>-bruto-*.json	resposta crua da PIED (auditoria)
<ts>-resumo.json	contadores e erros por entidade
estado.json	cursor do modo incremental

Logs vão para STDERR e logs/; o token nunca é logado.

Fronteira — handoff para a equipe X-Adm

Este app NÃO envia nada ao X-Adm. Ele lê da PIED, mapeia para o formato do X-Adm e grava arquivos JSON. Enviar esses dados ao X-Adm é a parte que a equipe X-Adm implementa.

O ponto de extensão está marcado no código:

• xadm/EnvioXAdm.java — stub com o TODO. É aqui que você implementa o envio (Despachador.despachar(entidade, objetos)), chamado pelo pipeline logo após cada entidade ser mapeada. objetos já está no formato do X-Adm (idêntico ao JSON gravado).
• Faça upsert pela chave de origem — produtos: productCode · clientes: CNPJ/CPF · pedidos: code. A ordem produtos → clientes → pedidos já é garantida.
• Stack livre: não precisa usar Gradle/picocli/OkHttp — o mapeamento é isolado. No limite, dá para ignorar o código Java e só consumir os arquivos JSON em outra linguagem.

Formato/schema da saída: modelagem e mapeamento. Visão de operação: integração com o X-Adm.

Estrutura

• docs/ — documentação (livro do projeto, requisitos, decisões, operação).
• src/main/java/br/com/xadm/maxsul/pied/ — código (feature-first com kernel: cli/, produtos/, clientes/, pedidos/, core/).
• Operação detalhada: docs/operacao/operacao-local.md; como rodar localmente: docs/dev/index.md.