Metadata-Version: 2.4
Name: relatorios-sivwin
Version: 0.3.0
Summary: Consultas SQL reutilizaveis para o ecossistema SivWin/Otimiza.
Keywords: sql,django,sivwin,otimiza,relatorios
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: validate-docbr<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"

# Relatorios SivWin

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

## Instalacao

```bash
pip install relatorios-sivwin
```

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

```python
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.

```python
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.

```python
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:

```python
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:

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

## Banco para inspecao da SQL

O banco padrao usado por `to_sql_raw()` e `otimiza`:

```python
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.
