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
17 changes: 10 additions & 7 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, 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 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, near-duplicates in the catalog and mixed time zones in dates) 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 @@ -62,7 +62,7 @@ erDiagram
int id PK
int cliente_id FK "NOT VALID in the broken dataset (inv. 02)"
int vendedor_id FK "optional"
timestamp data_pedido
timestamp data_pedido "no time zone (inv. 09)"
varchar status "no CHECK (inv. 03)"
numeric valor_total "= sum of items (validacoes/)"
}
Expand All @@ -79,12 +79,12 @@ erDiagram
int id PK "only identifier: no gateway transaction id (inv. 05)"
int pedido_id FK
numeric valor
timestamp data_pagamento "optional, not validated (inv. 04)"
timestamp data_pagamento "optional, not validated (inv. 04), no time zone (inv. 09)"
varchar status "no CHECK (inv. 03)"
}
```

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

---

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

---

## The 8 investigated defects
## The 9 investigated defects

| # | Defect | Simulated real-world scenario | Investigation |
|---|--------|-------------------------------|---------------|
Expand All @@ -189,6 +190,7 @@ Dependencies are kept up to date by **Dependabot** ([`.github/dependabot.yml`](.
| 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) |
| 9 | Mixed time zones in dates | The mobile app stores the order date in UTC, while the website and the payment gateway store Brasília time, in a column that does not keep the time zone | [Report](investigacoes/09-fuso-horario/README.md) |

The reports are in Portuguese.

Expand All @@ -204,6 +206,7 @@ The reports are in Portuguese.
| 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 |
| 9 | Two orders placed through the app at 10:30 and 11:10 pm on Jan 31 show up in February, with the payment 2h55 "before" the order. Removing the 3-hour offset puts the payment back in the normal pattern (5 minutes later). January is R$ 149.80 below the real figure | The date columns are `timestamp without time zone` and do not keep the time zone, so UTC and Brasília time mix without the database noticing |

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 @@ -221,7 +224,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 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).
Besides the 9 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
17 changes: 10 additions & 7 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, 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.
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, duplicidade aproximada no catálogo e fuso horário misturado nas datas — 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 @@ -58,7 +58,7 @@ erDiagram
int id PK
int cliente_id FK "NOT VALID na massa quebrada (inv. 02)"
int vendedor_id FK "opcional"
timestamp data_pedido
timestamp data_pedido "sem fuso (inv. 09)"
varchar status "sem CHECK (inv. 03)"
numeric valor_total "= soma dos itens (validacoes/)"
}
Expand All @@ -75,12 +75,12 @@ erDiagram
int id PK "único identificador: sem id da transação do gateway (inv. 05)"
int pedido_id FK
numeric valor
timestamp data_pagamento "opcional, sem validação (inv. 04)"
timestamp data_pagamento "opcional, sem validação (inv. 04), sem fuso (inv. 09)"
varchar status "sem CHECK (inv. 03)"
}
```

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

---

Expand All @@ -102,7 +102,8 @@ sql-defect-investigation/
│ ├── 05-pagamento-duplicado/ # mesma estrutura
│ ├── 06-dados-de-mentira/ # mesma estrutura
│ ├── 07-codificacao-quebrada/ # mesma estrutura
│ └── 08-duplicidade-aproximada/ # mesma estrutura
│ ├── 08-duplicidade-aproximada/ # mesma estrutura
│ └── 09-fuso-horario/ # 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 @@ -173,7 +174,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.

---

## Os 8 defeitos investigados
## Os 9 defeitos investigados

| # | Defeito | Cenário real simulado | Investigação |
|---|---------|------------------------|--------------|
Expand All @@ -185,6 +186,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.
| 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) |
| 9 | Fuso horário misturado nas datas | O app grava a data do pedido em UTC, enquanto o site e o gateway gravam no horário de Brasília, numa coluna que não guarda o fuso | [Relatório](investigacoes/09-fuso-horario/README.md) |

### Principais achados

Expand All @@ -198,6 +200,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.
| 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 |
| 9 | Dois pedidos feitos pelo app às 22:30 e 23:10 de 31/01 aparecem em fevereiro, com o pagamento 2h55 "antes" do pedido. Descontadas as 3 horas do fuso, o pagamento volta ao padrão normal (5 minutos depois). Janeiro fica R$ 149,80 abaixo do real | As colunas de data são `timestamp without time zone` e não guardam o fuso, então UTC e horário de Brasília se misturam sem o banco perceber |

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 @@ -215,7 +218,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 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).
Além dos 9 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
6 changes: 3 additions & 3 deletions investigacoes/02-fk-orfa/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Arquivos desta investigação:

