feat: implement module-based JWT authentication system with login and session handling

.agents/rules/main-rules.md

@@ -215,6 +215,114 @@ Ao implementar endpoints:
 
 Não altere contratos existentes sem avaliar seus consumidores.
 
+## 9.1. Identificadores nos endpoints
+
+**Endpoints devem utilizar exclusivamente UUID como identificador de recursos.**
+
+É **proibido expor ou utilizar IDs numéricos (`id`) nos endpoints da API**, tanto em parâmetros de rota quanto em parâmetros destinados a identificar recursos.
+
+Exemplos proibidos:
+
+```text
+GET /produtos/123
+GET /clientes/456
+GET /documentos-fiscais/789
+DELETE /produtos/123
+PUT /clientes/456
+```
+
+O padrão obrigatório é utilizar o `uuid`:
+
+```text
+GET /produtos/{uuid}
+GET /clientes/{uuid}
+GET /documentos-fiscais/{uuid}
+DELETE /produtos/{uuid}
+PUT /clientes/{uuid}
+```
+
+Também é proibido utilizar `id` numérico em:
+
+* parâmetros de rota;
+* query parameters quando o parâmetro representa a identificação de um recurso;
+* payloads de entrada quando o objetivo for referenciar uma entidade externamente;
+* respostas da API como identificador público;
+* links e relacionamentos retornados pela API;
+* filtros de endpoints que tenham como finalidade localizar uma entidade específica.
+
+Exemplo proibido:
+
+```json
+{
+    "cliente_id": 123
+}
+```
+
+Quando a referência for necessária através do contrato da API, utilize:
+
+```json
+{
+    "cliente_uuid": "019..."
+}
+```
+
+ou, conforme o padrão já estabelecido no projeto:
+
+```json
+{
+    "cliente": "019..."
+}
+```
+
+A nomenclatura deve seguir o padrão existente na API. Não crie uma nova convenção sem antes verificar como os recursos relacionados já são representados.
+
+### Uso interno do `id`
+
+O `id` numérico pode continuar sendo utilizado **internamente pela aplicação e pelo banco de dados**, quando essa for a estrutura existente.
+
+Por exemplo:
+
+```text
+API
+ ↓
+UUID
+ ↓
+Controller / DTO
+ ↓
+Service
+ ↓
+Repository
+ ↓
+id interno
+ ↓
+Banco de dados
+```
+
+Nesse cenário, o UUID é o identificador público e o `id` é apenas um identificador interno.
+
+É permitido, por exemplo, utilizar:
+
+```sql
+SELECT
+    id,
+    uuid,
+    nome
+FROM cliente
+WHERE uuid = :uuid;
+```
+
+e posteriormente utilizar o `id` internamente para relacionamentos, JOINs ou operações no banco, desde que o `id` **não seja exposto ao consumidor da API**.
+
+### Regra absoluta
+
+**`id` numérico é identificador interno. `uuid` é identificador público.**
+
+Nenhum endpoint deve exigir que o consumidor conheça ou forneça o `id` numérico de uma entidade.
+
+Antes de implementar ou alterar um endpoint, verifique se todos os identificadores expostos pelo contrato da API utilizam UUID.
+
+Caso um endpoint existente utilize `id` numérico, não faça a alteração automaticamente. Analise os consumidores, apresente o impacto e solicite autorização antes de alterar o contrato.
+
 ## 10. Alterações mínimas
 
 Altere somente o necessário para atender à tarefa.
@@ -374,9 +482,15 @@ Antes de finalizar uma implementação:
 * [ ] Nenhuma refatoração desnecessária.
 * [ ] Nenhum segredo ou credencial exposto.
 * [ ] Resultado informado ao usuário.
+* [ ] Endpoints utilizam exclusivamente UUID como identificador público.
+* [ ] Nenhum `id` numérico é exposto ou exigido pelos endpoints.
+* [ ] IDs numéricos são utilizados somente internamente, quando necessário.
+* [ ] Alterações em endpoints existentes que utilizam IDs numéricos foram analisadas antes de modificar o contrato.
 
 ## Regra de ouro
-
+**Use exclusivamente UUID nos endpoints.
+Nunca exponha ou exija IDs numéricos (`id`) na API.
+`id` é identificador interno; `uuid` é identificador público.**
 **Planeje antes de implementar.
 Peça autorização antes de alterar.
 Nunca utilize `SELECT *`.