diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 68a8580..7c197d6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,8 +41,8 @@ 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() { @@ -50,7 +50,7 @@ jobs: } 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 "❌"; } @@ -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 diff --git a/README.en.md b/README.en.md index a2f9bbe..94322d2 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 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. @@ -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" @@ -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. --- @@ -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 @@ -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 | |---|--------|-------------------------------|---------------| @@ -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. @@ -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. @@ -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 diff --git a/README.md b/README.md index 3f2b874..050ed79 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 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. @@ -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" @@ -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. --- @@ -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 @@ -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 | |---|---------|------------------------|--------------| @@ -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 @@ -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. @@ -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 diff --git a/investigacoes/01-clientes-duplicados/README.md b/investigacoes/01-clientes-duplicados/README.md index a97f89c..13bd68a 100644 --- a/investigacoes/01-clientes-duplicados/README.md +++ b/investigacoes/01-clientes-duplicados/README.md @@ -45,8 +45,8 @@ ORDER BY id; | id | nome | email | documento | telefone | data_cadastro | status | |---|---|---|---|---|---|---| -| 1 | Ana Carolina Ferreira | ana.ferreira@example.com | 11122233344 | 11988887777 | 2026-01-10 09:15:00 | ativo | -| 11 | Ana C. Ferreira | ana.ferreira@example.com | 11122233344 | 11988887777 | 2026-01-10 09:17:32 | ativo | +| 1 | Ana Carolina Ferreira | ana.ferreira@example.com | 11122233396 | 11988887777 | 2026-01-10 09:15:00 | ativo | +| 11 | Ana C. Ferreira | ana.ferreira@example.com | 11122233396 | 11988887777 | 2026-01-10 09:17:32 | ativo | **Achado:** **H1 confirmada.** São dois registros com o mesmo e-mail, documento e telefone. @@ -59,29 +59,33 @@ Os detalhes do par também separam H2 de H3: ### Passo 2: o caso é isolado? -Para varrer a base toda, a busca é generalizada para comparar todos os clientes entre si, aos pares. Dois cuidados nessa query: +Para varrer a base toda, a busca é generalizada para comparar todos os clientes entre si, aos pares. Três cuidados nessa query: -- **Normalização:** o e-mail é comparado em minúsculas e sem espaços nas pontas, e o documento só pelos dígitos. Assim, cadastros como `Ana.Ferreira@Example.com` ou `111.222.333-44` também seriam pegos. +- **Normalização:** o e-mail é comparado em minúsculas e sem espaços nas pontas, e o documento só pelos dígitos. Assim, cadastros como `Ana.Ferreira@Example.com` ou `111.222.333-96` também seriam pegos. - **Cada par conta uma vez só:** a condição `a.id < b.id` evita que o mesmo par apareça duas vezes, uma como (1, 11) e outra como (11, 1). Ela também evita que um registro seja comparado com ele mesmo. +- **Valores de mentira não identificam ninguém:** na primeira versão da query, os clientes `13` e `14` (Roberto e Sandra) também apareciam como par, porque os dois têm o e-mail `naotem@naotem.com`. São pessoas diferentes, com CPFs diferentes, e o e-mail é um valor de preenchimento que o atendente digitou para conseguir salvar o cadastro. Esses valores viram `NULL` antes da comparação e nunca formam par. Eles são o tema da [investigação 06](../06-dados-de-mentira/README.md). ```sql +WITH identificadores AS ( + SELECT id, nome, data_cadastro, + CASE WHEN THEN NULL ELSE lower(trim(email)) END AS email, + CASE WHEN THEN NULL ELSE regexp_replace(documento, '\D', '', 'g') END AS documento + FROM clientes +) SELECT a.id AS id_original, b.id AS id_duplicado, ... -FROM clientes a -JOIN clientes b +FROM identificadores a +JOIN identificadores b ON a.id < b.id - AND ( - lower(trim(a.email)) = lower(trim(b.email)) - OR regexp_replace(a.documento, '\D', '', 'g') = regexp_replace(b.documento, '\D', '', 'g') - ); + AND (a.email = b.email OR a.documento = b.documento); ``` -A query completa está em [`deteccao.sql`](deteccao.sql). +A query completa, com as listas de valores de mentira, está em [`deteccao.sql`](deteccao.sql). | id_original | id_duplicado | nome_original | nome_duplicado | mesmo_email | mesmo_documento | intervalo | |---|---|---|---|---|---|---| | 1 | 11 | Ana Carolina Ferreira | Ana C. Ferreira | true | true | 00:02:32 | -**Achado:** **H4 descartada.** Hoje existe só esse par duplicado na base. Mesmo assim, a causa (passo 4) permite que o defeito se repita a qualquer momento. +**Achado:** **H4 descartada.** Descontado o falso positivo do e-mail de mentira, existe só esse par duplicado na base. Mesmo assim, a causa (passo 4) permite que o defeito se repita a qualquer momento. ### Passo 3: impacto — qual registro tem histórico? @@ -146,7 +150,7 @@ Corrigir só a aplicação não basta. Qualquer outro caminho de escrita (import ## 6. Correção proposta -> **Não executada.** Fica como recomendação para o time de desenvolvimento. O script foi testado numa cópia descartável do banco: depois dele, a detecção retorna 0 pares, o pedido da cliente continua vinculado ao registro `1`, e uma nova tentativa de cadastro com `' Ana.Ferreira@Example.com'` e `'111.222.333-44'` é bloqueada pelo banco. +> **Não executada.** Fica como recomendação para o time de desenvolvimento. O script foi testado numa cópia descartável do banco: depois dele, a detecção retorna 0 pares, o pedido da cliente continua vinculado ao registro `1`, e uma nova tentativa de cadastro com `' Ana.Ferreira@Example.com'` e `'111.222.333-96'` é bloqueada pelo banco. Os índices da seção 6.2 só podem ser criados depois da correção da [investigação 06](../06-dados-de-mentira/README.md) (ver "Ordem" abaixo). ### 6.1 Limpeza dos dados @@ -180,6 +184,7 @@ São índices únicos sobre **expressões** (e-mail normalizado, documento só c Pontos de atenção para aplicar em produção: - **Ordem:** a limpeza (6.1) precisa vir antes. Se ainda houver qualquer duplicado na base, o `CREATE UNIQUE INDEX` falha. Rode o [`deteccao.sql`](deteccao.sql) antes e confirme que ele retorna zero linhas. +- **Valores de mentira também barram o índice:** o índice único olha o valor cru, e não a lista de valores de mentira da detecção. Com os clientes `13` e `14` compartilhando `naotem@naotem.com`, o `CREATE UNIQUE INDEX` no e-mail **falha**, mesmo com a detecção zerada. A correção da [investigação 06](../06-dados-de-mentira/README.md), que troca esses valores por `NULL`, precisa ser aplicada antes. O índice único aceita vários `NULL`. - **Bloqueio:** num banco grande, o `CREATE UNIQUE INDEX` comum bloqueia escritas na tabela enquanto o índice é construído. Em produção, use `CREATE UNIQUE INDEX CONCURRENTLY`, que não bloqueia, mas não pode rodar dentro de uma transação. ### 6.3 Prevenção na aplicação diff --git a/investigacoes/01-clientes-duplicados/deteccao.sql b/investigacoes/01-clientes-duplicados/deteccao.sql index 3cebe1c..c9d0889 100644 --- a/investigacoes/01-clientes-duplicados/deteccao.sql +++ b/investigacoes/01-clientes-duplicados/deteccao.sql @@ -3,23 +3,51 @@ -- Cada linha é um par (id_original, id_duplicado). O e-mail é comparado -- sem diferenciar maiúsculas/minúsculas e sem espaços nas pontas, e o -- documento só pelos dígitos, para pegar também cadastros digitados com --- formatação diferente (ex.: "111.222.333-44" e "11122233344"). +-- formatação diferente (ex.: "111.222.333-96" e "11122233396"). +-- +-- Valores de mentira (ex.: "naotem@naotem.com", "000.000.000-00") não +-- identificam ninguém: dois clientes diferentes podem ter o mesmo. Por +-- isso, eles viram NULL antes da comparação e nunca formam um par. As +-- listas são as mesmas da investigação 06, que trata desses valores. -- -- Resultado esperado: zero linhas. Qualquer linha é um defeito. +WITH emails_de_mentira (parte) AS ( + VALUES ('naotem'), ('nao'), ('sememail'), ('semmail'), ('nenhum'), ('teste'), + ('naotem.com'), ('sememail.com'), ('teste.com'), ('email.com') +), +cpfs_de_sequencia (cpf) AS ( + VALUES ('12345678909'), ('01234567890'), ('98765432100') +), +identificadores AS ( + SELECT + id, + nome, + data_cadastro, + CASE + WHEN split_part(lower(trim(email)), '@', 1) IN (SELECT parte FROM emails_de_mentira) + OR split_part(lower(trim(email)), '@', 2) IN (SELECT parte FROM emails_de_mentira) + THEN NULL + ELSE lower(trim(email)) + END AS email, + CASE + WHEN regexp_replace(documento, '\D', '', 'g') ~ '^(\d)\1{10}$' + OR regexp_replace(documento, '\D', '', 'g') IN (SELECT cpf FROM cpfs_de_sequencia) + THEN NULL + ELSE regexp_replace(documento, '\D', '', 'g') + END AS documento + FROM clientes +) SELECT a.id AS id_original, b.id AS id_duplicado, a.nome AS nome_original, b.nome AS nome_duplicado, - lower(trim(a.email)) = lower(trim(b.email)) AS mesmo_email, - regexp_replace(a.documento, '\D', '', 'g') = regexp_replace(b.documento, '\D', '', 'g') AS mesmo_documento, + a.email = b.email AS mesmo_email, + a.documento = b.documento AS mesmo_documento, b.data_cadastro - a.data_cadastro AS intervalo_entre_cadastros -FROM clientes a -JOIN clientes b +FROM identificadores a +JOIN identificadores b ON a.id < b.id - AND ( - lower(trim(a.email)) = lower(trim(b.email)) - OR regexp_replace(a.documento, '\D', '', 'g') = regexp_replace(b.documento, '\D', '', 'g') - ) + AND (a.email = b.email OR a.documento = b.documento) ORDER BY a.id, b.id; diff --git a/investigacoes/01-clientes-duplicados/exploracao.sql b/investigacoes/01-clientes-duplicados/exploracao.sql index 5fbb62d..a4ca712 100644 --- a/investigacoes/01-clientes-duplicados/exploracao.sql +++ b/investigacoes/01-clientes-duplicados/exploracao.sql @@ -9,22 +9,46 @@ WHERE lower(trim(email)) = 'ana.ferreira@example.com' ORDER BY id; -- Passo 2: o caso é isolado ou existe em outros clientes? --- (mesma query de deteccao.sql) +-- (mesma query de deteccao.sql; valores de mentira não formam par, +-- ver investigação 06) +WITH emails_de_mentira (parte) AS ( + VALUES ('naotem'), ('nao'), ('sememail'), ('semmail'), ('nenhum'), ('teste'), + ('naotem.com'), ('sememail.com'), ('teste.com'), ('email.com') +), +cpfs_de_sequencia (cpf) AS ( + VALUES ('12345678909'), ('01234567890'), ('98765432100') +), +identificadores AS ( + SELECT + id, + nome, + data_cadastro, + CASE + WHEN split_part(lower(trim(email)), '@', 1) IN (SELECT parte FROM emails_de_mentira) + OR split_part(lower(trim(email)), '@', 2) IN (SELECT parte FROM emails_de_mentira) + THEN NULL + ELSE lower(trim(email)) + END AS email, + CASE + WHEN regexp_replace(documento, '\D', '', 'g') ~ '^(\d)\1{10}$' + OR regexp_replace(documento, '\D', '', 'g') IN (SELECT cpf FROM cpfs_de_sequencia) + THEN NULL + ELSE regexp_replace(documento, '\D', '', 'g') + END AS documento + FROM clientes +) SELECT a.id AS id_original, b.id AS id_duplicado, a.nome AS nome_original, b.nome AS nome_duplicado, - lower(trim(a.email)) = lower(trim(b.email)) AS mesmo_email, - regexp_replace(a.documento, '\D', '', 'g') = regexp_replace(b.documento, '\D', '', 'g') AS mesmo_documento, + a.email = b.email AS mesmo_email, + a.documento = b.documento AS mesmo_documento, b.data_cadastro - a.data_cadastro AS intervalo_entre_cadastros -FROM clientes a -JOIN clientes b +FROM identificadores a +JOIN identificadores b ON a.id < b.id - AND ( - lower(trim(a.email)) = lower(trim(b.email)) - OR regexp_replace(a.documento, '\D', '', 'g') = regexp_replace(b.documento, '\D', '', 'g') - ) + AND (a.email = b.email OR a.documento = b.documento) ORDER BY a.id, b.id; -- Passo 3: impacto — quais registros do par têm pedidos e pagamentos diff --git a/investigacoes/01-clientes-duplicados/resultado-esperado.json b/investigacoes/01-clientes-duplicados/resultado-esperado.json index b5b9b88..a4d82c0 100644 --- a/investigacoes/01-clientes-duplicados/resultado-esperado.json +++ b/investigacoes/01-clientes-duplicados/resultado-esperado.json @@ -3,8 +3,8 @@ "consulta": 1, "colunas": ["id","nome","email","documento","telefone","data_cadastro","status"], "linhas": [ - ["1","Ana Carolina Ferreira","ana.ferreira@example.com","11122233344","11988887777","2026-01-10 09:15:00","ativo"], - ["11","Ana C. Ferreira","ana.ferreira@example.com","11122233344","11988887777","2026-01-10 09:17:32","ativo"] + ["1","Ana Carolina Ferreira","ana.ferreira@example.com","11122233396","11988887777","2026-01-10 09:15:00","ativo"], + ["11","Ana C. Ferreira","ana.ferreira@example.com","11122233396","11988887777","2026-01-10 09:17:32","ativo"] ] }, { diff --git a/investigacoes/02-fk-orfa/README.md b/investigacoes/02-fk-orfa/README.md index feab07c..5ba60ed 100644 --- a/investigacoes/02-fk-orfa/README.md +++ b/investigacoes/02-fk-orfa/README.md @@ -85,13 +85,13 @@ WHERE c.id IS NULL; | ultimo_id_gerado | maior_id_existente | qtd_clientes | |---|---|---| -| 12 | 11 | 11 | +| 15 | 15 | 14 | | id_gerado_e_ausente | |---| | 12 | -**Achado:** **H3 descartada.** O id 12 foi gerado pela sequence e é o único id ausente. Sozinha, uma lacuna na sequence não prova uma remoção, porque um `INSERT` que sofreu rollback também consome um id. Mas aqui existe um pedido apontando justamente para esse id, o que só faz sentido se o cliente existiu de fato. **Conclusão: o cliente 12 foi cadastrado e depois removido.** +**Achado:** **H3 descartada.** A sequence já gerou 15 ids, mas só existem 14 clientes: falta exatamente um. A segunda query mostra qual é: o id 12, o único gerado e ausente. Os ids 13 a 15 são clientes cadastrados depois, os três da [investigação 06](../06-dados-de-mentira/README.md). Sozinha, uma lacuna na sequence não prova uma remoção, porque um `INSERT` que sofreu rollback também consome um id. Mas aqui existe um pedido apontando justamente para esse id, o que só faz sentido se o cliente existiu de fato. **Conclusão: o cliente 12 foi cadastrado e depois removido.** ### Passo 4: como o banco permitiu? diff --git a/investigacoes/02-fk-orfa/resultado-esperado.json b/investigacoes/02-fk-orfa/resultado-esperado.json index bba0ce9..7d626fe 100644 --- a/investigacoes/02-fk-orfa/resultado-esperado.json +++ b/investigacoes/02-fk-orfa/resultado-esperado.json @@ -17,7 +17,7 @@ "consulta": 3, "colunas": ["ultimo_id_gerado","maior_id_existente","qtd_clientes"], "linhas": [ - ["12","11","11"] + ["15","15","14"] ] }, { diff --git a/investigacoes/06-dados-de-mentira/README.md b/investigacoes/06-dados-de-mentira/README.md new file mode 100644 index 0000000..4922c8f --- /dev/null +++ b/investigacoes/06-dados-de-mentira/README.md @@ -0,0 +1,264 @@ +# Investigação 06 — Valores de mentira em campos obrigatórios + +| | | +|---|---| +| **Defeito** | Clientes cadastrados com e-mail e CPF que não são dados de verdade, ou com o CPF digitado errado | +| **Registros afetados** | 3 clientes: `13` e `14` (e-mail `naotem@naotem.com` e CPFs de mentira) e `15` (CPF com dois dígitos trocados) | +| **Causa raiz** | O formulário de televendas exige e-mail e CPF, e o banco só garante que o campo não está vazio (`NOT NULL`), sem validar o conteúdo nem oferecer um jeito honesto de dizer "não informado" | +| **Severidade** | Média: cadastros barrados na análise de crédito, comunicação que não chega ao cliente e um falso positivo na detecção de duplicados | +| **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 lista os clientes com valor de mentira ou inválido e o motivo de cada um. É a mesma query que a CI executa. + +--- + +## 1. Sintoma relatado + +> Chamado da área de crédito: a integração que consulta o CPF de cada cliente novo no birô de crédito **rejeitou 3 cadastros de fevereiro**. Os três foram feitos pela equipe de televendas. + +## 2. Hipóteses iniciais + +| # | Hipótese | Como confirmar ou descartar | +|---|---|---| +| H1 | Falha técnica na integração de crédito, sem problema nos dados | Comparar os cadastros rejeitados com os aceitos do mesmo período | +| H2 | CPF digitado errado | Calcular o dígito verificador de cada CPF | +| H3 | Dados de preenchimento: o atendente não tinha a informação e digitou qualquer coisa para salvar | Procurar valores repetidos entre clientes diferentes e padrões típicos de "valor de mentira" | +| H4 | O problema não se limita aos 3 cadastros | Rodar a verificação em toda a base | + +## 3. Investigação + +### Passo 1: os cadastros de fevereiro + +```sql +SELECT id, nome, email, documento, telefone, data_cadastro +FROM clientes +WHERE data_cadastro >= '2026-02-01' +ORDER BY id; +``` + +| id | nome | email | documento | telefone | data_cadastro | +|---|---|---|---|---|---| +| 9 | Isabela Rocha Barbosa | isabela.barbosa@example.com | 99900011112 | 51900001111 | 2026-02-02 12:30:00 | +| 10 | João Pedro Azevedo | joao.azevedo@example.com | 00011122285 | 51999990000 | 2026-02-05 08:40:00 | +| **13** | **Roberto Lima Santos** | **naotem@naotem.com** | **00000000000** | 11987654321 | 2026-02-12 10:30:00 | +| **14** | **Sandra Melo Prado** | **naotem@naotem.com** | **12345678909** | 21976543210 | 2026-02-12 14:05:00 | +| **15** | **Paulo Henrique Dias** | paulo.dias@example.com | **14725836928** | 31965432109 | 2026-02-13 09:40:00 | + +**Achado:** **H1 descartada.** Os dois cadastros aceitos (`9` e `10`) têm e-mail e CPF com cara de dado real. Os três rejeitados se destacam a olho nu: um e-mail que diz "não tem", um CPF todo de zeros e o famoso `123.456.789-09`. O CPF do Paulo parece real, mas foi rejeitado também. A integração está funcionando, e o problema está nos dados. + +### Passo 2: valores repetidos entre clientes diferentes + +Um dado de verdade identifica uma pessoa. Se o mesmo valor aparece em clientes diferentes, ou é a mesma pessoa duplicada, ou não é dado de verdade: + +```sql +SELECT 'email' AS campo, lower(trim(email)) AS valor, COUNT(*) AS qtd_clientes, + string_agg(id::text, ', ' ORDER BY id) AS clientes +FROM clientes +GROUP BY lower(trim(email)) +HAVING COUNT(*) > 1 +UNION ALL +SELECT 'documento', regexp_replace(documento, '\D', '', 'g'), COUNT(*), + string_agg(id::text, ', ' ORDER BY id) +FROM clientes +GROUP BY regexp_replace(documento, '\D', '', 'g') +HAVING COUNT(*) > 1; +``` + +| campo | valor | qtd_clientes | clientes | +|---|---|---|---| +| documento | 11122233396 | 2 | 1, 11 | +| email | ana.ferreira@example.com | 2 | 1, 11 | +| email | naotem@naotem.com | 2 | 13, 14 | + +**Achado:** são dois casos de natureza diferente. + +- **Clientes `1` e `11`:** e-mail **e** CPF iguais. É a mesma pessoa cadastrada duas vezes, o defeito da [investigação 01](../01-clientes-duplicados/README.md). +- **Clientes `13` e `14`:** e-mail igual, mas **nomes, CPFs e telefones diferentes**. São duas pessoas, e o e-mail é um valor de preenchimento. **H3 confirmada** para esses dois. + +Esse segundo caso tem um efeito colateral. A primeira versão da detecção de duplicados da investigação 01 comparava e-mails crus e marcava Roberto e Sandra como a mesma pessoa, um **falso positivo**. A detecção da 01 foi ajustada para que valores de mentira não formem par, usando as mesmas listas desta investigação. + +### Passo 3: o dígito verificador de cada CPF + +Os dois últimos dígitos de um CPF são calculados a partir dos nove primeiros: cada dígito é multiplicado por um peso, de 10 a 2 para o primeiro verificador e de 11 a 2 para o segundo, e o resto da divisão da soma por 11 define o verificador (resto menor que 2 vira 0; senão, 11 menos o resto). Um erro de digitação quase sempre quebra essa conta. O cálculo foi feito em SQL, com `generate_series` percorrendo os nove dígitos: + +```sql +SELECT SUM(substr(cpf, i, 1)::int * (11 - i)) AS soma +FROM generate_series(1, 9) AS i; -- 1º dígito verificador; o 2º usa (12 - i) e soma o 1º com peso 2 +``` + +A query completa está em [`exploracao.sql`](exploracao.sql). Resultado para os 14 clientes: + +| id | nome | cpf | dv_informado | dv_calculado | dv_confere | +|---|---|---|---|---|---| +| 1 | Ana Carolina Ferreira | 11122233396 | 96 | 96 | true | +| 2 | Bruno Costa Lima | 22233344405 | 05 | 05 | true | +| 3 | Carla Mendes Souza | 33344455508 | 08 | 08 | true | +| 4 | Diego Alves Pereira | 44455566619 | 19 | 19 | true | +| 5 | Elisa Martins Rocha | 55566677720 | 20 | 20 | true | +| 6 | Fábio Nunes Castro | 66677788830 | 30 | 30 | true | +| 7 | Gabriela Dias Ramos | 77788899941 | 41 | 41 | true | +| 8 | Henrique Lopes Teixeira | 88899900078 | 78 | 78 | true | +| 9 | Isabela Rocha Barbosa | 99900011112 | 12 | 12 | true | +| 10 | João Pedro Azevedo | 00011122285 | 85 | 85 | true | +| 11 | Ana C. Ferreira | 11122233396 | 96 | 96 | true | +| **13** | **Roberto Lima Santos** | **00000000000** | **00** | **00** | **true** | +| **14** | **Sandra Melo Prado** | **12345678909** | **09** | **09** | **true** | +| **15** | **Paulo Henrique Dias** | **14725836928** | **28** | **82** | **false** | + +**Achados:** + +- **H2 confirmada para o Paulo (`15`).** O verificador informado é `28` e o calculado é `82`: os dois últimos dígitos foram **trocados** na digitação, o erro mais comum ao copiar um número. O CPF certo seria `147.258.369-82`. +- **O dígito verificador sozinho não pega valor de mentira.** `000.000.000-00` e `123.456.789-09` **passam** no cálculo. Todo CPF com os 11 dígitos iguais passa, por uma propriedade da própria conta, e `123.456.789-09` é justamente um exemplo famoso por ser válido. Por isso a detecção precisa de duas regras a mais: dígitos todos iguais e sequências conhecidas. + +### Passo 4: a detecção final — é isolado? + +A query de [`deteccao.sql`](deteccao.sql) junta todas as regras e lista, para cada cliente, os problemas encontrados: + +| Regra | O que pega | +|---|---| +| e-mail de mentira | `naotem@...`, `teste@...`, `...@sememail.com` e afins | +| e-mail com formato inválido | sem `@`, sem domínio, com espaço | +| CPF com todos os dígitos iguais | `000.000.000-00`, `111.111.111-11`... | +| CPF de sequência conhecida | `123.456.789-09` e afins | +| CPF com tamanho inválido | diferente de 11 dígitos | +| CPF com dígito verificador errado | erro de digitação | + +| cliente_id | nome | email | documento | problemas | +|---|---|---|---|---| +| 13 | Roberto Lima Santos | naotem@naotem.com | 00000000000 | e-mail de mentira; CPF com todos os dígitos iguais | +| 14 | Sandra Melo Prado | naotem@naotem.com | 12345678909 | e-mail de mentira; CPF de sequência conhecida | +| 15 | Paulo Henrique Dias | paulo.dias@example.com | 14725836928 | CPF com dígito verificador errado | + +**Achado:** **H4 descartada.** São exatamente os 3 cadastros do chamado. Os outros 11 clientes passam em todas as regras. + +As listas de "valores de mentira" são, por natureza, incompletas: alguém sempre inventa um novo (`xxx@xxx.com`, `999.999.999-99`). As regras de formato e de dígito verificador não dependem de lista, e as listas cobrem os casos que essas regras não pegam. + +### Passo 5: causa raiz — o que o banco exige hoje? + +```sql +SELECT column_name, data_type, is_nullable +FROM information_schema.columns +WHERE table_name = 'clientes' AND column_name IN ('email', 'documento'); + +SELECT conname, contype, pg_get_constraintdef(oid) +FROM pg_constraint +WHERE conrelid = 'clientes'::regclass; +``` + +| column_name | data_type | is_nullable | +|---|---|---| +| documento | character varying | NO | +| email | character varying | NO | + +| constraint | tipo | definição | +|---|---|---| +| clientes_pkey | p | PRIMARY KEY (id) | + +**Achado:** as duas colunas são `NOT NULL`, e não existe nenhuma `CHECK`. O banco exige **que algo seja digitado**, mas não **que seja válido**. Para quem atende um cliente que não sabe ou não quer informar o e-mail, a regra deixa só duas saídas: perder a venda ou digitar qualquer coisa. + +## 4. Causa raiz + +1. **Processo e aplicação (causa raiz):** o formulário de televendas trata e-mail e CPF como obrigatórios e não oferece uma opção "não informado". Diante de um cliente sem a informação, o atendente faz o que o sistema permite: digita um valor de preenchimento. +2. **Banco (por que passou):** `NOT NULL` garante presença, não validade. Nenhuma regra confere formato de e-mail, dígito verificador de CPF ou valores de preenchimento conhecidos. E, ao exigir o campo, o banco empurra o atendente justamente para o valor de mentira. + +O CPF do Paulo é um caso à parte do mesmo problema: o número foi informado, mas digitado errado, e nada no caminho conferiu o dígito verificador. + +## 5. Impacto + +- **Crédito e vendas:** os 3 cadastros foram barrados na análise de crédito, e as vendas para esses clientes ficam travadas até a correção. +- **Comunicação:** os e-mails para Roberto e Sandra não chegam a ninguém. Se um dia `naotem.com` virar um domínio real, chegam a um desconhecido, com dados de dois clientes. +- **Outras verificações:** o e-mail compartilhado criou um falso positivo na detecção de duplicados (investigação 01) e **impede** a criação do índice único de e-mail que a própria investigação 01 propõe. Um defeito contamina a verificação e a correção de outro. +- **Relatórios:** contagens de "clientes com e-mail" ou "com CPF" ficam infladas, porque contam valores que não são dado. + +## 6. Correção proposta + +> **Não executada.** A correção foi testada numa cópia descartável do banco, em sequência com a da investigação 01. **Sem** esta correção, o índice único de e-mail da 01 falha. **Com** ela, os índices da 01 são criados, a detecção desta investigação retorna 0 linhas, um cadastro sem e-mail e sem CPF (`NULL`) é aceito, e os novos cadastros com `naotem@naotem.com`, `000.000.000-00`, CPF com dígito trocado ou e-mail sem `@` são bloqueados pelo banco. + +### 6.1 Permitir "não informado" de forma honesta + +```sql +ALTER TABLE clientes ALTER COLUMN email DROP NOT NULL; +ALTER TABLE clientes ALTER COLUMN documento DROP NOT NULL; +``` + +Parece um passo para trás, mas é o oposto. `NULL` diz a verdade ("não sabemos"), e um valor de mentira finge que sabemos. Relatórios passam a contar só dado real, e o índice único aceita vários `NULL`. + +### 6.2 Limpar os valores de mentira + +```sql +UPDATE clientes SET email = NULL WHERE id IN (13, 14); -- naotem@naotem.com +UPDATE clientes SET documento = NULL WHERE id IN (13, 14); -- 000.000.000-00 e 123.456.789-09 +UPDATE clientes SET documento = NULL WHERE id = 15; -- CPF digitado errado +``` + +- **Roberto e Sandra:** os dados reais só podem vir dos próprios clientes. Até lá, `NULL`. +- **Paulo:** é muito provável que o certo seja `147.258.369-82` (os dois últimos dígitos trocados), mas isso continua sendo um palpite. Um CPF corrigido "por dedução" que estiver errado é pior que um campo vazio, porque parece verdade. O certo é confirmar com o cliente. Até lá, `NULL`, e o cadastro entra numa fila de contato. + +### 6.3 Validar o conteúdo no banco + +```sql +CREATE FUNCTION cpf_valido(doc text) RETURNS boolean +LANGUAGE plpgsql IMMUTABLE AS $$ +DECLARE + cpf text := regexp_replace(doc, '\D', '', 'g'); + soma int; + d1 int; + d2 int; +BEGIN + IF cpf !~ '^\d{11}$' OR cpf ~ '^(\d)\1{10}$' + OR cpf IN ('12345678909', '01234567890', '98765432100') THEN + RETURN false; + END IF; + soma := 0; + FOR i IN 1..9 LOOP + soma := soma + substr(cpf, i, 1)::int * (11 - i); + END LOOP; + d1 := CASE WHEN soma % 11 < 2 THEN 0 ELSE 11 - soma % 11 END; + soma := 0; + FOR i IN 1..9 LOOP + soma := soma + substr(cpf, i, 1)::int * (12 - i); + END LOOP; + soma := soma + d1 * 2; + d2 := CASE WHEN soma % 11 < 2 THEN 0 ELSE 11 - soma % 11 END; + RETURN substr(cpf, 10, 1)::int = d1 AND substr(cpf, 11, 1)::int = d2; +END; +$$; + +CREATE FUNCTION email_valido(email text) RETURNS boolean +LANGUAGE sql IMMUTABLE AS $$ + SELECT lower(trim(email)) ~ '^[^@\s]+@[^@\s]+\.[^@\s]+$' + AND split_part(lower(trim(email)), '@', 1) NOT IN ('naotem', 'nao', 'sememail', 'semmail', 'nenhum', 'teste') + AND split_part(lower(trim(email)), '@', 2) NOT IN ('naotem.com', 'sememail.com', 'teste.com', 'email.com'); +$$; + +ALTER TABLE clientes ADD CONSTRAINT clientes_documento_valido + CHECK (documento IS NULL OR cpf_valido(documento)); + +ALTER TABLE clientes ADD CONSTRAINT clientes_email_valido + CHECK (email IS NULL OR email_valido(email)); +``` + +- **Ordem:** as `CHECK` só podem ser criadas depois da limpeza (6.2). Com os valores atuais na base, a criação falharia. +- **Por que funções:** a regra do CPF não cabe numa expressão simples. Com as funções, a mesma lógica fica num lugar só, e as `CHECK` ficam legíveis. Elas precisam ser `IMMUTABLE` (mesmo resultado para a mesma entrada), uma exigência do PostgreSQL para uso em `CHECK`. +- **Limite:** a lista de e-mails de mentira dentro do `email_valido` bloqueia os valores conhecidos, mas não os que alguém inventar amanhã. É por isso que a parte mais importante da correção é a 6.4. + +### 6.4 Corrigir o formulário + +- Oferecer **"Cliente não informou"** para e-mail e CPF, gravando `NULL`. Se a saída honesta existir, o atendente não precisa inventar. +- Validar o CPF (dígito verificador) e o formato do e-mail **na tela**, no momento da digitação. O erro do Paulo seria pego antes de salvar. +- **Monitoramento:** rodar o [`deteccao.sql`](deteccao.sql) periodicamente e revisar os valores novos que aparecerem para atualizar as listas. + +### 6.5 Ordem em relação à investigação 01 + +A correção da [investigação 01](../01-clientes-duplicados/README.md) cria índices únicos em e-mail e documento. Esses índices só podem ser criados **depois** desta correção: enquanto Roberto e Sandra compartilharem `naotem@naotem.com`, o índice único de e-mail falha. + +## 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/06-dados-de-mentira/exploracao.sql +``` diff --git a/investigacoes/06-dados-de-mentira/deteccao.sql b/investigacoes/06-dados-de-mentira/deteccao.sql new file mode 100644 index 0000000..191deb3 --- /dev/null +++ b/investigacoes/06-dados-de-mentira/deteccao.sql @@ -0,0 +1,86 @@ +-- Detecção: clientes com valor de mentira ou inválido num campo +-- obrigatório (e-mail ou CPF). +-- +-- NOT NULL só impede o campo vazio. Esta query procura o que passa por +-- ele sem ser dado de verdade: +-- - e-mail de mentira: endereço "de preenchimento" (naotem@..., teste@...); +-- - e-mail com formato inválido; +-- - CPF com todos os dígitos iguais (000.000.000-00, 111.111.111-11...); +-- - CPF de sequência conhecida (123.456.789-09); +-- - CPF com tamanho diferente de 11 dígitos; +-- - CPF com dígito verificador errado (erro de digitação). +-- +-- Os dois primeiros tipos de CPF PASSAM no cálculo do dígito verificador, +-- por isso precisam de regra própria. +-- +-- Cada linha é um cliente, com a lista de problemas encontrados. +-- Resultado esperado: zero linhas. + +WITH emails_de_mentira (parte) AS ( + VALUES ('naotem'), ('nao'), ('sememail'), ('semmail'), ('nenhum'), ('teste'), + ('naotem.com'), ('sememail.com'), ('teste.com'), ('email.com') +), +cpfs_de_sequencia (cpf) AS ( + VALUES ('12345678909'), ('01234567890'), ('98765432100') +), +clientes_normalizados AS ( + SELECT + id, + nome, + email, + documento, + lower(trim(email)) AS email_norm, + regexp_replace(documento, '\D', '', 'g') AS cpf + FROM clientes +), +dv AS ( + -- Dígito verificador do CPF: os 9 primeiros dígitos pesam de 10 a 2 + -- (1º dígito) e de 11 a 3 mais o 1º dígito com peso 2 (2º dígito). + -- Resto da divisão por 11 menor que 2 vira 0; senão, 11 menos o resto. + SELECT + c.id, + d1.digito AS d1, + CASE WHEN (s2.soma + d1.digito * 2) % 11 < 2 THEN 0 ELSE 11 - (s2.soma + d1.digito * 2) % 11 END AS d2 + FROM clientes_normalizados c + CROSS JOIN LATERAL ( + SELECT SUM(substr(c.cpf, i, 1)::int * (11 - i)) AS soma + FROM generate_series(1, 9) AS i + ) s1 + CROSS JOIN LATERAL ( + SELECT CASE WHEN s1.soma % 11 < 2 THEN 0 ELSE 11 - s1.soma % 11 END AS digito + ) d1 + CROSS JOIN LATERAL ( + SELECT SUM(substr(c.cpf, i, 1)::int * (12 - i)) AS soma + FROM generate_series(1, 9) AS i + ) s2 + WHERE c.cpf ~ '^\d{11}$' +), +problemas AS ( + SELECT + c.id AS cliente_id, + c.nome, + c.email, + c.documento, + array_remove(ARRAY[ + CASE WHEN split_part(c.email_norm, '@', 1) IN (SELECT parte FROM emails_de_mentira) + OR split_part(c.email_norm, '@', 2) IN (SELECT parte FROM emails_de_mentira) + THEN 'e-mail de mentira' END, + CASE WHEN c.email_norm !~ '^[^@\s]+@[^@\s]+\.[^@\s]+$' + THEN 'e-mail com formato inválido' END, + CASE WHEN c.cpf ~ '^(\d)\1{10}$' + THEN 'CPF com todos os dígitos iguais' END, + CASE WHEN c.cpf IN (SELECT cpf FROM cpfs_de_sequencia) + THEN 'CPF de sequência conhecida' END, + CASE WHEN c.cpf !~ '^\d{11}$' + THEN 'CPF com tamanho inválido' END, + CASE WHEN dv.id IS NOT NULL + AND (substr(c.cpf, 10, 1)::int <> dv.d1 OR substr(c.cpf, 11, 1)::int <> dv.d2) + THEN 'CPF com dígito verificador errado' END + ], NULL) AS lista + FROM clientes_normalizados c + LEFT JOIN dv ON dv.id = c.id +) +SELECT cliente_id, nome, email, documento, array_to_string(lista, '; ') AS problemas +FROM problemas +WHERE cardinality(lista) > 0 +ORDER BY cliente_id; diff --git a/investigacoes/06-dados-de-mentira/exploracao.sql b/investigacoes/06-dados-de-mentira/exploracao.sql new file mode 100644 index 0000000..1a9ea8b --- /dev/null +++ b/investigacoes/06-dados-de-mentira/exploracao.sql @@ -0,0 +1,124 @@ +-- Investigação 06 — Valores de mentira em campos obrigatórios +-- Queries na ordem em que foram usadas na investigação. A numeração bate +-- com os passos do README.md desta pasta. + +-- Passo 1: os cadastros de fevereiro, quando a análise de crédito +-- começou a rejeitar clientes novos. +SELECT id, nome, email, documento, telefone, data_cadastro +FROM clientes +WHERE data_cadastro >= '2026-02-01' +ORDER BY id; + +-- Passo 2: e-mails e documentos que se repetem entre clientes. +SELECT 'email' AS campo, lower(trim(email)) AS valor, COUNT(*) AS qtd_clientes, + string_agg(id::text, ', ' ORDER BY id) AS clientes +FROM clientes +GROUP BY lower(trim(email)) +HAVING COUNT(*) > 1 +UNION ALL +SELECT 'documento', regexp_replace(documento, '\D', '', 'g'), COUNT(*), + string_agg(id::text, ', ' ORDER BY id) +FROM clientes +GROUP BY regexp_replace(documento, '\D', '', 'g') +HAVING COUNT(*) > 1 +ORDER BY campo, valor; + +-- Passo 3: o dígito verificador de cada CPF — o calculado a partir dos +-- 9 primeiros dígitos e o que foi informado. +WITH c AS ( + SELECT id, nome, regexp_replace(documento, '\D', '', 'g') AS cpf + FROM clientes +), +calculo AS ( + SELECT + c.id, + c.nome, + c.cpf, + d1.digito AS d1, + CASE WHEN (s2.soma + d1.digito * 2) % 11 < 2 THEN 0 ELSE 11 - (s2.soma + d1.digito * 2) % 11 END AS d2 + FROM c + CROSS JOIN LATERAL ( + SELECT SUM(substr(c.cpf, i, 1)::int * (11 - i)) AS soma FROM generate_series(1, 9) AS i + ) s1 + CROSS JOIN LATERAL ( + SELECT CASE WHEN s1.soma % 11 < 2 THEN 0 ELSE 11 - s1.soma % 11 END AS digito + ) d1 + CROSS JOIN LATERAL ( + SELECT SUM(substr(c.cpf, i, 1)::int * (12 - i)) AS soma FROM generate_series(1, 9) AS i + ) s2 + WHERE c.cpf ~ '^\d{11}$' +) +SELECT + id, + nome, + cpf, + substr(cpf, 10, 2) AS dv_informado, + d1::text || d2::text AS dv_calculado, + substr(cpf, 10, 2) = d1::text || d2::text AS dv_confere +FROM calculo +ORDER BY id; + +-- Passo 4: detecção final (mesma query de deteccao.sql). +WITH emails_de_mentira (parte) AS ( + VALUES ('naotem'), ('nao'), ('sememail'), ('semmail'), ('nenhum'), ('teste'), + ('naotem.com'), ('sememail.com'), ('teste.com'), ('email.com') +), +cpfs_de_sequencia (cpf) AS ( + VALUES ('12345678909'), ('01234567890'), ('98765432100') +), +clientes_normalizados AS ( + SELECT id, nome, email, documento, + lower(trim(email)) AS email_norm, + regexp_replace(documento, '\D', '', 'g') AS cpf + FROM clientes +), +dv AS ( + SELECT + c.id, + d1.digito AS d1, + CASE WHEN (s2.soma + d1.digito * 2) % 11 < 2 THEN 0 ELSE 11 - (s2.soma + d1.digito * 2) % 11 END AS d2 + FROM clientes_normalizados c + CROSS JOIN LATERAL ( + SELECT SUM(substr(c.cpf, i, 1)::int * (11 - i)) AS soma FROM generate_series(1, 9) AS i + ) s1 + CROSS JOIN LATERAL ( + SELECT CASE WHEN s1.soma % 11 < 2 THEN 0 ELSE 11 - s1.soma % 11 END AS digito + ) d1 + CROSS JOIN LATERAL ( + SELECT SUM(substr(c.cpf, i, 1)::int * (12 - i)) AS soma FROM generate_series(1, 9) AS i + ) s2 + WHERE c.cpf ~ '^\d{11}$' +), +problemas AS ( + SELECT + c.id AS cliente_id, c.nome, c.email, c.documento, + array_remove(ARRAY[ + CASE WHEN split_part(c.email_norm, '@', 1) IN (SELECT parte FROM emails_de_mentira) + OR split_part(c.email_norm, '@', 2) IN (SELECT parte FROM emails_de_mentira) + THEN 'e-mail de mentira' END, + CASE WHEN c.email_norm !~ '^[^@\s]+@[^@\s]+\.[^@\s]+$' THEN 'e-mail com formato inválido' END, + CASE WHEN c.cpf ~ '^(\d)\1{10}$' THEN 'CPF com todos os dígitos iguais' END, + CASE WHEN c.cpf IN (SELECT cpf FROM cpfs_de_sequencia) THEN 'CPF de sequência conhecida' END, + CASE WHEN c.cpf !~ '^\d{11}$' THEN 'CPF com tamanho inválido' END, + CASE WHEN dv.id IS NOT NULL + AND (substr(c.cpf, 10, 1)::int <> dv.d1 OR substr(c.cpf, 11, 1)::int <> dv.d2) + THEN 'CPF com dígito verificador errado' END + ], NULL) AS lista + FROM clientes_normalizados c + LEFT JOIN dv ON dv.id = c.id +) +SELECT cliente_id, nome, email, documento, array_to_string(lista, '; ') AS problemas +FROM problemas +WHERE cardinality(lista) > 0 +ORDER BY cliente_id; + +-- Passo 5: causa raiz — o que o banco exige hoje de e-mail e documento? +SELECT column_name, data_type, is_nullable +FROM information_schema.columns +WHERE table_name = 'clientes' AND column_name IN ('email', 'documento') +ORDER BY column_name; + +SELECT conname, contype, pg_get_constraintdef(oid) AS definicao +FROM pg_constraint +WHERE conrelid = 'clientes'::regclass +ORDER BY conname; diff --git a/investigacoes/06-dados-de-mentira/resultado-esperado.json b/investigacoes/06-dados-de-mentira/resultado-esperado.json new file mode 100644 index 0000000..8100f8e --- /dev/null +++ b/investigacoes/06-dados-de-mentira/resultado-esperado.json @@ -0,0 +1,66 @@ +[ + { + "consulta": 1, + "colunas": ["id","nome","email","documento","telefone","data_cadastro"], + "linhas": [ + ["9","Isabela Rocha Barbosa","isabela.barbosa@example.com","99900011112","51900001111","2026-02-02 12:30:00"], + ["10","João Pedro Azevedo","joao.azevedo@example.com","00011122285","51999990000","2026-02-05 08:40:00"], + ["13","Roberto Lima Santos","naotem@naotem.com","00000000000","11987654321","2026-02-12 10:30:00"], + ["14","Sandra Melo Prado","naotem@naotem.com","12345678909","21976543210","2026-02-12 14:05:00"], + ["15","Paulo Henrique Dias","paulo.dias@example.com","14725836928","31965432109","2026-02-13 09:40:00"] + ] + }, + { + "consulta": 2, + "colunas": ["campo","valor","qtd_clientes","clientes"], + "linhas": [ + ["documento","11122233396","2","1, 11"], + ["email","ana.ferreira@example.com","2","1, 11"], + ["email","naotem@naotem.com","2","13, 14"] + ] + }, + { + "consulta": 3, + "colunas": ["id","nome","cpf","dv_informado","dv_calculado","dv_confere"], + "linhas": [ + ["1","Ana Carolina Ferreira","11122233396","96","96","t"], + ["2","Bruno Costa Lima","22233344405","05","05","t"], + ["3","Carla Mendes Souza","33344455508","08","08","t"], + ["4","Diego Alves Pereira","44455566619","19","19","t"], + ["5","Elisa Martins Rocha","55566677720","20","20","t"], + ["6","Fábio Nunes Castro","66677788830","30","30","t"], + ["7","Gabriela Dias Ramos","77788899941","41","41","t"], + ["8","Henrique Lopes Teixeira","88899900078","78","78","t"], + ["9","Isabela Rocha Barbosa","99900011112","12","12","t"], + ["10","João Pedro Azevedo","00011122285","85","85","t"], + ["11","Ana C. Ferreira","11122233396","96","96","t"], + ["13","Roberto Lima Santos","00000000000","00","00","t"], + ["14","Sandra Melo Prado","12345678909","09","09","t"], + ["15","Paulo Henrique Dias","14725836928","28","82","f"] + ] + }, + { + "consulta": 4, + "colunas": ["cliente_id","nome","email","documento","problemas"], + "linhas": [ + ["13","Roberto Lima Santos","naotem@naotem.com","00000000000","e-mail de mentira; CPF com todos os dígitos iguais"], + ["14","Sandra Melo Prado","naotem@naotem.com","12345678909","e-mail de mentira; CPF de sequência conhecida"], + ["15","Paulo Henrique Dias","paulo.dias@example.com","14725836928","CPF com dígito verificador errado"] + ] + }, + { + "consulta": 5, + "colunas": ["column_name","data_type","is_nullable"], + "linhas": [ + ["documento","character varying","NO"], + ["email","character varying","NO"] + ] + }, + { + "consulta": 6, + "colunas": ["conname","contype","definicao"], + "linhas": [ + ["clientes_pkey","p","PRIMARY KEY (id)"] + ] + } +] diff --git a/scripts/validate.js b/scripts/validate.js index e5290c9..8d65c42 100644 --- a/scripts/validate.js +++ b/scripts/validate.js @@ -65,6 +65,12 @@ const CHECKS = [ esperadoValido: 0, esperadoQuebrado: 1, }, + { + label: 'clientes com e-mail ou CPF de mentira ou inválido', + sql: readDeteccao('06-dados-de-mentira'), + esperadoValido: 0, + esperadoQuebrado: 3, + }, { // 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 9011452..fa11b97 100644 --- a/sql/01_schema.sql +++ b/sql/01_schema.sql @@ -2,7 +2,7 @@ -- 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). +-- duplicidade, valores de mentira em campos obrigatórios). CREATE TABLE clientes ( id SERIAL PRIMARY KEY, @@ -13,6 +13,8 @@ CREATE TABLE clientes ( data_cadastro TIMESTAMP NOT NULL DEFAULT now(), status VARCHAR(20) NOT NULL DEFAULT 'ativo' ); +-- email e documento são só NOT NULL, sem nenhuma validação de conteúdo: é o +-- que permite os valores de mentira da investigação 06. -- Sem UNIQUE em email/documento de propósito: é exatamente a ausência dessa -- constraint que permite o defeito de clientes duplicados investigado aqui. diff --git a/sql/02_seed_valido.sql b/sql/02_seed_valido.sql index 2816c0b..7397969 100644 --- a/sql/02_seed_valido.sql +++ b/sql/02_seed_valido.sql @@ -4,16 +4,16 @@ -- retornar zero resultados rodada só contra este arquivo. INSERT INTO clientes (nome, email, documento, telefone, data_cadastro, status) VALUES - ('Ana Carolina Ferreira', 'ana.ferreira@example.com', '11122233344', '11988887777', '2026-01-10 09:15:00', 'ativo'), - ('Bruno Costa Lima', 'bruno.lima@example.com', '22233344455', '11977776666', '2026-01-12 14:30:00', 'ativo'), - ('Carla Mendes Souza', 'carla.souza@example.com', '33344455566', '21966665555', '2026-01-15 11:00:00', 'ativo'), - ('Diego Alves Pereira', 'diego.pereira@example.com','44455566677', '21955554444', '2026-01-18 16:45:00', 'ativo'), - ('Elisa Martins Rocha', 'elisa.rocha@example.com', '55566677788', '31944443333', '2026-01-20 10:20:00', 'ativo'), - ('Fábio Nunes Castro', 'fabio.castro@example.com', '66677788899', '31933332222', '2026-01-22 13:10:00', 'inativo'), - ('Gabriela Dias Ramos', 'gabriela.ramos@example.com','77788899900','41922221111', '2026-01-25 09:50:00', 'ativo'), - ('Henrique Lopes Teixeira','henrique.teixeira@example.com','88899900011','41911110000','2026-01-28 15:00:00', 'ativo'), - ('Isabela Rocha Barbosa', 'isabela.barbosa@example.com','99900011122','51900001111', '2026-02-02 12:30:00', 'ativo'), - ('João Pedro Azevedo', 'joao.azevedo@example.com', '00011122233', '51999990000', '2026-02-05 08:40:00', 'ativo'); + ('Ana Carolina Ferreira', 'ana.ferreira@example.com', '11122233396', '11988887777', '2026-01-10 09:15:00', 'ativo'), + ('Bruno Costa Lima', 'bruno.lima@example.com', '22233344405', '11977776666', '2026-01-12 14:30:00', 'ativo'), + ('Carla Mendes Souza', 'carla.souza@example.com', '33344455508', '21966665555', '2026-01-15 11:00:00', 'ativo'), + ('Diego Alves Pereira', 'diego.pereira@example.com','44455566619', '21955554444', '2026-01-18 16:45:00', 'ativo'), + ('Elisa Martins Rocha', 'elisa.rocha@example.com', '55566677720', '31944443333', '2026-01-20 10:20:00', 'ativo'), + ('Fábio Nunes Castro', 'fabio.castro@example.com', '66677788830', '31933332222', '2026-01-22 13:10:00', 'inativo'), + ('Gabriela Dias Ramos', 'gabriela.ramos@example.com','77788899941','41922221111', '2026-01-25 09:50:00', 'ativo'), + ('Henrique Lopes Teixeira','henrique.teixeira@example.com','88899900078','41911110000','2026-01-28 15:00:00', 'ativo'), + ('Isabela Rocha Barbosa', 'isabela.barbosa@example.com','99900011112','51900001111', '2026-02-02 12:30:00', 'ativo'), + ('João Pedro Azevedo', 'joao.azevedo@example.com', '00011122285', '51999990000', '2026-02-05 08:40:00', 'ativo'); INSERT INTO vendedores (nome, email, equipe) VALUES ('Mariana Oliveira', 'mariana.oliveira@empresa.com', 'Equipe A'), diff --git a/sql/03_seed_quebrado.sql b/sql/03_seed_quebrado.sql index b2eedd3..f4d5896 100644 --- a/sql/03_seed_quebrado.sql +++ b/sql/03_seed_quebrado.sql @@ -1,4 +1,4 @@ --- Introduz, de propósito, os 5 tipos de defeito investigados neste projeto. +-- Introduz, de propósito, os 6 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. @@ -9,7 +9,7 @@ -- constraint única em email/documento pra impedir o segundo registro. -- ===================================================================== INSERT INTO clientes (nome, email, documento, telefone, data_cadastro, status) VALUES - ('Ana C. Ferreira', 'ana.ferreira@example.com', '11122233344', '11988887777', '2026-01-10 09:17:32', 'ativo'); + ('Ana C. Ferreira', 'ana.ferreira@example.com', '11122233396', '11988887777', '2026-01-10 09:17:32', 'ativo'); -- Mesmo e-mail e documento do cliente id=1, cadastrado 2 minutos depois, -- com o nome digitado de forma levemente diferente. @@ -22,7 +22,7 @@ INSERT INTO clientes (nome, email, documento, telefone, data_cadastro, status) V -- bancos que já têm alguns anos de operação. -- ===================================================================== INSERT INTO clientes (nome, email, documento, telefone, data_cadastro, status) -VALUES ('Cliente Removido Depois', 'removido@example.com', '12312312312', '11900000000', '2025-11-01 10:00:00', 'ativo'); +VALUES ('Cliente Removido Depois', 'removido@example.com', '12312312387', '11900000000', '2025-11-01 10:00:00', 'ativo'); INSERT INTO pedidos (cliente_id, vendedor_id, data_pedido, status, valor_total) VALUES (currval('clientes_id_seq'), 1, '2025-12-01 10:00:00', 'confirmado', 99.90); @@ -85,3 +85,19 @@ INSERT INTO pagamentos (pedido_id, valor, data_pagamento, status) VALUES (2, 99.90, '2026-01-13 15:10:04', 'aprovado'); -- Mesmo pedido, mesmo valor e 4 segundos depois do pagamento original -- (id 2, 15:10:00). + +-- ===================================================================== +-- DEFEITO 6: Valores de mentira em campos obrigatórios +-- Cenário real: no cadastro por televendas, o formulário exige e-mail e +-- CPF. Quando o cliente não informa (ou o atendente não pergunta), o +-- atendente digita um valor qualquer só para conseguir salvar. O banco +-- aceita, porque NOT NULL só impede o campo vazio, não o valor falso. +-- ===================================================================== +INSERT INTO clientes (nome, email, documento, telefone, data_cadastro, status) VALUES + ('Roberto Lima Santos', 'naotem@naotem.com', '00000000000', '11987654321', '2026-02-12 10:30:00', 'ativo'), + ('Sandra Melo Prado', 'naotem@naotem.com', '12345678909', '21976543210', '2026-02-12 14:05:00', 'ativo'), + ('Paulo Henrique Dias', 'paulo.dias@example.com', '14725836928', '31965432109', '2026-02-13 09:40:00', 'ativo'); +-- Roberto e Sandra são pessoas diferentes com o mesmo e-mail de mentira, e +-- 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. diff --git a/validacoes/README.md b/validacoes/README.md index 2ef27dc..49c6c08 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 5 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 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. | Arquivo | Regra | Massa válida | Massa quebrada | |---|---|---|---|