hit-server-manager/backend/README.md

# Backend - Servers Manager

API REST em Spring Boot 4 (Java 21) com autenticação JWT stateless e refresh token em cookie HttpOnly.

## Stack
- Spring Boot 4.0 (Web MVC, Validation, Data JPA)
- Spring Security (JWT, stateless)
- MapStruct 1.6, Lombok
- PostgreSQL (padrão) ou H2
- JJWT 0.12 para geração/validação de tokens

## Configuração
Variáveis principais:
- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWD` — Postgres
- `JWT_SECRET` — chave HMAC >= 32 chars
- `security.jwt.access-token-expiration` — padrão 30m
- `security.jwt.refresh-token-expiration` — padrão 30d

Arquivo `src/main/resources/application.yaml` já traz defaults; adicione um `.env` ou exporte variáveis conforme o ambiente.

Seed: `src/main/resources/data.sql` cria usuário padrão `default@hittelco.com` (senha `senha123`, bcrypt).

## Endpoints chave
- `POST /api/auth/login` — autentica e devolve `access_token` (cookie) + `refresh_token` (HttpOnly).
- `POST /api/auth/refresh` — reemite cookies a partir do refresh.
- `POST /api/auth/signup` — cria usuário (requer auth).
- CRUD `/api/users` e `/api/servers` protegidos.

## Rodar local
```bash
./gradlew bootRun
```
API em `http://localhost:8080` com CORS liberado para `http://localhost:5173`.

## Documentação OpenAPI
- Dependência `springdoc-openapi` habilita `/swagger-ui.html` (UI) e `/v3/api-docs` (JSON).
- Endpoints agora trazem `@Operation` e `@ApiResponses`, facilitando entendimento e testes.
- Para testar rotas protegidas via Swagger UI, execute `/api/auth/login` pela própria interface; os cookies emitidos serão armazenados no navegador e enviados nas requisições seguintes.

## Formatação com Spotless
O projeto usa [Spotless](https://github.com/diffplug/spotless) para padronizar o código Java (imports, formatação Google Java Format).

Comandos úteis:
```bash
./gradlew spotlessCheck   # valida formatação (executado em pipelines via 'check')
./gradlew spotlessApply   # ajusta os arquivos automaticamente
```

## Testes
```bash
./gradlew test
```

## Postman
Use `postman_collection.json` na raiz; o login grava cookies e variáveis `access_token`/`refresh_token`.