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

2. 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

3. Construa e inicie os containers:

docker compose up -d --build

Nota: é normal que o container da API (aiprodutor-api) pare ou reinicie na primeira vez, pois o banco de dados ainda não foi configurado com as tabelas.

4. 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.

5. 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