Programação para Sistemas Web
Controle
Acadêmico
Um sistema web completo, explicado passo a passo: do conceito à depuração.
O que vamos ver
12 seções, do conceito ao sistema funcionando (e depurado)
O projeto
Conceitos fundamentais
A stack
Arquitetura e monorepo
Banco de dados
A API por dentro
O site por dentro
A viagem de um clique
Criando do zero
Executando
Depurando
Próximos passos
O projeto
Cadastros · Notas · Relatórios
O que o sistema faz
Um mini sistema de controle acadêmico feito para aprender programação web
Dashboard
Totais, média geral, taxa de aprovação e gráficos simples
Alunos
Nome, CPF, matrícula, e-mail, telefone e foto; busca, edição e exclusão
Professores
Nome, CPF, titulação, graduação, e-mail, telefone e foto
Disciplinas
Nome, curso e carga horária
Matrículas
Liga aluno + professor + disciplina em um semestre, com notas N1, N2 e PF
Relatórios
Boletim do aluno, desempenho por disciplina e turmas por professor
Simples de propósito
Nada que atrapalhe o entendimento de como as peças se conectam
Sem login e senha
Nenhuma camada de segurança para esconder o essencial
Tudo em português
Variáveis, funções, pastas e comentários: foco na lógica
Um README por pasta
Cada pasta explica o que existe nela e por quê
Peças conectadas
Site, API, banco e tipos: cada um com uma responsabilidade
Regra de aprovação
O status é calculado pela API: o usuário digita só as notas
Lançar notas
N1 e N2 (de 0 a 10)
Média
(N1 + N2) / 2
≥ 7
aprovado direto
< 7
faz a Prova Final (PF)
(média + PF) / 2
≥ 5 aprovado
< 5 reprovado
apps/api/src/regras/notas.tsConceitos fundamentais
Glossário · Web · Dados
Cliente e servidor
Quase todo sistema web é dividido em duas partes: a analogia do restaurante
Usuário
O cliente no salão faz o pedido: “quero ver os alunos”
Site (web)
O garçom: anota e leva o pedido. Não cozinha!
API (Bun)
A cozinha: prepara a resposta
Banco SQLite
A despensa: onde tudo fica guardado
apps/webapps/apiHTTP: o idioma da web
Cada pedido do navegador para a API tem um método e um caminho
GET
Buscar dados
GET /api/alunosPOST
Criar um registro
POST /api/alunosPUT
Atualizar um registro
PUT /api/alunos/7DELETE
Excluir um registro
DELETE /api/alunos/7Status HTTP
O número que a API devolve dizendo como foi o pedido
2xx · deu certo
200 Deu certo
201 Criado com sucesso
204 Concluído, corpo vazio
4xx · problema no pedido
400 Pedido com problema (ex.: campo faltando)
404 Não encontrado
409 Conflito com o estado atual
5xx · erro no servidor
500 Algo quebrou dentro da API
No Acadêmico, a função error() do index.ts captura o erro e responde com uma mensagem amigável.
JSON: o formato da conversa
Texto para trocar dados, parecido com um objeto JavaScript
{
"id": 1,
"nome": "Ana Souza",
"cpf": "111.222.333-44",
"matricula": "2026001",
"email": "[email protected]",
"telefone": "(69) 99999-0000",
"foto": null
}Ida: objeto → texto
JSON.stringify(dados) transforma o objeto em texto para enviar pela rede
Volta: texto → objeto
await resposta.json() no site e await req.json() na API
API, endpoint e REST
O endereço diz o quê; o método diz a ação
API
Application Programming Interface: o conjunto de operações que um cliente pode chamar pela rede. Métodos e caminhos formam o contrato.
Endpoint / rota
Uma operação identificada por método + caminho, como GET /api/alunos.
método
a ação: buscar
recurso
a coleção de alunos
:id
qual aluno (parte variável)
CRUD
As quatro operações básicas de qualquer cadastro, em cada camada do sistema
| Operação | Significado | HTTP (API) | SQL (banco) | No site |
|---|---|---|---|---|
| Create | Criar | POST | INSERT INTO | Botão “Novo aluno” |
| Read | Ler | GET | SELECT | Tabela da listagem |
| Update | Atualizar | PUT | UPDATE | Ícone de lápis |
| Delete | Excluir | DELETE | DELETE FROM | Lixeira com confirmação |
Porta, proxy e CORS
Como o site (5173) conversa com a API (3333) sem configuração extra
Navegador
pede /api/alunos a localhost:5173
Vite (proxy)
repassa tudo que começa com /api
API Bun
responde em localhost:3333
Porta
Número que diz qual serviço recebe a conexão: 5173 (site) e 3333 (API).
Proxy
Intermediário que encaminha pedidos. O Vite faz isso durante o desenvolvimento.
CORS
Regra do navegador entre origens diferentes (protocolo + host + porta). Com o proxy, tudo parece ter a mesma origem.
Banco de dados, SQL e chaves
Informações guardadas de forma organizada, mesmo depois que o programa desliga
Tabela, linha e coluna
Cada tabela guarda um assunto (alunos). Cada linha é um registro; cada coluna, um campo.
SQL
A linguagem do banco: SELECT, INSERT, UPDATE, DELETE, CREATE TABLE...
PK e FK
PK identifica cada linha (o id). FK aponta para a PK de outra tabela (ex.: aluno_id).
| id (PK) | aluno_id (FK) | disciplina_id (FK) | semestre |
|---|---|---|---|
| 1 | 3 → Ana | 2 → Web | 2026.1 |
| 2 | 3 → Ana | 5 → BD | 2026.1 |
| 3 | 8 → Caio | 2 → Web | 2026.1 |
Componente, props e JSX
A tela é montada com peças reutilizáveis, como LEGO
type Props = {
nome: string;
foto: string | null;
};
export function FotoPerfil({ nome, foto }: Props) {
return (
<Avatar>
{foto && <AvatarImage src={foto} />}
<AvatarFallback>{iniciais(nome)}</AvatarFallback>
</Avatar>
);
}Componente
Uma função que descreve o que aparecer na tela.
Props
O que o componente recebe: <FotoPerfil nome="Ana" foto={null} />
JSX / TSX
Marcação parecida com HTML dentro do código. .tsx = TypeScript + JSX.
Estado e hooks
Hooks são funções especiais do React que começam com use
// Lista de alunos que veio da API
const [alunos, setAlunos] = useState<Aluno[]>([]);
async function carregarAlunos() {
const lista = await listarAlunos();
setAlunos(lista); // muda o estado → redesenha
}
// [] = "rode só uma vez, quando a página abrir"
useEffect(() => {
carregarAlunos();
}, []);useState
Guarda uma informação entre renderizações e devolve a função para alterá-la. Mudou o estado, a tela é redesenhada.
useEffect
Executa algo quando a tela aparece. Aqui: buscar os dados na API.
Tipos no TypeScript
Um “corretor ortográfico” que avisa erros antes de rodar o código
export type Aluno = {
id: number;
nome: string;
cpf: string;
matricula: string;
email: string;
telefone: string;
foto: string | null; // base64 ou null
};
// Só estes três textos são aceitos
export type StatusMatricula =
"aprovado" | "reprovado" | "cursando";Tipo = formato do dado
Quais campos existem e de que tipo é cada um: texto, número, nulo...
Erro antes de rodar
Escreveu aluno.nme? O editor sublinha em vermelho na hora.
Monorepo, workspace e pacotes
Como o projeto organiza o próprio código e o código de terceiros
Monorepo
Vários projetos ou pacotes no mesmo repositório: aqui, a API, o site e os tipos.
Workspace
Pacote registrado na configuração do monorepo. @academico/tipos é uma pasta local, não um pacote da internet.
Dependência / pacote
Código feito por outras pessoas que o projeto usa. Fica listado no package.json.
bun install
Baixa as dependências para a pasta node_modules e liga os workspaces.
OpenAPI, Scalar e CDN
A API se autodocumenta, e a documentação permite testar cada endereço
openapi.ts
Descreve a API no padrão OpenAPI: endereços, o que recebem e devolvem
/api/openapi.json
A mesma descrição, entregue em JSON
/api/docs
O Scalar lê o JSON e desenha uma página interativa
/api/docs precisa de internet.Mais termos do dia a dia
Palavras que aparecem no código, nos comandos e nos READMEs
Build
Prepara os arquivos para publicação. bun run build confere tipos e gera o site.
Seed (popular)
Coloca dados de exemplo: bun run banco:popular.
Migração
Mudança versionada na estrutura do banco, como acrescentar uma coluna.
Base64
Representa dados binários como texto. Usado para as fotos no SQLite.
Validação
Verificação feita ao rodar: a API recusa campo obrigatório em branco.
Regra de negócio
Condição do mundo real que o software aplica: média 7 aprova.
A stack
Ferramentas · Analogias · Decisões
Ferramentas do back-end
O que roda no servidor e guarda os dados
Bun
Roda JavaScript/TypeScript fora do navegador, instala pacotes, executa scripts e já traz o SQLite (bun:sqlite).
o motor do projeto
TypeScript
JavaScript com tipos: avisa erros antes de rodar o código.
corretor ortográfico
SQLite
Banco de dados que fica todo em um único arquivo: academico.sqlite.
um caderno de dados
Scalar
Gera a documentação interativa da API a partir da descrição OpenAPI.
manual de instruções
Ferramentas do front-end
O que roda no navegador e desenha as telas
React
Biblioteca para construir telas a partir de peças (componentes).
peças de LEGO
Vite
Roda o site durante o desenvolvimento (com proxy) e gera a versão final.
o forno
Tailwind CSS
Estiliza com classes prontas: p-4, flex, text-sm...
lápis de cor organizados
shadcn/ui
Componentes prontos e bonitos (botões, tabelas, janelas) copiados para dentro do projeto.
móveis prontos
Decisões de projeto (e por quê)
Cada escolha favorece o entendimento
| Decisão | Por quê |
|---|---|
API sem framework (só Bun.serve) | Menos “mágica”: dá para ver exatamente como uma rota funciona |
| SQL puro (sem ORM) | Você aprende SQL de verdade, que serve para qualquer linguagem |
| SQLite | Não precisa instalar servidor de banco: é só um arquivo |
| Proxy do Vite | O site chama /api/... como se a API estivesse no mesmo endereço (sem CORS) |
| Status calculado na API | A regra fica num lugar só e ninguém “força” um status errado |
| Tipos compartilhados | API e site sempre concordam sobre o formato dos dados |
| Um formulário para criar e editar | Recebeu um registro? Edita. Não recebeu? Cria. Menos código repetido |
Arquitetura e monorepo
Pastas · Camadas · Workspaces
O que é um monorepo
“Mono” = um só: vários projetos morando no mesmo repositório
Um repositório, três partes
apps/api · apps/web · packages/tipos
Um único bun install
Instala as dependências de todos os projetos de uma vez.
Um único bun run dev
Liga a API e o site ao mesmo tempo.
Tipos compartilhados
Mudou um campo? API e site “ficam sabendo” na hora, e o TypeScript aponta o que ajustar.
A estrutura de pastas
pweb/academico: cada pasta tem o seu próprio README.md
academico.sqlite é criado em apps/api e fica fora do Git (.gitignore).As três partes e como se ligam
Dois programas que conversam por HTTP e um pacote que os dois importam
apps/web
React + shadcn
porta 5173apps/api
Bun.serve + SQLite
porta 3333packages/tipos
Aluno, Professor, Disciplina, Matricula...
biblioteca: não roda sozinhaO package.json da raiz
Liga o monorepo e cria os atalhos de comando
{
"name": "controle-academico",
"private": true,
"workspaces": ["apps/*", "packages/*"],
"scripts": {
"dev": "bun run --filter \"@academico/*\" dev",
"dev:api": "bun run --filter @academico/api dev",
"dev:web": "bun run --filter @academico/web dev",
"banco:popular": "bun run --filter @academico/api banco:popular",
"build": "bun run --filter @academico/web build"
}
}"workspaces"
Cada pasta dentro de apps/ e packages/ é um projeto do monorepo.
"scripts"
Atalhos: bun run dev executa o script dev de todos os projetos @academico/*.
--filter
Escolhe em qual projeto rodar. Nos projetos, "workspace:*" pega o pacote daqui.
packages/tipos: o cardápio
Um arquivo, index.ts, descreve o formato de cada informação do sistema
Aluno
id, nome, cpf, matricula, email, telefone, foto
Professor
id, nome, cpf, titulacao, graduacao, email, telefone, foto
Disciplina
id, nome, curso, carga_horaria
Matricula
aluno_id, professor_id, disciplina_id, semestre, n1, n2, pf, status
MatriculaDetalhada
Matricula & nomes do aluno, professor e disciplina (vindos do JOIN)
NovoAluno, NovaMatricula...
Os mesmos tipos sem o id, usados nos formulários
apps/api: organizada em camadas
Cada camada só conversa com a de baixo
index.ts
Porta de entrada: liga o servidor e lista as rotas
rotas/
Recebem o pedido, validam e devolvem a resposta
regras/
Regras de negócio: o cálculo das notas
banco/
Conexão, criação das tabelas e dados de exemplo
documentacao/
Descrição OpenAPI exibida pelo Scalar
Por que separar?
Cada arquivo fica pequeno e com uma única responsabilidade.
Manutenção fácil
Mudou a regra de aprovação? Só regras/. Mudou uma tabela? banco/ e as rotas dela.
apps/web: organização do site
Do ponto de entrada até as peças reaproveitáveis
main.tsx
Liga o React dentro do index.html
App.tsx
Diz qual página aparece em cada endereço
paginas/
As TELAS: uma pasta por assunto
components/
Peças nossas: menu, foto, botão excluir... ui/ = peças do shadcn
servicos/api.ts
O único lugar que conversa com a API
lib/
Funções de ajuda: formatar nota, iniciais do nome...
Como uma tela é montada
Componentes dentro de componentes: a árvore da página de alunos
paginas/ + uma <Route> no App.tsx + um item no menu do Layout.Modelo de banco de dados
Tabelas · Chaves · Restrições
O diagrama do banco
Quatro tabelas: matriculas liga as outras três
Criando a tabela de alunos
O SQL que define colunas, tipos e restrições
CREATE TABLE IF NOT EXISTS alunos (
id INTEGER PRIMARY KEY AUTOINCREMENT,
nome TEXT NOT NULL,
cpf TEXT NOT NULL UNIQUE,
matricula TEXT NOT NULL UNIQUE,
email TEXT NOT NULL,
telefone TEXT NOT NULL DEFAULT '',
foto TEXT
)PRIMARY KEY AUTOINCREMENT
O banco gera o id sozinho: 1, 2, 3...
NOT NULL
Campo obrigatório: o banco recusa vazio (nulo).
UNIQUE
Não aceita repetido: dois alunos com o mesmo CPF ou matrícula.
foto TEXT
Sem NOT NULL: aceita nulo quando não há foto.
Disciplinas e matrículas
Restrições que protegem os dados mesmo se a API errar
CREATE TABLE IF NOT EXISTS matriculas (
id INTEGER PRIMARY KEY AUTOINCREMENT,
aluno_id INTEGER NOT NULL REFERENCES alunos(id),
professor_id INTEGER NOT NULL REFERENCES professores(id),
disciplina_id INTEGER NOT NULL REFERENCES disciplinas(id),
semestre TEXT NOT NULL,
n1 REAL CHECK (n1 BETWEEN 0 AND 10),
n2 REAL CHECK (n2 BETWEEN 0 AND 10),
pf REAL CHECK (pf BETWEEN 0 AND 10),
status TEXT NOT NULL DEFAULT 'cursando',
UNIQUE (aluno_id, disciplina_id, semestre)
)REFERENCES
Chave estrangeira: o aluno_id precisa existir em alunos.
CHECK
Notas entre 0 e 10. Em disciplinas: carga_horaria > 0.
UNIQUE (aluno, disciplina, semestre)
Impede matricular o mesmo aluno duas vezes na mesma disciplina e semestre.
Conexão com o SQLite
Sem instalar servidor: o próprio Bun lê e escreve no arquivo
import { Database } from "bun:sqlite";
import { criarTabelas } from "./criar-tabelas";
// Sobe duas pastas: salva em apps/api
const caminhoDoArquivo = import.meta.dir + "/../../academico.sqlite";
// Abre o arquivo (e cria, se ainda não existir)
export const banco = new Database(caminhoDoArquivo, { create: true });
// No SQLite a checagem de FKs vem DESLIGADA!
banco.run("PRAGMA foreign_keys = ON");
// Garante que as tabelas existem
criarTabelas(banco);PRAGMA foreign_keys = ON, o SQLite aceitaria matrícula de aluno inexistente.CREATE TABLE IF NOT EXISTS é ignorado se a tabela já existe: por isso roda toda vez que a API liga..sqlite para recriar.Consultas com JOIN e GROUP BY
Juntar tabelas e agrupar linhas direto no SQL
JOIN: matrícula com os nomes
SELECT m.*,
a.nome AS aluno_nome,
p.nome AS professor_nome,
d.nome AS disciplina_nome
FROM matriculas m
JOIN alunos a ON a.id = m.aluno_id
JOIN professores p ON p.id = m.professor_id
JOIN disciplinas d ON d.id = m.disciplina_idGROUP BY: situação no dashboard
SELECT status AS rotulo,
COUNT(*) AS valor
FROM matriculas
GROUP BY status| rotulo | valor |
|---|---|
| aprovado | 12 |
| cursando | 7 |
| reprovado | 3 |
A API por dentro
Rotas · Regras · Documentação
index.ts: o mapa de rotas
O “cardápio” da API: lista tudo o que ela sabe fazer
Bun.serve({
port: 3333,
routes: {
"/api/alunos": { GET: alunos.listar, POST: alunos.criar },
"/api/alunos/:id": { GET: alunos.buscar,
PUT: alunos.atualizar,
DELETE: alunos.excluir },
// ... professores, disciplinas, matriculas
"/api/dashboard": { GET: relatorios.dashboard },
"/api/docs": { GET: documentacao.paginaDocumentacao },
},
// Endereço que não existe no mapa
fetch() { return erro("Rota não encontrada.", 404); },
// Alguma rota "quebrou": a API não cai
error(problema) {
console.error(problema);
return erro(traduzirErroDoBanco(problema.message));
},
});routes
Liga cada endereço + método a uma função. :id é a parte variável.
fetch
Resposta padrão: 404 para rotas desconhecidas.
error
Captura qualquer erro, mostra no terminal e responde com mensagem amigável.
Os endpoints da API
Padrão REST repetido para os quatro cadastros
| Método | Endereço | Ação |
|---|---|---|
| GET | /api/alunos | Lista todos |
| GET | /api/alunos/:id | Busca um |
| POST | /api/alunos | Cria |
| PUT | /api/alunos/:id | Atualiza |
| DELETE | /api/alunos/:id | Exclui |
Mesmo padrão
professores, disciplinas e matriculas
Relatórios (só leitura)
GET /api/dashboardGET /api/relatorios/disciplinasGET /api/relatorios/professores
Filtros
/api/matriculas?aluno_id=3 ou ?semestre=2026.1
Anatomia de uma rota
alunos.criar: o modelo que todas as rotas de cadastro seguem
export async function criar(req: BunRequest) {
// 1. Ler o corpo do pedido (dados do formulário)
const dados = (await req.json()) as NovoAluno;
// 2. Validar os campos obrigatórios
const problema = verificarObrigatorios(dados, CAMPOS_OBRIGATORIOS);
if (problema) return erro(problema);
// 3. Gravar: os "?" são preenchidos em ordem
const resultado = banco
.query(`INSERT INTO alunos
(nome, cpf, matricula, email, telefone, foto)
VALUES (?, ?, ?, ?, ?, ?)`)
.run(dados.nome, dados.cpf, dados.matricula,
dados.email, dados.telefone ?? "", dados.foto ?? null);
// 4. Responder com o aluno criado (201)
const alunoCriado = banco
.query("SELECT * FROM alunos WHERE id = ?")
.get(resultado.lastInsertRowid);
return Response.json(alunoCriado, { status: 201 });
}bun:sqlite
.all() todas as linhas · .get() uma linha · .run() INSERT, UPDATE, DELETE
?. Concatenar abre brecha para SQL Injection.lastInsertRowid
O id que o banco acabou de gerar.
Ajudantes e erros amigáveis
Pequenas funções reaproveitadas por todas as rotas (rotas/ajudantes.ts)
erro(mensagem, status = 400)
Devolve { "erro": "mensagem" } com o status certo.
verificarObrigatorios(dados, campos)
Devolve a mensagem do primeiro campo vazio, ou null se estiver tudo certo.
paraNota(valor)
Campo vazio vira null (nota ainda não lançada); o resto vira número.
traduzirErroDoBanco(msg)
Troca as mensagens técnicas do SQLite, em inglês, por frases que o usuário entende.
| O SQLite diz… | A API responde… |
|---|---|
UNIQUE constraint failed | Já existe um cadastro com esses dados (CPF, matrícula...) |
FOREIGN KEY constraint failed | Este registro está ligado a uma ou mais matrículas |
CHECK constraint failed | Notas entre 0 e 10 e carga horária maior que zero |
A regra de negócio no código
calcularStatus(n1, n2, pf) em regras/notas.ts
export const MEDIA_PARA_APROVAR = 7;
export const MEDIA_FINAL_PARA_APROVAR = 5;
export function calcularStatus(n1, n2, pf) {
if (n1 === null || n2 === null) return "cursando";
const media = (n1 + n2) / 2;
if (media >= MEDIA_PARA_APROVAR) return "aprovado";
// Não passou direto: depende da prova final
if (pf === null) return "cursando";
const mediaFinal = (media + pf) / 2;
if (mediaFinal >= MEDIA_FINAL_PARA_APROVAR) return "aprovado";
return "reprovado";
}| N1 | N2 | PF | Status |
|---|---|---|---|
| 8 | 7 | – | aprovado |
| 5 | 6 | – | cursando |
| 5 | 6 | 7 | aprovado (6,25) |
| 3 | 4 | 5 | reprovado (4,25) |
Documentação com Scalar
Abra http://localhost:3333/api/docs e teste a API sem escrever código
documentacao/openapi.ts
Descrição escrita à mão no padrão OpenAPI
GET /api/openapi.json
Rota que devolve a descrição em JSON
GET /api/docs
HTML que carrega o Scalar (CDN) e lê o JSON
Test Request
Alunos → Listar alunos → a lista aparece
openapi.ts, senão ela não aparece no Scalar.O site por dentro
React · Rotas · Componentes
main.tsx e App.tsx
Do <div id="root"> até a página certa para cada endereço
// main.tsx: liga o React dentro do index.html
const elementoRaiz = document.getElementById("root")!;
createRoot(elementoRaiz).render(
<StrictMode>
<BrowserRouter>
<App />
</BrowserRouter>
</StrictMode>
);// App.tsx: qual página em cada endereço
export function App() {
return (
<Layout>
<Routes>
<Route path="/" element={<PaginaDashboard />} />
<Route path="/alunos" element={<PaginaAlunos />} />
{/* ... as outras páginas */}
</Routes>
<Toaster position="top-right" richColors />
</Layout>
);
}BrowserRouter troca de página sem recarregar o site. Toaster é a área onde aparecem os avisos de sucesso e erro.servicos/api.ts
O único arquivo do site que conversa com a API
async function requisicao(caminho, metodo = "GET", dados?) {
const resposta = await fetch("/api" + caminho, {
method: metodo,
headers: { "Content-Type": "application/json" },
body: dados ? JSON.stringify(dados) : undefined,
});
const corpo = await resposta.json();
if (!resposta.ok) { // status 400, 404, 500...
const mensagem = corpo.erro ?? "Não foi possível falar com a API.";
toast.error(mensagem); // aviso vermelho na tela
throw new Error(mensagem); // interrompe quem chamou
}
return corpo;
}
// Com id: ATUALIZA (PUT). Sem id: CRIA (POST).
export function salvarAluno(dados: NovoAluno, id?: number) {
if (id) return requisicao("/alunos/" + id, "PUT", dados);
return requisicao("/alunos", "POST", dados);
}Um ponto de contato
As telas nunca chamam fetch: chamam as funções daqui.
Manutenção
O endereço da API mudou? Mexemos só neste arquivo.
Erro tratado uma vez
Toda falha vira um aviso vermelho com a mensagem da API.
A página modelo: PaginaAlunos
Estado, efeito e filtro: o mesmo jeito de funcionar em todos os cadastros
const [alunos, setAlunos] = useState<Aluno[]>([]);
const [busca, setBusca] = useState("");
const [formularioAberto, setFormularioAberto] = useState(false);
// null = cadastrando um aluno novo
const [alunoEmEdicao, setAlunoEmEdicao] = useState<Aluno | null>(null);
useEffect(() => { carregarAlunos(); }, []);
// Filtra pelo texto digitado (nome ou matrícula)
const termo = busca.toLowerCase();
const alunosFiltrados = alunos.filter((aluno) =>
aluno.nome.toLowerCase().includes(termo) ||
aluno.matricula.includes(termo)
);Novo aluno
alunoEmEdicao = null e abre o formulário.
Editar
Guarda o aluno clicado e abre o mesmo formulário.
Excluir
excluirAluno(id) → aviso de sucesso → recarrega a lista.
Componentes do shadcn/ui
O código é copiado para components/ui: dá para ler e alterar tudo
card
Caixas com borda
table
Tabelas de listagem
dialog
Janela do formulário
alert-dialog
“Tem certeza que deseja excluir?”
input · label · select
Campos de formulário
badge
Etiquetas de status e titulação
avatar
Foto redonda ou iniciais
tabs · sonner
Abas dos relatórios e avisos no canto
Os nossos componentes
Peças criadas para o projeto, em src/components
| Componente | O que faz |
|---|---|
Layout | Menu lateral + área de conteúdo de todas as páginas |
CabecalhoPagina | Título, descrição e botões no topo de cada tela |
Campo | Rótulo + campo de formulário |
FotoPerfil · CampoFoto | Mostra a foto (ou iniciais) · escolhe a foto no formulário |
SeloStatus | Etiqueta colorida: aprovado, reprovado, cursando |
BotaoExcluir | Lixeira com janela de confirmação |
GraficoBarras | Gráfico de barras feito só com CSS (dashboard) |
A viagem de um clique
Formulário · API · Banco
Cadastrar um aluno em 10 passos
Do botão “Salvar” até a tabela redesenhada
Usuário
Preenche o formulário e clica em “Salvar”
FormularioAluno.tsx
Chama salvarAluno(dados)
servicos/api.ts
fetch POST /api/alunos com o corpo em JSON
Vite (proxy)
Repassa o pedido de :5173 para :3333
api/src/index.ts
“POST /api/alunos” é com alunos.criar
rotas/alunos.ts
Confere os obrigatórios e executa INSERT INTO alunos
SQLite
Grava no arquivo academico.sqlite
rotas/alunos.ts
Devolve o aluno criado com status 201
FormularioAluno.tsx
Mostra “Aluno cadastrado.” e fecha a janela
PaginaAlunos.tsx
Busca a lista de novo e a tabela é redesenhada
E quando dá erro?
Exemplo: tentar cadastrar um aluno com um CPF que já existe
SQLite recusa
A regra UNIQUE da coluna cpf dispara: UNIQUE constraint failed
error() captura
A função error do index.ts pega o erro e chama traduzirErroDoBanco
API responde 400
{ "erro": "Já existe um cadastro com esses dados..." }
Site avisa
servicos/api.ts vê !resposta.ok e mostra o aviso vermelho
Criando do zero
Etapas · Comandos · Testes
As 8 etapas
Cada etapa termina com um teste antes de seguir
Preparar
Bun e VS Code
Monorepo
pastas e package.json
Tipos
packages/tipos
API
Bun + SQLite + Scalar
Site
Vite + React + Tailwind
shadcn/ui
componentes prontos
Código do site
serviços, peças, páginas
Rodar tudo
teste final
Etapa 0: preparar o computador
Instale o Bun uma única vez e confira a versão
# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"# Linux / macOS
curl -fsSL https://bun.sh/install | bashbun --versionVS Code
Editor recomendado (code.visualstudio.com)
Tailwind CSS IntelliSense
Sugere as classes do Tailwind enquanto digita
SQLite Viewer
Abre o arquivo do banco e mostra as tabelas
bun --version mostra um número (ex.: 1.3.12).Etapas 1 e 2: monorepo e tipos
A casa e o cardápio, antes de qualquer programa
Etapa 1: o monorepo
- Em
pweb/academico, crieapps/,packages/edocs/ - Crie o
package.jsonda raiz com workspaces e scripts (seção 04) - O
.gitignoreempwebignoranode_modules,diste*.sqlite - (Opcional)
git initna pastapweb
Etapa 2: o pacote de tipos
{
"name": "@academico/tipos",
"version": "1.0.0",
"private": true,
"type": "module",
"main": "index.ts",
"types": "index.ts"
}packages/tipos/index.ts existe e não tem sublinhado vermelho.Etapa 3: a API
Pastas, configuração e a ordem de criação dos arquivos
{
"name": "@academico/api",
"type": "module",
"scripts": {
"dev": "bun --watch src/index.ts",
"start": "bun src/index.ts",
"banco:popular": "bun src/banco/popular.ts"
},
"dependencies": {
"@academico/tipos": "workspace:*"
},
"devDependencies": { "@types/bun": "latest" }
}| # | Arquivo | Papel |
|---|---|---|
| 1 | banco/criar-tabelas.ts | CREATE TABLE das 4 tabelas |
| 2 | banco/conexao.ts | Abre o .sqlite e cria as tabelas |
| 3 | regras/notas.ts | calcularStatus |
| 4 | rotas/ajudantes.ts | erro, validação, tradução |
| 5 | rotas/alunos.ts | O modelo: leia com calma |
| 6 | rotas/*.ts | professores, disciplinas, matrículas, relatórios |
| 7 | index.ts | Liga o servidor na 3333 |
| 8 | banco/popular.ts | Dados de exemplo |
Etapa 3: testando a API
Antes de existir o site, a API já funciona sozinha
bun run banco:popular
bun run dev:api
# ✅ API rodando em http://localhost:3333/api| Abra no navegador | Resultado |
|---|---|
localhost:3333/api/alunos | lista em JSON |
localhost:3333/api/dashboard | números do dashboard |
localhost:3333/api/xyz | {"erro":"Rota não encontrada."} |
curl -X POST http://localhost:3333/api/disciplinas \
-H "Content-Type: application/json" \
-d '{"nome":"Redes","curso":"Computação","carga_horaria":60}'Invoke-RestMethod -Method Post `
-Uri http://localhost:3333/api/disciplinas `
-ContentType "application/json" `
-Body '{"nome":"Redes","curso":"Computação","carga_horaria":60}'Etapa 3.11: documentação com Scalar
Um pacote, dois arquivos e duas linhas no index.ts
cd apps/api
bun add @scalar/client-side-rendering
cd ../..
mkdir apps/api/src/documentacao| Arquivo | O que faz |
|---|---|
documentacao/openapi.ts | A descrição da API (OpenAPI) |
rotas/documentacao.ts | Entrega o JSON e a página do Scalar |
import * as documentacao from "./rotas/documentacao";
// dentro de routes:
"/api/openapi.json": { GET: documentacao.openapi },
"/api/docs": { GET: documentacao.paginaDocumentacao },localhost:3333/api/docs → Alunos → Listar alunos → Test Request.Etapa 4: o site com Vite
Criar o projeto React, limpar o exemplo e instalar o essencial
cd apps
bun create vite web --template react-ts --no-interactive
cd ..Remove-Item -Recurse -Force apps/web/src/App.css, apps/web/src/assets, `
apps/web/public/icons.svg, apps/web/README.md, apps/web/.oxlintrc.jsoncd apps/web
bun add tailwindcss @tailwindcss/vite react-router4.3 · Ajustar apps/web/package.json
- Nome:
"@academico/web" - Remover o script
linte a dependênciaoxlint - Acrescentar
"@academico/tipos": "workspace:*" - Rodar
bun installna raiz
src/index.css, troque tudo por @import "tailwindcss";Etapa 4: vite.config.ts
Plugins, atalho @/, porta fixa e o proxy para a API
export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
// Atalho: "@/" significa "a pasta src/"
alias: { "@": path.resolve(import.meta.dirname, "./src") },
// Uma única cópia do React (evita página em branco)
dedupe: ["react", "react-dom"],
},
server: {
port: 5173,
strictPort: true, // ocupada? para com aviso
// Tudo que começar com /api vai para a API
proxy: { "/api": "http://localhost:3333" },
},
});Atalho @/
Configure também em tsconfig.json e tsconfig.app.json: "paths": { "@/*": ["./src/*"] }
bun run dev dentro de apps/web abre localhost:5173 sem erros.Etapa 5: shadcn/ui
O shadcn copia o código dos componentes para dentro do projeto
bunx --bun shadcn@latest init -t vite -b radix -p nova --no-monorepobunx --bun shadcn@latest add card table dialog alert-dialog input label select badge avatar tabs sonner separator-t vite
Projeto usa Vite
-b radix
Base: Radix UI
-p nova
Estilo visual Nova
--no-monorepo
Cuida só do site
Etapa 6: o código do site
Do mais simples para o mais completo
6.1 Base
- index.html
- public/favicon.svg
- servicos/api.ts
- lib/formatar.ts
6.2 Componentes
- Layout
- CabecalhoPagina
- Campo
- FotoPerfil · CampoFoto
- SeloStatus
- BotaoExcluir
- GraficoBarras
6.3 Páginas
- alunos/ (o modelo)
- professores/
- disciplinas/
- matriculas/
- dashboard/
- relatorios/
6.4 Juntar
- App.tsx
- main.tsx
/alunos. Funcionou? Acrescente as outras.Executando o sistema
Instalar · Popular · Rodar
Rodar em 3 comandos
Na pasta raiz do projeto: pweb/academico
bun installbun run banco:popularbun run dev| O que | Endereço |
|---|---|
| Site (telas) | http://localhost:5173 |
| API (JSON) | http://localhost:3333/api/alunos |
| Documentação | http://localhost:3333/api/docs |
Ctrl + C no terminal.Comandos úteis
Os atalhos definidos no package.json da raiz
| Comando | O que faz |
|---|---|
bun run dev | Liga a API e o site ao mesmo tempo |
bun run dev:api | Liga só a API (porta 3333) |
bun run dev:web | Liga só o site (porta 5173) |
bun run banco:popular | Apaga os dados e coloca dados de exemplo |
bun run build | Confere os tipos e gera a versão final do site em apps/web/dist |
apps/api/academico.sqlite. Ele é recriado (vazio) quando a API ligar.Teste final
Confira, com o sistema rodando, se tudo se conecta
/api/docs e teste um endereço pelo ScalarDepurando o sistema
Encontrar · Entender · Corrigir
Onde está o problema?
Siga o pedido camada por camada: cada uma tem a sua ferramenta
Tela (React)
Console e React DevTools
Pedido HTTP
Aba Rede (Network) do F12
API (Bun)
Terminal, console.log e depurador
Banco
SQLite Viewer no VS Code
1 · O pedido saiu?
Se não aparece na aba Rede, o problema está na tela.
2 · Qual o status?
4xx/5xx: leia o corpo da resposta e o terminal da API.
3 · Gravou certo?
Abra a tabela no banco e confira os dados.
DevTools do navegador (F12)
A principal ferramenta para depurar o site
Console
Erros em vermelho (ex.: Invalid hook call) e as mensagens de console.log(dados) que você colocar no código.
Rede (Network)
Cada pedido para /api/...: método, status, o corpo enviado (Payload) e a resposta (Response).
Fontes (Sources)
Pontos de parada (breakpoints) no código .tsx. Ou escreva debugger; na linha: a execução pausa ali com o F12 aberto.
React DevTools
Extensão do navegador: mostra a árvore de componentes, as props e o estado (useState) de cada um.
Depurando o site na prática
Coloque pistas no código e observe
async function carregarAlunos() {
const lista = await listarAlunos();
console.log("alunos recebidos:", lista);
setAlunos(lista);
}
async function salvar() {
debugger; // pausa aqui com o F12 aberto
await salvarAluno(dados, aluno?.id);
}Pausado no debugger
Passe o mouse sobre as variáveis para ver os valores; use os botões para avançar linha a linha.
Passo a passo
F10 próxima linha · F11 entra na função · F8 continua.
console.log e debugger antes de entregar.Depurando a API
O terminal do bun run dev é o “console” do servidor
export async function criar(req: BunRequest) {
const dados = (await req.json()) as NovoAluno;
console.log("POST /api/alunos recebeu:", dados);
// ...
}cd apps/api
bun --inspect src/index.ts
# abre um link do depurador web do Bun (debug.bun.sh)Logs no terminal
console.log da API aparece no terminal, não no navegador. A função error() do index.ts já faz console.error de toda falha.
--watch
Salvou o arquivo? A API reinicia sozinha: é só repetir o pedido.
No VS Code
Com a extensão Bun for Visual Studio Code, clique na margem para criar breakpoints e rode a API em modo debug.
Testando a API isolada
Tire o site da equação: o problema é da API ou da tela?
Navegador
Pedidos GET: abra localhost:3333/api/alunos e veja o JSON cru.
Scalar
/api/docs: escolha o endereço, preencha o corpo e clique em Test Request. Funciona para POST, PUT e DELETE.
curl / Invoke-RestMethod
Pedidos pelo terminal: bons para repetir o mesmo teste várias vezes.
servicos/api.ts ou na tela. Falhou no Scalar também? Está na API ou no banco.Olhando o banco de dados
Confira o que realmente foi gravado
SQLite Viewer
Clique em apps/api/academico.sqlite no VS Code e navegue pelas tabelas.
Voltar ao início
bun run banco:popular substitui tudo pelos dados de exemplo.
Recriar do zero
Apague o .sqlite: a API cria de novo, vazio, ao ligar.
criar-tabelas.ts e nada mudou? CREATE TABLE IF NOT EXISTS não altera tabela existente. Apague o .sqlite e rode banco:popular.-- Teste uma consulta antes de pôr no código
SELECT a.nome, m.n1, m.n2, m.status
FROM matriculas m
JOIN alunos a ON a.id = m.aluno_id
WHERE m.semestre = '2026.1';Problemas comuns (1/2)
Do academico/tutorial.md: sintoma → solução
| Problema | Solução |
|---|---|
bun: command not found | Feche e abra o terminal depois de instalar o Bun |
| Site abre, mas as listas ficam vazias e aparece erro | A API está ligada? Use bun run dev na raiz (liga os dois) |
Port 3333 is already in use | Já existe uma API rodando em outro terminal: feche-a |
Port 5173 is already in use | Um bun run dev esquecido em outro terminal: feche com Ctrl + C |
Cannot find module '@academico/tipos' | Rode bun install na raiz do projeto |
Problemas comuns (2/2)
Página em branco, documentação e banco
| Problema | Solução |
|---|---|
| Site em branco, sem erro no terminal | F12 → Console. Se aparecer Invalid hook call: confira o dedupe no vite.config.ts, apague apps/web/node_modules/.vite e rode de novo |
A página /api/docs fica em branco | Ela precisa de internet: a interface do Scalar vem de um CDN |
| Criei uma rota e ela não aparece no Scalar | Documente-a em src/documentacao/openapi.ts |
| Mudei uma tabela e nada mudou | Apague o .sqlite e rode bun run banco:popular |
| Quero começar o banco do zero | Apague apps/api/academico.sqlite e rode bun run banco:popular |
Próximos passos
Praticar · Evoluir · Criar
Exercícios por nível
Cada um tem uma dica de por onde começar (docs/exercicios.md)
- Mudar a média de aprovação para 6 (
regras/notas.ts) - Mais um aluno e uma disciplina nos dados de exemplo (
popular.ts) - Titulação “Livre-Docente” no formulário de professor
- Quantidade de registros abaixo de cada tabela
- Busca de alunos também por CPF
- Filtro
?disciplina_id=nas matrículas (e documentar no Scalar)
- Campo “data de nascimento” no aluno
- Passos:
criar-tabelas.ts→ tipos → rotas (INSERT e UPDATE) → formulário e tabela - Repare como o TypeScript aponta o que ajustar
Roteiro de estudo
Os três projetos da pasta pweb e por onde continuar
academico/
O sistema exemplo desta aula.
controle_n2/
Sistema exemplo e controle dos grupos e apresentações.
web/
Este site da aula, explicando o Acadêmico passo a passo.
Ordem de leitura
- README.md · visão geral e como rodar
- arquitetura.md · como as partes conversam
- tutorial.md · construir do zero
- docs/ · rotas, banco e exercícios
- pweb/docs/ · glossário, TypeScript, React, SQLite, API e Scalar
Programação para Sistemas Web
Bons estudos
e bom código!
Dúvidas? Abra o projeto, rode, quebre, depure e conserte.