Metadata-Version: 2.4
Name: relatorios-sivwin
Version: 0.3.1
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 FormaPagamento, 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_os(103167)
relatorios.financeiro.por_nota_fiscal("12345")
relatorios.financeiro.por_periodo("2026-02-01", "2026-02-28")
relatorios.financeiro.por_forma_pagamento(
    "2026-02-01",
    "2026-02-28",
    FormaPagamento.PIX,
)
```

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

Os aliases seguem o padrao `<entidade><eventoOuAtributo><tipo>` em
`camelCase`. Em relatorios de dominio especifico, a entidade principal mantem
o prefixo do dominio, como `pessoaNomeCompleto`, `pessoaCidadeNome`,
`veiculoPlaca` e `veiculoMarcaModeloNome`. Entidades relacionadas usam o papel
que ocupam no relatorio, como `contratanteCpfCnpj`, `proprietarioEmail` e
`condutorCelularNumero`.

## Relatorio completo

O relatorio completo pertence ao dominio de servicos e combina fragmentos de
servico, veiculo, pessoas e os dados financeiros diretamente associados ao
servico. 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.

Os dados financeiros do relatorio completo se limitam a `notaFiscalNumero`,
`servicoValorBruto` e `servicoValorLiquido`. Formas de pagamento e parcelas nao
fazem parte dessa consulta, pois uma OS pode possuir varios lancamentos e eles
alterariam indevidamente a quantidade de linhas por inspecao.

## Relatorios financeiros

As consultas financeiras partem dos servicos e associam somente lancamentos do
SIVWIN com `Excluido = 0`. Cada lancamento ativo gera uma linha; quando uma OS
nao possui lancamento, ela ainda e retornada uma vez com os dados financeiros do
lancamento nulos. As consultas podem ser filtradas por OS, nota fiscal, periodo
de abertura da OS ou forma de pagamento dentro do periodo de entrada.

As primeiras colunas identificam a OS e o veiculo. Em seguida sao retornados a
nota fiscal, os valores bruto e liquido do servico, os dados do lancamento, o
contratante, os valores bruto e liquido do lancamento e a forma de pagamento.
O contratante inclui `contratanteId`, `contratanteNome`,
`contratanteCpfCnpj`, `contratanteTelefoneNumero`,
`contratanteCelularNumero` e `contratanteEmail`. Parcelas permanecem
identificadas individualmente por `lancamentoReferencia` e
`lancamentoVencimentoData`.

`por_forma_pagamento()` aceita texto ou `FormaPagamento`. As formas
padronizadas sao:

- `FormaPagamento.CARTAO_CREDITO`: `CARTÃO DE CRÉDITO`;
- `FormaPagamento.CARTAO_DEBITO`: `CARTÃO DE DÉBITO`;
- `FormaPagamento.DINHEIRO`: `DINHEIRO`;
- `FormaPagamento.NOTA_FATURADA`: `NOTA FATURADA`;
- `FormaPagamento.PIX`: `PIX`.

O relatorio por periodo considera a abertura da OS e inclui servicos com
inspecoes ativas, aprovadas, reprovadas, corrigidas ou reprovadas pelo SISCSV.
Inspecoes apenas canceladas ou vencidas nao participam desse recorte.

## 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.

Os relatorios de veiculos tambem retornam os dados basicos do proprietario:
`proprietarioNome`, `proprietarioCpfCnpj`, `proprietarioTelefoneNumero`,
`proprietarioCelularNumero` e `proprietarioEmail`. O vinculo do proprietario e
feito com `LEFT JOIN`, preservando o veiculo mesmo quando o cadastro vinculado
estiver ausente.

## 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.1

- o relatorio completo deixou de consultar formas de pagamento e parcelas;
- `notaFiscalNumero`, `servicoValorBruto` e `servicoValorLiquido` foram
  preservados;
- os lancamentos financeiros nao multiplicam mais as linhas das inspecoes no
  relatorio completo;
- foram adicionadas consultas financeiras por OS, nota fiscal, periodo de
  abertura da OS e forma de pagamento;
- `FormaPagamento` foi adicionado para padronizar os filtros de forma de
  pagamento;
- os relatorios financeiros retornam documento e contatos do contratante;
- os relatorios de veiculos retornam documento e contatos do proprietario;
- o alias `pessoaNome` foi substituido por `pessoaNomeCompleto`;
- consultas por OS, nota fiscal e periodo preservam servicos sem lancamento,
  mantendo disponiveis os valores bruto e liquido do servico;
- o relatorio de declaracoes deixou de consultar formas de pagamento, evitando
  multiplicacao por parcelas ou pagamentos mistos.

## 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.
