Módulo 08 — Lapidação e qualidade de código

1. O que é lapidação (e o que não é)

Lapidar não é adicionar funcionalidade. É pegar o que já funciona e deixar redondo: sem aresta, sem susto, sem feiúra. É a distância entre um sistema que passa no teste feliz (o "caminho certo", que a própria competidora testa porque sabe usar o que fez) e um sistema que aguenta o mundo real: a usuária fazendo besteira, o dado faltando, a internet caindo, o clique duplo, o campo vazio.

Uma forma de enxergar: todo sistema tem dois públicos. O primeiro é a pessoa que usa direito. O segundo é a pessoa que usa errado, de propósito ou por acidente. O caminho feliz atende o primeiro. A lapidação atende o segundo. E a banca é, por profissão, o segundo público.

1.1 O mapa da lapidação

Pra não virar "melhorar no olho", a lapidação tem endereço. Toda a passada final cabe em seis frentes, e é assim que esse módulo está organizado:

E fechando, a mentalidade que garante que nada disso passou batido: testar como a banca testa (§10). Cada frente vira item de checklist. É esse checklist que a gente saca na prova.

2. Máscaras e formatação de entrada

Campo que se formata sozinho enquanto a pessoa digita: telefone que vira (51) 99999-9999, data que vira 31/08/2026, valor que vira R$ 1.250,00. Parece detalhe, mas comunica cuidado já na primeira olhada, e previne erro na origem (a usuária não consegue digitar letra num campo de telefone). É das coisas de melhor retorno pelo esforço na prova inteira.

Só que máscara tem uma regra de ouro que separa quem sabe de quem só copiou: formata pra mostrar, guarda limpo pra mandar.

2.1 O padrão formata-mostra / guarda-limpo

O banco não quer (51) 99999-9999, quer 51999999999. O DECIMAL do módulo 03 não quer R$ 1.250,00, quer 1250.00. Então a máscara vive só na tela. Na hora de mandar pra API (o api() do módulo 05), a gente limpa o valor de volta pro cru.

São sempre duas funções por máscara: uma que formata (cru → bonito, roda a cada tecla) e uma que limpa (bonito → cru, roda antes de enviar).

// mascaras.js — front, vale igual nas duas stacks

// TELEFONE: formata enquanto digita, limpa antes de mandar
function formataTelefone(valor) {
  const numeros = valor.replace(/\D/g, '').slice(0, 11); // só dígitos, no máx 11
  if (numeros.length <= 2)  return numeros;
  if (numeros.length <= 7)  return `(${numeros.slice(0,2)}) ${numeros.slice(2)}`;
  return `(${numeros.slice(0,2)}) ${numeros.slice(2,7)}-${numeros.slice(7)}`;
}

function limpaTelefone(valor) {
  return valor.replace(/\D/g, ''); // guarda só os números
}

Ligar no campo é um addEventListener de input (dispara a cada tecla). O truque de sempre reposicionar o cursor no fim resolve 99% dos casos da prova sem complicar:

const campoTel = document.querySelector('#telefone');
campoTel.addEventListener('input', (e) => {
  e.target.value = formataTelefone(e.target.value);
});

E na hora de enviar, limpa:

const payload = {
  nome: campoNome.value.trim(),
  telefone: limpaTelefone(campoTel.value), // "51999999999", não "(51) 99999-9999"
};
await api('/convidados', { method: 'POST', body: payload });

2.2 Dinheiro é o caso chato (e cai)

Valor em reais tem vírgula decimal, ponto de milhar e o R$ na frente. E o back quer 1250.00 (ponto decimal, sem milhar). O caminho que menos dá dor de cabeça na prova é formatar na saída do campo (evento blur) e ter o par de conversão sempre à mão:

// mostra: 1250.5 -> "R$ 1.250,50"
function formataReais(numero) {
  return numero.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' });
}
// limpa: "R$ 1.250,50" -> 1250.5 (número que o DECIMAL aceita)
function limpaReais(texto) {
  const cru = texto.replace(/[^\d,]/g, '').replace(',', '.');
  return parseFloat(cru) || 0;
}

