Felipe/comparador-notas

Fork 0

Files

T

Felipe 913bbf3060 atualiza versão do PRD para 1.3 e detalha configurações de importação de arquivos CSV e XLSX

2026-03-02 21:09:45 -03:00

23 KiB

Raw Blame History

PRD — Comparador de Notas

Versão: 1.3 Data: 02/03/2026 Status: Planejamento

1. Visão Geral

1.1 Nome do Produto

Comparador de Notas

1.2 Descrição

Software desktop multiplataforma destinado à análise de sequências numéricas de notas fiscais (ou documentos equivalentes) a partir da importação de planilhas.

O sistema identifica quebras de sequência, duplicidades e inconsistências, além de calcular totais financeiros, permitindo auditoria rápida e confiável.

O software deve ser configurável para suportar diferentes formatos de planilhas sem depender de um layout fixo.

2. Problema

Muitos sistemas legados não fornecem ferramentas adequadas para validação da sequência de notas fiscais.

Como consequência, usuários precisam criar controles manuais em planilhas para:

Detectar notas faltantes
Conferir integridade da sequência
Somar valores
Separar por série

Esse processo é:

Manual
Repetitivo
Suscetível a erro humano
Ineficiente

O produto elimina esse processo manual.

3. Objetivos

3.1 Objetivo Principal

Permitir que o usuário importe uma planilha e obtenha automaticamente:

Notas faltantes
Notas duplicadas
Soma total dos valores
Agrupamento por série

3.2 Objetivos Secundários

Permitir configuração flexível das colunas
Permitir reutilização de configurações (presets)
Reduzir tempo de auditoria
Reduzir erros humanos

4. Escopo

4.1 Incluído

Importação de arquivos CSV
Importação de arquivos XLSX
Interface gráfica
Configuração de colunas (CSV por índice numérico; XLSX por letra+linha)
Detecção de quebras de sequência
Detecção de duplicidades
Soma de valores
Agrupamento por série
Relatório visual com paginação
Exportação de relatório para PDF
Salvar layouts personalizados (exclusivos por tipo de arquivo)
Carregar layouts salvos
Selecionar layout por menu dropdown
Excluir layouts
Exportar layout para JSON
Importar layout de JSON

4.2 Não Incluído (MVP)

Integração com ERP
Integração com banco de dados externo
Multiusuário
Acesso remoto

5. Modelo de Dados

O sistema trabalhará com os seguintes campos lógicos:

Campo	Obrigatório	Descrição
Numero	Sim	Número incremental da nota. Junto com a Série forma o identificador único
Serie	Sim	Série da nota (1–3 dígitos, ex: 001–999). Separa lotes de emissão
Valor	Não	Valor monetário da nota
Data	Não	Data de emissão da nota

Os campos serão mapeados pelo usuário conforme o tipo de arquivo: via índice numérico (base 0) para CSV, e via notação LetraLinha (ex: B3) para XLSX.

Identificador único de uma nota: combinação de Numero + Serie. Duplicidade e sequência são sempre avaliadas dentro da mesma série.

6. Requisitos Funcionais

RF01 — Importação de Arquivo

O sistema deve permitir importar arquivos:

CSV
XLSX

RF01.1 — Configurações de Importação CSV

Parâmetro	Comportamento
Delimitador	Configurável pelo usuário: vírgula, ponto e vírgula ou tabulação
Encoding	Suportados: UTF-8 e Windows-1252 (Latin-1). Configurável pelo usuário
Linha do cabeçalho	Configurável pelo usuário (pode estar na linha 1, 4, etc.)
Linhas em branco	Devem ser ignoradas silenciosamente
Linhas malformadas	Devem ser ignoradas; o sistema deve reportar ao usuário quais linhas foram descartadas, sem interromper a importação

RF01.2 — Configurações de Importação XLSX

Parâmetro	Comportamento
Seleção de aba	Imediatamente após a seleção do arquivo, o sistema exibe a lista de abas disponíveis para o usuário selecionar, antes de qualquer configuração de campos
Coluna e linha de início	O usuário informa a posição inicial de cada campo no formato `LetraLinha` (ex: `B3`)
Linhas em branco	Devem ser ignoradas silenciosamente
Linhas malformadas	Devem ser ignoradas; o sistema deve reportar ao usuário quais linhas foram descartadas
Arquivo corrompido	Se o arquivo não puder ser lido, exibir mensagem de erro em modal e limpar o arquivo carregado; o estado anterior é descartado

RF01.3 — Limite de Tamanho de Arquivo

