Sprint 4

.github/workflows/validate-main-pr-source.yml

@@ -0,0 +1,36 @@
+name: Validate main PR source
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+
+jobs:
+  validate-pr-source:
+    name: Validate PR source branch
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check if PR to main comes from development
+        run: |
+          echo "Target branch: ${{ github.base_ref }}"
+          echo "Source branch: ${{ github.head_ref }}"
+          echo "Source repository: ${{ github.event.pull_request.head.repo.full_name }}"
+          echo "Target repository: ${{ github.repository }}"
+
+          if [ "${{ github.event.pull_request.head.repo.full_name }}" != "${{ github.repository }}" ]; then
+            echo "Pull requests to main must come from the same repository."
+            exit 1
+          fi
+
+          if [ "${{ github.head_ref }}" != "development" ]; then
+            echo "Pull requests to main are only allowed from the development branch."
+            exit 1
+          fi
+
+          echo "Valid pull request source branch."

README.md

@@ -6,8 +6,6 @@ A proposta do sistema é permitir que o usuário, com base em sua localização,
 
 ## Sobre
 
-### Objetivo
-
 O backend do LocalHub é responsável por fornecer a infraestrutura da aplicação, incluindo:
 
 - gerenciamento de dados dos comércios;
@@ -16,90 +14,255 @@ O backend do LocalHub é responsável por fornecer a infraestrutura da aplicaç
 - integração com banco de dados PostgreSQL;
 - documentação da API com Swagger.
 
-### Tecnologias utilizadas
+A documentação técnica complementar fica em:
+
+```text
+docs/
+├── README.md
+├── backend-architecture.md
+└── database.md
+```
 
-Este projeto utiliza as seguintes tecnologias:
+## Tecnologias utilizadas
 
 - **Node.js**
 - **Express**
 - **PostgreSQL**
 - **Swagger**
+- **Docker**
 - **Docker Compose**
-- **dotenv**
-
-
-## Como executar (Docker)
-
-1. Clone o repositório  
-    ```sh
-    git clone https://github.com/JSangaleti/LocalHub_Back-end.git
-    cd LocalHub_Back-end
-    ```
-
-2. Suba os serviços (API + Postgres)  
-    ```sh
-    docker compose up -d --build
-    ```
-
-3. Aplique a modelagem e carga inicial no banco  
-    ```sh
-    docker compose exec backend npm run db:init
-    ```
-
-4. Acesse  
-    - API: http://localhost:3000  
-    - Swagger: http://localhost:3000/docs
-
-## Como executar (Local)
-
-1. Instale as dependências  
-    ```sh
-    npm install
-    ```
-
-2. Configure o arquivo `.env`  
-    ```text
-    PORT=3000
-    PROJECT_NAME=localhub
-
-    DB_HOST=localhost
-    DB_PORT=5432
-    DB_USER=postgres
-    DB_PASSWORD=postgres
-    DB_NAME=localhubdb
-    ```
-
-3. Suba o banco de dados com Docker Compose  
-    ```sh
-    docker compose up -d
-    ```
-
-4. Aplique a modelagem e carga inicial no banco  
-    ```sh
-    npm run db:init
-    ```
-
-5. Inicie o servidor  
-    ```sh
-    npm run dev
-    ```
-
-## Modelagem do banco de dados
-
-Os arquivos de modelagem ficam em `src/database`:
-
-- `schema.sql`: estrutura relacional (`users`, `stores`, `categories`, `posts`), índices, triggers e view `v_feed_posts`;
+
+## Como executar com Docker
+
+Este é o fluxo recomendado para executar o backend.
+
+O `docker-compose.yml` sobe dois serviços:
+
+- `postgres`: banco de dados PostgreSQL;
+- `backend`: aplicação Node.js/Express.
+
+### 1. Clone o repositório
+
+```bash
+git clone https://github.com/JSangaleti/LocalHub_Back-end.git
+cd LocalHub_Back-end
+```
+
+Se estiver trabalhando durante a sprint, utilize a branch de desenvolvimento:
+
+```bash
+git checkout development
+```
+
+### 2. Suba a API e o banco
+
+```bash
+docker compose up -d --build
+```
+
+Esse comando constrói a imagem da aplicação e sobe os containers do backend e do PostgreSQL.
+
+### 3. Inicialize o banco de dados
+
+Depois que os containers estiverem rodando, execute:
+
+```bash
+docker compose exec backend npm run db:init
+```
+
+Esse comando aplica as migrations e executa o seed inicial no banco.
+
+### 4. Acesse a aplicação
+
+- API: <http://localhost:3000>
+- Health check: <http://localhost:3000/api/health>
+- Swagger: <http://localhost:3000/docs>
+
+### Conta administrador (seed)
+
+Após `npm run db:init` ou `npm run db:seed`, o sistema possui um único usuário administrador:
+
+| Campo | Valor |
+|-------|-------|
+| E-mail | `admin@admin.com` |
+| Senha | `admin123` |
+
+Não é possível criar outro usuário `admin` pelo cadastro público (`POST /api/auth/register`).
+
+### 5. Ver logs
+
+Para acompanhar os logs do backend:
+
+```bash
+docker compose logs -f backend
+```
+
+Para acompanhar os logs do PostgreSQL:
+
+```bash
+docker compose logs -f postgres
+```
+
+### 6. Parar os containers
+
+```bash
+docker compose down
+```
+
+### 7. Resetar o banco local
+
+Caso seja necessário apagar o volume do PostgreSQL e recriar o banco do zero:
+
+```bash
+docker compose down -v
+docker compose up -d --build
+docker compose exec backend npm run db:init
+```
+
+> Atenção: o comando `docker compose down -v` remove os volumes do Docker, apagando os dados locais do banco.
+
+---
+
+## Como executar em modo local
+
+Use este fluxo apenas se quiser rodar a API diretamente na máquina, fora do container, mantendo somente o PostgreSQL no Docker.
+
+### 1. Instale as dependências
+
+```bash
+npm install
+```
+
+### 2. Configure o arquivo `.env`
+
+Crie ou ajuste o arquivo `.env` na raiz do projeto:
+
+```env
+PORT=3000
+PROJECT_NAME=localhub
+
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=postgres
+DB_NAME=localhubdb
+```
+
+Em modo local, o `DB_HOST` deve ser `localhost`, pois a aplicação está rodando fora do Docker.
+
+### 3. Suba somente o PostgreSQL
+
+```bash
+docker compose up -d postgres
+```
+
+Não use `docker compose up -d` neste fluxo, pois esse comando também sobe o container do backend e pode causar conflito com o `npm run dev` usando a mesma porta `3000`.
+
+### 4. Inicialize o banco
+
+```bash
+npm run db:init
+```
+
+### 5. Inicie a API em desenvolvimento
+
+```bash
+npm run dev
+```
+
+Acesse:
+
+- API: <http://localhost:3000>
+- Health check: <http://localhost:3000/api/health>
+- Swagger: <http://localhost:3000/docs>
+
+---
+
+## Variáveis de ambiente
+
+No Docker Compose, as variáveis do backend são definidas diretamente no serviço `backend`.
+
+Dentro do Docker, o backend deve se conectar ao banco usando:
+
+```env
+DB_HOST=postgres
+```
+
+Isso acontece porque `postgres` é o nome do serviço do banco no `docker-compose.yml`.
+
+Em execução local, o backend deve usar:
+
+```env
+DB_HOST=localhost
+```
+
+---
+
+## Banco de dados
+
+Os arquivos de banco ficam em `src/database`:
+
+- `schema.sql`: estrutura relacional inicial;
 - `seed.sql`: dados iniciais para ambiente local;
 - `migrations/*.sql`: migrations versionadas da estrutura do banco;