3. Biblioteca de regex pra validação

Regex (expressão regular) é o canivete da validação: um padrão que diz "esse texto tem a cara certa?". Vale a pena chegar na prova com uma bibliotequinha pronta na cola, porque validar formato é ponto garantido e escrever regex sob pressão é onde todo mundo trava.

// validacao.js — os padrões que caem no Wedding Pass
const REGEX = {
  email:    /^[^\s@]+@[^\s@]+\.[^\s@]+$/,        // algo@algo.algo
  telefone: /^\d{10,11}$/,                        // 10 ou 11 dígitos (já limpo)
  data:     /^\d{2}\/\d{2}\/\d{4}$/,              // dd/mm/aaaa
  codigo:   /^[A-Z0-9]{8}$/,                      // código do convite, CHAR(8)
  soLetras: /^[A-Za-zÀ-ÿ\s]+$/,                   // nome sem número
};

function pareceEmail(v)    { return REGEX.email.test(v.trim()); }
function pareceTelefone(v) { return REGEX.telefone.test(v.replace(/\D/g, '')); }

3.1 CPF: regex não basta, precisa do dígito verificador

Um erro comum é achar que /^\d{11}$/ valida CPF. Valida o formato (onze dígitos), não o CPF. 00000000000 passa nesse regex e não é CPF nenhum. CPF de verdade tem dígito verificador, e a banca sabe disso. A função abaixo é feia mas é a que separa nível 2 de nível 3 num campo de documento:

function cpfValido(cpf) {
  cpf = cpf.replace(/\D/g, '');
  if (cpf.length !== 11 || /^(\d)\1{10}$/.test(cpf)) return false; // 111.111... é inválido

  const digito = (fatiaAte) => {
    let soma = 0, peso = fatiaAte + 1;
    for (let i = 0; i < fatiaAte; i++) soma += Number(cpf[i]) * (peso--);
    const resto = (soma * 10) % 11;
    return resto === 10 ? 0 : resto;
  };
  return digito(9) === Number(cpf[9]) && digito(10) === Number(cpf[10]);
}

No PHP a lógica é idêntica, muda a função: preg_match('/^[^\s@]+@[^\s@]+\.[^\s@]+$/', $email) no lugar do .test(). O padrão entre barras é o mesmo texto. Regex é uma linguagem só, viaja entre as stacks sem tradução.

4. Validações finas: os cantos que ninguém testa

O caminho feliz qualquer uma faz. Lapidação é cuidar dos cantos, e o jeito de não esquecer nenhum é varrer campo por campo perguntando "e se vier vazio? e se vier errado? e se vier absurdo?". Vira uma tabelinha por tela:

Cada linha dessas tratada com uma resposta clara é um ponto que sobe. Cada uma que quebra a tela é um ponto que cai.

5. Componente de confirmação de ação destrutiva

Toda ação que apaga ou desfaz algo importante pede uma pergunta antes: "tem certeza que quer apagar essa convidada?". É prevenção de erro (Nielsen, módulo 06) na veia, e evita o desastre do clique acidental que apaga a lista toda na frente da banca.

5.1 A gambiarra que já serve

O confirm() nativo do navegador resolve na marra e não custa nada:

if (confirm('Apagar essa convidada? Essa ação não volta.')) {
  await api(`/convidados/${id}`, { method: 'DELETE' });
  render();
}

Funciona, protege, e num aperto de tempo está de bom tamanho. Mas é feio (aquela caixa cinza do navegador quebra a identidade visual que a gente cuidou no módulo 06) e trava a página inteira enquanto está aberto.

5.2 O componente reusável (o que dá nível 3)