O sistema deve recusar arquivos maiores que 50 MB e exibir mensagem de erro ao usuário.

O limite refere-se ao tamanho do arquivo no disco (tamanho comprimido para XLSX, que é um arquivo ZIP internamente). Base de cálculo: 100.000 registros com 5–10 colunas geram aproximadamente 5–15 MB em CSV e até 30 MB em XLSX. O limite de 50 MB oferece margem adequada.

RF02 — Configuração de Colunas

O mapeamento de colunas varia conforme o tipo de arquivo.

RF02.1 — Mapeamento CSV (índice numérico)

O usuário define, via índice numérico (posição da coluna, base 0), qual coluna representa cada campo:

Qual índice representa o número (obrigatório)
Qual índice representa a série (obrigatório)
Qual índice representa o valor (opcional)
Qual índice representa a data (opcional)

RF02.2 — Mapeamento XLSX (letra + linha)

O usuário define, no formato LetraLinha, a posição inicial de cada campo na planilha:

Ex: B3 indica coluna B a partir da linha 3
Os campos mapeáveis são os mesmos: Numero (obrigatório), Serie (obrigatório), Valor (opcional) e Data (opcional)

A linha informada é a linha de início dos dados (não o cabeçalho). O cabeçalho, se existir, é a linha imediatamente anterior.

Comportamento de Memória

Após a importação, o arquivo permanece em memória e o usuário pode alterar o mapeamento de colunas e reprocessar sem selecionar o arquivo novamente. Ao importar um novo arquivo, os dados do arquivo anterior são descartados da memória.

Tratamento de Erros de Configuração

Situação	Comportamento
Índice/posição configurado não existe no arquivo importado	Exibir erro ao usuário identificando qual campo está inválido
Campo obrigatório (Numero ou Serie) não mapeado	Bloquear execução da análise e solicitar configuração
Campo opcional não mapeado	Ignorar o campo; funcionalidades dependentes ficam desabilitadas
Dois campos mapeados para o mesmo índice/posição	Bloquear e exibir erro de validação imediatamente, antes de executar a análise

RF03 — Presets

O sistema deve permitir:

Salvar configurações (armazenadas internamente via SQLite)
Carregar configurações existentes
Exportar um layout para arquivo JSON
Importar um layout a partir de arquivo JSON

O formato JSON é utilizado exclusivamente para importação e exportação de layouts entre dispositivos ou sistemas.

O armazenamento interno dos layouts é realizado via SQLite (ver Seção 10).

Tipo de Layout

Cada layout é exclusivo de um tipo de arquivo: CSV ou XLSX. Um layout CSV armazena configurações específicas de CSV (delimitador, encoding, índices de coluna). Um layout XLSX armazena configurações específicas de XLSX (aba, posições no formato LetraLinha).

Conflito ao Importar Layout JSON

Se o usuário importar um arquivo JSON com o nome de um layout já existente no banco, o sistema deve perguntar ao usuário o que fazer, oferecendo as opções:

Sobrescrever o layout existente
Salvar com novo nome

Erros na Importação de Layout JSON

Se o arquivo JSON estiver malformado ou com campos obrigatórios ausentes, o sistema deve exibir mensagem de erro descrevendo o problema e cancelar a importação. Nenhum dado parcial deve ser salvo.

Nome do Arquivo ao Exportar Layout

Ao exportar um layout para JSON, o sistema deve sugerir o nome do arquivo com base no nome do layout (ex: layout Padrão CSV → Padrão CSV.json). O usuário pode alterar o nome antes de salvar.

Limite de Layouts

Não há limite no número de layouts que podem ser armazenados.

RF04 — Detecção de Sequência

O sistema deve:

Ordenar os registros por número dentro de cada série
Detectar números faltantes na sequência

Regra de Detecção

A sequência é avaliada entre o menor e o maior número encontrado dentro de cada série. Qualquer número ausente nesse intervalo é considerado faltante.

Exemplo: série 001 contém os números 0001, 0002, 0003, 0005 → 0004 está faltando.

Tratamento de Valores Não Numéricos

Se o valor de um campo Numero não for numérico (ex: NF-001, ABC):

O sistema deve tentar extrair apenas os dígitos do valor (ex: NF-001 → 1)
Se após a extração restar um número válido, utilizá-lo
Se não restar valor numérico utilizável, descartar o registro
Em ambos os casos, reportar ao usuário quais registros foram afetados

Número Zero

Registros com o campo Numero igual a 0 devem ser descartados e reportados ao usuário. O valor 0 não é considerado um número de nota válido.