## 1. Sintoma relatado

> Chamado do financeiro: o relatório "Vendas por cliente" fecha em **R$ 2.069,00**, mas o total de pedidos registrados no sistema é **R$ 2.168,90**. A diferença é de **R$ 99,90**.
> Chamado do financeiro: o relatório "Vendas por cliente" fecha em **R$ 2.218,80**, mas o total de pedidos registrados no sistema é **R$ 2.318,70**. A diferença é de **R$ 99,90**.

Dois relatórios que deveriam somar a mesma coisa e não batem. Antes de olhar dado, a primeira pergunta é: o que um relatório faz que o outro não faz?

Expand Down Expand Up @@ -46,7 +46,7 @@ SELECT

| qtd_pedidos_tabela | total_tabela | qtd_pedidos_relatorio | total_relatorio |
|---|---|---|---|
| 13 | 2168.90 | 12 | 2069.00 |
| 15 | 2318.70 | 14 | 2218.80 |

**Achado:** **H1 descartada.** Sem nenhum filtro, a divergência continua: o `JOIN` sozinho faz **1 pedido** e **R$ 99,90** sumirem. Um `JOIN` comum (`INNER JOIN`) só devolve as linhas que encontram correspondência dos dois lados, então algum pedido não tem cliente.

Expand Down Expand Up @@ -169,7 +169,7 @@ O banco não tem trilha de auditoria. Por isso, não é possível saber **quem**

## 6. Correção proposta

> **Não executada.** Fica como recomendação. O caminho B, seguido do `VALIDATE`, foi testado numa cópia descartável do banco: depois dele, a FK fica `validada = true`, a detecção retorna 0 órfãos e os dois totais do chamado passam a bater (R$ 2.168,90 nos dois).
> **Não executada.** Fica como recomendação. O caminho B, seguido do `VALIDATE`, foi testado numa cópia descartável do banco: depois dele, a FK fica `validada = true`, a detecção retorna 0 órfãos e os dois totais do chamado passam a bater (R$ 2.318,70 nos dois).

### 6.1 Tratar o pedido órfão: decisão do negócio

Expand Down
2 changes: 1 addition & 1 deletion investigacoes/02-fk-orfa/resultado-esperado.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"consulta": 1,
"colunas": ["qtd_pedidos_tabela","total_tabela","qtd_pedidos_relatorio","total_relatorio"],
"linhas": [
["13","2168.90","12","2069.00"]
["15","2318.70","14","2218.80"]
]
},
{
Expand Down
4 changes: 2 additions & 2 deletions investigacoes/03-status-inconsistente/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,9 @@ GROUP BY status_pedido, situacao_pagamento;
|---|---|---|---|---|
| cancelado | **aprovado** | 1 | 12 | ❌ |
| cancelado | estornado | 1 | 4 | ✅ |
| confirmado | aprovado | 3 | 3, 7, 13 | ✅ |
| confirmado | aprovado | 4 | 3, 7, 13, 15 | ✅ |
| confirmado | **sem pagamento** | 1 | 10 | ❌ |
| entregue | aprovado | 4 | 1, 2, 5, 8 | ✅ |
| entregue | aprovado | 5 | 1, 2, 5, 8, 14 | ✅ |
| entregue | **pendente** | 1 | 11 | ❌ |
| pendente | sem pagamento | 2 | 6, 9 | ✅ |

Expand Down
4 changes: 2 additions & 2 deletions investigacoes/03-status-inconsistente/resultado-esperado.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@
"linhas": [
["cancelado","aprovado","1","12"],
["cancelado","estornado","1","4"],
["confirmado","aprovado","3","3, 7, 13"],
["confirmado","aprovado","4","3, 7, 13, 15"],
["confirmado","sem pagamento","1","10"],
["entregue","aprovado","4","1, 2, 5, 8"],
["entregue","aprovado","5","1, 2, 5, 8, 14"],
["entregue","pendente","1","11"],
["pendente","sem pagamento","2","6, 9"]
]
Expand Down
Loading
Loading