Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, 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 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, text with broken encoding and near-duplicates in the catalog) 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.

Expand Down Expand Up @@ -53,7 +53,7 @@ erDiagram

produtos {
int id PK
varchar nome "text not validated (inv. 07)"
varchar nome "text not validated (inv. 07), no UNIQUE (inv. 08)"
numeric preco "CHECK >= 0"
varchar categoria "optional, text not validated (inv. 07)"
}
Expand Down Expand Up @@ -84,7 +84,7 @@ erDiagram
}
```

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.
The **inv. 01** to **inv. 08** notes mark the schema characteristic that is the root cause of each [investigated defect](#the-8-investigated-defects). For example, the missing `UNIQUE` on `email` and `documento` is what allows the duplicate customers of investigation 01.

---

Expand All @@ -105,7 +105,8 @@ sql-defect-investigation/
│ ├── 04-data-invalida/ # same structure
│ ├── 05-pagamento-duplicado/ # same structure
│ ├── 06-dados-de-mentira/ # same structure
│ └── 07-codificacao-quebrada/ # same structure
│ ├── 07-codificacao-quebrada/ # same structure
│ └── 08-duplicidade-aproximada/ # same structure
├── validacoes/ # value consistency rules (total, payment, catalog)
├── sql/
│ ├── 01_schema.sql # DDL: tables, FKs, constraints
Expand Down Expand Up @@ -176,7 +177,7 @@ Dependencies are kept up to date by **Dependabot** ([`.github/dependabot.yml`](.

---

## The 7 investigated defects
## The 8 investigated defects

| # | Defect | Simulated real-world scenario | Investigation |
|---|--------|-------------------------------|---------------|
Expand All @@ -187,6 +188,7 @@ Dependencies are kept up to date by **Dependabot** ([`.github/dependabot.yml`](.
| 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) |
| 8 | Near-duplicate in the catalog | The sales screen search is exact, did not find the product, and the sales rep created another one with a typo in the name | [Report](investigacoes/08-duplicidade-aproximada/README.md) |

The reports are in Portuguese.

Expand All @@ -201,6 +203,7 @@ The reports are in Portuguese.
| 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 |
| 8 | "Consultoria Avulsa (hora)" and "Consutoria avulsa - hora" are the same service, with its sales split between the two. No exact comparison links them, but text similarity (`pg_trgm`) gives 0.808, and the extension's default threshold (0.3) would flag legitimate plans as duplicates | `produtos.nome` has no uniqueness constraint, and the exact search on the sales screen pushes the rep into creating the product again |

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.

Expand All @@ -218,7 +221,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 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).
Besides the 8 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

Expand Down
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, 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.
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, texto com codificação quebrada e duplicidade aproximada no catálogo — 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.

Expand Down Expand Up @@ -49,7 +49,7 @@ erDiagram

produtos {
int id PK
varchar nome "texto sem validação (inv. 07)"
varchar nome "texto sem validação (inv. 07), sem UNIQUE (inv. 08)"
numeric preco "CHECK >= 0"
varchar categoria "opcional, texto sem validação (inv. 07)"
}
Expand Down Expand Up @@ -80,7 +80,7 @@ erDiagram
}
```

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.
As anotações **inv. 01** a **inv. 08** marcam a característica do schema que é a causa raiz de cada [defeito investigado](#os-8-defeitos-investigados). Por exemplo, a falta de `UNIQUE` em `email` e `documento` é o que permite os clientes duplicados da investigação 01.

---

Expand All @@ -101,7 +101,8 @@ sql-defect-investigation/
│ ├── 04-data-invalida/ # mesma estrutura
│ ├── 05-pagamento-duplicado/ # mesma estrutura
│ ├── 06-dados-de-mentira/ # mesma estrutura
│ └── 07-codificacao-quebrada/ # mesma estrutura
│ ├── 07-codificacao-quebrada/ # mesma estrutura
│ └── 08-duplicidade-aproximada/ # mesma estrutura
├── validacoes/ # regras de consistência de valores (total, pagamento, catálogo)
├── sql/
│ ├── 01_schema.sql # DDL: tabelas, FKs, constraints
Expand Down Expand Up @@ -172,7 +173,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.

---

## Os 7 defeitos investigados
## Os 8 defeitos investigados

| # | Defeito | Cenário real simulado | Investigação |
|---|---------|------------------------|--------------|
Expand All @@ -183,6 +184,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.
| 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) |
| 8 | Duplicidade aproximada no catálogo | A busca da tela de venda é exata, não achou o produto, e o vendedor cadastrou outro com o nome digitado errado | [Relatório](investigacoes/08-duplicidade-aproximada/README.md) |

### Principais achados

Expand All @@ -195,6 +197,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.
| 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 |
| 8 | "Consultoria Avulsa (hora)" e "Consutoria avulsa - hora" são o mesmo serviço, com as vendas divididas entre os dois. Nenhuma comparação exata os liga, mas a similaridade de texto (`pg_trgm`) dá 0.808, e o limite padrão da extensão (0.3) marcaria planos legítimos como duplicados | `produtos.nome` não tem nenhuma restrição de unicidade, e a busca exata da tela de venda empurra o vendedor a cadastrar de novo |

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.

Expand All @@ -212,7 +215,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 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).
Além dos 8 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

Expand Down
5 changes: 3 additions & 2 deletions investigacoes/07-codificacao-quebrada/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,9 @@ SELECT id, nome, categoria FROM produtos ORDER BY id;
| 6 | **Módulo de Relatórios** | Add-on |
| 7 | **Módulo de Integrações** | Add-on |
| 8 | **Suporte Prioritário** | Add-on |
| 9 | Consutoria avulsa - hora | Serviço |

**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.
**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. O produto `9` também está correto, porque foi cadastrado à mão, fora da sincronização. Ele é um cadastro duplicado do produto `5`, assunto da [investigação 08](../08-duplicidade-aproximada/README.md).

### Passo 2: os bytes de um nome certo e de um quebrado

Expand Down Expand Up @@ -134,7 +135,7 @@ GROUP BY pr.id, pr.nome;

- **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.
- **Relatórios:** a categoria "Serviço" é, para o banco, um texto **diferente** de "Serviço". Os dois produtos que vieram da sincronização estão em "Serviço", e o produto `9`, cadastrado à mão, está em "Serviço" correto. **A categoria já está dividida em duas**: qualquer relatório agrupado por categoria mostra "Serviço" e "Serviço" como se fossem categorias diferentes.
- **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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
["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"]
["8","Suporte Prioritário","Add-on"],
["9","Consutoria avulsa - hora","Serviço"]
]
},
{
Expand Down
Loading
Loading