490 lines
12 KiB
Markdown
490 lines
12 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
{
|
||
"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.
|
||
|
||
---
|