Projeto Integrador de Sistemas

Do repositório vazio à aplicação testada

Um passo a passo de como executar um projeto web completo, usando um único exemplo do começo ao fim: a Biblioteca Comunitária Cantinho da Leitura. Cada etapa mostra o que fazer, em que pasta, com qual comando e como testar. Escolha no topo da página a linguagem do back-end e do front-end: o código e a estrutura do projeto se ajustam à escolha.

Prévia para avaliação

Estão prontas a Etapa 0, com o exemplo, suas regras, o diagrama de classes e o código, e a Etapa 1, com o Git e o GitHub passo a passo. As etapas marcadas como “em breve” mostram o que será construído.

Etapa 0

O exemplo: Biblioteca Comunitária

Um minimundo pequeno, com regras de negócio suficientes para exercitar todas as camadas e todos os tipos de teste.

Minimundo

A Biblioteca Comunitária Cantinho da Leitura empresta livros aos moradores do bairro. Hoje os empréstimos são anotados em um caderno, o que dificulta saber quais livros estão emprestados, com quem estão e quem está atrasado.

Cada livro possui título, autor e ano de publicação. Os leitores são cadastrados com nome e telefone. Cada empréstimo registra o livro, o leitor e a data em que foi realizado.

O prazo de devolução é de 7 (sete) dias, contados a partir da data do empréstimo. Se o livro for devolvido após o prazo, o leitor paga uma multa de R$ 1,00 (um real) por dia de atraso. Um leitor pode ter, no máximo, 3 (três) empréstimos em aberto ao mesmo tempo, e um livro emprestado não pode ser emprestado novamente até que seja devolvido.

Escopo do exemplo

Registrar um empréstimo.
Registrar a devolução, informando a multa, se houver.
Listar os empréstimos em aberto, destacando os atrasados.

Não há cadastros nem login: livros e leitores já vêm preenchidos no banco de dados.

Regras de negócio e onde cada uma é testada

Regra	Descrição	Onde fica	Teste que comprova
R1	Prazo de devolução de 7 dias	`Emprestimo.dataLimite()`	“é sete dias após a data do empréstimo”
R2	Multa de R$ 1,00 por dia de atraso	`Emprestimo.calcularMulta()`	“cobra um real por dia de atraso”
R3	No máximo 3 empréstimos em aberto por leitor	`Leitor.podePegarEmprestado()`	“não permite o quarto empréstimo” (etapa 4)
R4	Livro emprestado fica indisponível	`GestorEmprestimos.registrar()`	“lança exceção quando o livro já está emprestado” (etapa 4)
R5	Um empréstimo não pode ser devolvido duas vezes	`Emprestimo.devolver()`	“lança exceção ao devolver um empréstimo já devolvido”

Diagrama de Classes do Modelo de Domínio (essencial)

Construído em quatro passos: primeiro as entidades do negócio, depois os comportamentos de negócio, depois os atributos que sustentam esses comportamentos e, por fim, as associações.

Diagrama de classes com três classes. Livro, com os atributos titulo, autor e ano. Emprestimo, com os atributos dataEmprestimo e dataDevolucao e as operações dataLimite, estaEmAberto, devolver, diasDeAtraso e calcularMulta. Leitor, com os atributos nome e telefone e a operação podePegarEmprestado. Emprestimo refere-se a um Livro e é feito por um Leitor; cada Livro e cada Leitor podem ter vários empréstimos. — Modelo essencial da Biblioteca Comunitária.

Boas práticas aplicadas neste diagrama

Setas de direção saindo de Emprestimo, que conhece o livro e o leitor.
Rótulo de leitura com seta: “Emprestimo refere-se a Livro”, “Emprestimo é feito por Leitor”.
Multiplicidade nas duas pontas de cada associação.
Livro e leitor são associações, não atributos do tipo String.
Sem id, sem salvar() e sem agregação ou composição — são detalhes de implementação.
Não existe atributo multa: ela é calculada por calcularMulta().

Como o projeto vai ficar ao final

A estrutura completa está na coluna da esquerda, em Estrutura do projeto. Ela muda conforme as linguagens escolhidas no topo. Clique em qualquer arquivo para ver o código completo, com comentários, e em qual etapa ele é explicado.

Amostra: a entidade `Emprestimo` em cada linguagem

As mesmas regras (R1, R2 e R5), escritas em quatro linguagens, com comentários explicando cada parte. Troque a aba ou use o seletor de back-end no topo: a escolha vale para todos os blocos de código da página.

