Aula 6 — Plano de Ensino — Back-End II · Endpoints de leitura e escrita

Identificação

Disciplina

IN02 · Desenvolvimento Web

Módulo

2 — Ciclo Comum

Aula

6 de 11

Carga horária do dia

6h (2h + 2h + 2h)

Modalidade

Presencial · Metodologia ativa

Pré-aula

Autoestudo guiado

Resumo

A aula 6 fecha o esqueleto do back-end. Os alunos completam o CRUD via HTTP — POST, PUT, PATCH, DELETE — com validação por zod, transações pg (BEGIN/COMMIT/ROLLBACK), erros de domínio (AppError/NotFoundError/ConflictError), middleware central de erro e wrapper asyncHandler.

A coreografia req → controller → service → repository → DB roda nos dois sentidos. Idempotência (PUT/DELETE vs POST) entra como conceito-chave para distinguir desenho de endpoint que pode ser re-tentado de outro que cria duplicidade.

Objetivos de aprendizagem

OA-1Implementar endpoints REST completos (POST/PUT/PATCH/DELETE) por recurso.
OA-2Validar payload com zod e devolver 400/422 em payload inválido.
OA-3Aplicar status codes corretos (201, 204, 409, 404, 422, 500).
OA-4Usar transações pg em operações multi-statement (BEGIN/COMMIT/ROLLBACK).
OA-5Centralizar tratamento de erro com middleware e classes AppError.
OA-6Diferenciar idempotência de PUT/DELETE vs POST.

Pré-requisitos

Aula 5 concluída: setup TypeScript + Node.js + Express + pg rodando localmente.
Arquitetura MVC de 6 camadas implementada (models, views, controllers, services, repositories, helpers).
GET do recurso principal já implementado, com specs Jest verdes.

Cronograma do dia

📚 Bloco 1 · Autoestudo

08h00 — 10h00

Estudo individual orientado pelo material da aula 6.

Leitura completa do Material da Aula 6 (REST, zod, transações, middleware de erro, idempotência).
Listar 3 regras de negócio do projeto que precisam de transação para manter consistência.
Validar que as specs Jest da aula 5 (GET) estão verdes — pré-requisito para qualquer escrita.
Caderno de bordo: anotar dúvidas sobre quando usar PUT vs PATCH.

🎓 Bloco 2 · Instrução PE — Aula em metodologia ativa

10h00 — 12h00

Encontro síncrono com o professor especialista. 15 minutos de daily seguidos de 1h45 de aula.

10h00 — 10h15 · Daily: regras de negócio trazidas do autoestudo.
10h15 — 12h00 · REST refresher, zod, transações, AppError, middleware, idempotência.

🍴 Intervalo · Almoço

12h00 — 14h00

Janela livre.

🛠️ Bloco 3 · Desenvolvimento do projeto

14h00 — 16h00

Janela de trabalho da equipe sobre o projeto integrador.

Implementar o CRUD completo do recurso principal do projeto: POST, PUT, PATCH, DELETE.
Validar payload em todos os endpoints com schemas zod.
Aplicar transação pg em pelo menos 1 operação multi-statement.
Specs Jest + supertest verdes para todos os verbos.
Abrir Merge Request feat(api): crud completo do recurso X com evidência de execução.

Detalhamento da instrução PE (10h00 — 12h00)

10h00
10h15

DailyDaily de abertura

Cada aluno apresenta, em 1 minuto, uma regra de negócio do projeto que precisa de transação para não corromper dados.

10h15
10h35

TalkREST verbos × CRUD × status codes

Mapeamento dos verbos HTTP em operações de banco. Quadro com a tabela: POST=201, PUT=200/204, PATCH=200, DELETE=204, 409 em conflito, 404 em recurso ausente, 422 em payload inválido.

10h35
10h55

CodingSpec do POST primeiro (RED)

Coding em pares: escrever o describe('POST /users') com supertest antes de qualquer implementação. RED forçando design pelo teste. Discussão sobre o status esperado e o shape da resposta.

10h55
11h15

AtivaValidação com zod — exemplo guiado

Em pares, escrever um schema zod para o payload do POST, integrar no controller via schema.safeParse(req.body) e devolver 422 com a lista de erros. Debate sobre 400 vs 422.

11h15
11h35

CodingTransação no repository (BEGIN/COMMIT/ROLLBACK)

Mob programming: refatorar uma operação multi-statement (ex.: criar pedido + itens) usando client = await pool.connect(), BEGIN, dois INSERT, COMMIT, ROLLBACK em catch e client.release() no finally.

11h35
11h50

TalkErros de domínio + middleware central

Apresentação das classes AppError, NotFoundError, ConflictError. Wrapper asyncHandler capturando promises rejeitadas. Middleware central (err, req, res, next) mapeando classe → status. Debate sobre por que NUNCA logar err.stack em produção sem sanitizar.

11h50
12h00

AtivaSíntese + idempotência

Cada aluno escreve em 30 segundos a diferença entre POST e PUT. Coletivo: por que retentar um POST pode duplicar e retentar um PUT não. Anúncio da entrega da tarde: CRUD completo + MR.

Estratégias de metodologia ativa

Predição antes do código — alunos escrevem o teste primeiro (TDD-flavored), forçando a explicitar o contrato antes da implementação.
Mob programming na transação — toda a turma orienta um único par escrevendo a transação, expondo o raciocínio em voz alta sobre ROLLBACK e release.
Debate sobre idempotência — pergunta provocativa "qual cliente HTTP você confia para retentar?" cria contexto para a regra do verbo idempotente.

Recursos e ferramentas

Categoria	Recurso	Uso
Slides	`slides/slide-lesson-6.html`	Exposição na instrução PE
Material	`materials/lesson-6-material.html`	Autoestudo
Validação	`zod`	Schemas de payload nos controllers
Banco	`pg` (transações)	`BEGIN/COMMIT/ROLLBACK` em operações multi-statement
Testes	Jest + `supertest`	Specs por verbo HTTP
Manual	REST Client (`.http`)	Testes manuais dos endpoints
Repositório	`src/`	Controllers, services, repositories

Verificação de aprendizagem

CR-1Spec do POST com supertest verde, devolvendo 201 e o recurso criado.
CR-2Validação zod retornando 422 em payload inválido, com lista de erros.
CR-3Transação pg aplicada em pelo menos 1 operação multi-statement com ROLLBACK testado.
CR-4AppError/NotFoundError/ConflictError ligados ao middleware central de erro.
CR-5Merge Request feat(api): crud completo do recurso X aberto até as 16h00.

Critério mínimo

Aluno que sair às 16h sem ao menos POST + DELETE funcionais com validação zod está em débito técnico para iniciar o front-end na aula 7.

Conexão com a aula 7

O back-end pronto começa a ganhar interface visível na aula 7 — Front-End I com SSR + EJS. Os mesmos controllers ganharão um par res.render(...) para servir HTML em vez de (ou ao lado de) JSON.

Os services e repositories escritos hoje serão reaproveitados sem alteração — só a camada de Views muda.
O contrato de validação zod seguirá vivo: forms tradicionais entram pelo mesmo controller e passam pela mesma validação.

Para o autoestudo da aula 7

Antes das 8h do próximo dia: ler o material da aula 7, esboçar wireframe de 2 telas do projeto e instalar EJS (npm i ejs) no repositório.