Aula 15 — Deploy, apresentação e finalização

🎯 Objetivos de aprendizagem¶

Ao final desta aula você será capaz de:

• Gerar o build de produção de uma aplicação Vue com Vite e explicar o que existe dentro de dist/.
• Publicar o front-end em um serviço de hospedagem estática (Vercel, Firebase Hosting ou GitHub Pages), configurando variáveis de ambiente e rewrite de SPA.
• Publicar o back-end Express em um serviço de nuvem, com PORT dinâmico, health check e variáveis de ambiente seguras.
• Escrever um Dockerfile simples para a API e um docker-compose.yml com API + MySQL.
• Diagnosticar e corrigir os erros mais comuns pós-deploy (CORS, mixed content, 404 em rota interna, banco inacessível).
• Configurar um pipeline básico de CI/CD no GitHub Actions que roda lint e testes a cada push.
• Relacionar cada padrão de projeto estudado no semestre ao trecho de código onde ele apareceu no UniEventos.
• Apresentar o projeto autoral em formato de seminário técnico, dentro de um tempo definido, explicando as próprias decisões técnicas.
• Alcançar o Marco 3 do projeto autoral, conferindo cada requisito da unidade de ponta a ponta.

📋 Pré-requisitos desta aula¶

Na Aula 14 documentamos a API inteira com OpenAPI e Swagger UI — qualquer pessoa consegue entender e testar o UniEventos sem ler uma linha de código. Falta uma última etapa: tirar o projeto do localhost e colocá-lo no ar, com URL pública, para qualquer pessoa acessar. Hoje fechamos esse ciclo — e fechamos o semestre.

• unieventos-api (ou projeto autoral) com arquitetura em camadas (Aula 13) e documentação Swagger (Aula 14) completas.
• Front-end (unieventos-web ou equivalente) com build funcionando localmente (npm run build sem erro).
• Conta gratuita em pelo menos um serviço de hospedagem de front (Vercel, Netlify, Firebase Hosting ou GitHub Pages) e um de back (Render, Railway ou Fly.io).
• Repositórios do projeto autoral publicados e atualizados no GitHub.

Checklist antes de começar:

• [ ] npm run build do front gera a pasta dist/ sem erro.
• [ ] npm test do back passa localmente.
• [ ] Você tem acesso de administrador aos dois repositórios (front e back) no GitHub.

🗺️ Roteiro¶

1. Build de produção do front-end¶

1.1 O que npm run build faz¶

cd unieventos-web
npm run build

O Vite lê src/, resolve todos os imports, faz tree-shaking (remove código não utilizado), minifica JavaScript e CSS, gera hashes nos nomes de arquivo (para cache eficiente no navegador) e escreve tudo em dist/:

dist/
├─ assets/
│  ├─ index-BvPPrto3.css     ← todo o CSS do projeto, minificado
│  ├─ index-EL0WAqE7.js      ← todo o JavaScript, empacotado e minificado
│  └─ materialdesignicons-*.woff2  ← fontes de ícone do @mdi/font
├─ favicon.ico
└─ index.html                ← HTML final, já referenciando os assets com hash

🔎 Por baixo do capô O hash no nome do arquivo (index-BvPPrto3.js) muda sempre que o conteúdo muda. Isso permite configurar cache agressivo e "para sempre" nesses arquivos no servidor: o navegador só baixa de novo se o hash (e portanto o conteúdo) mudou. O index.html, em contrapartida, nunca deve ser cacheado agressivamente — ele é o que aponta para os hashes corretos a cada novo deploy.

🔬 Investigue Abra a aba Network do DevTools em qualquer site grande que você usa no dia a dia (não precisa ser o UniEventos) e clique num arquivo .js ou .css com um hash estranho no nome. Olhe o cabeçalho de resposta Cache-Control — em serviços bem configurados, ele costuma trazer algo como max-age=31536000, immutable (um ano). Agora clique no documento principal da página (o HTML) e compare: o Cache-Control dele é bem mais curto, ou no-cache. Por que faz sentido cachear "para sempre" um arquivo, mas nunca o HTML que aponta para ele?

dist/ é tudo que o servidor de hospedagem precisa: arquivos estáticos, sem Node.js rodando por trás. É por isso que hospedar um front-end Vue construído é barato (ou gratuito) — não é um processo de servidor, é só arquivos.

1.2 Variáveis de ambiente do Vite¶

O Vite só expõe ao código do navegador variáveis de ambiente prefixadas com VITE_ — qualquer outra fica de fora do bundle final, por segurança (evita vazar segredos de build no JavaScript público).

# .env.production — lido automaticamente quando NODE_ENV=production (no build)
VITE_API_URL=https://unieventos-api.onrender.com/api
VITE_FIREBASE_API_KEY=AIzaSy...
VITE_FIREBASE_AUTH_DOMAIN=unieventos.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=unieventos

# .env.development — lido em npm run dev
VITE_API_URL=http://localhost:3000/api
VITE_FIREBASE_API_KEY=AIzaSy...
VITE_FIREBASE_AUTH_DOMAIN=unieventos.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=unieventos

// src/services/http.js — o cliente da Aula 06, agora lendo a variável de ambiente
import axios from 'axios'

const http = axios.create({
  baseURL: import.meta.env.VITE_API_URL, // troca sozinho entre dev e produção
})

export default http

⚠️ Atenção VITE_API_URL inclui o sufixo /api — é o prefixo em que a unieventos-api monta suas rotas desde a Aula 07. Os services chamam http.get('/eventos'), e a URL final vira .../api/eventos. Esquecer o /api aqui é o erro pós-deploy mais comum: tudo compila, tudo publica, e toda requisição volta 404 porque foi para .../eventos.

