Operação e Manutenção

Ferramentas para diagnosticar problemas e controlar o ponto de partida da extração, sem precisar mexer em código.

Nome do domínio nos comandos

Todo comando abaixo recebe --domain <dominio>. <dominio> é sempre um placeholder — troque pelo valor real do domínio que você quer afetar, usando a coluna "Valor de --domain" abaixo (não é o mesmo texto do prefixo do .env):

Domínio	Prefixo `.env`	Valor de `--domain`
Produtividade	`PROD`	`productivity`
Plantio	`PLANT`	`planting`
CTT	`CTT`	`ctt`
Ordem de Serviço	`ORDEM`	`ordem`
Pragas	`PRAGAS`	`pragas`
Clima	`CLIMA`	`clima`

Se --domain for omitido, o comando roda para todos os domínios ativos.

Checkup de conectividade e queries

Testa, para cada domínio ativo, se a conexão Oracle funciona, se a query {PREFIXO}_QUERY_CTRL_MAX executa sem erro, se a {PREFIXO}_QUERY_TEMPLATE roda (com limit=1) e se a autenticação OAuth2 do Hub está correta.

Não altera nada

O checkup é somente leitura: não grava no estado local (SQLite) nem envia dados ao Hub. Requer npm run build antes de usar (roda sobre o build em dist/).

# Roda o checkup de todos os domínios
npm run extrator -- --checkup

# Roda apenas um domínio — troque "planting" pelo domínio desejado (tabela acima)
npm run extrator -- --checkup --domain planting

# Testa com um ctrl_min específico (sem alterar o estado salvo)
npm run extrator -- --checkup --domain planting --min-ctrl "2020-03-01 00:00:00"

# Pula o teste de autenticação do Hub
npm run extrator -- --checkup --skip-hub

# Saída em JSON (para automação)
npm run extrator -- --checkup --json

O que valida:

🔌 Conexão Oracle de cada domínio
📊 A query {PREFIXO}_QUERY_CTRL_MAX real, mostrando o valor obtido (ou o erro exato do Oracle)
📋 Um dry-run da {PREFIXO}_QUERY_TEMPLATE (1 registro), pegando erros de sintaxe/coluna antes do CRON rodar
🔑 As credenciais CLIENT_ID/CLIENT_SECRET/scope, obtendo um token OAuth2 real do Hub

Códigos de saída: 0 = tudo passou (ou não havia dados novos); 1 = alguma conexão, query ou autenticação falhou.

Use isso antes de configurar o CRON — assim os erros de configuração (ex: divergência de máscara de data) aparecem na hora, sem precisar vasculhar logs do container.

Consultar e resetar o ponto de partida (`ctrl_min` / `ctrl_max`)

O Extrator guarda localmente (em SQLite, dentro do container) o último ponto processado de cada domínio: minCtrl, maxCtrl, status e offset. Isso é o que permite ele continuar de onde parou a cada execução, sem reprocessar tudo.

Por que mudar {PREFIXO}_QUERY_CTRL_MIN_DEFAULT no .env às vezes não faz efeito

Essa variável só é usada quando não existe nenhum registro salvo ainda para aquele domínio. Depois da primeira execução bem-sucedida, o próximo ponto de partida vem do estado salvo — não do .env. Se você mudar o .env depois disso e nada mudar no comportamento, é esse o motivo. Use o comando de reset abaixo para forçar um novo ponto de partida.

Ler o estado atual

# Todos os domínios
docker compose run --rm app node scripts/extrator.mjs

# Um domínio específico — troque "productivity" pelo domínio desejado (tabela acima)
docker compose run --rm app node scripts/extrator.mjs --domain productivity

Forçar reprocessamento a partir de uma data

# Troque "productivity" pelo domínio desejado (tabela acima)
docker compose run --rm app node scripts/extrator.mjs --domain productivity --min-ctrl "2020-04-01 00:00:00"

A próxima execução do CRON (ou o próximo docker compose up -d, se o container não estiver rodando) já vai partir dessa data.

Error: attempt to write a readonly database

Aparece se você rodar node scripts/extrator.mjs direto no host, fora do container. O arquivo SQLite é criado pelo container (geralmente como root) e o seu usuário local não tem permissão de escrita nele. Sempre rode via docker compose run --rm app ... (como nos exemplos acima) — assim o comando executa com a mesma permissão do container que já escreve nesse arquivo normalmente.

Referência rápida de erros

Sintoma	Causa	Onde resolver
`ORA-01861: literal does not match format string`	Coluna de data não é `DATE`/`TIMESTAMP` no Oracle, ou tem valor que não bate com o formato usado	Tipo das colunas de data
Mudei `{PREFIXO}_QUERY_CTRL_MIN_DEFAULT` e nada mudou	Já existe estado salvo para o domínio; o `.env` só vale na primeira execução	Comando de reset acima
Dados repetidos sendo enviados	`{PREFIXO}_QUERY_CTRL_MAX` sem `HH24:MI:SS`	Precisão de timestamps
Extrator não envia nada	Sem dados novos, CRON ainda não chegou na hora, ou credenciais OAuth erradas	Rode o `--checkup` acima para isolar a causa
`Error: attempt to write a readonly database`	Rodou `node scripts/extrator.mjs` fora do container, sem permissão no arquivo SQLite	Rode via `docker compose run --rm app ...`
`Invalid environment variables`	Variável obrigatória faltando ou com formato inválido no `.env`	Solução de problemas — o erro lista qual variável
`DPI-1047: Cannot locate a 64-bit Oracle Client library`	Oracle Instant Client não encontrado no container	Solução de problemas