Ver também as classes de apoio: Livro, Leitor e a exceção de domínio

Amostra: o teste unitário da entidade

Cada linguagem usa o seu framework de testes — Kahlan no PHP, Vitest em TypeScript e JavaScript, JUnit 5 no Java —, mas os casos de teste são os mesmos. O comando para executá-los aparece no rodapé do bloco.

Etapa 1

Git e GitHub do início ao merge

O fluxo completo de trabalho em dupla: Ana cria o repositório e a primeira funcionalidade; depois Bruno entra no projeto e os dois resolvem um conflito.

Como o Git guarda as mudanças

Toda alteração passa por quatro lugares. Entender esse caminho explica quase todos os comandos desta etapa.

Pasta do projeto Onde você edita os arquivos. git add
Área de preparação O que vai entrar no próximo commit. git commit
Repositório local O histórico de commits no seu computador. git push
GitHub A cópia compartilhada com o grupo, chamada origin. git pull · git clone

Como ler os terminais

O texto antes do sinal > é a pasta em que o comando foi digitado, como no Prompt de Comando do Windows. O texto em branco depois dele é o que você digita; as linhas abaixo são a resposta do Git. Use ▶ Reproduzir para ver o comando sendo digitado e Copiar comandos para levar os comandos ao seu terminal. Os comandos do Git são os mesmos em qualquer linguagem.

1.1 Instalar e configurar o Git

Baixe o Git em git-scm.com e instale com as opções padrão. Depois, abra o Prompt de Comando (tecla Windows, digite cmd e aperte Enter). A configuração é feita uma única vez por computador.

1.2 Criar o repositório no GitHub

Feito uma vez, por uma pessoa do grupo — no exemplo, a Ana.

Crie o repositório

Entre em github.com, clique no botão New e preencha Repository name com biblioteca-comunitaria.
Escolha a visibilidade e inclua um README

Escolha Public ou Private e ative Add README. Assim o repositório já nasce com um primeiro commit e pode ser clonado. Clique em Create repository.
Dê acesso ao colega

Em Settings → Collaborators → Add people, informe o usuário do Bruno. Ele recebe um convite por e-mail e precisa aceitar antes de enviar alterações.
Copie o endereço

Na página do repositório, clique em Code, aba HTTPS, e copie o endereço:

https://github.com/ana-souza/biblioteca-comunitaria.git

1.3 Baixar o projeto para o computador

1.4 Adicionar arquivos e fazer o primeiro commit

Com o projeto aberto no editor, crie o arquivo .gitignore na raiz do projeto. Ele lista o que o Git deve ignorar: pastas de dependências e arquivos gerados, que cada pessoa recria no próprio computador.

Em seguida, substitua o conteúdo do README.md:

Salve os dois arquivos e volte ao terminal.

1.5 Criar uma branch para a funcionalidade

Uma branch é uma linha de trabalho separada. Cada funcionalidade é feita na sua própria branch e só entra na main quando estiver pronta. Assim, a main sempre funciona e cada pessoa trabalha sem atrapalhar a outra.

Na nova branch, crie a pasta backend/src/emprestimo/ e, dentro dela, o arquivo com a primeira versão da entidade:

1.6 Alterar um arquivo e ver o que mudou

Ainda na branch emprestimo-dominio, Ana adiciona a regra da multa ao Emprestimo.php: a constante EMPRESTIMO_MULTA_POR_DIA e os métodos diasDeAtraso() e calcularMulta(), chegando à versão mostrada na Etapa 0.

1.7 Juntar a branch na main

Há dois caminhos. Em equipe, o mais comum é o pull request, porque permite que outra pessoa revise antes de juntar.

Pelo GitHub, com pull request

Abra o pull request

Na página do repositório aparece o aviso da branch enviada. Clique em Compare & pull request (ou use o link que o git push mostrou).
Descreva e crie

Confira se está indo de emprestimo-dominio para main, escreva o que foi feito e clique em Create pull request.
Revise e junte

Na aba Files changed, o colega revisa as linhas alteradas. Depois, clique em Merge pull request, Confirm merge e, por fim, Delete branch.
Atualize o seu computador

O merge aconteceu só no GitHub. No terminal, rode git checkout main e depois git pull.

Pelo terminal

1.8 Trabalhar em dupla e resolver um conflito

Um conflito acontece quando duas pessoas alteram a mesma linha do mesmo arquivo. Nesta simulação, Bruno e Ana trocam a linha Em construção. do README.md ao mesmo tempo, cada um com um texto.