⚠️ Atenção import.meta.env.VITE_* só existe em tempo de build — o Vite substitui essas referências por valores literais no JavaScript final. Trocar a variável depois do build (por exemplo, direto no painel do serviço de hospedagem, sem rebuildar) não tem efeito nenhum: você precisa gerar um novo build para que um novo valor de VITE_API_URL entre no bundle. Serviços como Vercel fazem isso automaticamente a cada push, rodando npm run build de novo.

1.3 base no vite.config.js¶

Se o site for publicado em um subcaminho (comum no GitHub Pages, ex.: usuario.github.io/unieventos-web/), configure base:

// vite.config.js — trecho relevante para deploy em subcaminho
export default defineConfig({
  base: '/unieventos-web/', // necessário só se NÃO estiver na raiz do domínio
  plugins: [
    vue({ template: { transformAssetUrls } }),
    vuetify({ autoImport: true }),
  ],
})

Em Vercel, Netlify e Firebase Hosting, o projeto normalmente fica na raiz do domínio (base: '/', o padrão) — só ajuste isso para GitHub Pages em repositório de projeto (não em usuario.github.io).

1.4 Por que SPA precisa de rewrite para index.html¶

Uma SPA como o UniEventos tem uma única página real (index.html); rotas como /eventos/3 ou /minhas-inscricoes só existem no navegador, resolvidas pelo Vue Router (Aula 04) via History API — o servidor nunca teve, e nunca terá, um arquivo físico chamado eventos/3.

O problema: se o usuário aperta F5 (recarrega a página) estando em /eventos/3, o navegador faz uma requisição HTTP real, ao servidor, pedindo o caminho /eventos/3. Um servidor de arquivos estáticos comum não encontra esse arquivo e responde 404.

A solução é configurar o servidor para, em qualquer caminho que não seja um arquivo estático real, devolver index.html — o Vue Router então assume o controle no navegador e resolve a rota /eventos/3 normalmente.

// vercel.json — rewrite de SPA na Vercel
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

