AGENTS.md — Swift Reports Desktop (Python, PySide6)
Propósito: guia operacional para agentes de IA (e humanos) evoluírem o aplicativo desktop que importa lançamentos do Sucessor e Suprema, normaliza e exibe em tabela com busca ao vivo, filtros, tooltips (plano de contas/participantes) e exportação. Prioridades: desempenho com 100k+ linhas, parsing correto (datas/valores), UX leve e moderna.
- Estado atual (snapshot)
Stack: Python 3.10+, PySide6 (Qt), xlsxwriter (XLSX), pandas (somente export).
Estrutura principal:
main.py — janela, menus, filtros (busca/data/origem), seleção persistente, export.
data_io.py — parsers e normalização: Sucessor, Suprema (Entradas/Saídas/Serviços), Plano de Contas, Participantes.
models.py — LancamentosModel (QAbstractTableModel) + LancamentosFilterProxy (filtros/busca).
UI: tabela única; tooltips em contas/participantes; export de selecionados.
Pontos a resolver: lentidão >100k; filtros adicionais; vírgula decimal; unificação de arquivos; histórico do Suprema; coluna Documento; seleção some ao trocar filtro; botão “Limpar seleção”; tabela de planos.
- Escopo
Inclui
Importar CSV do Sucessor (Consulta Lançamentos).
Importar CSV do Suprema (Entradas, Saídas, Serviços).
Importar Plano de Contas e Participantes (clientes/fornecedores) como bases fixas (atualizações incrementais).
Normalizar + unificar em uma única tabela.
Busca ao vivo (case-insensitive, sem acentos) + filtros por data, origem, conta, participante, CFOP, valor min–max, tipo, modelo.
Histórico:
Suprema: gerar Nome participante - CFOP nnnn - Doc nnn.
Sucessor: manter como está (concatenar “Complemento” se existir).
Exportar selecionados (CSV/XLSX) mantendo seleção ao trocar filtros.
UI moderna e leve (sem efeitos pesados).
Fora do escopo
Banco de dados local (dados in-memory).
Download direto dos ERPs.
Relatórios/BI avançados e gráficos pesados.
- Contrato de dados (modelo normalizado por linha)
Chaves esperadas:
origem: "Sucessor" | "Suprema"
tipo: "Lançamento" | "Entrada" | "Saída" | "Serviço"
transacao: identificador/descrição curta
data: datetime.date
valor: float
debito, credito: códigos de contas (ou "")
participante_debito, participante_credito: códigos (ou "")
historico: str
origem_arquivo: nome do arquivo
documento, serie, modelo: str (ou "")
cfop: str (ou "")
id: único na sessão (f"{origem}|{origem_arquivo}|{tipo}|{indice}")
Colunas na UI (ordem):
Trans. | Data | Valor | Déb. | Part. Déb. | Créd. | Part. Créd. | Hist. | Orig. | Doc.
- Regras de parsing (obrigatórias)
CSV: separador ;.
Encoding: tentar latin1, cp1252, utf-8-sig (auto-detecção rápida).
Datas: tentar %d/%m/%Y, depois %Y-%m-%d; inválida → None.
Valores: remover . (milhar) e trocar , (decimal) por . → float.
"1.234,56" -> 1234.56
"250,00" -> 250.00
Histórico:
Suprema: "" + (" - CFOP " + cfop if cfop) + (" - Doc " + documento if documento)
Sucessor: manter; se houver “Complemento”, concatenar com " — ".
- Mapeamento por origem (aliases)
Nomes variam por exportação. Use listas de aliases por campo e normalize.
Sucessor — Consulta de Lançamentos
Data → ["Data", "DATA"]
Transação → ["Transação", "Transacao", "LANÇAMENTO", "NUM_LANC"]
Débito → ["Débito", "Debito", "DEBITO"]
Crédito → ["Crédito", "Credito", "CREDITO"]
Participante Débito → ["Participante Débito", "Participante Debito", "PART_DEB"]
Participante Crédito → ["Participante Crédito", "Participante Credito", "PART_CRED"]
Valor → ["Valor", "VALOR", "Valor Contábil"]
Histórico → ["Histórico", "Historico", "HISTORICO"]
Complemento → ["Complemento", "COMPLEMENTO"]
Documento → ["Documento", "Nº Docto", "Nº docto", "Doc"]
Série/Modelo → ["Série", "Serie"], ["Modelo"]
Suprema — Entradas/Saídas/Serviços
Data → ["Data", "Data de Entrada", "Entrada", "Emissão", "Emissao"]
Documento → ["Documento", "Nota", "Nº Docto", "Nº docto"]
Série/Modelo → ["Série", "Serie"], ["Modelo"]
CFOP → ["CFOP", "Cfop"]
Valor → ["Valor", "Valor Contábil", "Total", "VALOR"]
Participante → ["Participante", "Fornecedor", "Cliente", "CodParticipante", "Cod Fornecedor", "Cod Cliente"]
Conta Débito/Crédito (se houver) → ["Conta Débito", "Debito"], ["Conta Crédito", "Credito"]
Planos (Contas / Participantes)
Plano de Contas: codigo;nome
Participantes: codigo;nome (clientes e fornecedores integrados)
- UX e interação
Busca ao vivo: debounce ~150 ms; sem acentos; case-insensitive; busca nas colunas textuais e valor como texto.
Filtros mínimos: De/Até (data), Origem (Sucessor/Suprema).
Filtros extras: Conta (Déb./Créd.), Participante, CFOP, Valor [min–max], Tipo, Modelo.
Seleção persistente: selected_ids: set não deve sumir ao trocar filtros/busca.
Ações: Importar Planos; Importar Sucessor; Importar Entradas/Saídas/Serviços; Exportar Selecionados; Limpar Seleção.
Tooltips: mostrar “<código> - ” para contas/participantes.
Tabela de Planos: segunda aba com consulta de plano de contas e participantes (busca por código/nome).
- Performance (100k+ linhas)
Requisitos:
LancamentosModel.data() O(1); evitar criação de objetos/strings por chamada.
Sem pandas no hot-path (apenas export).
Filtro em LancamentosFilterProxy: curto-circuito (origem → data → texto); opcional cache por linha.
Importação em thread (QThread/QRunnable) por lotes; UI nunca bloqueia.
Memória: não manter “bruto + normalizado” ao mesmo tempo; descartar colunas não usadas.
Export: iterar somente selected_ids; CSV streaming.
Sinais de regressão: UI congela ao digitar; rolagem engasga; picos de RAM.
- Arquitetura e arquivos
swift-reports-desktop/
├─ main.py # janela, filtros, seleção, export, abas
├─ models.py # QAbstractTableModel + QSortFilterProxyModel
├─ data_io.py # parsers + normalização + utilidades de parsing
├─ requirements.txt
├─ README.md
└─ tests/ # (sugerido) unit tests parsing/normalização
Fluxo: Import → Normaliza → Unifica → Model/Proxy → UI → Export.
- Playbooks (passos rápidos)
A) Corrigir valores (vírgula decimal)
Local: data_io.py
Ação: _parse_number_br(s) — remover . (milhar), substituir , por ., float().
Testes: "250,00" → 250.00; "1.234,56" → 1234.56.
B) Unificar lançamentos (múltiplos arquivos)
Local: main.py + data_io.py
Ação: concatenar tudo em records; setar origem, tipo, origem_arquivo; gerar id único.
C) Histórico do Suprema
Local: data_io.py
Ação: montar Nome - CFOP - Doc usando base de Participantes; omitir partes vazias.
D) Coluna Documento
Local: data_io.py (parsers) + models.py (cabeçalhos)
Ação: extrair documento/serie/modelo; exibir Doc. na UI.
E) Persistência de seleção
Local: main.py + models.py
Ação: manter selected_ids; ao recriar model, reconectar selectionModel().selectionChanged.
F) Filtros extras
Local: models.py (LancamentosFilterProxy)
Ação: implementar filtros por Conta/Participante/CFOP/Valor/Tipo/Modelo (parâmetros setáveis pela UI).
G) Import em thread
Local: main.py
Ação: usar QThread/QRunnable; reportar progresso; merge incremental em records.
H) Otimização do model
Local: models.py
Ação: cache leve de DisplayRole (data/valor/histórico) se medir ganho; flags() simples para checkbox/seleção.
I) Tabela de Planos (segunda aba)
Local: main.py
Ação: QTableView para contas e participantes com busca por código/nome.
- Critérios de aceitação (DoD)
Importa todos os CSVs fornecidos sem erro; unificação na mesma tabela.
Valores corretos (sem multiplicação indevida).
Datas interpretadas corretamente.
Histórico (Suprema) = Nome - CFOP - Doc; Sucessor intacto.
UI mostra: Trans. / Data / Valor / Déb. / Part. Déb. / Créd. / Part. Créd. / Hist. / Orig. / Doc..
Busca + filtros < 200 ms para 10k linhas; UI fluida com 100k+.
Seleção persiste ao trocar filtros; Limpar Seleção funciona.
Tooltips corretos para contas/participantes quando bases importadas.
Export CSV/XLSX correto; data dd/MM/yyyy.
- Testes (sugeridos)
Unitários: _parse_number_br, _parse_date, montagem do histórico (Suprema), concat Sucessor+Suprema.
Integração: importar amostras reais; conferir colunas e contagens.
Carga: dataset sintético 100k+; medir filtro/busca e RAM.
Regressão: seleção não pode sumir ao trocar filtros/busca.
- Padrões de código
Type hints + from future import annotations.
Nomes pt-BR para domínio; comentários objetivos.
Parsers puros; UI orquestra.
Mensagens de erro claras (QMessageBox).
Logs opcionais via env (DEBUG).
- Roadmap curto (após correções)
Paginador virtual (se necessário em máquinas com pouca RAM).
Integração opcional com DuckDB para consultas ad hoc (futuro).
Empacotar com PyInstaller + pipeline de release.
- Como rodar
python -m venv .venv
..venv\Scripts\activate
pip install -r requirements.txt
python main.py