-- `run-sql.js`: executor para aplicar schema/seed usando as variáveis de ambiente do projeto.
+- `run-sql.js`: executor para aplicar schema, migrations e seed usando as variáveis de ambiente do projeto.
 
 Scripts disponíveis:
 
-- `npm run db:schema`: aplica apenas a modelagem;
-- `npm run db:migrate`: aplica apenas as migrations pendentes;
-- `npm run db:seed`: aplica apenas dados iniciais;
-- `npm run db:init`: aplica migrations + seed.
+```bash
+npm run db:schema
+npm run db:migrate
+npm run db:seed
+npm run db:init
+```
+
+| Script               | Função                       |
+| -------------------- | ---------------------------- |
+| `npm run db:schema`  | Aplica o schema              |
+| `npm run db:migrate` | Executa migrations pendentes |
+| `npm run db:seed`    | Insere dados iniciais        |
+| `npm run db:init`    | Executa migrations e seed    |
+
+No Docker, execute os scripts dentro do container do backend:
+
+```bash
+docker compose exec backend npm run db:init
+```
+
+Em modo local, execute diretamente na máquina:
+
+```bash
+npm run db:init
+```
+
+---
+
+## Documentação da API
+
+Todos os endpoints estão documentados no Swagger:
+
+```text
+http://localhost:3000/docs
+```
+
+As rotas principais são registradas a partir de `/api`:
+
+```text
+/api/health
+/api/auth
+/api/users
+/api/categories
+/api/stores
+/api/posts
+```
+
+---
+
+## Documentação técnica
+
+A documentação técnica do backend fica na pasta `docs/`.
 
-## End-points iniciais implementados
+Arquivos principais:
 
-Todos os *end-points* estão documentados no Swagger em `localhost:3000/docs`.
+- [`docs/backend-architecture.md`](./docs/backend-architecture.md)
+- [`docs/database.md`](./docs/database.md)