diff --git a/README.en.md b/README.en.md index 94322d2..d2b1db2 100644 --- a/README.en.md +++ b/README.en.md @@ -8,7 +8,7 @@ ## Description -This repository simulates a sales CRM/ERP database with real-world data defects (duplicate customers, orphaned foreign keys, inconsistent statuses, invalid dates, duplicate payments and fake values in required fields) and documents the SQL investigations that find each one of them. It uses the same method applied when investigating production bugs: symptom → hypotheses → queries and evidence → root cause → impact → proposed fix. +This repository simulates a sales CRM/ERP database with real-world data defects (duplicate customers, orphaned foreign keys, inconsistent statuses, invalid dates, duplicate payments, fake values in required fields and text with broken encoding) and documents the SQL investigations that find each one of them. It uses the same method applied when investigating production bugs: symptom → hypotheses → queries and evidence → root cause → impact → proposed fix. This is not a SQL syntax exercise. The goal is to show how to use SQL to **find real defects** in a database whose data is already corrupted, the way it would happen while investigating a bug reported in production. @@ -53,9 +53,9 @@ erDiagram produtos { int id PK - varchar nome + varchar nome "text not validated (inv. 07)" numeric preco "CHECK >= 0" - varchar categoria "optional" + varchar categoria "optional, text not validated (inv. 07)" } pedidos { @@ -84,7 +84,7 @@ erDiagram } ``` -The **inv. 01** to **inv. 06** notes mark the schema characteristic that is the root cause of each [investigated defect](#the-6-investigated-defects). For example, the missing `UNIQUE` on `email` and `documento` is what allows the duplicate customers of investigation 01. +The **inv. 01** to **inv. 07** notes mark the schema characteristic that is the root cause of each [investigated defect](#the-7-investigated-defects). For example, the missing `UNIQUE` on `email` and `documento` is what allows the duplicate customers of investigation 01. --- @@ -104,7 +104,8 @@ sql-defect-investigation/ │ ├── 03-status-inconsistente/ # same structure │ ├── 04-data-invalida/ # same structure │ ├── 05-pagamento-duplicado/ # same structure -│ └── 06-dados-de-mentira/ # same structure +│ ├── 06-dados-de-mentira/ # same structure +│ └── 07-codificacao-quebrada/ # same structure ├── validacoes/ # value consistency rules (total, payment, catalog) ├── sql/ │ ├── 01_schema.sql # DDL: tables, FKs, constraints @@ -175,7 +176,7 @@ Dependencies are kept up to date by **Dependabot** ([`.github/dependabot.yml`](. --- -## The 6 investigated defects +## The 7 investigated defects | # | Defect | Simulated real-world scenario | Investigation | |---|--------|-------------------------------|---------------| @@ -185,6 +186,7 @@ Dependencies are kept up to date by **Dependabot** ([`.github/dependabot.yml`](. | 4 | Invalid date | Payment entered by hand during reconciliation with a mistyped date, earlier than the order itself | [Report](investigacoes/04-data-invalida/README.md) | | 5 | Duplicate payment | The gateway resent the payment confirmation (webhook) and the application recorded both, with no idempotency key | [Report](investigacoes/05-pagamento-duplicado/README.md) | | 6 | Fake values in required fields | In phone sales sign-ups, email and CPF (Brazilian taxpayer ID) are required, and the agent typed filler values when the customer did not provide them | [Report](investigacoes/06-dados-de-mentira/README.md) | +| 7 | Text with broken encoding (mojibake) | The catalog sync with the ERP read a UTF-8 file as Windows-1252 | [Report](investigacoes/07-codificacao-quebrada/README.md) | The reports are in Portuguese. @@ -198,6 +200,7 @@ The reports are in Portuguese. | 4 | A payment dated 48h before its own order, at the exact same time of day, which skews the time-to-approval metric | Manual entry with a mistyped date, with no date validation and no record of where the entry came from | | 5 | Order 2 has two identical approved payments, 4 seconds apart: the system records R$ 199.80 received for a single R$ 99.90 transaction at the gateway | The `pagamentos` table does not store the gateway transaction id, so a resent webhook becomes a new payment | | 6 | Three sign-ups rejected by the credit check: two with the email `naotem@naotem.com` ("don't have one") and fake CPFs (which **pass** the check-digit test), and one with two CPF digits swapped | `NOT NULL` only ensures the field is not empty: nothing validates its content, and the form offers no "not provided" option | +| 7 | Products named like "Módulo de Relatórios" in the emails of 5 orders, while "Plano Básico Mensal" is still correct: the defect is in the data, not in how it is displayed | The ERP sync reads the UTF-8 file as Windows-1252; the reverse operation restores the original text exactly, which proves the diagnosis | Each report ends with a proposed fix, tested on a disposable copy of the database but **not applied**: as in a real investigation, QA delivers evidence and a recommendation, and the decision to change the data belongs to the responsible team. @@ -215,7 +218,7 @@ Change the folder to run the other investigations. Each defect is implemented and commented in `sql/03_seed_quebrado.sql`. Each investigation lives in `investigacoes/`, with a full report and the detection query (`deteccao.sql`), which the CI runs against both datasets. That way, what is documented is exactly what is tested. -Besides the 6 defects, the validation also checks value consistency rules (order total = sum of its items, approved payments = order total, and item price equal to the catalog price in the control dataset). The rules, and the reason for each one, are in [`validacoes/`](validacoes/README.md) (in Portuguese). +Besides the 7 defects, the validation also checks value consistency rules (order total = sum of its items, approved payments = order total, and item price equal to the catalog price in the control dataset). The rules, and the reason for each one, are in [`validacoes/`](validacoes/README.md) (in Portuguese). ### When the data changes diff --git a/README.md b/README.md index 050ed79..65b82b0 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ ## Descrição -Este repositório simula um banco de dados de CRM/ERP de vendas com defeitos de dados reais — clientes duplicados, foreign keys órfãs, status inconsistentes, datas inválidas, pagamentos em duplicidade e valores de mentira em campos obrigatórios — e documenta as investigações SQL que encontram cada um deles, com a mesma metodologia usada em investigação de bugs de produção: sintoma → hipóteses → queries e evidências → causa raiz → impacto → correção proposta. +Este repositório simula um banco de dados de CRM/ERP de vendas com defeitos de dados reais — clientes duplicados, foreign keys órfãs, status inconsistentes, datas inválidas, pagamentos em duplicidade, valores de mentira em campos obrigatórios e texto com codificação quebrada — e documenta as investigações SQL que encontram cada um deles, com a mesma metodologia usada em investigação de bugs de produção: sintoma → hipóteses → queries e evidências → causa raiz → impacto → correção proposta. Não é um exercício de sintaxe SQL: o objetivo é demonstrar a habilidade de usar SQL para **encontrar defeito real** num banco com dados já corrompidos, do jeito que aconteceria investigando um bug relatado em produção. @@ -49,9 +49,9 @@ erDiagram produtos { int id PK - varchar nome + varchar nome "texto sem validação (inv. 07)" numeric preco "CHECK >= 0" - varchar categoria "opcional" + varchar categoria "opcional, texto sem validação (inv. 07)" } pedidos { @@ -80,7 +80,7 @@ erDiagram } ``` -As anotações **inv. 01** a **inv. 06** marcam a característica do schema que é a causa raiz de cada [defeito investigado](#os-6-defeitos-investigados). Por exemplo, a falta de `UNIQUE` em `email` e `documento` é o que permite os clientes duplicados da investigação 01. +As anotações **inv. 01** a **inv. 07** marcam a característica do schema que é a causa raiz de cada [defeito investigado](#os-7-defeitos-investigados). Por exemplo, a falta de `UNIQUE` em `email` e `documento` é o que permite os clientes duplicados da investigação 01. --- @@ -100,7 +100,8 @@ sql-defect-investigation/ │ ├── 03-status-inconsistente/ # mesma estrutura │ ├── 04-data-invalida/ # mesma estrutura │ ├── 05-pagamento-duplicado/ # mesma estrutura -│ └── 06-dados-de-mentira/ # mesma estrutura +│ ├── 06-dados-de-mentira/ # mesma estrutura +│ └── 07-codificacao-quebrada/ # mesma estrutura ├── validacoes/ # regras de consistência de valores (total, pagamento, catálogo) ├── sql/ │ ├── 01_schema.sql # DDL: tabelas, FKs, constraints @@ -171,7 +172,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](. --- -## Os 6 defeitos investigados +## Os 7 defeitos investigados | # | Defeito | Cenário real simulado | Investigação | |---|---------|------------------------|--------------| @@ -181,6 +182,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](. | 4 | Data inválida | Pagamento lançado à mão na conciliação com a data digitada errada, anterior ao próprio pedido | [Relatório](investigacoes/04-data-invalida/README.md) | | 5 | Pagamento em duplicidade | O gateway reenviou a confirmação do pagamento (webhook) e a aplicação registrou as duas, sem chave de idempotência | [Relatório](investigacoes/05-pagamento-duplicado/README.md) | | 6 | Valores de mentira em campos obrigatórios | No cadastro por televendas, e-mail e CPF são obrigatórios, e o atendente digitou valores de preenchimento quando o cliente não informou | [Relatório](investigacoes/06-dados-de-mentira/README.md) | +| 7 | Texto com codificação quebrada | A sincronização do catálogo com o ERP leu um arquivo UTF-8 como Windows-1252 | [Relatório](investigacoes/07-codificacao-quebrada/README.md) | ### Principais achados @@ -192,6 +194,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](. | 4 | Um pagamento datado 48h antes do próprio pedido, com o mesmo horário dele, o que distorce o indicador de tempo até aprovação | Lançamento manual com a data digitada errada, sem validação de data nem registro da origem | | 5 | O pedido 2 tem dois pagamentos aprovados idênticos, com 4 segundos de diferença: o sistema registra R$ 199,80 recebidos para uma única transação de R$ 99,90 no gateway | A tabela `pagamentos` não guarda o id da transação do gateway, então um webhook reenviado vira um pagamento novo | | 6 | Três cadastros barrados na análise de crédito: dois com o e-mail `naotem@naotem.com` e CPFs de mentira (que **passam** no dígito verificador) e um com dois dígitos do CPF trocados | `NOT NULL` só garante que o campo não está vazio: nada valida o conteúdo, e o formulário não oferece "não informado" | +| 7 | Produtos com nomes como "Módulo de Relatórios" em e-mails de 5 pedidos, enquanto o "Plano Básico Mensal" continua certo: o defeito está no dado, não na exibição | A sincronização com o ERP lê o arquivo UTF-8 como Windows-1252, e a operação inversa devolve o texto original exatamente, o que prova o diagnóstico | Cada relatório termina com uma correção proposta, testada numa cópia descartável do banco, mas **não executada**: como numa investigação real, o QA entrega evidência e recomendação, e a decisão de mexer nos dados é do time responsável. @@ -209,7 +212,7 @@ Basta trocar a pasta para rodar as outras investigações. Cada defeito está implementado e comentado em `sql/03_seed_quebrado.sql`. Cada investigação fica em `investigacoes/`, com um relatório completo e a query de detecção (`deteccao.sql`), que a CI executa contra as duas massas de dados. Assim, o que está documentado é exatamente o que é testado. -Além dos 6 defeitos, a validação confere regras de consistência de valores (total do pedido = soma dos itens, pagamentos aprovados = total do pedido, e o preço do item igual ao do catálogo na massa de controle). As regras e o motivo de cada uma estão em [`validacoes/`](validacoes/README.md). +Além dos 7 defeitos, a validação confere regras de consistência de valores (total do pedido = soma dos itens, pagamentos aprovados = total do pedido, e o preço do item igual ao do catálogo na massa de controle). As regras e o motivo de cada uma estão em [`validacoes/`](validacoes/README.md). ### Quando a massa de dados muda diff --git a/investigacoes/07-codificacao-quebrada/README.md b/investigacoes/07-codificacao-quebrada/README.md new file mode 100644 index 0000000..9f8c826 --- /dev/null +++ b/investigacoes/07-codificacao-quebrada/README.md @@ -0,0 +1,187 @@ +# Investigação 07 — Texto com codificação quebrada (mojibake) + +| | | +|---|---| +| **Defeito** | Nomes e categorias de produtos gravados com caracteres trocados: "Módulo de Relatórios" em vez de "Módulo de Relatórios" | +| **Registros afetados** | 5 campos em 5 produtos: o nome dos produtos `6`, `7` e `8` e a categoria dos produtos `4` e `5` | +| **Causa raiz** | A sincronização do catálogo com o ERP recebe um arquivo em UTF-8, mas o importador o lê como Windows-1252 | +| **Severidade** | Média: não há perda financeira, mas o texto errado aparece para o cliente (e-mails, documentos) e quebra buscas e relatórios por categoria | +| **Status** | Diagnóstico concluído, com correção proposta e **não executada** | + +Arquivos desta investigação: + +- [`exploracao.sql`](exploracao.sql): as queries na ordem em que foram usadas, numeradas conforme os passos abaixo. +- [`deteccao.sql`](deteccao.sql): a query final de detecção, que procura texto quebrado em todas as colunas de texto do banco. É a mesma query que a CI executa. + +--- + +## 1. Sintoma relatado + +> Chamado de suporte: o cliente **Henrique Lopes Teixeira** enviou o print do e-mail de confirmação do pedido 7, em que o produto aparece como **"Módulo de Relatórios"**. + +Esse tipo de texto tem nome: **mojibake**, ou texto lido com a codificação errada. A pergunta é onde a troca aconteceu: no envio do e-mail, na exibição ou no próprio dado. + +## 2. Hipóteses iniciais + +| # | Hipótese | Como confirmar ou descartar | +|---|---|---| +| H1 | O problema está só no e-mail (template ou programa de e-mail do cliente) | Ver como o nome está gravado no banco | +| H2 | O banco (ou a conexão com ele) usa a codificação errada | Se fosse isso, **todo** texto acentuado estaria quebrado, e os bytes gravados estariam certos | +| H3 | O texto foi gravado já quebrado, por um processo que leu UTF-8 como Windows-1252 | Desfazer essa troca específica e ver se o texto volta exatamente ao original | +| H4 | O problema não se limita a esse produto | Procurar o padrão em todas as colunas de texto do banco | + +## 3. Investigação + +### Passo 1: o catálogo como está gravado + +```sql +SELECT id, nome, categoria FROM produtos ORDER BY id; +``` + +| id | nome | categoria | +|---|---|---| +| 1 | Plano Básico Mensal | Assinatura | +| 2 | Plano Profissional Mensal | Assinatura | +| 3 | Plano Enterprise Mensal | Assinatura | +| 4 | Pacote de Onboarding | **Serviço** | +| 5 | Consultoria Avulsa (hora) | **Serviço** | +| 6 | **Módulo de Relatórios** | Add-on | +| 7 | **Módulo de Integrações** | Add-on | +| 8 | **Suporte Prioritário** | Add-on | + +**Achado:** **H1 descartada.** O nome já está gravado errado no banco, e o e-mail só mostra o que recebeu. O detalhe mais importante é o produto `1`: **"Plano Básico Mensal" está correto**, com o "á" no lugar. Uma parte dos acentos está certa e outra está quebrada. + +### Passo 2: os bytes de um nome certo e de um quebrado + +Em UTF-8, uma letra acentuada ocupa 2 bytes. Comparando os bytes gravados: + +```sql +SELECT id, nome, length(nome) AS caracteres, + octet_length(convert_to(nome, 'UTF8')) AS bytes_utf8, + encode(convert_to(nome, 'UTF8'), 'hex') AS bytes_hex +FROM produtos +WHERE id IN (1, 6); +``` + +| id | nome | caracteres | bytes_utf8 | bytes_hex | +|---|---|---|---|---| +| 1 | Plano Básico Mensal | 19 | 20 | 506c616e6f2042**c3a1**7369636f204d656e73616c | +| 6 | Módulo de Relatórios | 22 | 26 | 4d**c383c2b3**64756c6f2064652052656c6174**c383c2b3**72696f73 | + +- No produto `1`, o "á" é `c3 a1`: os 2 bytes corretos do "á" em UTF-8. +- No produto `6`, o "ó" (que seria `c3 b3`) virou `c3 83 c2 b3`, ou seja, **dois caracteres**: "Ã" (`c3 83`) e "³" (`c2 b3`). O nome passou de 20 para 22 caracteres. + +**Achado:** **H2 descartada.** Se a codificação do banco ou da conexão estivesse errada, os bytes gravados estariam certos e só a exibição sairia trocada, e isso valeria para todos os acentos. Aqui, os bytes do produto `1` estão certos, e os do `6` contêm, de fato, os caracteres errados. **O defeito está no dado, não na exibição.** + +### Passo 3: prova do diagnóstico + +O padrão do passo 2 é a assinatura de um erro específico. Os 2 bytes UTF-8 de cada letra (`c3 b3`) foram lidos como Windows-1252, em que cada byte é um caractere (`c3` = "Ã", `b3` = "³"), e regravados em UTF-8. Se o diagnóstico estiver certo, a operação inversa (voltar o texto para os bytes Windows-1252 e reler como UTF-8) devolve o texto original **exatamente**. O teste só lê, sem alterar nada: + +```sql +SELECT id, nome AS gravado, + convert_from(convert_to(nome, 'WIN1252'), 'UTF8') AS relido_como_utf8 +FROM produtos +WHERE nome ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]'; +``` + +| id | gravado | relido_como_utf8 | +|---|---|---| +| 6 | Módulo de Relatórios | Módulo de Relatórios | +| 7 | Módulo de Integrações | Módulo de Integrações | +| 8 | Suporte Prioritário | Suporte Prioritário | + +**Achado:** **H3 confirmada.** A inversão devolve o texto perfeito. Isso só acontece se a troca foi exatamente "UTF-8 lido como Windows-1252". Qualquer outra causa (outra codificação, digitação, corrupção) não seria desfeita por essa operação. + +### Passo 4: é isolado? + +A detecção procura o padrão em **todas** as colunas de texto do banco: um "Ã" ou "Â" seguido de um caractere que só aparece nesse tipo de erro. Um "Ã" legítimo do português, como em "SÃO PAULO" ou "CORAÇÃO", é seguido de letra e não é marcado. Isso foi testado com casos de borda, e "IRMÃ," e "CORAÇÃO" ficaram de fora, enquanto "João" e "ÉRICA" foram marcados. A query completa está em [`deteccao.sql`](deteccao.sql). + +| tabela | registro_id | coluna | valor | +|---|---|---|---| +| produtos | 4 | categoria | Serviço | +| produtos | 5 | categoria | Serviço | +| produtos | 6 | nome | Módulo de Relatórios | +| produtos | 7 | nome | Módulo de Integrações | +| produtos | 8 | nome | Suporte Prioritário | + +**Achado:** **H4 descartada** fora do catálogo. Clientes e vendedores, inclusive nomes acentuados como "Fábio", "João" e "Patrícia", estão corretos. No catálogo, o padrão atinge só alguns produtos, e o "Plano Básico Mensal" continua certo. Isso é compatível com a sincronização semanal com o ERP, que regrava apenas os produtos alterados no ERP naquela semana. A lista de produtos enviados em cada sincronização, no log da integração, confirma quais foram atingidos. + +### Passo 5: impacto — onde o texto quebrado aparece + +```sql +SELECT pr.id AS produto_id, pr.nome AS produto, COUNT(i.id) AS qtd_itens, + array_to_string(array_agg(DISTINCT i.pedido_id ORDER BY i.pedido_id), ', ') AS pedidos +FROM produtos pr +LEFT JOIN itens_pedido i ON i.produto_id = pr.id +WHERE pr.nome ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]' +GROUP BY pr.id, pr.nome; +``` + +| produto_id | produto | qtd_itens | pedidos | +|---|---|---|---| +| 6 | Módulo de Relatórios | 3 | 1, 7, 12 | +| 7 | Módulo de Integrações | 1 | 6 | +| 8 | Suporte Prioritário | 1 | 11 | + +**Achado:** 5 pedidos (`1`, `6`, `7`, `11` e `12`) mostram nomes quebrados em qualquer documento gerado a partir do catálogo: e-mails, segunda via, nota. O pedido 7 é o do chamado. + +## 4. Causa raiz + +1. **Integração (causa raiz):** o importador da sincronização do catálogo lê o arquivo do ERP como Windows-1252, a codificação padrão do servidor em que ele roda, mas o arquivo é UTF-8. O importador não declara a codificação do arquivo e depende do padrão da máquina. +2. **Banco (por que passou):** para o banco, "Módulo" é um texto válido como qualquer outro. Nenhuma regra impede gravar a combinação típica de mojibake. + +## 5. Impacto + +- **Cliente:** nomes de produto quebrados em e-mails e documentos de 5 pedidos, o que passa uma imagem de sistema malfeito. +- **Busca:** quem procurar "Módulo" no catálogo não encontra os produtos `6` e `7`. +- **Relatórios:** a categoria "Serviço" é, para o banco, um texto **diferente** de "Serviço". Hoje os dois produtos da categoria estão quebrados, então ela só aparece com o nome errado. Mas basta a próxima sincronização regravar só um deles, ou um produto novo entrar certo, para a categoria se dividir em duas linhas em qualquer relatório agrupado por categoria. +- **Reincidência:** como a causa está no importador, **a próxima sincronização quebra de novo** qualquer produto acentuado que for alterado no ERP. + +## 6. Correção proposta + +> **Não executada.** A correção foi testada numa cópia descartável do banco. Os 5 textos voltaram exatamente ao original (comparação texto a texto). A detecção passou a retornar 0 linhas, e uma nova gravação quebrada passou a ser bloqueada pela `CHECK`. + +### 6.1 Corrigir o importador (antes de tudo) + +Fazer o importador **declarar** que o arquivo é UTF-8, em vez de depender do padrão do servidor. Sem isso, qualquer correção nos dados dura só até a próxima sincronização. + +### 6.2 Reverter o texto quebrado + +```sql +BEGIN; + +UPDATE produtos +SET nome = convert_from(convert_to(nome, 'WIN1252'), 'UTF8') +WHERE nome ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]'; + +UPDATE produtos +SET categoria = convert_from(convert_to(categoria, 'WIN1252'), 'UTF8') +WHERE categoria ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]'; + +COMMIT; +``` + +- **O filtro (`WHERE`) é obrigatório.** Aplicada num texto que já está certo, a mesma operação **quebra** o texto ou dá erro. Testado: no "Plano Básico Mensal", o PostgreSQL recusa com `invalid byte sequence for encoding "UTF8"`. Com o filtro, a correção só toca o texto quebrado. +- **Pode rodar mais de uma vez:** depois da primeira execução, nenhum texto casa mais com o filtro, então uma segunda execução não faz nada. +- **Limite:** algumas letras maiúsculas acentuadas, como "Á" e "Í", geram em UTF-8 um byte que **não existe** no Windows-1252. Dependendo do importador, esse byte vira "?" ou é descartado, e a informação se perde. Nesses casos, a reversão automática não funciona, e o texto precisa ser corrigido à mão a partir da origem (o ERP). Não é o caso de nenhum dos 5 campos daqui. + +### 6.3 Impedir que volte + +```sql +ALTER TABLE produtos ADD CONSTRAINT produtos_texto_sem_mojibake CHECK ( + nome !~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]' + AND (categoria IS NULL OR categoria !~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]') +); +``` + +- Testado: depois da correção, uma nova gravação com o mesmo erro é recusada pelo banco. A sincronização passa a **falhar com erro**, em vez de gravar texto quebrado em silêncio, e o problema aparece no primeiro produto, e não no chamado de um cliente. +- **Ordem:** a `CHECK` só pode ser criada depois da reversão (6.2). +- **Monitoramento:** rodar o [`deteccao.sql`](deteccao.sql) depois de cada sincronização. Ele cobre também clientes e vendedores, que podem receber o mesmo erro por outra integração. + +## 7. Como reproduzir + +Com o banco no ar (`docker compose up -d --wait`, ver o [README principal](../../README.md)): + +```bash +docker compose exec -T postgres psql -U postgres -d defect_investigation < investigacoes/07-codificacao-quebrada/exploracao.sql +``` diff --git a/investigacoes/07-codificacao-quebrada/deteccao.sql b/investigacoes/07-codificacao-quebrada/deteccao.sql new file mode 100644 index 0000000..05298e6 --- /dev/null +++ b/investigacoes/07-codificacao-quebrada/deteccao.sql @@ -0,0 +1,28 @@ +-- Detecção: texto com codificação quebrada (mojibake) em qualquer coluna +-- de texto do banco. +-- +-- Quando um texto UTF-8 é lido como Windows-1252, cada letra acentuada +-- vira dois caracteres: "Ã" ou "Â" seguido de um caractere de pontuação +-- ou símbolo ("ó" vira "ó", "ç" vira "ç", "ã" vira "ã"). Essa +-- combinação praticamente não existe em português escrito certo: um "Ã" +-- legítimo, como em "SÃO PAULO", é seguido de letra. +-- +-- O segundo caractere vem de duas faixas: U+00A1 a U+00BF (¡ a ¿, das +-- minúsculas acentuadas) e os símbolos que o Windows-1252 coloca nos +-- bytes 0x80 a 0x9F (€, ‰, “, Š..., das maiúsculas acentuadas). +-- +-- Cada linha é uma coluna de um registro com texto quebrado. +-- Resultado esperado: zero linhas. + +WITH textos (tabela, registro_id, coluna, valor) AS ( + SELECT 'clientes', id, 'nome', nome FROM clientes + UNION ALL SELECT 'clientes', id, 'email', email FROM clientes + UNION ALL SELECT 'vendedores', id, 'nome', nome FROM vendedores + UNION ALL SELECT 'vendedores', id, 'equipe', equipe FROM vendedores + UNION ALL SELECT 'produtos', id, 'nome', nome FROM produtos + UNION ALL SELECT 'produtos', id, 'categoria', categoria FROM produtos +) +SELECT tabela, registro_id, coluna, valor +FROM textos +WHERE valor ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]' +ORDER BY tabela, coluna, registro_id; diff --git a/investigacoes/07-codificacao-quebrada/exploracao.sql b/investigacoes/07-codificacao-quebrada/exploracao.sql new file mode 100644 index 0000000..20e42f9 --- /dev/null +++ b/investigacoes/07-codificacao-quebrada/exploracao.sql @@ -0,0 +1,59 @@ +-- Investigação 07 — Texto com codificação quebrada (mojibake) +-- Queries na ordem em que foram usadas na investigação. A numeração bate +-- com os passos do README.md desta pasta. + +-- Passo 1: o catálogo de produtos como está gravado no banco. +SELECT id, nome, categoria +FROM produtos +ORDER BY id; + +-- Passo 2: os bytes de um nome correto e de um nome quebrado. Cada letra +-- acentuada ocupa 2 bytes em UTF-8; no texto quebrado, ocupa 4. +SELECT + id, + nome, + length(nome) AS caracteres, + octet_length(convert_to(nome, 'UTF8')) AS bytes_utf8, + encode(convert_to(nome, 'UTF8'), 'hex') AS bytes_hex +FROM produtos +WHERE id IN (1, 6) +ORDER BY id; + +-- Passo 3: prova do diagnóstico — desfazer o erro só na leitura (sem +-- alterar nada): pegar o texto, voltar para os bytes Windows-1252 e +-- reler como UTF-8. +SELECT + id, + nome AS gravado, + convert_from(convert_to(nome, 'WIN1252'), 'UTF8') AS relido_como_utf8 +FROM produtos +WHERE nome ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]' +ORDER BY id; + +-- Passo 4: é isolado? Texto quebrado em todas as colunas de texto do +-- banco (mesma query de deteccao.sql). +WITH textos (tabela, registro_id, coluna, valor) AS ( + SELECT 'clientes', id, 'nome', nome FROM clientes + UNION ALL SELECT 'clientes', id, 'email', email FROM clientes + UNION ALL SELECT 'vendedores', id, 'nome', nome FROM vendedores + UNION ALL SELECT 'vendedores', id, 'equipe', equipe FROM vendedores + UNION ALL SELECT 'produtos', id, 'nome', nome FROM produtos + UNION ALL SELECT 'produtos', id, 'categoria', categoria FROM produtos +) +SELECT tabela, registro_id, coluna, valor +FROM textos +WHERE valor ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]' +ORDER BY tabela, coluna, registro_id; + +-- Passo 5: impacto — pedidos que têm itens dos produtos com nome quebrado +-- (são os que mostram o nome errado em e-mails e documentos). +SELECT + pr.id AS produto_id, + pr.nome AS produto, + COUNT(i.id) AS qtd_itens, + array_to_string(array_agg(DISTINCT i.pedido_id ORDER BY i.pedido_id), ', ') AS pedidos +FROM produtos pr +LEFT JOIN itens_pedido i ON i.produto_id = pr.id +WHERE pr.nome ~ '[ÃÂ][¡-¿€‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ]' +GROUP BY pr.id, pr.nome +ORDER BY pr.id; diff --git a/investigacoes/07-codificacao-quebrada/resultado-esperado.json b/investigacoes/07-codificacao-quebrada/resultado-esperado.json new file mode 100644 index 0000000..3c5fd40 --- /dev/null +++ b/investigacoes/07-codificacao-quebrada/resultado-esperado.json @@ -0,0 +1,53 @@ +[ + { + "consulta": 1, + "colunas": ["id","nome","categoria"], + "linhas": [ + ["1","Plano Básico Mensal","Assinatura"], + ["2","Plano Profissional Mensal","Assinatura"], + ["3","Plano Enterprise Mensal","Assinatura"], + ["4","Pacote de Onboarding","Serviço"], + ["5","Consultoria Avulsa (hora)","Serviço"], + ["6","Módulo de Relatórios","Add-on"], + ["7","Módulo de Integrações","Add-on"], + ["8","Suporte Prioritário","Add-on"] + ] + }, + { + "consulta": 2, + "colunas": ["id","nome","caracteres","bytes_utf8","bytes_hex"], + "linhas": [ + ["1","Plano Básico Mensal","19","20","506c616e6f2042c3a17369636f204d656e73616c"], + ["6","Módulo de Relatórios","22","26","4dc383c2b364756c6f2064652052656c6174c383c2b372696f73"] + ] + }, + { + "consulta": 3, + "colunas": ["id","gravado","relido_como_utf8"], + "linhas": [ + ["6","Módulo de Relatórios","Módulo de Relatórios"], + ["7","Módulo de Integrações","Módulo de Integrações"], + ["8","Suporte Prioritário","Suporte Prioritário"] + ] + }, + { + "consulta": 4, + "colunas": ["tabela","registro_id","coluna","valor"], + "linhas": [ + ["produtos","4","categoria","Serviço"], + ["produtos","5","categoria","Serviço"], + ["produtos","6","nome","Módulo de Relatórios"], + ["produtos","7","nome","Módulo de Integrações"], + ["produtos","8","nome","Suporte Prioritário"] + ] + }, + { + "consulta": 5, + "colunas": ["produto_id","produto","qtd_itens","pedidos"], + "linhas": [ + ["6","Módulo de Relatórios","3","1, 7, 12"], + ["7","Módulo de Integrações","1","6"], + ["8","Suporte Prioritário","1","11"] + ] + } +] diff --git a/scripts/validate.js b/scripts/validate.js index 8d65c42..1e08bf6 100644 --- a/scripts/validate.js +++ b/scripts/validate.js @@ -71,6 +71,13 @@ const CHECKS = [ esperadoValido: 0, esperadoQuebrado: 3, }, + { + // 5 na massa quebrada: o nome de 3 produtos e a categoria de outros 2. + label: 'textos com codificação quebrada (mojibake)', + sql: readDeteccao('07-codificacao-quebrada'), + esperadoValido: 0, + esperadoQuebrado: 5, + }, { // 1 na massa quebrada: o pedido 10 tem valor_total e nenhum item. label: 'pedidos com total diferente da soma dos itens', diff --git a/sql/01_schema.sql b/sql/01_schema.sql index fa11b97..b170edb 100644 --- a/sql/01_schema.sql +++ b/sql/01_schema.sql @@ -2,7 +2,8 @@ -- pedidos e pagamentos. Modelo propositalmente simples, mas realista o -- bastante pra sustentar os tipos de defeito investigados neste projeto -- (duplicidade, FK órfã, status inconsistente, data inválida, pagamento em --- duplicidade, valores de mentira em campos obrigatórios). +-- duplicidade, valores de mentira em campos obrigatórios, texto com +-- codificação quebrada). CREATE TABLE clientes ( id SERIAL PRIMARY KEY, diff --git a/sql/03_seed_quebrado.sql b/sql/03_seed_quebrado.sql index f4d5896..399a68a 100644 --- a/sql/03_seed_quebrado.sql +++ b/sql/03_seed_quebrado.sql @@ -1,4 +1,4 @@ --- Introduz, de propósito, os 6 tipos de defeito investigados neste projeto. +-- Introduz, de propósito, os 7 tipos de defeito investigados neste projeto. -- Cada bloco está comentado com o cenário real que ele simula. Execute -- depois de 01_schema.sql + 02_seed_valido.sql. @@ -101,3 +101,23 @@ INSERT INTO clientes (nome, email, documento, telefone, data_cadastro, status) V -- os dois CPFs passam no cálculo do dígito verificador. O CPF do Paulo é -- real, mas foi digitado com os dois últimos números trocados (o certo -- seria 14725836982), e o dígito verificador não fecha. + +-- ===================================================================== +-- DEFEITO 7: Texto com codificação quebrada (mojibake) +-- Cenário real: a sincronização semanal do catálogo com o ERP recebe um +-- arquivo em UTF-8, mas o importador o lê como Windows-1252 (o padrão do +-- servidor onde ele roda). Cada letra acentuada, que em UTF-8 ocupa 2 +-- bytes, vira 2 caracteres: "ó" vira "ó", "ç" vira "ç". Só os produtos +-- alterados no ERP naquela semana foram regravados. +-- O UPDATE abaixo reproduz exatamente esse erro: pega os bytes UTF-8 do +-- texto e os interpreta como Windows-1252. +-- ===================================================================== +UPDATE produtos +SET nome = convert_from(convert_to(nome, 'UTF8'), 'WIN1252') +WHERE id IN (6, 7, 8); +-- Módulo de Relatórios, Módulo de Integrações e Suporte Prioritário. + +UPDATE produtos +SET categoria = convert_from(convert_to(categoria, 'UTF8'), 'WIN1252') +WHERE id IN (4, 5); +-- Categoria "Serviço" do Pacote de Onboarding e da Consultoria Avulsa. diff --git a/validacoes/README.md b/validacoes/README.md index 49c6c08..481c09e 100644 --- a/validacoes/README.md +++ b/validacoes/README.md @@ -1,6 +1,6 @@ # Validações de consistência de valores -Regras sobre os **valores** de pedidos, itens e pagamentos que não fazem parte dos 6 defeitos investigados, mas que o `npm run validate` confere a cada execução (e a CI, a cada pull request). Cada arquivo é uma query que lista os registros que quebram a regra. +Regras sobre os **valores** de pedidos, itens e pagamentos que não fazem parte dos 7 defeitos investigados, mas que o `npm run validate` confere a cada execução (e a CI, a cada pull request). Cada arquivo é uma query que lista os registros que quebram a regra. | Arquivo | Regra | Massa válida | Massa quebrada | |---|---|---|---|