Escopo da Detecção

Faltantes são detectados por série. Cada série possui sua própria sequência independente.

Proteção contra Intervalos Anormalmente Grandes

Se o intervalo de faltantes de qualquer série exceder 10.000 registros, o sistema deve:

Interromper o processamento dessa série
Exibir aviso informando o intervalo calculado (ex: "Série 001: intervalo de 999.996 faltantes detectado")
Solicitar confirmação do usuário antes de continuar

Se o usuário confirmar, o sistema deve listar todos os faltantes normalmente, com paginação. Não há truncamento da lista após a confirmação.

Esse comportamento protege contra mapeamentos incorretos de colunas que gerariam listas ilegíveis.

Tratamento de Série com Valor Inválido

Se o campo Série de um registro estiver vazio ou contiver valor não utilizável:

O registro deve ser descartado
O sistema deve reportar ao usuário quais linhas foram afetadas, sem interromper a importação

RF05 — Detecção de Duplicidade

O sistema deve identificar registros duplicados.

Um registro é considerado duplicado quando existe mais de uma ocorrência da mesma combinação Numero + Serie no arquivo importado.

Exibição das Duplicatas

A lista de duplicatas exibe o identificador (Numero + Serie) e a contagem de ocorrências por grupo. Exemplo: NF 0004 / Série 001 — 3 ocorrências. As ocorrências individuais não são listadas separadamente.

Impacto na Soma de Valores

Todas as ocorrências de registros duplicados são incluídas na soma de valores, pois refletem os lançamentos reais presentes no arquivo.

RF06 — Soma de Valores

O sistema deve calcular:

Soma total
Soma por série

Formato de Valor Aceito

O sistema deve aceitar valores numéricos com ponto ou vírgula como separador decimal, detectando o formato automaticamente por registro.

Exemplo de entrada	Resultado parseado
`1000.00`	1000,00
`1000,00`	1000,00
`1.000,00`	1000,00
`1,000.00`	1000,00
`1.000`	1000,00 (ponto interpretado como separador de milhar quando seguido de exatamente 3 dígitos sem parte decimal subsequente)

Valores negativos (precedidos de -) devem ser rejeitados e reportados ao usuário como inválidos.

Valores que não puderem ser interpretados como número devem ser descartados e reportados ao usuário.

Formato de Exibição de Valores

Todos os valores monetários são exibidos com 2 casas decimais fixas no formato brasileiro (ex: 1.234,56).

RF07 — Exibição de Resultados

O sistema deve exibir:

Lista de notas faltantes agrupadas por série
Lista de duplicadas agrupadas por série
Totais (soma total e soma por série)

Organização dos Resultados

Aspecto	Comportamento
Agrupamento	Resultados sempre agrupados por série
Listas longas	Paginação — o usuário navega entre páginas de resultados
Itens por página	Selecionável via dropdown com as opções: 50, 100, 200, 1000

RF07.1 — Exportação de Relatório

O sistema deve permitir exportar o relatório de resultados para PDF utilizando a biblioteca genpdf.

O PDF deve conter:

Notas faltantes por série
Duplicatas por série
Totais por série e total geral

Metadados do relatório:

Nome do arquivo importado
Data e hora da geração
Nome do layout utilizado

RF08 — Gerenciamento de Layouts

O sistema deve permitir salvar layouts personalizados.
O sistema deve permitir listar layouts salvos.
O sistema deve permitir selecionar layouts salvos.
O sistema deve permitir excluir layouts.
Os layouts devem ser armazenados localmente via SQLite.

A exibição dos resultados de análise é coberta pelo RF07.

7. Requisitos Não Funcionais

RNF01 — Plataforma

O sistema deve funcionar em:

Windows
Linux
macOS

RNF02 — Execução Offline

O sistema deve funcionar sem conexão com internet.

RNF03 — Performance

O sistema deve suportar no mínimo:

100.000 registros por arquivo

RNF04 — Usabilidade

O sistema deve possuir interface simples.

RNF05 — Idioma

O idioma da interface é Português do Brasil (PT-BR).

RNF06 — Mensagens de Erro e Aviso

Todas as mensagens de erro e aviso devem ser exibidas em modal/popup bloqueante. O usuário deve fechar o modal explicitamente para continuar.

8. Fluxo do Usuário

Fluxo principal:

Usuário abre o sistema
Usuário importa planilha
Usuário configura colunas
Usuário executa análise
Sistema exibe resultado

9. Arquitetura Inicial Sugerida

Arquitetura desktop local.

Componentes:

Interface gráfica
Módulo de importação
Módulo de processamento
Módulo de configuração

Sem dependências externas obrigatórias.

9.1 Stack Tecnológica

Camada	Tecnologia	Status
Linguagem	Rust	Definido
Framework de UI	egui	Definido
SQLite	rusqlite	Definido
Leitura de CSV	csv	Definido
Leitura de XLSX	calamine	Definido
Geração de PDF	genpdf	Definido

10. Persistência de Dados

10.1 Visão Geral

O sistema deve possuir mecanismo de persistência de dados local para armazenamento de layouts criados pelo usuário.

Esse mecanismo deve permitir que o usuário salve, carregue, selecione e exclua layouts sem a necessidade de importar arquivos de configuração manualmente.

10.2 Tecnologia

O sistema deve utilizar banco de dados local SQLite.

Motivos:

Não requer servidor
Funciona offline
Arquivo único
Multiplataforma
Alta confiabilidade

O banco de dados deve ser armazenado na pasta de dados do usuário, de acordo com o sistema operacional:

Sistema Operacional	Caminho
Linux	`~/.config/comparador-notas/config.db`
Windows	`%APPDATA%\comparador-notas\config.db`
macOS	`~/Library/Application Support/comparador-notas/config.db`

O diretório e o arquivo devem ser criados automaticamente pelo sistema na primeira execução.

10.2.1 — Banco de Dados Corrompido

Se o arquivo config.db estiver ilegível ou corrompido ao iniciar o programa, o sistema deve:

Exibir aviso ao usuário informando que o banco de dados está corrompido e será recriado
Recriar o banco de dados vazio
Continuar a execução normalmente

Os layouts salvos anteriormente serão perdidos neste cenário.

10.2.2 — Migração de Schema

O banco de dados deve conter uma tabela de controle de versão (schema_version) com o número da versão atual do schema. A cada inicialização, o sistema deve verificar a versão e aplicar migrations automáticas quando necessário, garantindo compatibilidade com versões anteriores do banco.

10.3 Dados Armazenados

O sistema deve armazenar:

Layouts personalizados

10.4 Entidade: Layout

Cada layout é exclusivo de um tipo de arquivo (csv ou xlsx). As configurações variam conforme o tipo.

Campos comuns:

Campo	Tipo	Descrição
id	inteiro	Identificador único
nome	texto	Nome do layout
tipo	texto	Tipo do arquivo: `csv` ou `xlsx`

Campos exclusivos de layouts CSV:

Campo	Tipo	Descrição
delimitador	texto	Caractere delimitador (`,`, `;`, `\t`)
encoding	texto	Encoding do arquivo (`utf-8` ou `windows-1252`)
linha_cabecalho	inteiro	Número da linha do cabeçalho (base 1)
indice_numero	inteiro	Índice da coluna Numero (base 0)
indice_serie	inteiro	Índice da coluna Serie (base 0)
indice_valor	inteiro	Índice da coluna Valor (base 0, nulo se ausente)
indice_data	inteiro	Índice da coluna Data (base 0, nulo se ausente)

Campos exclusivos de layouts XLSX:

Campo	Tipo	Descrição
aba	texto	Nome ou índice da aba a ser processada
pos_numero	texto	Posição inicial da coluna Numero no formato `LetraLinha` (ex: `D3`)
pos_serie	texto	Posição inicial da coluna Serie no formato `LetraLinha` (ex: `B3`)
pos_valor	texto	Posição inicial da coluna Valor (nulo se ausente)
pos_data	texto	Posição inicial da coluna Data (nulo se ausente)

10.5 Requisitos Funcionais Relacionados

O sistema deve permitir:

Salvar layout

Listar layouts

Selecionar layout

Excluir layout

10.6 Interface do Usuário

Os layouts salvos devem ser exibidos em um menu dropdown.

O usuário deve poder:

Selecionar layout existente

Criar novo layout

Excluir layout

10.7 Requisitos Não Funcionais

O banco de dados deve:

Funcionar offline

Não depender de serviços externos

Não exigir configuração manual

Ser criado automaticamente pelo sistema

10.8 Futuras Expansões

O banco de dados poderá armazenar futuramente:

Histórico de análises

Relatórios

Configurações do usuário

11. Formato de Configuração (Import/Export)

Quando o usuário exportar ou importar um layout, o arquivo gerado será no formato JSON.

Esse formato é usado apenas para portabilidade entre dispositivos. O armazenamento interno é sempre via SQLite.

O campo tipo define qual conjunto de configurações está presente no arquivo.

