simplifique/portalweb-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

push da documentacao da api

Browse Source
This commit is contained in:
JurTI-BR
2025-04-02 18:18:13 -03:00
parent 4719279ab7
commit 15bb11fc4c
6 changed files with 578 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
src/auth/doc/doc.txt
View File

@@ -1,53 +0,0 @@
// Documentação atualizada da funcionalidade de autenticação usando Command + Microservice
/*
Fluxo atualizado:
Client (HTTP POST /api/v1/auth/login)
↓ envia LoginRequestDto
AuthController
↓ envia AuthenticateUserCommand para CommandBus
AuthenticateUserHandler (CommandHandler)
↓ executa regras de negócio
UserRepository
↓ executa query no banco
Result<User>
← resposta encapsulada
AuthController
↓ gera JWT com AuthService
Resposta final: LoginResponseDto com token
*/
// 1. AuthController
// Entrada da requisição HTTP (POST /api/v1/auth/login)
// - Recebe LoginRequestDto com username e password
// - Cria AuthenticateUserCommand
// - Envia para CommandBus
// - Se sucesso, gera JWT via AuthService e retorna LoginResponseDto
// 2. AuthenticateUserCommand
// Representa a intenção de autenticação
// - Dados: username, password
// 3. AuthenticateUserHandler
// Executa o caso de uso de autenticação
// - Busca usuário no UserRepository
// - Verifica se o usuário está desligado ou inativo
// - Retorna Result<User>
// 4. UserRepository
// Camada de persistência (interface com o banco de dados)
// - Executa query findByUsernameAndPassword(username, password)
// 5. Result<T>
// Objeto genérico de retorno que encapsula:
// - Sucesso (success = true, data: User)
// - Falha (success = false, error: string)
// 6. AuthService
// Gera token JWT com base nos dados do usuário
// - Pode gerar access token e refresh token (se necessário)
// Estrutura atual suporta futura extração do AuthModule como microserviço
// - Usando @MessagePattern('auth.login') no AuthController do microserviço
// - Consumo via ClientProxy na aplicação principal com ClientModule

117
src/auth/doc/login.fluxo.html
View File

@@ -1,117 +0,0 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Documentação - Fluxo de Login com Microserviço</title>
<style>
body {
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
background-color: #f9f9f9;
color: #333;
line-height: 1.6;
padding: 2rem;
}
h1, h2, h3 {
color: #007acc;
}
code, pre {
background-color: #eee;
padding: 1rem;
border-radius: 4px;
display: block;
white-space: pre-wrap;
margin-bottom: 1rem;
}
table {
width: 100%;
border-collapse: collapse;
margin: 1rem 0;
}
th, td {
border: 1px solid #ddd;
padding: 0.75rem;
}
th {
background-color: #007acc;
color: white;
}
.tag {
display: inline-block;
background: #007acc;
color: white;
padding: 0.2rem 0.6rem;
border-radius: 4px;
font-size: 0.85rem;
}
</style>
</head>
<body>
<h1>🔐 Fluxo de Login com Microserviço - Portal Juru API</h1>
<h2>📌 Rota de Login</h2>
<p><strong>URL:</strong> <code>POST /api/v1/auth/login</code></p>
<p><strong>Descrição:</strong> Autentica o usuário via microserviço e retorna um token JWT.</p>
<h3>📤 Body (JSON)</h3>
<pre>{
"username": "joelson.r",
"password": "1010"
}</pre>
<h3>✅ Resposta (200 OK)</h3>
<pre>{
"id": 1498,
"sellerId": 2013,
"name": "JOELSON DE BRITO RIBEIRO",
"username": "JOELSON DE BRITO RIBEIRO",
"storeId": "4",
"email": "JOELSON.R@JURUNENSE.COM.BR",
"token": "eyJhbGciOiJIUzI1NiIsInR5..."
}</pre>
<h3>❌ Resposta (401 Unauthorized)</h3>
<pre>{
"success": false,
"message": "Usuário ou senha inválidos.",
"data": null,
"error": "Usuário ou senha inválidos."
}</pre>
<h2>🧱 Camadas e Responsabilidades (CQRS + Microservice)</h2>
<table>
<tr><th>Componente</th><th>Responsabilidade</th></tr>
<tr><td>AuthController</td><td>Recebe requisição HTTP e envia AuthenticateUserCommand ao CommandBus</td></tr>
<tr><td>AuthenticateUserCommand</td><td>Representa a intenção de autenticar um usuário</td></tr>
<tr><td>AuthenticateUserHandler</td><td>Executa regras de autenticação com base no comando</td></tr>
<tr><td>UserRepository</td><td>Consulta o banco para obter dados do usuário</td></tr>
<tr><td>Result&lt;T&gt;</td><td>Encapsula sucesso ou falha com mensagens claras</td></tr>
<tr><td>AuthService</td><td>Gera token JWT e/ou Refresh Token</td></tr>
<tr><td>Auth Microservice</td><td>Escuta o evento 'auth.login' e executa a autenticação</td></tr>
<tr><td>ClientProxy</td><td>Faz chamada ao microserviço de autenticação</td></tr>
</table>
<h2>🔗 Comunicação via Microserviço</h2>
<ul>
<li><strong>Protocolo:</strong> TCP</li>
<li><strong>Evento:</strong> <code>auth.login</code></li>
<li><strong>Porta:</strong> 3001</li>
<li><strong>Formato:</strong> <code>{ username, password }</code></li>
<li><strong>Resposta:</strong> <code>Result&lt;User&gt;</code></li>
</ul>
<h2>🛡️ Proteção com JWT</h2>
<p>Após o login, o token JWT é retornado e deve ser enviado em todas as requisições protegidas.</p>
<code>Authorization: Bearer &lt;token&gt;</code>
<h2>🚀 Melhorias Futuras</h2>
<ul>
<li>[ ] Blacklist de tokens</li>
<li>[ ] Refresh Token</li>
<li>[ ] Log de auditoria</li>
<li>[ ] Controle de permissões e roles</li>
</ul>
<p><strong>Última atualização:</strong> 31/03/2025</p>
</body>
</html>

