Felipe/comparador-notas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
82e3f40c4f2f96b1ff4a8a331bded79daa03ed03
comparador-notas/PRD.md
T

12 KiB
Raw Blame History

PRD — Comparador de Notas

Versão: 1.1 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
  • Detecção de quebras de sequência
  • Detecção de duplicidades
  • Soma de valores
  • Agrupamento por série
  • Relatório visual
  • Salvar layouts personalizados
  • Carregar layouts salvos
  • Selecionar layout por menu dropdown
  • Excluir layouts

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 via índice de coluna.

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 — Limite de Tamanho de Arquivo

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

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 sistema deve permitir ao usuário definir, via índice numérico (posição da coluna), qual coluna representa cada campo:

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

Tratamento de Erros de Configuração

Situação Comportamento
Índice 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

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

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):

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

Escopo da Detecção

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

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.

RF06 — Soma de Valores

O sistema deve calcular:

  • Soma total
  • Soma por série

RF07 — Exibição de Resultados

O sistema deve exibir:

  • Lista de notas faltantes
  • Lista de duplicadas
  • Totais

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.

8. Fluxo do Usuário

Fluxo principal:

  1. Usuário abre o sistema
  2. Usuário importa planilha
  3. Usuário configura colunas
  4. Usuário executa análise
  5. 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

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 localmente no dispositivo do usuário.

Exemplo:

config.db

10.3 Dados Armazenados

O sistema deve armazenar:

Layouts personalizados

10.4 Entidade: Layout

Campos:

Campo Tipo Descrição

id inteiro Identificador único nome texto Nome do layout coluna_numero texto Nome da coluna do número coluna_serie texto Nome da coluna da série coluna_valor texto Nome da coluna do valor coluna_data texto Nome da coluna da data

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.

Exemplo de arquivo JSON exportado:

{
  "nome": "Layout Padrão",
  "coluna_numero": "Nota",
  "coluna_serie": "Serie",
  "coluna_valor": "Valor",
  "coluna_data": "Data"
}

12. Critérios de Aceite

O sistema será considerado funcional quando:

  • Importar planilha
  • Detectar notas faltantes corretamente
  • Calcular totais corretamente
  • Permitir configuração

13. MVP — Versão Inicial

Escopo mínimo:

  • Importar CSV
  • Mapear coluna Número
  • Detectar faltantes
  • Exibir resultado

14. Evoluções Futuras

Possíveis melhorias:

  • Exportação de relatório
  • Exportação PDF
  • Integração com ERP
  • Banco de dados
  • Automação

15. Definições

Nota

Documento com número sequencial.

Série

Agrupador independente de sequência.

Sequência

Ordem numérica crescente sem lacunas.

Reference in New Issue View Git Blame Copy Permalink