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
10 changes: 5 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -41,16 +41,16 @@ jobs:
run: docker compose up -d --wait

# Confere que as três camadas (schema, massa válida e massa quebrada)
# foram carregadas: 10 clientes da massa válida + 1 duplicado = 11, e
# o pedido órfão da massa quebrada está lá.
# foram carregadas: 10 clientes da massa válida + 1 duplicado + 3 da
# investigação 06 = 14, e o pedido órfão da massa quebrada está lá.
- name: Conferir dados carregados
run: |
query() {
docker compose exec -T postgres psql -U postgres -d defect_investigation -tAc "$1"
}
clientes=$(query "SELECT COUNT(*) FROM clientes")
orfaos=$(query "SELECT COUNT(*) FROM pedidos p LEFT JOIN clientes c ON c.id = p.cliente_id WHERE c.id IS NULL")
echo "clientes: $clientes (esperado 11)"
echo "clientes: $clientes (esperado 14)"
echo "pedidos órfãos: $orfaos (esperado 1)"

marca() { [ "$1" = "$2" ] && echo "✅" || echo "❌"; }
Expand All @@ -59,14 +59,14 @@ jobs:
echo ""
echo "| Conferência | Esperado | Encontrado | |"
echo "|---|---|---|---|"
echo "| clientes carregados | 11 | $clientes | $(marca "$clientes" 11) |"
echo "| clientes carregados | 14 | $clientes | $(marca "$clientes" 14) |"
echo "| pedidos órfãos (massa quebrada) | 1 | $orfaos | $(marca "$orfaos" 1) |"
echo ""
} >> "$GITHUB_STEP_SUMMARY"

# Tem que ser a última linha: com bash -e, uma lista com && que
# falha só derruba o passo quando é o último comando.
[ "$clientes" = "11" ] && [ "$orfaos" = "1" ]
[ "$clientes" = "14" ] && [ "$orfaos" = "1" ]

# Roda cada exploracao.sql do jeito que o "Como reproduzir" dos
# relatórios ensina. Com ON_ERROR_STOP, o psql sai com erro na
Expand Down
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 and duplicate payments) 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 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 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 @@ -37,8 +37,8 @@ erDiagram
clientes {
int id PK
varchar nome
varchar email "no UNIQUE (inv. 01)"
varchar documento "no UNIQUE (inv. 01)"
varchar email "no UNIQUE (inv. 01), not validated (inv. 06)"
varchar documento "no UNIQUE (inv. 01), not validated (inv. 06)"
varchar telefone "optional"
timestamp data_cadastro
varchar status "ativo | inativo"
Expand Down Expand Up @@ -84,7 +84,7 @@ erDiagram
}
```

The **inv. 01** to **inv. 05** notes mark the schema characteristic that is the root cause of each [investigated defect](#the-5-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. 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.

---

Expand All @@ -103,7 +103,8 @@ sql-defect-investigation/
│ ├── 02-fk-orfa/ # same structure
│ ├── 03-status-inconsistente/ # same structure
│ ├── 04-data-invalida/ # same structure
│ └── 05-pagamento-duplicado/ # same structure
│ ├── 05-pagamento-duplicado/ # same structure
│ └── 06-dados-de-mentira/ # same structure
├── validacoes/ # value consistency rules (total, payment, catalog)
├── sql/
│ ├── 01_schema.sql # DDL: tables, FKs, constraints
Expand Down Expand Up @@ -174,7 +175,7 @@ Dependencies are kept up to date by **Dependabot** ([`.github/dependabot.yml`](.

---

## The 5 investigated defects
## The 6 investigated defects

| # | Defect | Simulated real-world scenario | Investigation |
|---|--------|-------------------------------|---------------|
Expand All @@ -183,6 +184,7 @@ Dependencies are kept up to date by **Dependabot** ([`.github/dependabot.yml`](.
| 3 | Inconsistent status | Order marked "delivered" without an approved payment; order "cancelled" with the payment still "approved" | [Report](investigacoes/03-status-inconsistente/README.md) |
| 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) |

The reports are in Portuguese.

Expand All @@ -195,6 +197,7 @@ The reports are in Portuguese.
| 3 | A cancelled order with its payment still approved (no refund), a delivered order with no confirmed payment, and order 10 confirmed with no payment | Order status and payment status change independently, and the database enforces no rule on them |
| 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 |

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 @@ -212,7 +215,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 5 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 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).

### 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 e pagamentos em duplicidade — 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 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.

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 All @@ -33,8 +33,8 @@ erDiagram
clientes {
int id PK
varchar nome
varchar email "sem UNIQUE (inv. 01)"
varchar documento "sem UNIQUE (inv. 01)"
varchar email "sem UNIQUE (inv. 01), sem validação (inv. 06)"
varchar documento "sem UNIQUE (inv. 01), sem validação (inv. 06)"
varchar telefone "opcional"
timestamp data_cadastro
varchar status "ativo | inativo"
Expand Down Expand Up @@ -80,7 +80,7 @@ erDiagram
}
```

As anotações **inv. 01** a **inv. 05** marcam a característica do schema que é a causa raiz de cada [defeito investigado](#os-5-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. 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.

---

Expand All @@ -99,7 +99,8 @@ sql-defect-investigation/
│ ├── 02-fk-orfa/ # mesma estrutura
│ ├── 03-status-inconsistente/ # mesma estrutura
│ ├── 04-data-invalida/ # mesma estrutura
│ └── 05-pagamento-duplicado/ # mesma estrutura
│ ├── 05-pagamento-duplicado/ # mesma estrutura
│ └── 06-dados-de-mentira/ # 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 @@ -170,7 +171,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.

---

## Os 5 defeitos investigados
## Os 6 defeitos investigados

| # | Defeito | Cenário real simulado | Investigação |
|---|---------|------------------------|--------------|
Expand All @@ -179,6 +180,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.
| 3 | Status inconsistente | Pedido marcado "entregue" sem pagamento aprovado; pedido "cancelado" com pagamento ainda "aprovado" | [Relatório](investigacoes/03-status-inconsistente/README.md) |
| 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) |

### Principais achados

Expand All @@ -189,6 +191,7 @@ As dependências são mantidas pelo **Dependabot** ([`.github/dependabot.yml`](.
| 3 | Um pedido cancelado com o pagamento ainda aprovado (sem estorno), um pedido entregue sem pagamento confirmado e o pedido 10 confirmado sem pagamento | Os status de pedido e de pagamento mudam de forma independente, e o banco não tem nenhuma regra sobre eles |
| 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" |

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 @@ -206,7 +209,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 5 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 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).

### Quando a massa de dados muda

Expand Down
Loading
Loading