Antes de juntar a branch dele, Bruno atualiza a main com o que está no GitHub.

Resolvendo o conflito no editor

Ao abrir o README.md, Bruno encontra as duas versões separadas por marcações:

Entre <<<<<<< HEAD e ======= está a versão da branch atual, a main — o texto da Ana.
Entre ======= e >>>>>>> readme-execucao está a versão que está chegando — o texto do Bruno.
Resolver é deixar o arquivo como deve ficar e apagar as três linhas de marcação. Aqui, os dois textos são úteis, então viram dois passos.

1.9 Desfazer e guardar alterações

Descartar uma alteração que ainda não foi adicionada

Tirar um arquivo da área de preparação

Corrigir a mensagem do último commit

Desfazer um commit que já foi enviado

Guardar alterações para depois

1.10 Resumo dos comandos

Comando	O que faz	Exemplo no projeto
`git clone`	Baixa um repositório	`git clone https://github.com/ana-souza/biblioteca-comunitaria.git`
`git status`	Mostra a branch atual e o que mudou	`git status`
`git add`	Coloca alterações na área de preparação	`git add backend/src/emprestimo/Emprestimo.php`
`git commit -m`	Grava um ponto no histórico	`git commit -m "Adiciona cálculo de dias de atraso e multa"`
`git push`	Envia commits para o GitHub	`git push --set-upstream origin emprestimo-dominio`
`git pull`	Baixa e junta commits do GitHub	`git pull`
`git fetch`	Baixa commits sem juntar	`git fetch`
`git checkout -b`	Cria uma branch e entra nela	`git checkout -b emprestimo-dominio`
`git merge`	Junta outra branch na atual	`git merge emprestimo-dominio`
`git diff`	Mostra as linhas alteradas	`git diff`
`git log --oneline --graph`	Mostra o histórico	`git log --oneline --graph -6`
`git restore`	Descarta alterações de um arquivo	`git restore README.md`
`git revert`	Desfaz um commit criando outro	`git revert --no-edit HEAD`
`git stash`	Guarda alterações sem commit	`git stash push -m "Rascunho"`

Etapa 2 em breve

Modelagem e diagramas

Como sair do minimundo e chegar aos diagramas.

A modelagem passo a passo: entidades, comportamentos, atributos e associações, com a imagem do diagrama crescendo a cada passo.
Erros comuns lado a lado: diagrama com cara de modelo relacional, id no modelo, atributo no lugar de associação.
Imagem do diagrama parcial da arquitetura para “registrar empréstimo”: visão, controladora, serviço, gestor e repositórios.
Uma organização de pastas simples para os arquivos de modelagem.

Etapa 3 em breve

Pastas do projeto

A estrutura completa, arquivo por arquivo, e o que cada um faz.

Imagem de como a organização das pastas fica no editor, para cada combinação de linguagens.
Passo a passo de criação das pastas e dos arquivos iniciais.
O README.md completo: integrantes, comandos para rodar e referências.
O que entra e o que não entra no repositório.

Etapa 4 em breve

Back-end e testes

Das classes de domínio às rotas, com teste em cada passo.

Criar o projeto, configurar dependências e scripts, com terminais mostrando cada comando e a resposta.
GestorEmprestimos com as regras R3 e R4 e testes usando um dublê do repositório.
Rotas GET, POST e PATCH de /emprestimos com CORS.
Imagens dos testes rodando, da saída com falha e com sucesso, e da análise estática.

Etapa 5 em breve

Banco de dados e fetch

Guardar os empréstimos no banco e buscá-los pelo navegador.

Criação do banco em MariaDB ou MySQL, lado a lado: instalação, usuário, conexão e diferenças entre os dois.
estrutura.sql, dados.sql e dados-teste.sql, com scripts para recriar o banco.
Repositório com consultas preparadas e o teste de integração.
Formato JSON de cada rota e como testá-las antes de ter a tela.
fetch no front-end: GET, POST e PATCH, tratamento de erros e a mensagem para o usuário.

Etapa 6 em breve

Front-end e testes

A tela de empréstimos com visão, controladora e serviço separados, testes unitários e testes de ponta a ponta.

Criar o projeto com PNPM e Vite; index.html, páginas e roteamento.
Visão, controladora e serviço separados, e testes com Vitest usando uma visão falsa.
Cenários em .feature, testes com Playwright e o Page Object TelaEmprestimos.
Imagens da aplicação rodando no navegador em cada passo.