# _redirects — Netlify (arquivo dentro de public/, copiado para dist/ no build)
/*  /index.html  200

// firebase.json — trecho relevante do Firebase Hosting
{
  "hosting": {
    "public": "dist",
    "rewrites": [
      { "source": "**", "destination": "/index.html" }
    ]
  }
}

📌 Vale gravar "F5 em rota interna dá 404" é o sintoma mais clássico de rewrite de SPA mal configurado. Sempre que alguém relatar esse erro pós-deploy, a primeira pergunta é: "o servidor está configurado para devolver index.html em qualquer caminho desconhecido?"

2. Deploy do front-end¶

2.1 Vercel (recomendado — passo a passo testado)¶

1. Crie conta em vercel.com usando login do GitHub.
2. No painel, clique "Add New... → Project" e selecione o repositório unieventos-web.
3. A Vercel detecta automaticamente que é um projeto Vite. Confirme: - Build Command: npm run build - Output Directory: dist
4. Antes de clicar em "Deploy", adicione as variáveis de ambiente na seção Environment Variables: VITE_API_URL, VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID — os mesmos valores do seu .env.production local.
5. Clique Deploy. Em cerca de 1 minuto, a Vercel devolve uma URL pública (https://unieventos-web.vercel.app).
6. A cada git push na branch main, a Vercel refaz o deploy automaticamente.

💡 Dica A Vercel também cria um preview deploy automático para cada Pull Request, com URL própria — ótimo para revisar uma feature antes de mesclar em main, mas não obrigatório nesta trilha.

2.2 Alternativa: Firebase Hosting¶

npm install -g firebase-tools
firebase login
firebase init hosting
# Public directory: dist
# Configure as a single-page app (rewrite all urls to /index.html)? Yes
# Set up automatic builds and deploys with GitHub? (opcional, responda conforme preferir)

npm run build
firebase deploy --only hosting

Como o UniEventos já usa Firebase Auth (Aula 10), hospedar no Firebase Hosting mantém tudo no mesmo painel — vantagem organizacional, sem necessidade técnica adicional.

2.3 Alternativa: GitHub Pages¶

npm install -D gh-pages

// package.json — trecho de "scripts"
{
  "scripts": {
    "deploy": "npm run build && gh-pages -d dist"
  }
}

Lembre de configurar base: '/unieventos-web/' no vite.config.js (Seção 1.3) antes de publicar, já que o GitHub Pages de repositório de projeto serve em um subcaminho. Depois:

npm run deploy

A URL pública fica em https://<seu-usuario>.github.io/unieventos-web/. Habilite em Settings → Pages do repositório, escolhendo a branch gh-pages (criada automaticamente pelo pacote gh-pages) como fonte.

3. Deploy do back-end¶

3.1 O essencial, independente do serviço escolhido¶

// src/server.js — PORT precisa vir do ambiente, nunca fixo
import { app } from './app.js'
import { config } from './config/index.js'

// A maioria dos serviços de nuvem injeta a variável PORT automaticamente —
// escutar em uma porta fixa (3000) quebra o deploy nesses ambientes.
const servidor = app.listen(config.PORT, () => {
  console.log(`API rodando na porta ${config.PORT}`)
})

// package.json — script "start" é o que o serviço de deploy roda em produção
{
  "scripts": {
    "start": "node src/server.js",
    "dev": "node --watch src/server.js"
  }
}

// trecho de src/app.js — health check simples, usado pelo serviço de deploy
// para saber se o processo está de pé (e reiniciar automaticamente se não estiver)
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', ambiente: config.NODE_ENV })
})

Checklist mínimo antes de publicar o back:

• [ ] PORT vem de process.env.PORT (via config, Aula 13), nunca hardcoded.
• [ ] Script start existe em package.json e sobe a API com node puro (sem --watch, que é só para desenvolvimento).
• [ ] GET /health responde 200 sem exigir autenticação nem banco de dados obrigatoriamente disponível.
• [ ] Banco de dados gerenciado (não localhost) — MySQL na nuvem (ex.: Railway, PlanetScale-compatível, ou o banco oferecido pelo próprio Render).
• [ ] Todas as variáveis de .env configuradas como secrets no painel do serviço, nunca commitadas no Git.

3.2 Opções gratuitas/baratas e o que considerar¶

⚠️ Atenção — cold start Planos gratuitos costumam "dormir" o processo após um período sem tráfego. A primeira requisição depois disso demora vários segundos (o serviço precisa religar o container). Isso é normal e esperado no plano gratuito — não é bug do seu código. Avise sobre isso na apresentação se seu projeto usar plano gratuito.

3.3 Deploy na Render (passo a passo)¶

1. Crie conta em render.com com login do GitHub.
2. New → Web Service, selecione o repositório unieventos-api.
3. Configure: - Runtime: Node - Build Command: npm install - Start Command: npm start
4. Na aba Environment, adicione todas as variáveis do seu .env (exceto as que só existem localmente).
5. Se precisar de MySQL gerenciado, crie um New → MySQL (ou Postgres, se preferir migrar) separado na Render e copie a string de conexão para as variáveis DB_* do Web Service.
6. Clique Create Web Service. A Render builda, sobe o processo, e devolve uma URL pública (https://unieventos-api.onrender.com).
7. Rode as migrations manualmente uma vez, via o Shell da Render (aba disponível no painel do serviço) ou como Build Command combinado: npm install && npm run migrar.

3.4 Dockerfile simples para a API¶

Mesmo usando um serviço que builda direto do GitHub, ter um Dockerfile documenta exatamente o ambiente de execução e permite rodar a API localmente de forma idêntica à produção.

# Dockerfile
FROM node:22-alpine

WORKDIR /app

# Copiar só os arquivos de manifesto primeiro aproveita o cache de camadas do
# Docker: se package.json não mudou, o npm install não roda de novo no rebuild.
COPY package.json package-lock.json ./
RUN npm install --omit=dev

COPY src ./src
COPY migrations ./migrations
COPY scripts ./scripts

EXPOSE 3000

CMD ["npm", "start"]

# .dockerignore
node_modules
.env
.git
test

docker build -t unieventos-api .
docker run -p 3000:3000 --env-file .env unieventos-api

🧠 Você sabia? Contêineres não são uma invenção da Docker. As primitivas do kernel Linux que tornam a isolação possível — cgroups (limitar quanto de CPU e memória um processo pode usar) e namespaces (isolar o que um processo enxerga do sistema) — existem desde 2007/2008, quase seis anos antes do lançamento da Docker em 2013. O que a Docker inventou não foi a isolação em si: foi a experiência — empacotar essas primitivas complexas atrás de um Dockerfile legível e de dois comandos (docker build, docker run) que qualquer pessoa consegue usar sem entender kernel Linux por dentro.

3.5 docker-compose.yml com API + MySQL¶

# docker-compose.yml
services:
  api:
    build: .
    ports:
      - '3000:3000'
    environment:
      NODE_ENV: development
      PORT: 3000
      DB_HOST: mysql
      DB_PORT: 3306
      DB_USER: root
      DB_PASSWORD: senha_local
      DB_NAME: unieventos
      FIREBASE_PROJECT_ID: unieventos
      CORS_ORIGEM_PERMITIDA: http://localhost:5173
    depends_on:
      mysql:
        condition: service_healthy

  mysql:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: senha_local
      MYSQL_DATABASE: unieventos
    ports:
      - '3306:3306'
    volumes:
      - dados_mysql:/var/lib/mysql
    healthcheck:
      test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost']
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  dados_mysql:

docker compose up --build
# API e MySQL sobem juntos, na mesma rede virtual — a API conversa
# com o banco pelo nome do serviço ("mysql"), não por "localhost"

🔎 Por baixo do capô Dentro da rede criada pelo docker compose, cada serviço enxerga os outros pelo nome do serviço no YAML (mysql), não por localhost — por isso DB_HOST: mysql e não DB_HOST: localhost. O valor de "isso funcionar de primeira" é enorme: qualquer pessoa que clonar o repositório sobe o ambiente completo (API + banco, com schema aplicável via npm run migrar) com um único comando, sem instalar MySQL na própria máquina.

4. CORS em produção e diagnóstico de erros pós-deploy¶

Em produção, restrinja CORS apenas ao domínio real do front publicado — nunca deixe origin: '*' ou o domínio de localhost esquecido em produção:

# .env de produção da API
CORS_ORIGEM_PERMITIDA=https://unieventos-web.vercel.app

4.1 Erros clássicos pós-deploy e como diagnosticar¶

💡 Dica Sempre teste /health primeiro depois de um deploy. Se ele responde 200, o processo subiu — o problema está em uma camada específica (banco, CORS, variável de ambiente), não na infraestrutura toda.

5. CI/CD introdutório com GitHub Actions¶

CI (Integração Contínua) roda verificações automáticas a cada mudança no código — lint e testes, neste caso. CD (Entrega Contínua) automatiza a publicação quando essas verificações passam. Juntos, eliminam o "funciona na minha máquina" e o deploy manual esquecido.

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: ['**']
  pull_request:
    branches: [main]

jobs:
  lint-e-testes:
    runs-on: ubuntu-latest

    steps:
      - name: Baixar o código do repositório
        uses: actions/checkout@v4

      - name: Configurar Node.js 22
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Instalar dependências
        run: npm ci

      - name: Rodar lint
        run: npm run lint --if-present

      - name: Rodar testes
        run: npm test

  deploy:
    needs: lint-e-testes
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest

    steps:
      - name: Baixar o código do repositório
        uses: actions/checkout@v4

      - name: Disparar deploy na Render via deploy hook
        run: curl -X POST "${{ secrets.RENDER_DEPLOY_HOOK_URL }}"

Explicando as partes:

• on.push.branches: ['**'] — roda lint/teste em qualquer push, em qualquer branch, dando feedback rápido antes mesmo de abrir Pull Request.
• needs: lint-e-testes — o job deploy só roda depois que lint-e-testes termina com sucesso; se um teste falhar, o deploy nunca acontece.
• if: github.ref == 'refs/heads/main' && github.event_name == 'push' — restringe o deploy a pushes diretos (ou merges) na branch main, nunca em branches de feature.
• secrets.RENDER_DEPLOY_HOOK_URL — configurado em Settings → Secrets and variables → Actions do repositório GitHub; nunca aparece em texto puro no workflow nem no log de execução.

⚠️ Atenção npm ci (não npm install) dentro de workflows de CI: ele instala exatamente as versões travadas em package-lock.json, de forma determinística, e falha se o lockfile estiver dessincronizado do package.json — evita o "passou no CI, mas com uma versão diferente da que alguém tem local".

Para a Vercel (front-end), normalmente não é preciso workflow de deploy próprio — a integração da Vercel com o GitHub já dispara build e deploy automaticamente a cada push em main, de forma nativa, sem depender do GitHub Actions.

🔎 Por baixo do capô O nome "CI/CD" às vezes confunde por juntar duas ideias distintas. Integração Contínua é sobre confiança: cada push prova, automaticamente, que o código continua íntegro (lint limpo, testes passando) antes de qualquer humano revisar. Entrega/Implantação Contínua é sobre velocidade: reduzir a distância entre "código pronto" e "código no ar" para minutos, não para um ritual manual de deploy que alguém precisa lembrar de fazer. O workflow desta seção faz as duas coisas: garante qualidade antes, entrega depois — e só entrega se a qualidade passou.

💡 Dica Um erro comum de quem está aprendendo CI/CD é tratar o pipeline como "burocracia extra". Na prática, ele é o que permite a um time (ou a você sozinho, meses depois) fazer mudanças com confiança: se o CI ficou verde, você sabe que não quebrou nada que já estava coberto por teste — sem isso, cada mudança pequena vira um momento de ansiedade.

6. Retrospectiva da trilha¶

6.1 Mapa mental textual do que foi construído¶

UniEventos
│
├─ Front-end (unieventos-web)
│  ├─ Vue 3 (Composition API, <script setup>)          — Aulas 01–03
│  ├─ Vuetify 4 (UI, layout, formulários)               — Aulas 04–05
│  ├─ Vue Router 5 (SPA navegável, guards)              — Aulas 04, 10
│  ├─ Pinia 4 (estado global: usuário, eventos)          — Aula 06
│  ├─ Axios (consumo da API, interceptors)               — Aula 06
│  ├─ Firebase Auth (login, cadastro)                    — Aula 10
│  └─ Deploy (Vercel/Firebase Hosting/GitHub Pages)      — Aula 15
│
├─ Back-end (unieventos-api)
│  ├─ Node.js + Express 5 (rotas, middlewares)           — Aula 07–08
│  ├─ MySQL (mysql2/promise, pool, transações)           — Aula 09
│  ├─ Firebase Admin (verificação de token)               — Aula 10
│  ├─ CRUD completo (front + back integrados)             — Aula 11
│  ├─ Supabase (alternativa: RLS, Storage, Realtime)      — Aula 12
│  ├─ Arquitetura em camadas + testes + segurança         — Aula 13
│  ├─ Documentação OpenAPI/Swagger                        — Aula 14
│  └─ Deploy + CI/CD                                      — Aula 15
│
└─ Padrões de projeto (GoF) — ver tabela consolidada abaixo

🧩 Todos os padrões de projeto usados nesta trilha¶

Esta trilha cobre explicitamente padrões criacionais, estruturais e comportamentais. Aqui está a lista completa, com onde cada um apareceu de verdade no UniEventos.

Criacionais

Estruturais

Comportamentais

📌 Vale gravar Dominar de verdade os padrões de projeto desta trilha exige duas coisas: saber a definição de cada padrão e conseguir apontar um exemplo concreto de onde ele apareceu — não basta decorar o nome, é preciso reconhecer o padrão dentro de um trecho de código real.

7. Teste seu domínio: padrões de projeto e arquitetura de toda a trilha¶

Esta seção é uma autoavaliação, cobrindo as três unidades desta trilha. O objetivo não é "rodar código" — é entender o porquê de cada decisão técnica, não só a sintaxe. Use as perguntas para descobrir sozinho o que você já domina e o que vale revisar antes de fechar o projeto (ou de explicar seu código na apresentação).

7.1 Lista de 25 a 30 perguntas para se testar¶

Unidade 1 — Fundamentos de Vue.js

1. O que é programação declarativa e como ela difere de manipulação manual do DOM? (Aula 01)
2. O que é reatividade no Vue e qual padrão de projeto (GoF) explica seu funcionamento? (Aula 02)
3. Qual a diferença entre Options API e Composition API? Quando usar <script setup>? (Aula 02)
4. Como reactive() e ref() diferem na forma como armazenam e expõem o valor? (Aula 03)
5. Por que v-for sempre precisa de :key, e o que acontece se ela faltar? (Aula 02–03)
6. O que é uma computed e por que ela é preferível a um método equivalente, em termos de performance? (Aula 03)
7. Qual é a diferença entre onMounted e o restante do ciclo de vida de um componente? (Aula 03)

Unidade 2 — Vue avançado (Vuetify, Vue Router, Axios, Pinia)

8. Como o Vue Router resolve navegação sem recarregar a página inteira (SPA)? (Aula 04)
9. O que é um navigation guard e para que serve beforeEach? (Aula 10)
10. Por que instanciar axios.create({ baseURL }) com interceptors é melhor do que usar axios global? (Aula 06)
11. Que padrão de projeto os interceptors do Axios exemplificam? (Aula 06)
12. Qual é o papel do Pinia como single source of truth do estado da aplicação? (Aula 06)
13. Por que a store Pinia é um exemplo de Singleton? (Aula 06)
14. Como slots permitem que um componente de layout seja reutilizável em vários contextos? (Aula 05)
15. O que muda estruturalmente do Vuetify 3 para o Vuetify 4 (tema padrão, tipografia, breakpoints)? (Aula 04–05)

Unidade 3 — Back-end, autenticação, banco de dados, deploy

16. Qual a diferença entre autenticação e autorização, e onde cada uma aparece no UniEventos? (Aula 10)
17. Como o Express 5 muda o tratamento de erros assíncronos em relação ao Express 4? (Aula 07–08, 13)
18. O que é middleware no Express e que padrão de projeto (GoF) o pipeline de middlewares representa? (Aula 07–08)
19. Por que usar mysql2/promise com queries parametrizadas (?) em vez de concatenar strings? (Aula 09)
20. O que é uma transação de banco de dados e quando ela é necessária? (Aula 09)
21. Como o back-end verifica um token do Firebase, e por que essa verificação precisa acontecer no servidor (nunca só no front)? (Aula 10)
22. O que é RLS (Row Level Security) no Supabase, e por que uma tabela com RLS habilitado e sem policies retorna lista vazia sem erro? (Aula 12)
23. Que padrão de projeto permite trocar MySQL por Supabase sem alterar o front-end? (Aula 12)
24. O que é injeção de dependência, e por que um service que recebe o repositório por parâmetro é mais testável? (Aula 13)
25. Qual a diferença entre um erro operacional (esperado) e um erro inesperado, e por que essa diferença importa no log? (Aula 13)
26. Por que nunca se deve vazar stack trace em uma resposta de erro em produção? (Aula 13)
27. Qual a diferença entre OpenAPI e Swagger? (Aula 14)
28. Por que a chave correta no swagger-jsdoc 6.x é definition, e o que acontece se usar swaggerDefinition? (Aula 14)
29. O que é uma migration de banco de dados e por que ela substitui um schema.sql aplicado manualmente? (Aula 13)
30. Por que uma SPA precisa de configuração de rewrite no servidor de hospedagem para funcionar corretamente com F5 em rotas internas? (Aula 15)

7.2 Questões objetivas de exemplo, com gabarito comentado¶

1. No Vue 3, o sistema de reatividade (reactive, ref) é implementado, por baixo dos panos, principalmente com:

(A) Object.defineProperty apenas (B) Proxy do ES6 (C) WeakMap apenas (D) Getters e setters manuais escritos pelo desenvolvedor

2. Em Express 5, qual das alternativas abaixo é a forma correta de responder com status 201 e um corpo JSON?

(A) res.json(objeto, 201) (B) res.status(201).json(objeto) (C) res.send(201, objeto) (D) res.json(201, objeto)

3. Uma tabela no Supabase tem RLS (Row Level Security) habilitado, mas nenhuma policy foi criada. Uma consulta SELECT feita por um cliente autenticado retorna:

(A) Um erro 403 Forbidden (B) Todos os registros da tabela, normalmente (C) data: [], sem nenhum erro (D) Um erro 500 Internal Server Error

4. Qual padrão de projeto GoF melhor descreve o pipeline de middlewares do Express, em que cada função decide processar a requisição e passá-la adiante com next(), ou interrompê-la?

(A) Observer (B) Chain of Responsibility (C) Singleton (D) Facade

5. Sobre swagger-jsdoc na versão 6.x usada nesta trilha, a chave correta dentro das opções para declarar openapi, info e components é:

(A) swaggerDefinition (B) spec (C) definition (D) openApiDefinition

6. Por que uma SPA hospedada em produção pode retornar 404 ao usuário apertar F5 em uma rota interna como /eventos/3?

(A) Porque o Vue Router não suporta navegação direta por URL (B) Porque o servidor de hospedagem, sem configuração de rewrite, procura um arquivo físico eventos/3 que não existe (C) Porque o Vite não gera index.html no build de produção (D) Porque import.meta.env não funciona em produção

7. No padrão de injeção de dependência aplicado na Aula 13, qual é a principal vantagem de um service receber o repository como parâmetro em vez de importá-lo diretamente?

(A) O código fica mais curto (B) É possível testar o service com um repositório falso, sem depender de um banco de dados real (C) É a única forma de usar async/await no Node.js (D) Reduz o número de arquivos do projeto

8. No Vuetify 4, o comportamento padrão da propriedade theme.defaultTheme, se não for explicitamente definida, é:

(A) 'light', igual ao Vuetify 3 (B) 'dark' (C) 'system' — segue a preferência do sistema operacional do usuário (D) Não existe tema padrão; é obrigatório declarar

8. Apresentação dos resultados¶

8.1 Estrutura da apresentação final¶

Apresente seu projeto autoral individualmente, em 8 minutos, cobrindo estes pontos:

1. O problema (1 min) — que problema real o projeto resolve, para quem.
2. Demonstração ao vivo (3 min) — navegar pela aplicação publicada (URL real, não localhost): listagem com filtro, detalhe, fluxo autenticado, CRUD funcionando.
3. Arquitetura (2 min) — diagrama rápido das camadas (front → API → banco), tecnologias escolhidas, e onde a documentação Swagger vive.
4. Decisão técnica mais difícil (1 min) — um problema real enfrentado e como foi resolvido (ex.: "por que troquei X por Y", "como resolvi o CORS em produção").
5. O que faria diferente (1 min) — autoavaliação honesta: o que ficaria melhor com mais tempo ou outra escolha técnica.

8.2 O que uma boa apresentação tem¶

Use esta tabela para se autoavaliar — ou peça a um colega que assista e aponte o que falta:

⚠️ Atenção A apresentação é sobre o projeto autoral publicado, com URL pública real — apresentar rodando em localhost não mostra o que você realmente construiu. Se o deploy falhar na hora, tenha um vídeo curto de backup gravado com antecedência mostrando o fluxo funcionando.

8.3 Quando apresentar¶

Se você está seguindo esta trilha em uma turma com professor, apresente na ordem e no dia combinados por ele, dentro do tempo do encontro. Se está estudando por conta própria, grave a apresentação e revise-a no dia seguinte, ou apresente-a para outra pessoa — um colega de estudo, alguém da família, ou uma chamada rápida com alguém da comunidade. O que importa é o exercício em si: explicar o próprio projeto em voz alta, dentro de um tempo limitado.

9. Encerramento: caminhos depois desta trilha¶

O que foi construído nesta trilha é uma base real de desenvolvimento full stack moderno — mas é só o começo. Caminhos naturais de continuidade:

• Nuxt — framework full stack sobre o Vue, com SSR (Server-Side Rendering) e SSG (Static Site Generation) nativos, útil quando SEO ou performance de primeira carga importam mais do que em uma SPA pura.
• TypeScript — adicionar tipagem estática ao que hoje é JavaScript puro; o Vue 3 e o Vuetify 4 têm suporte de primeira classe a TS, e o ganho em projetos maiores (detecção de erro em tempo de escrita, autocomplete mais forte) é significativo.
• Testes E2E — Cypress ou Playwright, testando a aplicação inteira pela interface, como um usuário real faria — o topo da pirâmide de testes que só citamos na Aula 13.
• Vue 3.6 — acompanhar o roadmap oficial do Vue (Vapor Mode e otimizações de compilador são a fronteira de pesquisa ativa do framework no momento).
• Mobile com Capacitor/Ionic — reaproveitar o conhecimento de Vue para publicar o mesmo código (ou uma variação) como app nativo Android/iOS.
• Back-end com NestJS — um framework Node.js opinativo, construído sobre Express (ou Fastify), que formaliza com decorators e módulos exatamente a arquitetura em camadas que construímos manualmente na Aula 13.

9.1 Como montar um portfólio a partir desta trilha¶

• Deixe o projeto autoral publicado e funcionando — um link ao vivo vale mais, para quem recruta, do que um repositório que só roda localmente.
• Escreva um README que conte a história do projeto: problema, decisões técnicas, dificuldades reais (os ADRs da Aula 14 são ótimo material bruto para isso).
• Grave um vídeo curto de demonstração e fixe no topo do repositório (ou no README, como GIF).
• Continue commitando — um projeto "morto" no GitHub (sem commit há meses) comunica menos do que um projeto pequeno e ativo.

9.2 Convite para iniciação científica e extensão¶

Muitos dos temas tocados de leve nesta trilha — arquitetura de software, segurança de aplicações web, engenharia de dados, IA aplicada a desenvolvimento — são linhas de pesquisa ativas em diversos grupos de pesquisa em Computação. Se você está cursando esta trilha em uma instituição de ensino e algum tópico despertou curiosidade além do conteúdo de uma aula, procure o professor da disciplina para conversar sobre projetos de iniciação científica ou extensão relacionados. Se você chegou até aqui por conta própria, esses mesmos temas são bons pontos de partida para aprofundar — grupos de pesquisa, comunidades on-line e cursos avançados costumam orbitar exatamente esses assuntos.

🧩 Padrão de projeto em uso — Configuração externa (Twelve-Factor) e Adapter¶

Duas decisões de arquitetura tomadas ao longo desta trilha ficam evidentes só agora, no momento de publicar de verdade.

Configuração externa por variáveis de ambiente. Desde a Aula 13, o unieventos-api lê PORT, DB_HOST, CORS_ORIGEM_PERMITIDA etc. de process.env, nunca de um valor fixo no código (Seção 3.1). Isso não é só "boa prática" abstrata: é o que permite o mesmo código-fonte, sem alterar uma linha, rodar em três ambientes diferentes — seu notebook (.env local), o CI (variáveis do GitHub Actions) e a nuvem (secrets da Render) — só trocando o que fica fora do código. O manifesto The Twelve-Factor App formalizou esse princípio (fator III, "Config") como um dos doze fatores de aplicações que escalam bem em nuvem; é o mesmo raciocínio por trás de VITE_API_URL no front (Seção 1.2).

// PORT vem de fora — o mesmo código roda em dev, CI e produção sem mudar
const servidor = app.listen(config.PORT, () => {
  console.log(`API rodando na porta ${config.PORT}`)
})

Adapter — trocar o banco sem tocar no service. Na Aula 12, MySQL virou Supabase mantendo a mesma interface de repositório (listar, buscarPorId, criar, atualizar, remover) — o service nunca soube qual banco estava por trás. Hoje, ao decidir onde hospedar o banco de produção (MySQL gerenciado na Render/Railway, ou Supabase), essa escolha de infraestrutura continua isolada na camada de repositório: o Adapter já construído é exatamente o que torna essa decisão, tomada agora no deploy, indiferente para o resto da aplicação.

📌 Vale gravar Configuração externa e Adapter resolvem problemas diferentes, mas se reforçam: uma isola onde a aplicação roda, a outra isola em que banco ela persiste — juntas, permitem que o mesmo código passe de localhost para produção sem reescrever uma linha de lógica de negócio.

💻 Mão na massa — publicando o UniEventos¶

Passo 1 — configure as variáveis de ambiente de produção do front:

# no repositório unieventos-web
touch .env.production
# preencha VITE_API_URL com a URL da API já publicada (Passo 4 abaixo)

Passo 2 — confirme que o build local funciona:

npm run build
npm run preview
# abra http://localhost:4173 e navegue pelas rotas internas — confirme que
# recarregar a página (F5) numa rota interna NÃO quebra localmente
# (o "vite preview" já simula o comportamento de servidor de produção)

Passo 3 — publique o front na Vercel seguindo o passo a passo da Seção 2.1.

Passo 4 — publique o back na Render seguindo o passo a passo da Seção 3.3. Anote a URL pública gerada.

Passo 5 — volte ao front e atualize VITE_API_URL com a URL real da API publicada, faça commit e push — a Vercel refaz o build automaticamente.

Passo 6 — atualize CORS_ORIGEM_PERMITIDA na API publicada com a URL real do front publicado (Seção 4), reinicie o serviço.

Passo 7 — teste o fluxo completo em produção: abra a URL do front publicado, faça login, liste eventos, crie uma inscrição, atualize a página em uma rota interna (F5) e confirme que não dá 404.

Passo 8 — crie o workflow de CI:

mkdir -p .github/workflows
# cole o conteúdo de .github/workflows/ci.yml da Seção 5
git add .github/workflows/ci.yml
git commit -m "adiciona pipeline de CI com lint e testes"
git push

Confira na aba Actions do GitHub que o workflow rodou e passou.

Como testar¶

O teste do deploy é feito de fora, numa aba anônima — exatamente como qualquer pessoa acessando de fora vai ver. Nada de "funciona na minha máquina".

# 1) a API publicada responde
curl -i https://<sua-api>.onrender.com/health
curl -s https://<sua-api>.onrender.com/api/eventos | jq '.paginacao'

Resultado esperado: 200 {"status":"ok"} no health check e o objeto paginacao do envelope de listagem. Se a segunda chamada devolver 404, o /api foi esquecido em algum lugar.

2. Front publicado — abra a URL da Vercel numa janela anônima. A lista de eventos carrega (dado real, vindo da API publicada). Resultado esperado: nenhum erro de CORS no console, e nenhuma requisição para localhost.
3. Rota interna com F5 — navegue até /eventos/1 e recarregue a página. Resultado esperado: a página carrega normalmente; um 404 aqui significa que falta o rewrite de SPA (Seção 1.4).
4. Login e escrita — faça login pelo Firebase e crie um evento. Resultado esperado: 201, o evento aparece na lista, e outra pessoa abrindo a URL num outro computador vê o mesmo evento.
5. Variáveis — confira no painel da Vercel que VITE_API_URL termina em /api, e no painel da Render que CORS_ORIGEM_PERMITIDA é exatamente a URL do front (sem barra no fim).
6. CI — faça um commit qualquer e confirme na aba Actions que lint e testes rodaram no push.

Só depois que os seis passam é que o Marco 3 está de fato completo.

🧪 Laboratório¶

Nível A — Fixação¶

A1. Verdadeiro ou falso, com justificativa de uma linha: "trocar VITE_API_URL no painel do serviço de hospedagem, depois que o front já está publicado, atualiza a URL usada pelo bundle sem precisar gerar um novo build."

Resultado esperado: falso. import.meta.env.VITE_* é substituído por um valor literal em tempo de build — trocar a variável depois, sem rebuildar, não tem efeito nenhum no JavaScript já gerado.

A2. Complete a linha que falta para que o rewrite de SPA funcione na Vercel (F5 numa rota interna não pode dar 404):

{
  "rewrites": [
    { "source": "/(.*)", "destination": "______________" }
  ]
}

Resultado esperado: "/index.html".

A3. Em uma frase: por que app.listen(config.PORT, ...) precisa ler PORT de process.env em vez de usar 3000 fixo no código?

Resultado esperado: porque a maioria dos serviços de nuvem injeta a própria porta via variável de ambiente — escutar numa porta fixa quebra o deploy nesses ambientes.

A4. Ache o erro nas linhas abaixo (a API sobe normalmente no docker compose up, mas todo endpoint que usa banco falha com erro de conexão):

environment:
  DB_HOST: localhost
  DB_PORT: 3306

Resultado esperado: DB_HOST deveria ser o nome do serviço no docker-compose.yml (mysql), não localhost — dentro da rede criada pelo Compose, cada serviço enxerga os outros pelo nome do serviço, não por localhost.

A5. Preveja a saída: o workflow de CI tem on.push.branches: ['**'] e o job deploy com if: github.ref == 'refs/heads/main' && github.event_name == 'push'. Você faz git push numa branch feature/relatorio. O job deploy roda?

Resultado esperado: não. lint-e-testes roda (o push bateu em alguma branch, e o padrão '**' cobre qualquer uma), mas deploy não roda, porque a condição if exige que a branch seja main.

Nível B — Aplicação¶

B1. Gere o build de produção do seu projeto autoral e rode npm run preview — confirme que todas as rotas funcionam, incluindo F5 em rota interna.

Resultado esperado: nenhum erro no console, navegação idêntica ao ambiente de desenvolvimento.

B2. Publique o front-end em um dos serviços da Seção 2, com as variáveis VITE_* corretas.

Resultado esperado: URL pública funcionando, aplicação carrega sem tela em branco.

B3. Publique o back-end em um dos serviços da Seção 3, com /health respondendo publicamente.

Resultado esperado: curl https://sua-api.onrender.com/health retorna {"status":"ok",...}.

B4. Configure CORS restritivo em produção, apontando exatamente para a URL do front publicado.

Resultado esperado: requisições do front publicado funcionam; uma requisição feita a partir de uma origem diferente é bloqueada.

Nível C — Desafio¶

C1. Crie o workflow de CI/CD completo no seu repositório de back-end: um job lint-e-testes que roda em qualquer push, e um job deploy que só roda depois do primeiro passar, restrito à branch main, disparando o deploy de verdade (deploy hook do seu serviço de hospedagem).

Resultado esperado: um push numa branch de feature só dispara lint-e-testes; um push (ou merge) em main dispara os dois jobs, e a aba Actions do GitHub mostra ambos passando em verde, nessa ordem.

🏆 Desafios¶

🐛 Erros comuns e como resolver¶

🏠 Para praticar depois da aula (1 h)¶

1. Finalize o deploy completo (front + back) do projeto autoral, se ainda não tiver feito no laboratório.
2. Grave um vídeo curto (3 a 5 minutos, pode ser não listado no YouTube ou enviado por link de drive) demonstrando o fluxo publicado, como backup para a apresentação.
3. Prepare os slides ou roteiro da apresentação de 8 minutos, seguindo a estrutura da Seção 8.1.
4. Revise, uma última vez, o README, garantindo que o link da aplicação publicada e do /api-docs estejam visíveis.

Critério de pronto: aplicação publicada e acessível publicamente; vídeo de backup gravado; roteiro da apresentação pronto.

✅ Checkpoint do projeto autoral¶

Ao final desta aula, seu projeto deve ter:

• [ ] Front-end publicado com URL pública, variáveis VITE_* corretas, rewrite de SPA configurado.
• [ ] Back-end publicado com URL pública, /health respondendo, banco gerenciado acessível, migrations aplicadas.
• [ ] CORS restrito ao domínio real do front publicado.
• [ ] Workflow de CI (.github/workflows/ci.yml) rodando lint e testes a cada push.
• [ ] README com links da aplicação publicada, da API publicada e de /api-docs.
• [ ] Roteiro de apresentação pronto, dentro de 8 minutos.

🎓 Marco do projeto — Unidade 3¶

O Marco 3 fecha esta trilha: uma aplicação full stack completa, construída sobre o projeto autoral definido na Aula 01 e evoluído ao longo de todas as aulas.

Requisitos¶

1. Back-end próprio, em Express ou usando Supabase como back-end gerenciado (ou uma combinação dos dois, desde que a arquitetura em camadas da Aula 13 esteja presente onde houver código Express) — Aulas 07/13.
2. Banco de dados persistente (MySQL ou Supabase/Postgres), com schema versionado (migrations ou scripts SQL organizados) — Aulas 09/12.
3. Autenticação funcional (Firebase Auth ou autenticação nativa do Supabase), protegendo pelo menos as rotas de escrita (criação/edição/remoção) — Aula 10.
4. CRUD completo de pelo menos 2 entidades relacionadas (ex.: "Evento" e "Inscrição"), com relacionamento real no banco (chave estrangeira ou equivalente) — Aula 11.
5. Documentação Swagger (OpenAPI 3) cobrindo todos os endpoints, ou documentação equivalente de todas as políticas/endpoints se o back for majoritariamente Supabase — Aula 14.
6. Deploy funcionando com URL pública — tanto do front quanto do back (ou só do front, se usando Supabase como back completo) — Aula 15.
7. README completo, seguindo a estrutura da Aula 14 (badges, requisitos, instalação, variáveis de ambiente, scripts, endpoints, licença), com os links de aplicação publicada e repositório.

Checklist de qualidade¶

O que separa um projeto pronto de um feito às pressas na véspera:

• [ ] CRUD completo de 2+ entidades relacionadas funcionando de ponta a ponta (criar, listar, editar, remover), com relacionamento real entre elas.
• [ ] Banco de dados corretamente modelado: schema versionado, queries corretas, sem duplicação nem inconsistência de dados.
• [ ] Rotas de escrita exigindo usuário autenticado, com a identidade usada corretamente (ex.: só o dono edita/remove seu próprio recurso).
• [ ] Documentação Swagger/OpenAPI completa: todos os endpoints documentados, schemas reutilizáveis, segurança declarada, /api-docs acessível.
• [ ] Front e back publicados e acessíveis externamente, sem depender de localhost em nenhum lugar (nem no README, nem em variável de ambiente esquecida).
• [ ] README completo conforme a estrutura da Aula 14; arquitetura em camadas aplicada; ao menos alguns testes automatizados presentes.

Como saber que está pronto¶

• Abra a aplicação publicada em uma aba anônima do navegador (sem cache, sem sessão salva) e percorra o fluxo completo: listar, ver detalhe, autenticar, criar, editar, remover.
• Teste com curl (ou uma aba anônima) que uma rota de escrita sem token retorna 401/403, não 200.
• Abra /api-docs publicamente e use o botão "Authorize" com um token real — todos os endpoints devem responder como documentado.
• Aperte F5 em pelo menos três rotas internas da aplicação publicada: nenhuma deve retornar 404.
• Rode npm install && npm run dev (ou docker compose up) em uma cópia limpa dos dois repositórios e confirme que tudo sobe sem passo não documentado no README.
• Explique em voz alta, para um colega ou para você mesmo, uma decisão técnica do próprio código — se travar, é sinal de que vale revisar aquele trecho antes da apresentação.

📚 Para aprofundar¶

• Documentação oficial da Vercel
• Documentação oficial do Firebase Hosting
• GitHub Pages — documentação oficial
• Documentação oficial da Render
• Docker — documentação oficial
• GitHub Actions — documentação oficial
• Vite — variáveis de ambiente e modos
• Vue Router — histórico HTML5 e configuração de servidor
• Nuxt — site oficial
• NestJS — site oficial
• Bibliografia do plano da disciplina em que esta trilha nasceu — capítulos sobre implantação, integração contínua e ciclo de vida de aplicações web.

Fim da trilha. Obrigado pelo empenho nas 15 aulas — do primeiro console.log da Aula 01 até uma aplicação full stack publicada, com autenticação, banco de dados e documentação. Se você quer testar o quanto absorveu, revise as questões da Seção 7 com calma, não na véspera da apresentação. Bom estudo, e bom portfólio.