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