adiciona arquivos de configuração iniciais e estrutura do projeto

2026-03-02 16:58:55 -03:00
commit 82e3f40c4f
5 changed files with 506 additions and 0 deletions
@@ -0,0 +1,489 @@
+# 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.
+
+---