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 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.

Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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.

---

Expand All @@ -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
Expand Down Expand Up @@ -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 |
|---|--------|-------------------------------|---------------|
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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

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 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.

Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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.

---

Expand All @@ -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
Expand Down Expand Up @@ -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 |
|---|---------|------------------------|--------------|
Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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

Expand Down
Loading
Loading