feat: implement JWT-based authentication system with login, profile endpoints, and user creation utility

2026-09-09 19:33:53 -03:00
parent f7f052fcb4
commit f188337479
1 changed files with 388 additions and 0 deletions
@@ -0,0 +1,388 @@
+---
+trigger: always_on
+---
+
+# AGENTS.md
+
+## Workbloom ERP — Diretrizes para Agentes de IA
+
+Este documento define as regras obrigatórias para qualquer agente que analise, altere, refatore ou implemente código no Workbloom ERP.
+
+## 1. Regra principal: planejar antes de implementar
+
+**Nunca altere o projeto diretamente.**
+
+Antes de modificar qualquer arquivo, código, banco, endpoint, classe, serviço ou estrutura:
+
+1. Analise o código existente.
+2. Identifique arquivos, componentes, dependências e impactos.
+3. Crie um plano objetivo.
+4. Apresente o plano ao usuário.
+5. Solicite autorização explícita.
+6. Só implemente após a autorização.
+
+Consultas, análises, diagnósticos, explicações e sugestões que não alterem arquivos podem ser realizadas normalmente.
+
+Para bugs, primeiro identifique causa e sintoma, analise o fluxo e apresente o plano de correção. Não faça tentativas de correção diretamente.
+
+Formato:
+
+```text
+Análise concluída.
+
+Plano:
+1. ...
+2. ...
+3. ...
+
+Arquivos que serão alterados:
+- ...
+
+Impacto:
+- ...
+
+Posso implementar?
+```
+
+Após autorização:
+
+```text
+Implementado.
+
+Alterações:
+- ...
+
+Validações realizadas:
+- ...
+
+Possíveis pontos de atenção:
+- ...
+```
+
+## 2. Stack e arquitetura
+
+O backend **não utiliza Laravel nem CodeIgniter**.
+
+A API utiliza:
+
+```text
+claudecio/krothiumapi v1.0
+```
+
+Respeite a arquitetura e as abstrações existentes no `claudecio/krothiumapi`. Não introduza outro framework, padrão ou arquitetura sem necessidade e autorização.
+
+Antes de criar qualquer classe, serviço, repository, DTO, controller ou estrutura:
+
+1. Procure uma estrutura equivalente.
+2. Identifique o padrão existente.
+3. Reutilize-o quando possível.
+4. Crie uma nova abordagem somente quando justificado.
+
+Não replique funcionalidades já fornecidas pelo `krothiumapi`.
+
+## 3. Banco de dados
+
+O banco utilizado é **PostgreSQL**.
+
+O sistema possui múltiplos domínios, incluindo autenticação, multi-tenant, empresas, configurações fiscais, clientes, fornecedores, produtos, serviços, documentos fiscais, pagamentos e administração.
+
+Antes de qualquer alteração estrutural, analise o modelo atual, dependências e impacto nos dados.
+
+Alterações em tabelas, colunas, índices, constraints, foreign keys, enums, funções, triggers, views ou migrations exigem:
+
+1. análise;
+2. plano;
+3. autorização;
+4. implementação.
+
+Nunca altere o banco diretamente sem autorização.
+
+## 4. Regra absoluta de SQL
+
+**É proibido utilizar `SELECT *` ou qualquer variação.**
+
+Proibido:
+
+```sql
+SELECT * FROM produto;
+
+SELECT p.* FROM produto p;
+
+SELECT COUNT(*) FROM produto;
+```
+
+Prefira:
+
+```sql
+SELECT
+    id,
+    uuid,
+    nome,
+    ncm
+FROM produto;
+```
+
+Para contagem:
+
+```sql
+SELECT COUNT(id)
+FROM produto;
+```
+
+ou:
+
+```sql
+SELECT COUNT(1)
+FROM produto;
+```
+
+Toda consulta deve selecionar **somente as colunas necessárias**.
+
+Isso vale para repositories, queries, services, endpoints, relatórios, JOINs, subqueries e views.
+
+Nunca concatene valores fornecidos pelo usuário no SQL. Utilize parâmetros conforme o mecanismo existente no projeto.
+
+## 5. JOINs
+
+Sempre informe explicitamente as colunas e utilize aliases quando necessário.
+
+```sql
+SELECT
+    df.id,
+    df.uuid,
+    df.numero,
+    c.id AS cliente_id,
+    c.nome AS cliente_nome
+FROM documento_fiscal df
+INNER JOIN cliente c
+    ON c.id = df.cliente_id;
+```
+
+## 6. UUID
+
+As entidades principais utilizam UUID.
+
+A estratégia recomendada é UUID v7 gerado pela aplicação antes do `INSERT`, quando essa for a convenção da tabela.
+
+Não altere a estratégia existente sem analisar primeiro sua implementação atual.
+
+## 7. Transações e integridade
+
+Operações que modificam múltiplos registros relacionados devem respeitar o padrão transacional existente.
+
+Exemplo:
+
+```text
+Documento fiscal
+ ├── Itens
+ ├── Pagamentos
+ ├── Duplicatas
+ └── Série
+```
+
+Operações fiscais relacionadas devem manter consistência e, quando aplicável, atomicidade.
+
+Nunca:
+
+* desabilite foreign keys;
+* ignore constraints;
+* insira dados inconsistentes;
+* utilize valores mágicos para contornar regras;
+* duplique dados para contornar relacionamentos.
+
+## 8. Precisão numérica
+
+Respeite a precisão definida pelo domínio:
+
+```text
+Valores monetários: NUMERIC(15,2)
+Quantidades, pesos, alíquotas e fatores: NUMERIC(15,4)
+```
+
+Não altere a precisão sem justificativa e autorização.
+
+## 9. Backend e API
+
+Ao implementar endpoints:
+
+1. Valide as entradas.
+2. Utilize DTOs quando esse for o padrão existente.
+3. Mantenha regras de negócio fora de controllers excessivamente grandes.
+4. Utilize repositories quando esse for o padrão.
+5. Não espalhe SQL pela aplicação.
+6. Trate erros conforme o padrão existente.
+7. Preserve contratos da API.
+
+Não altere contratos existentes sem avaliar seus consumidores.
+
+## 10. Alterações mínimas
+
+Altere somente o necessário para atender à tarefa.
+
+Não faça:
+
+* refatorações fora do escopo;
+* reorganização desnecessária;
+* renomeações por preferência pessoal;
+* alterações de estilo sem motivo;
+* atualizações de dependências sem necessidade;
+* mudanças em contratos não relacionados.
+
+Quanto menor o escopo, melhor.
+
+## 11. Remoção de código
+
+Não remova métodos, classes, endpoints, tabelas, colunas, validações ou testes sem verificar seus consumidores e dependências.
+
+Qualquer remoção deve ter justificativa.
+
+## 12. Testes e validação
+
+Toda alteração que modifique comportamento deve considerar testes.
+
+Antes de finalizar:
+
+1. Execute os testes relacionados.
+2. Valide o comportamento alterado.
+3. Verifique possíveis regressões.
+4. Informe o que foi testado.
+
+Não crie uma infraestrutura de testes inteira sem necessidade quando ela não existir.
+
+## 13. Documentação
+
+Quando uma alteração modificar contrato de API, comportamento importante, banco, fluxo fiscal, configuração ou integração externa, avalie a necessidade de atualizar a documentação correspondente.
+
+## 14. Segurança
+
+Nunca:
+
+* exponha senhas;
+* exponha tokens;
+* exponha certificados;
+* exponha chaves privadas;
+* exponha credenciais;
+* coloque secrets diretamente no código;
+* faça commit de credenciais;
+* registre dados sensíveis desnecessários.
+
+Utilize o mecanismo de segurança já existente no projeto.
+
+## 15. Logs
+
+Logs devem auxiliar no diagnóstico sem expor informações sensíveis.
+
+Nunca registre:
+
+```text
+senhas
+tokens
+certificados
+chaves privadas
+credenciais
+dados sensíveis desnecessários
+```
+
+Siga o padrão de logging existente e utilize o nível adequado.
+
+## 16. Integrações fiscais
+
+O sistema possui integrações com:
+
+* NF-e Modelo 55;
+* NFC-e Modelo 65;
+* NFS-e;
+* CT-e Modelo 57;
+* MDF-e Modelo 58;
+* eventos fiscais e serviços relacionados.
+
+Não simplifique regras fiscais apenas para facilitar uma implementação.
+
+Alterações devem considerar os fluxos e relacionamentos existentes.
+
+## 17. Fluxos críticos
+
+Tenha atenção especial a operações com múltiplas etapas, como:
+
+```text
+Produto
+ ↓
+Documento Fiscal
+ ↓
+Itens
+ ↓
+Pagamentos
+ ↓
+Duplicatas
+ ↓
+Assinatura
+ ↓
+Transmissão
+ ↓
+Autorização
+ ↓
+Atualização do documento
+ ↓
+Numeração da série
+```
+
+Alterações em uma etapa podem afetar as demais.
+
+## 18. Não assumir
+
+Quando algo não estiver claro:
+
+* procure no código;
+* procure configurações;
+* procure migrations;
+* procure classes relacionadas;
+* procure documentação;
+* verifique contratos existentes.
+
+Não invente comportamento.
+
+Se permanecer uma ambiguidade relevante, informe a dúvida ao usuário antes de implementar.
+
+## 19. Regra de escopo
+
+Não faça alterações silenciosas.
+
+Não implemente melhorias não solicitadas.
+
+Não introduza arquitetura nova sem necessidade.
+
+Não altere banco sem planejamento e autorização.
+
+Não comprometa integridade ou segurança para "fazer funcionar".
+
+## 20. Checklist obrigatório
+
+Antes de finalizar uma implementação:
+
+* [ ] Plano apresentado antes da implementação.
+* [ ] Autorização explícita recebida.
+* [ ] Alteração dentro do escopo solicitado.
+* [ ] Arquitetura existente respeitada.
+* [ ] Nenhum Laravel utilizado.
+* [ ] Nenhum CodeIgniter utilizado.
+* [ ] `claudecio/krothiumapi v1.0` respeitado.
+* [ ] Nenhum `SELECT *` utilizado.
+* [ ] Colunas SQL explicitamente definidas.
+* [ ] SQL parametrizado.
+* [ ] Alterações de banco avaliadas.
+* [ ] Testes/validações executados.
+* [ ] Nenhuma refatoração desnecessária.
+* [ ] Nenhum segredo ou credencial exposto.
+* [ ] Resultado informado ao usuário.
+
+## Regra de ouro
+
+**Planeje antes de implementar.
+Peça autorização antes de alterar.
+Nunca utilize `SELECT *`.
+Respeite a arquitetura existente.
+Não utilize Laravel ou CodeIgniter.
+Respeite `claudecio/krothiumapi v1.0`.
+Não altere banco sem planejamento e autorização.
+Não faça alterações fora do escopo.
+Preserve segurança e integridade dos dados.**