Create AGENTS.md

2026-03-04 18:18:11 -03:00
parent 06eca335db
commit 3af14ab957
9 changed files with 918 additions and 1012 deletions
@@ -0,0 +1,162 @@
+# Backlog de Features — Comparador de Notas
+
+> Features avaliadas em 03/03/2026. Organizadas por categoria e esforço estimado.
+
+## Alta Prioridade
+
+### F-01 — Exportar Resultado em CSV.
+
+**Problema:** O único formato de exportação é PDF. Para processar os resultados em ferramentas externas (Excel, Power BI, sistemas ERP), o usuário precisa redigitar dados do PDF.
+
+**Solução:** Botão "Exportar CSV" na tela de resultado, gerando dois arquivos (ou um com duas seções):
+- `faltantes.csv`: `serie,documento_tipo,numero`
+- `duplicatas.csv`: `serie,documento_tipo,numero,ocorrencias`
+
+**Escopo técnico:**
+- `use case` `exportar_csv(resultado: &ResultadoAnalise, caminho: &Path)`
+- Trait `CsvExporter` análoga à `PdfGenerator` (opcional, para testabilidade)
+- Botão na barra de ações da tela `resultado.rs`
+- Dependência `csv` já está no `Cargo.toml`
+
+**Esforço estimado:** Médio (2–3h)
+**Impacto:** Alto — elimina retrabalho manual
+
+**Observações:** 
+Se não for muito custoso para implementar, pode ser uma boa ideia adicionar uma essa função.
+
+---
+
+### F-02 — Validação de Tamanho de Arquivo (PRD RF01.3) (Implementado)
+
+**Status:** Já implementado. Ambos `csv_reader.rs` e `xlsx_reader.rs` verificam o tamanho do arquivo
+antes de qualquer leitura via constante `LIMITE_BYTES = 50 MB`, retornando `ErroArquivo::TamanhoExcedido`
+se excedido — exibido como modal de erro pela UI.
+
+**Esforço estimado:** Baixo (30min) — *concluído*
+**Impacto:** Médio — evita travamentos inesperados
+
+---
+
+## Média Prioridade
+
+### F-03 — Preview de Colunas Antes da Análise (Isso já existe?)
+
+**Problema:** Erros de mapeamento de colunas (índice errado, encoding incorreto) só são descobertos depois da importação, que pode falhar silenciosamente com "0 notas válidas".
+
+**Solução:** Na tela de configuração de colunas, exibir uma tabela das primeiras 5 linhas mostrando como os campos serão interpretados, com highlight em células que falhariam o parse.
+
+**Escopo técnico:**
+- Função `pre_visualizar(caminho, layout, n_linhas: usize) -> Vec<LinhaPreview>`
+- `LinhaPreview`: `{ numero: Result<u64>, serie: Result<String>, valor: Result<Decimal>, ... }`
+- Widget de tabela em `configuracao_colunas.rs`
+- Atualizar preview ao mudar qualquer campo de configuração (via `changed()`)
+
+**Esforço estimado:** Alto (4–6h)
+**Impacto:** Alto — reduz drasticamente "por que não importou nada?"
+
+**Observações:** 
+Verificar se já existe no codigo, pois na tela de configuração do Layout ele exibe as 5 primeiras linhas do arquivo.
+
+---
+
+### F-04 — Busca por Número na Tela de Resultado (Util)
+
+**Problema:** Com listas longas, o usuário precisa navegar páginas para verificar se um número específico está faltante ou duplicado.
+
+**Solução:** Campo de busca no topo da tela de resultado. Ao digitar `1234`, destaca se a nota:
+- está **faltante** (aparece na lista de faltantes)
+- está **duplicada** (aparece na lista de duplicatas)
+- está **presente** (está nas notas importadas)
+- **não encontrada** (fora do intervalo conhecido)
+
+**Escopo técnico:**
+- Campo `filtro_numero: String` no `App`
+- Busca em `resultado.faltantes_por_serie` e `resultado.duplicadas_por_serie`
+- Para "presente": busca em `app.notas_importadas` (já mantido em memória)
+- Banner de resultado no topo da tela
+
+**Esforço estimado:** Médio (2–3h)
+**Impacto:** Médio — uso diário em auditorias pontuais
+
+---
+
+### F-05 — Recarregar Arquivo Sem Reconfigurar (Implementado)
+
+**Problema:** Quando o usuário corrige o arquivo fonte e quer re-verificar, precisa navegar todo o fluxo novamente (selecionar arquivo → configurar colunas → analisar).
+
+**Solução:** Botão "🔄 Reanalisar Arquivo" na tela de resultado que reimporta o mesmo caminho com o mesmo layout atual, sem nenhuma interação adicional.
+
+**Escopo técnico:**
+- Persistir `caminho_arquivo_atual: Option<PathBuf>` no `App` (já existe parcialmente como `nome_arquivo`)
+- Reaproveitar o fluxo de `executar_importacao()` com os parâmetros atuais
+- Botão na barra de ações da tela `resultado.rs`
+
+**Esforço estimado:** Baixo (1h)
+**Impacto:** Médio — elimina atrito no ciclo corrigir → verificar
+
+---
+
+### F-06 — Auto-detecção de Delimitador CSV (Util)
+
+**Problema:** O usuário precisa saber antecipadamente qual delimitador o arquivo usa (`,`, `;`, `\t`). Arquivos gerados por diferentes sistemas variam.
+
+**Solução:** Ao selecionar o arquivo CSV, amostrar as primeiras 5 linhas e contar ocorrências de cada delimitador candidato. Sugerir o mais frequente como padrão, mantendo a ComboBox editável.
+
+**Escopo técnico:**
+- Função `detectar_delimitador(primeiras_linhas: &[&str]) -> char`
+- Chamar na transição para `ConfigurandoColunas` quando `TipoArquivo::Csv`
+- Pré-selecionar na ComboBox sem impedir mudança manual
+
+**Esforço estimado:** Médio (2h)
+**Impacto:** Baixo-Médio — reduz um passo de configuração na maioria dos casos
+
+---
+
+## Baixa Prioridade
+
+### F-07 — Auto-detecção de Encoding CSV (Util)
+
+**Problema:** Arquivos gerados por sistemas legados brasileiros frequentemente usam `windows-1252`, mas o padrão selecionado é `utf-8`. O usuário descobre o problema somente ao ver caracteres estranhos nos dados.
+
+**Solução:** Tentar ler as primeiras linhas em `utf-8`; se houver erro de decodificação, sugerir automaticamente `windows-1252` com aviso visual na tela de configuração.
+
+**Escopo técnico:**
+- Função `detectar_encoding(caminho: &Path) -> String`
+- Usar `encoding_rs` (já dependência) para tentar decode e verificar `had_errors`
+- Aviso na tela de configuração: "Encoding detectado: windows-1252"
+
+**Esforço estimado:** Médio (2h)
+**Impacto:** Baixo — problema raro, mas confuso quando ocorre
+
+---
+
+### F-09 — Paginação Automática de Faltantes no PDF (Util)
+
+**Problema:** PDFs com muitos faltantes (ex: 5.000 números) geram um único bloco de texto muito longo, difícil de ler e imprimir.
+
+**Solução:** No `pdf_generator.rs`, ao adicionar a lista de faltantes, agrupar em intervalos contíguos (usando a função `agrupar_contiguos` já implementada) e formatar como `100–104 (5 notas)`. Reduz drasticamente o tamanho do PDF e melhora legibilidade.
+
+**Escopo técnico:**
+- Importar `agrupar_contiguos` em `pdf_generator.rs`
+- Substituir o `join(", ")` atual pelo formato de intervalos
+- Sem novas dependências
+
+**Esforço estimado:** Baixo (30min)
+**Impacto:** Baixo-Médio — melhora legibilidade de PDFs com muitos faltantes
+
+> **Nota:** Esta feature é especialmente fácil porque a lógica de agrupamento já existe — é só aplicar no PDF.
+
+---
+
+## Resumo
+
+| ID | Feature | Esforço | Impacto | Prioridade | Status |
+|---|---|---|---|---|---|
+| F-01 | Exportar resultado em CSV | Médio | Alto | Alta |
+| F-02 | Validação de tamanho de arquivo | Baixo | Médio | Alta |
+| F-03 | Preview de colunas antes da análise | Alto | Alto | Média |
+| F-04 | Busca por número no resultado | Médio | Médio | Média |
+| F-06 | Recarregar arquivo sem reconfigurar | Baixo | Médio | Média |
+| F-07 | Auto-detecção de delimitador CSV | Médio | Baixo-Médio | Média |
+| F-08 | Auto-detecção de encoding CSV | Médio | Baixo | Baixa |
+| F-09 | Agrupamento de faltantes no PDF | Baixo | Baixo-Médio | Baixa | ✅ Implementado |
@@ -0,0 +1,353 @@
+# FIX — Salvar Layout no Banco de Dados
+
+**Data:** 04/03/2026  
+**Versão do PRD:** 1.7  
+**Status:** Pendente de Implementação
+
+---
+
+## Sumário dos Problemas
+
+| # | Severidade | Arquivo(s) | Descrição |
+|---|-----------|------------|-----------|
+| 1 | **Crítico** | `migrations.rs` | `migration_v3` sem transação — falha parcial deixa banco permanentemente quebrado |
+| 2 | **Crítico** | `migrations.rs` | `schema_version` atualizada fora da transação das migrations |
+| 3 | **Crítico** | `usecases/layouts.rs` | Erros SQL mapeados como `ErroLayout::JsonMalformado` — mensagem completamente enganosa |
+| 4 | Moderado | `layout_repository.rs` | `delimitador` TAB salvo como byte de controle invisível no banco |
+| 5 | Moderado | `usecases/layouts.rs` | `pos_numero` / `pos_serie` XLSX podem ser strings vazias — sem validação no fluxo de save da UI |
+| 6 | Moderado | `layout_repository.rs` | Índices posicionais hardcoded em `row.get(N)` — quebra silenciosa se colunas do SELECT forem reordenadas |
+| 7 | Menor | `usecases/layouts.rs` + `layout_repository.rs` | Renomear layout para nome já existente (UPDATE) gera `JsonMalformado` em vez de `NomeConflitante` |
+| 8 | Menor | `connection.rs` | `SELECT 1` não detecta corrupção real de páginas SQLite |
+| 9 | Menor | `layout_repository.rs` | UPDATE não zera campos do tipo oposto ao tipo atual do layout |
+
+---
+
+## Problema 1 (Crítico) — `migration_v3` sem transação atômica
+
+### Local
+`src/infrastructure/sqlite/migrations.rs` — função `migration_v3`
+
+### Situação Atual
+```rust
+fn migration_v3(conn: &Connection) -> Result<()> {
+    conn.execute_batch(
+        "ALTER TABLE layouts ADD COLUMN indice_documento_tipo INTEGER;
+         ALTER TABLE layouts ADD COLUMN pos_documento_tipo TEXT;",
+    )?;
+    Ok(())
+}
+```
+
+`execute_batch` executa os dois `ALTER TABLE` sem transação explícita. Se o processo for interrompido após o primeiro e antes do segundo, o banco fica em estado parcial:
+
+- `indice_documento_tipo` existe, `pos_documento_tipo` não existe.
+- A versão no banco não é atualizada (o erro propaga antes).
+- Na próxima execução, `migration_v3` tenta adicionar `indice_documento_tipo` novamente → SQLite retorna `"duplicate column name"` → **o app nunca mais inicializa sem intervenção manual**.
+
+### Correção Necessária
+Envolver cada migration em uma transação explícita e atualizar `schema_version` **dentro da mesma transação**:
+
+```rust
+fn migration_v3(conn: &Connection) -> Result<()> {
+    conn.execute_batch("
+        BEGIN;
+        ALTER TABLE layouts ADD COLUMN indice_documento_tipo INTEGER;
+        ALTER TABLE layouts ADD COLUMN pos_documento_tipo TEXT;
+        UPDATE schema_version SET versao = 3;
+        COMMIT;
+    ")?;
+    Ok(())
+}
+```
+
+> **Nota:** O SQLite suporta `ALTER TABLE` dentro de transação explícita desde a versão 3.x. `execute_batch` executa múltiplos statements quando delimitados por `;` dentro do mesmo bloco `BEGIN/COMMIT`.
+
+---
+
+## Problema 2 (Crítico) — `schema_version` atualizada fora da transação das migrations
+
+### Local
+`src/infrastructure/sqlite/migrations.rs` — função `aplicar_migrations`
+
+### Situação Atual
+O fluxo atual é:
+1. Executa `migration_v1(conn)?`
+2. Executa `migration_v2(conn)?`
+3. Executa `migration_v3(conn)?`
+4. **Depois** executa `INSERT OR REPLACE INTO schema_version ...`
+
+Se qualquer migration falhar após outras já terem sido aplicadas, a versão não é atualizada, causando re-execução problemática na próxima abertura.
+
+### Correção Necessária
+Cada migration deve atualizar `schema_version` internamente (dentro de sua própria transação), como mostrado no Problema 1. A função `aplicar_migrations` não deve mais atualizar a versão centralmente — ela apenas chama as migrations que ainda não foram aplicadas.
+
+Adicionalmente, as migrations v1 e v2 devem seguir o mesmo padrão:
+
+```rust
+fn migration_v1(conn: &Connection) -> Result<()> {
+    conn.execute_batch("
+        BEGIN;
+        CREATE TABLE IF NOT EXISTS layouts ( ... );
+        INSERT OR REPLACE INTO schema_version (id, versao) VALUES (1, 1);
+        COMMIT;
+    ")?;
+    Ok(())
+}
+
+fn migration_v2(conn: &Connection) -> Result<()> {
+    conn.execute_batch("
+        BEGIN;
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_layouts_nome ON layouts (nome);
+        -- renomeia duplicatas existentes se houver
+        UPDATE schema_version SET versao = 2;
+        COMMIT;
+    ")?;
+    Ok(())
+}
+```
+
+---
+
+## Problema 3 (Crítico) — Erros SQL mapeados como `ErroLayout::JsonMalformado`
+
+### Local
+`src/application/usecases/layouts.rs` — função `salvar_layout` e `atualizar_layout`
+
+### Situação Atual
+```rust
+layout_repository::salvar(conn, layout)
+    .map_err(|e| ErroLayout::JsonMalformado(e.to_string()))?;
+
+layout_repository::atualizar(conn, layout)
+    .map_err(|e| ErroLayout::JsonMalformado(e.to_string()))?;
+```
+
+Qualquer erro do banco de dados (violação de constraint, coluna ausente, banco travado) é apresentado ao usuário como **"JSON malformado"**, o que é completamente incorreto. Exemplos de mensagens enganosas que o usuário veria:
+
+- `"UNIQUE constraint failed: layouts.nome"` → exibido como "JSON malformado"
+- `"no such column: pos_documento_tipo"` → exibido como "JSON malformado"
+- `"attempt to write a readonly database"` → exibido como "JSON malformado"
+
+### Correção Necessária
+
+1. Adicionar variante própria em `domain/errors.rs`:
+```rust
+pub enum ErroLayout {
+    // ... variantes existentes ...
+    ErroBanco(String),       // erros genéricos de I/O do banco
+    NomeConflitante,         // já existe (para uso tanto em INSERT quanto em UPDATE)
+}
+```
+
+2. No use case, inspecionar o erro antes de mapear:
+```rust
+layout_repository::salvar(conn, layout)
+    .map_err(|e| {
+        let msg = e.to_string();
+        if msg.contains("UNIQUE constraint failed") {
+            ErroLayout::NomeConflitante
+        } else {
+            ErroLayout::ErroBanco(msg)
+        }
+    })?;
+```
+
+3. Na UI (`ui/screens/layouts.rs`), tratar `ErroBanco` com mensagem clara ao usuário: `"Erro ao salvar no banco de dados: {mensagem}"`.
+
+---
+
+## Problema 4 (Moderado) — `delimitador` TAB salvo como byte de controle no banco
+
+### Local
+`src/infrastructure/sqlite/layout_repository.rs` — funções `salvar` e `atualizar` (CSV)
+
+### Situação Atual
+O `char` `'\t'` é convertido para `String` via `.to_string()`, armazenando um caractere de tabulação literal (byte `0x09`) no campo `TEXT` do banco. Embora funcional, é opaco para inspeção manual do banco e incompatível com exports/backups que não preservam bytes de controle.
+
+### Correção Necessária
+Normalizar o delimitador para um token legível antes de salvar:
+
+```rust
+// Ao salvar:
+let delim_str = match config.delimitador {
+    '\t' => "tab".to_string(),
+    c    => c.to_string(),
+};
+
+// Ao ler:
+let delimitador = match delim_str.as_str() {
+    "tab" => '\t',
+    s     => s.chars().next().unwrap_or(';'),
+};
+```
+
+> Isso também melhora a legibilidade dos arquivos JSON de export/import de layouts.
+
+---
+
+## Problema 5 (Moderado) — `pos_numero` e `pos_serie` XLSX sem validação no fluxo de save da UI
+
+### Local
+`src/application/usecases/layouts.rs` — função `salvar_layout`
+
+### Situação Atual
+A validação atual verifica apenas que `nome` não esteja vazio. Os campos `pos_numero` e `pos_serie` de layouts XLSX são `String` obrigatórias (não `Option<String>`), mas podem ser strings vazias `""`. O banco os aceita sem restrição, e o erro só apareceria na análise, sem indicar que o layout está incompleto.
+
+### Correção Necessária
+Expandir a validação no use case `salvar_layout`:
+
+```rust
+match layout {
+    Layout::Csv { config, .. } => {
+        // indice_numero e indice_serie são usize — sempre válidos se presentes
+        // nenhuma validação adicional necessária aqui
+    }
+    Layout::Xlsx { config, .. } => {
+        if config.pos_numero.trim().is_empty() {
+            return Err(ErroLayout::CampoObrigatorioAusente("pos_numero".to_string()));
+        }
+        if config.pos_serie.trim().is_empty() {
+            return Err(ErroLayout::CampoObrigatorioAusente("pos_serie".to_string()));
+        }
+    }
+}
+```
+
+---
+
+## Problema 6 (Moderado) — Índices posicionais hardcoded em `row.get(N)`
+
+### Local
+`src/infrastructure/sqlite/layout_repository.rs` — função `listar`
+
+### Situação Atual
+O mapeamento usa índices numéricos (`row.get(0)`, `row.get(1)`, ..., `row.get(16)`). Qualquer reordenação das colunas no `SELECT` quebra silenciosamente o mapeamento sem erro de compilação.
+
+### Correção Necessária
+Substituir por nomes de colunas usando `row.get::<_, T>(nome_coluna)`:
+
+```rust
+// Em vez de:
+let id: i64 = row.get(0)?;
+let nome: String = row.get(1)?;
+
+// Usar:
+let id: i64 = row.get("id")?;
+let nome: String = row.get("nome")?;
+```
+
+O `rusqlite` suporta `row.get("nome_coluna")` desde a versão 0.26. A versão usada no projeto é 0.32, portanto compatível.
+
+---
+
+## Problema 7 (Menor) — Renomear para nome conflitante em UPDATE gera mensagem errada
+
+### Local
+`src/application/usecases/layouts.rs` + `src/infrastructure/sqlite/layout_repository.rs`
+
+### Situação Atual
+No fluxo de UPDATE (re-save de layout existente), não há verificação de conflito de nome antes de chamar `atualizar`. Se o usuário renomear um layout para um nome já em uso, a constraint `UNIQUE` do banco rejeita o UPDATE, o erro é mapeado como `JsonMalformado` (Problema 3 acima).
+
+### Correção Necessária
+No use case `atualizar_layout`, verificar se o novo nome conflita com outro layout (excluindo o próprio ID):
+
+```rust
+// Verificar conflito excluindo o próprio registro
+if layout_repository::existe_nome_excluindo_id(conn, layout.nome(), layout.id())? {
+    return Err(ErroLayout::NomeConflitante);
+}
+```
+
+Adicionar função no repository:
+```rust
+pub fn existe_nome_excluindo_id(conn: &Connection, nome: &str, id: Option<i64>) -> Result<bool> {
+    match id {
+        Some(id) => {
+            let count: i64 = conn.query_row(
+                "SELECT COUNT(*) FROM layouts WHERE nome = ?1 AND id != ?2",
+                params![nome, id],
+                |row| row.get(0),
+            )?;
+            Ok(count > 0)
+        }
+        None => layout_repository::existe_nome(conn, nome),
+    }
+}
+```
+
+---
+
+## Problema 8 (Menor) — `SELECT 1` não detecta corrupção real do banco
+
+### Local
+`src/infrastructure/sqlite/connection.rs`
+
+### Situação Atual
+```rust
+match conn.execute_batch("SELECT 1;") {
+    Ok(_) => return Ok((conn, false)),
+    Err(_) => { /* trata como banco corrompido */ }
+}
+```
+
+`SELECT 1` não acessa nenhuma página de dados do SQLite. Um banco com tabelas corrompidas, índices inválidos ou páginas com checksum errado passaria nessa verificação sem ser detectado, causando erros inesperados posteriormente.
+
+### Correção Necessária
+```rust
+match conn.execute_batch("PRAGMA quick_check;") {
+    Ok(_) => return Ok((conn, false)),
+    Err(_) => { /* banco corrompido */ }
+}
+```
+
+`PRAGMA quick_check` verifica a integridade estrutural do banco (sem verificar cada valor de dado, como `integrity_check` faz). É mais rápido que `integrity_check` e muito mais confiável que `SELECT 1`.
+
+---
+
+## Problema 9 (Menor) — UPDATE não zera campos do tipo oposto
+
+### Local
+`src/infrastructure/sqlite/layout_repository.rs` — função `atualizar`
+
+### Situação Atual
+O UPDATE de CSV não zera campos XLSX (`aba`, `pos_numero`, etc.) e o UPDATE de XLSX não zera campos CSV. Na prática não ocorre troca de tipo, mas se ocorrer (via importação JSON com mesmo nome e tipo diferente + sobrescrita), os campos do tipo anterior ficam no banco.
+
+### Correção Necessária
+Adicionar `SET campo = NULL` explícito para os campos do tipo oposto em cada UPDATE:
+
+```sql
+-- UPDATE CSV: zerar campos XLSX
+UPDATE layouts SET
+    nome = ?1, delimitador = ?2, encoding = ?3, linha_cabecalho = ?4,
+    indice_numero = ?5, indice_serie = ?6, indice_valor = ?7,
+    indice_data = ?8, indice_documento_tipo = ?9,
+    -- zerar campos XLSX:
+    aba = NULL, pos_numero = NULL, pos_serie = NULL,
+    pos_valor = NULL, pos_data = NULL, pos_documento_tipo = NULL
+WHERE id = ?10
+```
+
+```sql
+-- UPDATE XLSX: zerar campos CSV
+UPDATE layouts SET
+    nome = ?1, aba = ?2, pos_numero = ?3, pos_serie = ?4,
+    pos_valor = ?5, pos_data = ?6, pos_documento_tipo = ?7,
+    -- zerar campos CSV:
+    delimitador = NULL, encoding = NULL, linha_cabecalho = NULL,
+    indice_numero = NULL, indice_serie = NULL, indice_valor = NULL,
+    indice_data = NULL, indice_documento_tipo = NULL
+WHERE id = ?8
+```
+
+---
+
+## Ordem de Implementação Recomendada
+
+1. **Problema 1 + 2** (migrations com transação) — Risco de banco permanentemente inutilizável; implementar primeiro.
+2. **Problema 3** (mapeamento de erros) — Sem isso o usuário não entende o que está errado.
+3. **Problema 5** (validação de campos XLSX) — Evita layouts inválidos serem salvos.
+4. **Problema 7** (conflito de nome em UPDATE) — Depende da solução do Problema 3.
+5. **Problema 4** (delimitador TAB) — Melhoria de robustez; não causa crash.
+6. **Problema 6** (índices posicionais) — Refactor preventivo.
+7. **Problema 8** (PRAGMA quick_check) — Melhoria de confiabilidade.
+8. **Problema 9** (zerar campos opostos) — Limpeza defensiva.