114
src/data-consult/doc.html
View File

@@ -1,114 +0,0 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Documentação - DataConsult Module</title>
<style>
body {
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
background-color: #f9f9f9;
color: #333;
line-height: 1.6;
padding: 2rem;
}
h1, h2, h3 {
color: #007acc;
}
code, pre {
background-color: #eee;
padding: 1rem;
border-radius: 4px;
display: block;
white-space: pre-wrap;
margin-bottom: 1rem;
}
table {
width: 100%;
border-collapse: collapse;
margin: 1rem 0;
}
th, td {
border: 1px solid #ddd;
padding: 0.75rem;
}
th {
background-color: #007acc;
color: white;
}
.tag {
display: inline-block;
background: #007acc;
color: white;
padding: 0.2rem 0.6rem;
border-radius: 4px;
font-size: 0.85rem;
}
</style>
</head>
<body>
<h1>📊 Módulo de Consultas - Portal Juru API</h1>
<h2>📌 Endpoints Disponíveis</h2>
<h3>🔹 GET /api/v1/data-consult/stores</h3>
<p><strong>Descrição:</strong> Lista todas as lojas.</p>
<p><strong>Autenticação:</strong> <span class="tag">JWT</span></p>
<code>Retorna: StoreDto[]</code>
<h3>🔹 GET /api/v1/data-consult/sellers</h3>
<p><strong>Descrição:</strong> Lista todos os vendedores ativos.</p>
<p><strong>Autenticação:</strong> <span class="tag">JWT</span></p>
<code>Retorna: SellerDto[]</code>
<h3>🔹 GET /api/v1/data-consult/billings</h3>
<p><strong>Descrição:</strong> Retorna todos os tipos de faturamento válidos.</p>
<p><strong>Autenticação:</strong> <span class="tag">JWT</span></p>
<code>Retorna: BillingDto[]</code>
<h3>🔹 GET /api/v1/data-consult/customers/:filter</h3>
<p><strong>Descrição:</strong> Busca clientes por nome, código ou CPF/CNPJ.</p>
<p><strong>Parâmetro:</strong> <code>filter</code></p>
<p><strong>Autenticação:</strong> <span class="tag">JWT</span></p>
<code>Retorna: CustomerDto[]</code>
<h3>🔹 GET /api/v1/data-consult/products/:filter</h3>
<p><strong>Descrição:</strong> Busca produtos por descrição, código ou código auxiliar.</p>
<p><strong>Parâmetro:</strong> <code>filter</code></p>
<p><strong>Autenticação:</strong> Não requer</p>
<code>Retorna: ProductDto[]</code>
<h2>🧱 Camadas e Responsabilidades</h2>
<table>
<tr><th>Camada</th><th>Responsabilidade</th></tr>
<tr><td>DataConsultController</td><td>Recebe as requisições HTTP e delega para o service</td></tr>
<tr><td>DataConsultService</td><td>Intermediário entre controller e repositório; adiciona logs e trata exceções</td></tr>
<tr><td>DataConsultRepository</td><td>Executa queries SQL no Oracle via TypeORM</td></tr>
<tr><td>LoggerService</td><td>Registra logs de acesso, sucesso ou erro</td></tr>
</table>
<h2>📦 Detalhes Técnicos</h2>
<ul>
<li>Utiliza <strong>Oracle</strong> como banco de dados com configuração customizada.</li>
<li>As buscas por cliente e produto realizam múltiplas tentativas de match (ex: por código, nome, etc.).</li>
<li>Repositório implementa <code>queryRunner</code> com liberação segura de conexão.</li>
<li>Camada de serviço registra log com <code>ILogger</code> em todas as operações.</li>
<li>Erros no endpoint <code>products</code> são tratados com <code>HttpException</code>.</li>
</ul>
<h2>🔐 Segurança</h2>
<p>Endpoints protegidos utilizam <code>@UseGuards(JwtAuthGuard)</code> e <code>@ApiBearerAuth()</code>.</p>
<p><strong>Header necessário:</strong></p>
<code>Authorization: Bearer &lt;token&gt;</code>
<h2>🚀 Melhorias Futuras</h2>
<ul>
<li>[🔹 ] Cache Redis para lojas, vendedores e faturamentos</li>
<li>[ ] Auditoria detalhada de acessos no logger</li>
<li>[ ] Paginação nas buscas de clientes e produtos</li>
<li>[ ] Endpoint para exportação dos dados em CSV</li>
</ul>
<p><strong>Última atualização:</strong> 29/03/2025</p>
</body>
</html>