Metadata-Version: 2.4
Name: jupiter-subtes
Version: 1.0.3
Summary: Biblioteca para automatização web nos sistemas do Tesouro do Estado do Rio de Janeiro
Author: EOP/SUPCONC
License: MIT
Project-URL: Homepage, https://github.com/bvkila/jupiter
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: selenium
Requires-Dist: automaweb
Dynamic: license-file

# 🪐 Biblioteca Jupiter

Jupiter é uma biblioteca Python desenvolvida para centralizar e padronizar o ecossistema tecnológico do setor contábil do Tesouro. Seu principal objetivo é simplificar tarefas diárias por meio da automação de processos sistêmicos (Siafe) e da integração fluida com o repositório em nuvem corporativo (SharePoint), com uma arquitetura preparada para abraçar novas integrações no futuro.

---

## ✨ Principais Funcionalidades

O projeto atualmente é dividido em dois grandes módulos operacionais:

### 🏛️ 1. Automação Contábil (siafelibrary.py)
Encapsula toda a interação com o Sistema Integrado de Gestão Orçamentária, Financeira e Contábil (Siafe-Rio2).
* Login Automatizado: Suporte para ambientes de Produção e Testes (Beta).
* Geração de Documentos em Lote: Processa grandes volumes de dados a partir de tabelas do pandas (DataFrame).
* Documentos Suportados:
    * Guia de Recolhimento (GR) - Orçamentária e Extra-orçamentária
    * Programação de Desembolso (PDE) - Extra-orçamentária
    * Programação de Desembolso de Transferência (PDT)
    * Nota Patrimonial (NP)
    * Nota de Aplicação e Resgate (NA)
* Resiliência: Possui sistema embutido de tratamento de erros, alertas visuais (tkinter), controle de re-tentativas (até 3 vezes por documento) e inteligência para pular registros com falhas de comunicação e retomá-los posteriormente.

### ☁️ 2. Integração em Nuvem (apipoint.py)
Gerencia conexões e operações de arquivos com o Microsoft SharePoint.
* Autenticação Inteligente: Utiliza extração automatizada de cookies do navegador para estabelecer uma conexão segura.
* Gestão de Arquivos e Pastas:
    * Upload e Download de arquivos individuais.
    * Upload e Download recursivo de pastas completas.
    * Verificação de existência de caminhos e criação de diretórios estruturados.
    * Exclusão de arquivos e pastas antigas.

### 🚀 O que vem por aí (Roadmap)
* Integração com o Microsoft Outlook (Disparo e leitura automatizada de e-mails contábeis).
* Integração com o Microsoft Teams (Alertas em canais sobre status de contabilização, como "Rotina X finalizada com sucesso").

---

## 📦 Dependências

Para que o Jupiter funcione corretamente, seu ambiente Python precisa contar com as seguintes bibliotecas:

* office365-rest-python-client (Comunicação com o ecossistema Microsoft)
* selenium (Controle do navegador para o Siafe)
* pandas (Manipulação dos dados e planilhas)
* automaweb (Biblioteca base interna de automação web)

---

## 🛠️ Instalação e Configuração do Ambiente

Como o Jupiter utiliza bibliotecas externas e módulos de automação web, siga os passos abaixo para preparar o seu ambiente local:

1. Clone o repositório (ou baixe os arquivos fonte):
   git clone https://seu-repositorio-interno/jupiter.git
   cd jupiter

2. Instale as dependências públicas via pip:
   pip install pandas selenium office365-rest-python-client

3. Instale a biblioteca base automaweb:
   Como a automaweb é uma biblioteca de uso interno, certifique-se de que ela está no mesmo diretório do seu projeto ou instale-a conforme a documentação da sua equipe (por exemplo, via arquivo .whl ou clonando o repositório respectivo).

4. Webdriver: 
   O Jupiter gerencia o navegador via Selenium. Certifique-se de ter o Google Chrome instalado e atualizado na sua máquina. A biblioteca automaweb deve lidar com o gerenciamento do ChromeDriver automaticamente em segundo plano.

---

## 💻 Como Usar (Quick Start)

Abaixo estão exemplos básicos de como importar e utilizar os módulos da biblioteca Jupiter nos seus scripts diários.

### Manipulando o SharePoint

from jupiter import apipoint

# Inicializa a conexão com o site da sua equipe
sp = apipoint.SharePoint(site_url="https://sua-url-sharepoint.com/sites/SetorContabil")

# Fazendo o download de um relatório específico
sp.download_arquivo(
    caminho_sharepoint="/sites/SetorContabil/Shared Documents/Relatorios/balancete_01.xlsx", 
    pasta_local="C:/Users/SeuUsuario/Downloads"
)

# Fazendo o upload de uma pasta inteira de arquivos processados
sp.upload_pasta(
    pasta_local="C:/Users/SeuUsuario/Documentos/Processados",
    pasta_sharepoint="/sites/SetorContabil/Shared Documents/Processados_Mes_Atual"
)


### Automatizando o Siafe

from jupiter import siafelibrary
import pandas as pd

# Carrega sua planilha de lançamentos contábeis
df_lancamentos = pd.read_excel("lancamentos.xlsx")

# Dicionário mapeando as regras de negócio para as contas
# (Permite separar as regras de contabilidade do código da biblioteca)
regras_contabeis = {
    "TIPO_A": {
        "TipoDocumento": "01", "UG": "123456", "DomicilioBancario": "0001",
        "IEF": "1", "Fonte": "100", "FonteRJ": "100", "TipoDetalhamentoFonte": "0",
        "TipoPatrimonial": "Ativo", "ItemPatrimonial": "Bancos", "OperacaoPatrimonial": "Entrada",
        # ... outros campos ...
    }
}

