relatorios-sivwin 0.3.0

Consultas SQL reutilizaveis para o ecossistema SivWin/Otimiza.

Relatorios SivWin

Biblioteca Python para centralizar consultas SQL parametrizadas do ecossistema SivWin/Otimiza.

Instalacao

pip install relatorios-sivwin

O pacote requer Python 3.10 ou superior. O nome publicado usa hifen, mas o import Python usa underscore:

from relatorios_sivwin import RelatoriosSivWin

Dominios

RelatoriosSivWin organiza as consultas em cinco grupos:

• gerais: ARTs, declaracoes e relatorios transversais;
• servicos: servicos, inspecoes, escopos, normas e o relatorio completo;
• veiculos: consultas cadastrais e tecnicas por placa, chassi ou RENAVAM;
• pessoas: consulta por CPF/CNPJ;
• financeiro: consultas financeiras, inicialmente por nota fiscal.

relatorios = RelatoriosSivWin()

relatorios.servicos.relatorio_completo(
    inicio="2026-02-01",
    fim="2026-02-28",
)
relatorios.servicos.por_os(103167)
relatorios.servicos.por_ri(12345)
relatorios.servicos.por_placa("ABC-1D23")
relatorios.servicos.por_chassi("9BWZZZ377VT004251")
relatorios.servicos.ris_emitidos("2026-02-01", "2026-02-28")

relatorios.veiculos.por_placa("ABC-1D23")
relatorios.veiculos.por_chassi("9BWZZZ377VT004251")
relatorios.veiculos.por_renavam("00012345679")

relatorios.pessoas.por_cpf_cnpj("529.982.247-25")
relatorios.financeiro.por_nota_fiscal("12345")

Cada metodo retorna um SQLQuery com SQL parametrizada, parametros normalizados, nome da consulta e aliases das colunas.

Relatorio completo

O relatorio completo pertence ao dominio de servicos e combina fragmentos de servico, veiculo, pessoas e financeiro. Ele e o consumidor mais abrangente dos fragmentos; consultas especificas usam somente os campos e JOINs necessarios.

consulta = relatorios.servicos.relatorio_completo(
    inicio="2026-02-01",
    fim="2026-02-28",
)

print(consulta.sql)
print(consulta.params)
print(consulta.columns)

Os principais timestamps da inspecao sao:

• inspecaoAberturaDataHora;
• inspecaoRegistradoDataHora;
• inspecaoConclusaoDataHora;
• inspecaoCorrecaoDataHora.

veiculoSituacaoNome representa o resultado do veiculo inspecionado, enquanto inspecaoSituacaoNome representa o estado da inspecao.

Caracteristicas veiculares

Os dados tecnicos priorizam SivWin_CaracteristicasSerpro. Quando um campo esta nulo ou vazio, a consulta usa o valor equivalente de Caracteristicas. O fallback ocorre campo a campo, atendendo tambem veiculos de laudos SISLIT.

Placa, chassi e RENAVAM sao retornados sem mascara. O RENAVAM e preenchido com zeros a esquerda ate 11 posicoes.

Validacao

• CPF e CNPJ aceitam valores com ou sem mascara e sao validados por digito;
• placas aceitam os formatos antigo e Mercosul;
• RENAVAM aceita mascara, recebe zeros a esquerda e tem o digito validado;
• chassi e normalizado sem impor a regra moderna de VIN com 17 caracteres;
• periodos aceitam date ou texto YYYY-MM-DD e usam os argumentos inicio/fim;
• OS e RI devem ser inteiros positivos.

Entradas invalidas geram TypeError ou ValueError antes da execucao SQL.

Execucao com cursor

O pacote nao gerencia conexoes ou credenciais. Uma consulta pode ser executada com qualquer cursor DB-API compativel:

from relatorios_sivwin import RelatoriosSivWin, fetch_all

relatorios = RelatoriosSivWin()
consulta = relatorios.servicos.por_os(103167)

with connections["otimiza"].cursor() as cursor:
    dados = fetch_all(cursor, consulta)

Tambem e possivel executar diretamente:

cursor.execute(consulta.sql, consulta.params)
linhas = cursor.fetchall()

Banco para inspecao da SQL

O banco padrao usado por to_sql_raw() e otimiza:

relatorios = RelatoriosSivWin(database="sivwin_homolog")
consulta = relatorios.servicos.por_os(103167)

print(consulta.to_sql_raw())

O nome do banco nao e incorporado ao SQL executado; ele serve apenas para a representacao bruta destinada a inspecao e depuracao.

Evolucoes futuras

Os seguintes pontos ficam registrados para uma versao posterior:

• tornar servicos.por_ri() deterministicamente limitado a ultima inspecao aprovada ou corrigida;
• revisar os relatorios que usam ROW_NUMBER() diante de relacionamentos 1:N, selecionando primeiro a inspecao e compondo os demais fragmentos depois;
• executar uma validacao integrada de todas as consultas no SQL Server real;
• confirmar o mapeamento completo dos campos equivalentes entre SivWin_CaracteristicasSerpro e Caracteristicas.

Mudancas da versao 0.3.0

A versao 0.3.0 nao mantem aliases de compatibilidade da serie 0.2.x:

• start e end foram substituidos por inicio e fim;
• relatorios_gerais e relatorios_servicos foram removidos;
• os grupos veiculos, pessoas e financeiro foram adicionados;
• o relatorio completo passou a ser composto por fragmentos de dominio;
• os aliases de status e timestamps seguem a nova semantica da inspecao.