Exemplo — layout CSV:

{
  "nome": "Layout Padrão CSV",
  "tipo": "csv",
  "delimitador": ";",
  "encoding": "utf-8",
  "linha_cabecalho": 1,
  "indice_numero": 3,
  "indice_serie": 1,
  "indice_valor": 5,
  "indice_data": null
}

Exemplo — layout XLSX:

{
  "nome": "Layout Padrão XLSX",
  "tipo": "xlsx",
  "aba": "Plan1",
  "pos_numero": "D3",
  "pos_serie": "B3",
  "pos_valor": "F3",
  "pos_data": null
}

12. Critérios de Aceite

O sistema será considerado funcional quando:

Importar planilha CSV com configurações de delimitador, encoding e linha de cabeçalho
Importar planilha XLSX com seleção de aba e posicionamento por LetraLinha
Detectar notas faltantes por série corretamente
Detectar duplicatas por série corretamente
Calcular soma total e soma por série corretamente
Exibir resultados agrupados por série com paginação
Exportar relatório de resultados para PDF
Salvar, carregar, selecionar e excluir layouts
Exportar e importar layouts via JSON
Exibir aviso de confirmação quando intervalo de faltantes exceder 10.000 por série

13. MVP — Versão Inicial

O MVP inclui o escopo completo descrito neste PRD:

Importar CSV e XLSX
Mapear colunas Numero, Serie, Valor e Data
Detectar notas faltantes por série
Detectar duplicatas por série
Calcular soma total e por série
Exibir resultados agrupados por série com paginação
Exportar relatório para PDF
Gerenciar layouts (salvar, carregar, excluir)
Exportar e importar layouts via JSON

14. Evoluções Futuras

Possíveis melhorias:

Integração com ERP
Histórico de análises
Automação de importação (monitorar pasta)
Exportação para CSV
Multiusuário

15. Definições

Nota

Documento com número sequencial.

Série

Agrupador independente de sequência.

Sequência

Ordem numérica crescente sem lacunas.

23 KiB Raw Blame History Unescape Escape

PRD — Comparador de Notas

1. Visão Geral

1.1 Nome do Produto

1.2 Descrição

2. Problema

3. Objetivos

3.1 Objetivo Principal

3.2 Objetivos Secundários

4. Escopo

4.1 Incluído

4.2 Não Incluído (MVP)

5. Modelo de Dados

6. Requisitos Funcionais

RF01 — Importação de Arquivo

RF01.1 — Configurações de Importação CSV

RF01.2 — Configurações de Importação XLSX

RF01.3 — Limite de Tamanho de Arquivo

RF02 — Configuração de Colunas

RF02.1 — Mapeamento CSV (índice numérico)

RF02.2 — Mapeamento XLSX (letra + linha)

Comportamento de Memória

Tratamento de Erros de Configuração

RF03 — Presets

Tipo de Layout

Conflito ao Importar Layout JSON

Erros na Importação de Layout JSON

Nome do Arquivo ao Exportar Layout

Limite de Layouts

RF04 — Detecção de Sequência

Regra de Detecção

Tratamento de Valores Não Numéricos

Número Zero

Escopo da Detecção

Proteção contra Intervalos Anormalmente Grandes

Tratamento de Série com Valor Inválido

RF05 — Detecção de Duplicidade

Exibição das Duplicatas

Impacto na Soma de Valores

RF06 — Soma de Valores

Formato de Valor Aceito

Formato de Exibição de Valores

RF07 — Exibição de Resultados

Organização dos Resultados

RF07.1 — Exportação de Relatório

RF08 — Gerenciamento de Layouts

7. Requisitos Não Funcionais

RNF01 — Plataforma

RNF02 — Execução Offline

RNF03 — Performance

RNF04 — Usabilidade

RNF05 — Idioma

RNF06 — Mensagens de Erro e Aviso

8. Fluxo do Usuário

9. Arquitetura Inicial Sugerida

9.1 Stack Tecnológica

10. Persistência de Dados

10.1 Visão Geral

10.2 Tecnologia

10.2.1 — Banco de Dados Corrompido

10.2.2 — Migração de Schema

10.3 Dados Armazenados

10.4 Entidade: Layout

10.5 Requisitos Funcionais Relacionados

10.6 Interface do Usuário

10.7 Requisitos Não Funcionais

10.8 Futuras Expansões

11. Formato de Configuração (Import/Export)

12. Critérios de Aceite

13. MVP — Versão Inicial

14. Evoluções Futuras

15. Definições

23 KiB

Raw Blame History