O pulo do gato é ter um componente de confirmação que combina com o sistema e serve pra tudo: apagar convidada, cancelar convite, resetar o evento. Faz uma vez, usa em todo lugar (componentização, módulo 05). A sacada é ele devolver uma Promise, pra usar com await igualzinho ao confirm() nativo, sem espalhar callback pelo código:

// confirmar.js — um componente, toda confirmação do sistema
function confirmar(mensagem) {
  return new Promise((resolve) => {
    const fundo = document.createElement('div');
    fundo.className = 'modal-fundo';
    fundo.innerHTML = `
      <div class="modal-caixa" role="alertdialog" aria-modal="true">
        <p>${mensagem}</p>
        <div class="modal-acoes">
          <button class="btn-cancelar" autofocus>Cancelar</button>
          <button class="btn-confirmar">Confirmar</button>
        </div>
      </div>`;
    document.body.appendChild(fundo);

    const fecha = (resposta) => { fundo.remove(); resolve(resposta); };
    fundo.querySelector('.btn-confirmar').onclick = () => fecha(true);
    fundo.querySelector('.btn-cancelar').onclick  = () => fecha(false);
    fundo.onkeydown = (e) => { if (e.key === 'Escape') fecha(false); }; // Esc cancela
  });
}

Uso no lugar do nativo, mesma cara, visual do sistema:

if (await confirmar('Apagar essa convidada? Essa ação não volta.')) {
  await api(`/convidados/${id}`, { method: 'DELETE' });
  render();
}

6. Busca, filtro e ordenação de ponta a ponta

Quando as listas crescem (e o seed em massa do módulo 03 faz elas crescerem de propósito), rolar a tela atrás de uma convidada é sofrimento. Lapidação adiciona três coisas que andam juntas: busca (achar pelo nome ou código), filtro (ver só confirmados, só pendentes, só quem já entrou) e ordenação (por nome, por status, por hora do check-in).

O ponto que pontua: isso acontece no servidor, não no front. A API recebe o que filtrar e o banco devolve só o que interessa, com o WHERE e o ORDER BY dos módulos 03 e 04. Trazer a lista inteira e filtrar no navegador funciona com 10 convidados e derrete com 500. Mostrar que você sabe onde cada coisa mora (o banco filtra, o back orquestra, o front mostra) é a maturidade que a banca lê como nível 3, e é como escala no mercado.

6.1 O SQL é um só

-- busca por nome OU código, filtro por status, ordenação escolhida
SELECT c.id, c.nome, c.status, ck.registrado_em
FROM convidado c
LEFT JOIN checkin ck ON ck.convidado_id = c.id
WHERE (c.nome LIKE ? OR c.codigo LIKE ?)
  AND (? = 'todos' OR c.status = ?)
ORDER BY c.nome ASC;

O LIKE com %termo% acha pedaço de nome. O truque do (? = 'todos' OR c.status = ?) deixa o mesmo SQL servir pra "todos" e pra um status específico, sem montar query diferente pra cada caso.

6.2 O endpoint muda de sintaxe entre as stacks

Conceito idêntico: ler os parâmetros da URL (?busca=ana&status=confirmado&ordem=nome), montar a consulta com prepared statement (nunca concatenar string, é a porta da SQL injection do módulo 04) e devolver o resultado.

Node + Express + mysql2:

app.get('/convidados', async (req, res) => {
  const { busca = '', status = 'todos', ordem = 'nome' } = req.query;

  // ordenação não entra por prepared statement (é nome de coluna), então valida por lista branca
  const colunas = { nome: 'c.nome', status: 'c.status', checkin: 'ck.registrado_em' };
  const orderBy = colunas[ordem] || 'c.nome';

  const termo = `%${busca}%`;
  const [linhas] = await db.query(
    `SELECT c.id, c.nome, c.status, ck.registrado_em
       FROM convidado c
       LEFT JOIN checkin ck ON ck.convidado_id = c.id
      WHERE (c.nome LIKE ? OR c.codigo LIKE ?)
        AND (? = 'todos' OR c.status = ?)
      ORDER BY ${orderBy} ASC`,
    [termo, termo, status, status]
  );
  res.json(linhas);
});

