Skip to content

GitLab

Last edited by Gustavo Borges Pasquali
Page history

configuracao

Home

Escopo

Arquitetura

Configuração

Mockups

BD

Gerência

Qualidade

Processo

CONFIGURAÇÃO

Guia passo a passo para configurar o ambiente de desenvolvimento dos projetos Ai Produtor - Backend e Ai Produtor - Frontend.

Este documento reúne as instruções "Começando / Getting Started" dos READMEs do backend e do frontend e acrescenta detalhes práticos (pré-requisitos, comandos na ordem correta e instruções de execução no dia a dia) para que qualquer desenvolvedor consiga configurar o ambiente rapidamente.

Backend — Ai Produtor

📥 Começando (Getting Started)

Siga os passos abaixo para configurar e rodar o projeto. A aplicação inteira (API e Banco de Dados) é orquestrada com Docker, garantindo um ambiente consistente para todos os desenvolvedores.

Pré-requisitos

  • Git
  • Docker e Docker Compose
  • Node.js e npm (recomendado para executar comandos do Prisma localmente e para integração com VS Code)

Instalação e Primeira Execução (Feito apenas uma vez)

  1. Clone o repositório:
git clone https://tools.ages.pucrs.br/ai-produtor-sistema-de-cadastro-e-gestao-de-produtores-de-hortifrutie/aiprodutor-backend.git
cd aiprodutor-backend
  1. Configure as variáveis de ambiente:
cp .env.example .env    # macOS / Linux
# no PowerShell (Windows):
# copy .env.example .env

As variáveis de ambiente estão disponíveis no chat designado ao backend, no discord

  1. Construa e inicie os containers:
docker compose up -d --build
  1. Aplique as migrações do banco de dados:
npx prisma migrate dev

Se for a primeira vez ou se precisar recomeçar do zero, npx prisma migrate reset é uma opção.

  1. Reinicie o container da API (se necessário):
docker compose restart backend

Como rodar no dia a dia (breve):

  • Iniciar containers: docker compose up (ou docker compose up -d para rodar em background)
  • API: http://localhost:3000
  • Swagger (API docs): http://localhost:3000/api-docs

⚙️ Como Rodar o Projeto no Dia a Dia (modo desenvolvimento)

Porque dois terminais? Normalmente você precisa de um terminal para os serviços orquestrados pelo Docker (banco de dados, e opcionalmente backend) e outro terminal para rodar o servidor de desenvolvimento (hot-reload) do frontend e/ou backend quando você preferir desenvolver localmente em vez de dentro do container.

Fluxo recomendado (desenvolvimento rápido)

Terminal 1 — Banco de dados (Docker):

# na raiz do backend
cd aiprodutor-backend
docker compose up -d postgres

Terminal 2 — Backend em hot-reload (local):

cd aiprodutor-backend
npm install        # se ainda não instalou
npm run start:dev

🌱 Populando o Banco de Dados (Seed)

O projeto contém um script para popular o banco com dados de exemplo (produtores, áreas, safras, etc).

Execução automática:

  • O seed pode ser executado automaticamente na primeira vez que o ambiente é criado com docker compose up --build ou após npx prisma migrate reset.

Execução manual:

# com o banco rodando
npx prisma db seed

Prisma Studio (visualização):

npx prisma studio
# e acesse http://localhost:5555/

🔄 Resetando o Banco de Dados

Se você precisar resetar o banco de dados (apagar tabelas e dados e reaplicar migrations):

npx prisma migrate reset

Atenção: usar apenas em ambientes de desenvolvimento ou testes — todos os dados serão perdidos.

🖥️ Dicas para Windows (PowerShell)

Se o PowerShell bloquear a execução de scripts como npm/npx, execute no mesmo terminal:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Em seguida rode npm run start:dev novamente.

⚠️ Problemas comuns & soluções rápidas

  • Collation Version Mismatch (Postgres): conectar ao container e rodar ALTER DATABASE template1 REFRESH COLLATION VERSION; (instruções completas no README do backend).
  • Portas ocupadas: verifique se as portas padrão (3000, 5432, etc.) estão livres.

✅ Checklist final antes de começar a desenvolver

  • Git instalado e configurado (nome/email)
  • Node via nvm instalado e versão LTS ativa (nvm use --lts)
  • Docker rodando
  • Repositórios clonados e .env copiado
  • Dependências instaladas (npm install)
  • Banco de dados migrado/seed aplicado (se for necessário)

🔗 Repositórios

  • Backend: https://tools.ages.pucrs.br/ai-produtor-sistema-de-cadastro-e-gestao-de-produtores-de-hortifrutie/aiprodutor-backend.git
  • Frontend: https://tools.ages.pucrs.br/ai-produtor-sistema-de-cadastro-e-gestao-de-produtores-de-hortifrutie/aiprodutor-frontend.git