# Inicializa o robô
robo = siafelibrary.Siafe()

# Faz o login no ambiente de produção (1)
if robo.logar_siafe(versaoSiafe=1, usuario="12345678900", senha="sua_senha_segura"):
    
    # Inicia a geração de Guias de Recolhimento
    sucesso = robo.gerar_gr(df=df_lancamentos, dict_map=regras_contabeis)
    
    if sucesso:
        print("Lançamentos contabilizados com sucesso!")


---

## 🧩 Estruturando o Dicionário de Regras (dict_map)

A grande vantagem da biblioteca Jupiter é a separação das regras de negócio do código de automação. Toda a inteligência contábil (qual conta usar, qual fonte, qual UG) é injetada nas funções através do dict_map. 

O dict_map é um dicionário Python onde a chave é o ID do tipo de lançamento (que deve bater com a coluna tipo_id da sua planilha/DataFrame) e o valor é outro dicionário contendo os campos que o Siafe exige.

### Exemplo Completo e Comentado

Aqui está um modelo de como montar o seu dict_map com as principais chaves suportadas pelas funções (gerar_gr, gerar_pde, gerar_pdt, gerar_np, gerar_na):


regras_contabeis = {
    # Exemplo 1: Regra para uma GR Orçamentária Padrão (Chave "TIPO_01")
    "TIPO_01": {
        # --- Identificação ---
        "TipoDocumento": "01 - Arrecadação",
        "UG": "123456", 
        "DomicilioBancario": "0001",
        "DomicilioBancarioCompleto": "0001 - BANCO EXEMPLO S.A.", # Usado para validação de segurança pelo robô
        
        # --- Detalhamento ---
        "IEF": "1",
        "Fonte": "100",
        "FonteRJ": "100",
        "TipoDetalhamentoFonte": "0",
        "DetalhamentoFonte": "0000",
        "Convenio": "99999",
        
        # --- Item Patrimonial e Orçamentário ---
        "TipoPatrimonial": "Ativo",
        "ItemPatrimonial": "Bancos Conta Movimento",
        "OperacaoPatrimonial": "Entrada de Recursos",
        "NaturezaReceita": "11180111", # Exclusivo para fluxos Orçamentários
    },

    # Exemplo 2: Regra para uma GR ou PD Extra-Orçamentária (Chave "TIPO_02")
    "TIPO_02": {
        "ExtraOrcamentario": True, # Flag essencial: avisa ao robô para usar o caminho Extra-Orçamentário
        
        "TipoDocumento": "02 - Extra-orçamentário",
        "UG": "654321",
        "DomicilioBancario": "0002",
        "DomicilioBancarioCompleto": "0002 - OUTRO BANCO S.A.",
        
        "IEF": "1", "Fonte": "100", "FonteRJ": "100", "TipoDetalhamentoFonte": "0", "Convenio": "99999",
        
        "TipoPatrimonial": "Passivo",
        "ItemPatrimonial": "Obrigações a Pagar",
        "OperacaoPatrimonial": "Saída de Recursos",
        
        # --- Dados do Credor (Exclusivo Extra-Orçamentário) ---
        "TipoCredor": "PJ", # Pode ser: PJ, CG, PF ou UG
        "Credor": "12345678000199" # CNPJ, CPF ou código da UG
    },
    
    # Exemplo 3: Flags e Lógicas Especiais (NP, PDT, NA)
    "TIPO_03": {
        # Campos básicos omitidos para brevidade...
        "TipoPatrimonial": "Ativo",
        "ItemPatrimonial": "Ajustes",
        "OperacaoPatrimonial": "899991", # Pode usar o código numérico
        
        # --- Flags Especiais do Jupiter ---
        
        "SelecaoPorValor": True,       # Diz ao robô para selecionar a Operação Patrimonial pelo Value (código) e não pelo texto visível.
        "Estorno": True,               # (Exclusivo para NA) Marca a caixa de Estorno na tela inicial.
        "Regularizacao": "01 - Tipo",  # (Exclusivo para PD) Marca a caixa de Regularização e seleciona o tipo.
        
        # --- Inscrição Genérica (Exclusivo para NP) ---
        "InscricaoGenerica": "12345",
        "TipoInscricaoGenerica": "01",
        "IGCompleta": "12345 - DESCRIÇÃO DA INSCRIÇÃO" # Usado para o robô validar se o Siafe carregou a IG corretamente antes de prosseguir.
    }
}


### 💡 Dicas Importantes:
* Certifique-se de que os textos no dicionário sejam exatamente iguais aos exibidos nas caixas de seleção (dropdowns) do Siafe, pois o robô utiliza o texto exato para clicar, a menos que você utilize a flag "SelecaoPorValor": True.
* A sua planilha (df) só precisa ter as seguintes colunas obrigatórias: id, data, valor, observacao, tipo_id. O robô se encarrega de criar/preencher as colunas num_documento e tempo_contab em tempo de execução.

---

## 🏗️ Arquitetura e Decisões de Design

* Separação de Preocupações: O módulo do Siafe foi desenhado para não conter regras de negócio (códigos de fontes, UGs, naturezas). Tudo é injetado via dicionários (dict_map), permitindo que a mesma biblioteca atenda a diferentes sub-setores do Tesouro sem precisar de alterações no código-fonte.
* Tratamento de Exceções: Devido à natureza instável de sistemas governamentais, o Jupiter utiliza blocos densos de validação. Ele verifica via XPath se o texto realmente foi digitado/selecionado no Siafe antes de prosseguir. Se algo falha, o robô aperta o botão "Voltar" do próprio sistema, limpa as variáveis e tenta novamente.