PHP + PDO:

$busca  = $_GET['busca']  ?? '';
$status = $_GET['status'] ?? 'todos';
$ordem  = $_GET['ordem']  ?? 'nome';

$colunas = ['nome' => 'c.nome', 'status' => 'c.status', 'checkin' => 'ck.registrado_em'];
$orderBy = $colunas[$ordem] ?? 'c.nome'; // lista branca, mesmo motivo

$termo = "%{$busca}%";
$sql = "SELECT c.id, c.nome, c.status, ck.registrado_em
          FROM convidado c
          LEFT JOIN checkin ck ON ck.convidado_id = c.id
         WHERE (c.nome LIKE ? OR c.codigo LIKE ?)
           AND (? = 'todos' OR c.status = ?)
         ORDER BY {$orderBy} ASC";
$stmt = $pdo->prepare($sql);
$stmt->execute([$termo, $termo, $status, $status]);
echo json_encode($stmt->fetchAll(PDO::FETCH_ASSOC));

6.3 No front, debounce pra não sufocar a API

Busca que dispara uma requisição a cada tecla manda dez chamadas pra escrever "roberto". O debounce segura: só busca quando a pessoa para de digitar por um tempinho.

function debounce(fn, ms = 300) {
  let t;
  return (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
}

const buscar = debounce(async (termo) => {
  const lista = await api(`/convidados?busca=${encodeURIComponent(termo)}`);
  renderLista(lista); // reusa o render dos quatro estados do módulo 05
}, 300);

campoBusca.addEventListener('input', (e) => buscar(e.target.value));

7. Código limpo, refatoração e OO (UC4)

Aqui a lapidação vira pra dentro do código. O sistema funciona, mas o código pode estar embolado, e a banca lê o código (é critério de julgamento explícito). Refatorar é melhorar a organização sem mudar o comportamento. Código limpo não é frescura: é o que faz a banca dar nível 3 em qualidade e é o que faz você achar o bug rápido quando o relógio da prova aperta. As duas coisas ao mesmo tempo.

7.1 Os quatro movimentos que pagam

Não precisa decorar os SOLID inteiros. Na prova, quatro movimentos resolvem quase tudo (é o Clean Code do Martin filtrado pro que a banca vê):

1. Nome que explica. Variável e função com nome que diz o que é.

// antes: ninguém sabe o que é
const x = c.filter(i => i.s === 'confirmado');
// depois: o nome é a documentação
const convidadosConfirmados = convidados.filter(c => c.status === 'confirmado');

2. Função curta que faz uma coisa. Se a função tem "e" no meio do que ela faz (valida e salva e renderiza), são três funções.

// antes: uma função que faz tudo, 40 linhas
async function salvar() { /* valida, monta payload, chama api, trata erro, re-renderiza... */ }
// depois: cada passo com nome, o salvar vira um roteiro legível
async function salvar() {
  const erros = validarFormulario();
  if (erros.length) return mostrarErros(erros);
  const payload = montarPayload();
  await enviarConvidado(payload);
  await recarregarLista();
}

3. DRY, o mesmo código num lugar só. O trecho copiado em cinco telas vira uma função. Se precisar mudar, muda num lugar (menos bug). O api() do módulo 05 já é isso: em vez de fetch repetido com header de token em toda tela, um helper só.

4. Sem número mágico, sem código morto. O 90 do alerta de capacidade (módulo 07) vira const LIMITE_ALERTA = 0.9. A função comentada que ninguém usa mais sai (o Git guarda a história, módulo 02, então apagar é seguro). Código morto confunde a banca e confunde você.

7.2 Um toque de orientação a objetos (UC4)

A UC4 é sobre código orientado a objetos, e dá pra pontuar com pouco: agrupar o que anda junto. Em vez de funções soltas de validação espalhadas, uma peça com responsabilidade clara. Pode ser uma classe ou um módulo, o que a stack pedir:

// validadorConvidado.js — encapsula as regras de uma convidada num lugar só
class ValidadorConvidado {
  constructor(dados) { this.dados = dados; this.erros = []; }

  validar() {
    if (!this.dados.nome?.trim())        this.erros.push('O nome é obrigatório.');
    if (this.dados.email && !pareceEmail(this.dados.email))
      this.erros.push('E-mail inválido.');
    if (this.dados.acompanhantes > 5)    this.erros.push('Máximo de 5 acompanhantes.');
    return this.erros;
  }
}
// uso: const erros = new ValidadorConvidado(payload).validar();

Ganhou três coisas: as regras da convidada moram num lugar (encapsulamento), o resto do código não precisa saber como valida (só chama .validar()), e pra mudar uma regra você sabe exatamente onde ir. Isso é OO servindo a lapidação, não OO por enfeite.

7.3 Refatorar com segurança: passo pequeno, teste, repete

Refatoração tem uma regra de sobrevivência: um passo de cada vez, testando entre um e outro. Renomeou uma função? Roda, vê se ainda funciona, commita (módulo 02). Só então extrai a próxima. Assim, se quebrou, você sabe exatamente o que quebrou (foi a última coisa) e o git te devolve pra antes num comando.

8. Padronização: o sistema parecendo feito por uma pessoa só

São duas competidoras codando o mesmo sistema. Sem combinação, sai uma colcha de retalhos: uma escreve nomeConvidado, a outra guest_name; uma indenta com dois espaços, a outra com quatro; um botão de ação é roxo numa tela e azul na outra. A banca percebe na hora, e isso derruba a nota de consistência (a heurística de consistência do Nielsen, módulo 06, agora aplicada ao código inteiro).

Consistência de ponta a ponta é combinar antes:

• No visual: os tokens do módulo 05 (--cor-acao, --espaco-*, --raio) resolvem. Se a cor de ação sai de um lugar só, ela é a mesma em toda tela por construção. Botão primário sempre no mesmo canto, mensagem sempre no mesmo tom.
• No código: um idioma só (tudo em português ou tudo em inglês, não misturado), um estilo de indentação, um jeito de organizar cada arquivo (a mesma ordem: imports, depois funções, depois o que dispara).

9. Mensagens de erro: a passada que mais paga

O módulo 06 já bateu nisso e a lapidação fecha de vez: passar o sistema inteiro trocando todo "deu erro" genérico por uma mensagem que diz o que aconteceu e o que fazer. É o ganho de nível 3 mais barato que existe, porque não muda lógica nenhuma, só troca texto, e sobe a percepção de qualidade da tela toda.

O segredo pra isso ser rápido é o back já mandar a mensagem pronta no formato único do módulo 04 ({ erro: 'texto pra pessoa', detalhes: [...] }) e o front só exibir o que chegou (o avisar() do módulo 05), em vez de cada tela inventar seu próprio texto. Mensagem boa nasce no back, viaja no formato padrão, aparece no componente padrão. Uma passada final só pra revisar as mensagens é das coisas de melhor retorno na reta final.

10. Testar como a banca vai testar (UC11)

O plano de curso tem uma UC inteira de testes (UC11), e ela não pede teste automatizado sofisticado na prova. Pede a mentalidade de teste: antes de dizer "pronto", usar o sistema tentando quebrar. Testar é procurar defeito de propósito, não confirmar que funciona.

10.1 O vocabulário que a banca (e a prova escrita) usa

Vale saber os nomes, porque a Prova Objetiva (módulo 01) cobra e falar a língua sobe a percepção na apresentação (módulo 10):

10.2 O checklist do sabotador (o plano de teste da prova)

Esse é o instrumento central da UC11 na prática. Na reta final, uma das duas usa o sistema de propósito errado enquanto a outra anota o que quebra. É simular a banca antes da banca. Cada linha que quebrou vira item pra lapidar:

11. Como o CIS enxerga a lapidação

Lapidação não tem uma linha própria na planilha CIS. Ela é transversal: sobe as notas de julgamento espalhadas por vários critérios ao mesmo tempo. É por isso que rende tanto. Onde cada frente desse módulo aparece na hora da correção:

12. Autoavaliação do módulo

Responder em voz alta, como se explicasse pra banca. Onde travar, o número da seção diz pra onde voltar.

1. Qual a diferença entre lapidar e adicionar funcionalidade? Por que a lapidação decide a competição mesmo sem ter peso próprio? (§1, §11)
2. Explica o padrão "formata pra mostrar, guarda limpo". Por que mandar "(51) 99999-9999" pro banco é erro? (§2)
3. Escreve de cabeça a máscara genérica por molde de #. Pra que campos ela serve? (§2.1)
4. Por que /^\d{11}$/ não valida um CPF? O que falta? (§3.1)
5. Por que um regex de e-mail simples ganha do "perfeito" na prova? (§3)
6. Preenche a tabela "vazio / errado / absurdo" pro campo capacidade da mesa. (§4)
7. Onde moram as três camadas de validação e qual o papel de cada uma? Por que validar só no front é armadilha? (§4)
8. Por que o componente de confirmação devolve uma Promise? Cita os três detalhes de acessibilidade que ele precisa ter. (§5)
9. Por que busca e filtro devem acontecer no servidor e não no front? (§6)
10. O que é a lista branca de colunas no ORDER BY e qual ataque ela previne? (§6.2)
11. O que é debounce e que problema ele resolve na busca? (§6.3)
12. Cita os quatro movimentos de código limpo que mais pagam na prova, com um exemplo de cada. (§7.1)
13. Como um pouco de OO (uma classe validadora) ajuda a lapidação? (§7.2)
14. Qual a regra de ouro pra refatorar sem quebrar? Por que nunca refatorar na véspera sem testar? (§7.3)
15. Reescreve três mensagens de erro genéricas pra mensagens úteis do Wedding Pass. (§9)
16. Diferencia caso de teste, teste de fronteira e teste de regressão com um exemplo do Wedding Pass em cada. (§10.1)
17. Como funciona o checklist do sabotador e por que ele é o plano de teste da UC11? (§10.2)
18. Por que uma máscara bem-feita rende ponto em dois critérios do CIS ao mesmo tempo? (§11)

Referências do módulo

Do plano de curso (bibliografia das UCs):

• UC4 — Desenvolver código orientado a objetos (92h): SCHILDT, Herbert. Java para iniciantes / referência de linguagem OO. GAMMA, Erich et al. Padrões de Projeto (Design Patterns), Bookman. Base pra §7 (encapsulamento, funções coesas, o embrião de Factory).
• UC11 — Realizar testes de software (36h): DELAMARO, Márcio E.; MALDONADO, José C.; JINO, Mario. Introdução ao Teste de Software, Elsevier. ANICHE, Maurício. Testes Automatizados de Software: um guia prático, Casa do Código. PRESSMAN, Roger S. Engenharia de Software, McGraw-Hill (capítulos de teste e qualidade). Base pra §10 (vocabulário: caso de teste, plano, caixa-preta/branca, fronteira, regressão, smoke).

Complementares de mercado (código limpo e refino):

• MARTIN, Robert C. Código Limpo (Clean Code), Alta Books. O filtro do §7 (nomes, funções curtas, DRY, sem código morto).
• MDN Web Docs, guia de Expressões Regulares: developer.mozilla.org/pt-BR/docs/Web/JavaScript/Guide/Regular_expressions. Base do §3.
• Refactoring Guru, catálogo de refatorações e padrões: refactoring.guru/pt-br. Apoio ao §7.3.
• MDN, Intl.NumberFormat / toLocaleString (formatação de moeda pt-BR): base do §2.2.