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

300
API.md Normal file
View File

@@ -0,0 +1,300 @@
# Portal Juru API Documentation
## Índice
1. [Autenticação](#autenticação)
2. [Endpoints](#endpoints)
- [Consulta de Dados](#consulta-de-dados)
- [Pedidos e Pagamentos](#pedidos-e-pagamentos)
3. [Modelos de Dados](#modelos-de-dados)
4. [Exemplos de Uso](#exemplos-de-uso)
5. [Códigos de Erro](#códigos-de-erro)
## Autenticação
A API utiliza autenticação JWT. Para acessar os endpoints protegidos, inclua o token no header:
```
Authorization: Bearer seu-token-jwt
```
## Endpoints
### Consulta de Dados
#### Listar Lojas
```http
GET /api/v1/data-consult/stores
```
**Resposta**
```json
[
{
"id": "001",
"name": "Loja Principal",
"store": "001 - Loja Principal"
}
]
```
#### Listar Vendedores
```http
GET /api/v1/data-consult/sellers
```
**Resposta**
```json
[
{
"id": "001",
"name": "João Silva"
}
]
```
#### Consultar Faturamento
```http
GET /api/v1/data-consult/billings
```
**Resposta**
```json
[
{
"id": "001",
"date": "2024-04-02T10:00:00Z",
"total": 1000.00
}
]
```
#### Filtrar Clientes
```http
GET /api/v1/data-consult/customers/:filter
```
**Parâmetros**
- `filter`: Termo de busca (nome, documento, etc.)
**Resposta**
```json
[
{
"id": "001",
"name": "Maria Silva",
"document": "123.456.789-00"
}
]
```
#### Buscar Produtos
```http
GET /api/v1/data-consult/products/:filter
```
**Parâmetros**
- `filter`: Termo de busca (nome, código, etc.)
**Resposta**
```json
[
{
"id": "001",
"name": "Produto Exemplo",
"manufacturerCode": "ABC123"
}
]
```
### Pedidos e Pagamentos
#### Listar Pedidos da Loja
```http
GET /api/v1/orders-payment/orders/:id
```
**Parâmetros**
- `id`: ID da loja
**Resposta**
```json
[
{
"createDate": "2024-04-02T10:00:00Z",
"storeId": "001",
"orderId": 12345,
"customerId": "001",
"customerName": "João Silva",
"sellerId": "001",
"sellerName": "Maria Santos",
"billingId": "001",
"billingName": "Cartão de Crédito",
"planId": "001",
"planName": "3x sem juros",
"amount": 1000.00,
"installments": 3,
"amountPaid": 1000.00
}
]
```
#### Buscar Pedido Específico
```http
GET /api/v1/orders-payment/orders/:id/:orderId
```
**Parâmetros**
- `id`: ID da loja
- `orderId`: ID do pedido
**Resposta**
```json
{
"createDate": "2024-04-02T10:00:00Z",
"storeId": "001",
"orderId": 12345,
"customerId": "001",
"customerName": "João Silva",
"sellerId": "001",
"sellerName": "Maria Santos",
"billingId": "001",
"billingName": "Cartão de Crédito",
"planId": "001",
"planName": "3x sem juros",
"amount": 1000.00,
"installments": 3,
"amountPaid": 1000.00
}
```
#### Listar Pagamentos do Pedido
```http
GET /api/v1/orders-payment/payments/:id
```
**Parâmetros**
- `id`: ID do pedido
**Resposta**
```json
[
{
"orderId": 12345,
"payDate": "2024-04-02T10:00:00Z",
"card": "**** **** **** 1234",
"installments": 3,
"flagName": "VISA",
"type": "CREDITO",
"amount": 1000.00,
"userId": "001",
"nsu": "123456789",
"auth": "A12345"
}
]
```
#### Criar Pagamento
```http
POST /api/v1/orders-payment/payments/create
```
**Corpo da Requisição**
```json
{
"orderId": 12345,
"card": "**** **** **** 1234",
"auth": "A12345",
"nsu": "123456789",
"installments": 3,
"amount": 1000.00,
"flagName": "VISA",
"paymentType": "CREDITO",
"userId": 1
}
```
#### Criar Fatura
```http
POST /api/v1/orders-payment/invoice/create
```
**Corpo da Requisição**
```json
{
"orderId": 12345,
"userId": 1
}
```
## Modelos de Dados
### OrderDto
```typescript
interface OrderDto {
createDate: Date; // Data de criação do pedido
storeId: string; // ID da loja
orderId: number; // ID do pedido
customerId: string; // ID do cliente
customerName: string; // Nome do cliente
sellerId: string; // ID do vendedor
sellerName: string; // Nome do vendedor
billingId: string; // ID da forma de pagamento
billingName: string; // Nome da forma de pagamento
planId: string; // ID do plano de pagamento
planName: string; // Nome do plano de pagamento
amount: number; // Valor total do pedido
installments: number; // Número de parcelas
amountPaid: number; // Valor total pago
}
```
### PaymentDto
```typescript
interface PaymentDto {
orderId: number; // ID do pedido
payDate: Date; // Data do pagamento
card: string; // Número do cartão
installments: number; // Número de parcelas
flagName: string; // Nome da bandeira
type: string; // Tipo de pagamento
amount: number; // Valor do pagamento
userId: string; // ID do usuário
nsu: string; // NSU da transação
auth: string; // Código de autorização
}
```
## Códigos de Erro
| Código | Descrição |
|--------|-----------|
| 400 | Requisição inválida |
| 401 | Não autorizado |
| 403 | Acesso negado |
| 404 | Recurso não encontrado |
| 500 | Erro interno do servidor |
## Exemplos de Uso
### Exemplo de Requisição com cURL
```bash
# Listar pedidos de uma loja
curl -X GET "http://localhost:3000/api/v1/orders-payment/orders/001" \
-H "Authorization: Bearer seu-token-jwt"
# Criar novo pagamento
curl -X POST "http://localhost:3000/api/v1/orders-payment/payments/create" \
-H "Authorization: Bearer seu-token-jwt" \
-H "Content-Type: application/json" \
-d '{
"orderId": 12345,
"card": "**** **** **** 1234",
"auth": "A12345",
"nsu": "123456789",
"installments": 3,
"amount": 1000.00,
"flagName": "VISA",
"paymentType": "CREDITO",
"userId": 1
}'

141
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,141 @@
# Guia de Contribuição
Obrigado por considerar contribuir para o Portal Juru API! Este documento fornece um conjunto de diretrizes para contribuir com o projeto.
## Como Contribuir
1. Faça um fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request
## Padrões de Código
### TypeScript/JavaScript
- Use TypeScript para todo o código
- Siga o [style guide oficial do TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-files/by-example.html)
- Use ESLint e Prettier para formatação
- Mantenha o código limpo e bem documentado
### NestJS
- Siga as [melhores práticas do NestJS](https://docs.nestjs.com/recipes/prisma)
- Use decorators apropriadamente
- Mantenha os módulos bem organizados
- Use DTOs para validação de dados
### Banco de Dados
- Use TypeORM para todas as operações de banco de dados
- Mantenha as queries SQL otimizadas
- Use transações quando necessário
- Documente as queries complexas
## Estrutura do Projeto
```
src/
├── core/ # Configurações e utilitários core
│ ├── configs/ # Configurações do projeto
│ ├── database/ # Configuração do banco de dados
│ └── constants/ # Constantes do sistema
├── data-consult/ # Módulo de consulta de dados
│ ├── dto/ # Data Transfer Objects
│ ├── controllers/ # Controladores
│ └── services/ # Serviços
├── orders-payment/ # Módulo de pedidos e pagamentos
│ ├── dto/ # Data Transfer Objects
│ ├── controllers/ # Controladores
│ └── services/ # Serviços
└── orders/ # Módulo de pedidos
├── modules/ # Módulos
├── controllers/ # Controladores
├── services/ # Serviços
└── repositories/ # Repositórios
```
## Convenções de Commits
Use o seguinte formato para commits:
```
<type>(<scope>): <subject>
<body>
<footer>
```
Tipos de commit:
- `feat`: Nova feature
- `fix`: Correção de bug
- `docs`: Mudanças na documentação
- `style`: Formatação, ponto e vírgula, etc.
- `refactor`: Refatoração de código
- `test`: Adição ou correção de testes
- `chore`: Atualização de tarefas, configuração, etc.
Exemplo:
```
feat(orders): adiciona endpoint para criar pedidos
- Implementa validação de dados
- Adiciona testes unitários
- Atualiza documentação
Closes #123
```
## Testes
- Mantenha a cobertura de testes acima de 80%
- Use Jest para testes
- Escreva testes unitários e de integração
- Execute todos os testes antes de submeter um PR
```bash
# Executar testes
npm run test
# Executar testes com cobertura
npm run test:cov
```
## Documentação
- Mantenha a documentação atualizada
- Use Swagger para documentação da API
- Documente todas as novas features
- Atualize o README quando necessário
## Pull Requests
1. Descreva claramente as mudanças
2. Inclua exemplos de uso quando relevante
3. Atualize a documentação
4. Certifique-se que todos os testes passam
5. Solicite revisão de pelo menos um mantenedor
## Issues
- Use o template apropriado
- Forneça informações detalhadas
- Inclua exemplos de reprodução quando possível
- Use labels apropriadas
## Código de Conduta
- Seja respeitoso
- Mantenha discussões construtivas
- Aceite críticas construtivas
- Ajude outros contribuidores
## Suporte
Se você tiver dúvidas ou precisar de ajuda:
- Abra uma issue
- Entre em contato com os mantenedores
- Consulte a documentação

190
README.md
View File

@@ -1,73 +1,157 @@
<p align="center"> # Portal Juru API
<a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo_text.svg" width="320" alt="Nest Logo" /></a>
</p>
[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456 API para gerenciamento de pedidos, pagamentos e consultas de dados do sistema Portal Juru.
[circleci-url]: https://circleci.com/gh/nestjs/nest
<p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p> ## 🚀 Tecnologias
<p align="center">
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
<a href="https://coveralls.io/github/nestjs/nest?branch=master" target="_blank"><img src="https://coveralls.io/repos/github/nestjs/nest/badge.svg?branch=master#9" alt="Coverage" /></a>
<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
<a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg"/></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
<a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
</p>
<!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
[![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
## Description - [NestJS](https://nestjs.com/) - Framework Node.js
- [TypeORM](https://typeorm.io/) - ORM para banco de dados
- [Swagger](https://swagger.io/) - Documentação da API
- [Oracle Database](https://www.oracle.com/database/) - Banco de dados
- [Redis](https://redis.io/) - Cache em memória
[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository. ## 📋 Pré-requisitos
## Installation - Node.js (v16 ou superior)
- Oracle Database
- Redis
- npm ou yarn
## 🔧 Instalação
1. Clone o repositório:
```bash ```bash
$ npm install git clone https://github.com/seu-usuario/portaljuru-api.git
cd portaljuru-api
``` ```
## Running the app 2. Instale as dependências:
```bash ```bash
# development npm install
$ npm run start # ou
yarn install
# watch mode
$ npm run start:dev
# production mode
$ npm run start:prod
``` ```
## Test 3. Configure as variáveis de ambiente:
```bash ```bash
# unit tests cp .env.example .env
$ npm run test # Edite o arquivo .env com suas configurações
# e2e tests
$ npm run test:e2e
# test coverage
$ npm run test:cov
``` ```
## Support 4. Inicie o servidor:
```bash
npm run start:dev
# ou
yarn start:dev
```
Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support). ## 📚 Documentação da API
## Stay in touch A documentação completa da API está disponível em `/api` quando o servidor estiver rodando.
- Author - [Kamil Myśliwiec](https://kamilmysliwiec.com) ### Endpoints Principais
- Website - [https://nestjs.com](https://nestjs.com/)
- Twitter - [@nestframework](https://twitter.com/nestframework)
## License #### Consulta de Dados
- `GET /api/v1/data-consult/stores` - Lista todas as lojas
- `GET /api/v1/data-consult/sellers` - Lista todos os vendedores
- `GET /api/v1/data-consult/billings` - Retorna informações de faturamento
- `GET /api/v1/data-consult/customers/:filter` - Filtra clientes
- `GET /api/v1/data-consult/products/:filter` - Busca produtos filtrados
Nest is [MIT licensed](LICENSE). #### Pedidos e Pagamentos
- `GET /api/v1/orders-payment/orders/:id` - Lista pedidos de uma loja
- `GET /api/v1/orders-payment/orders/:id/:orderId` - Busca pedido específico
- `GET /api/v1/orders-payment/payments/:id` - Lista pagamentos de um pedido
- `POST /api/v1/orders-payment/payments/create` - Cria novo pagamento
- `POST /api/v1/orders-payment/invoice/create` - Cria nova fatura
## 🛠️ Estrutura do Projeto
```
src/
├── core/ # Configurações e utilitários core
│ ├── configs/ # Configurações do projeto
│ ├── database/ # Configuração do banco de dados
│ └── constants/ # Constantes do sistema
├── data-consult/ # Módulo de consulta de dados
│ ├── dto/ # Data Transfer Objects
│ ├── controllers/ # Controladores
│ └── services/ # Serviços
├── orders-payment/ # Módulo de pedidos e pagamentos
│ ├── dto/ # Data Transfer Objects
│ ├── controllers/ # Controladores
│ └── services/ # Serviços
└── orders/ # Módulo de pedidos
├── modules/ # Módulos
├── controllers/ # Controladores
├── services/ # Serviços
└── repositories/ # Repositórios
```
## 🔐 Autenticação
A API utiliza autenticação JWT. Para acessar os endpoints protegidos, inclua o token no header:
```
Authorization: Bearer seu-token-jwt
```
## 📦 DTOs (Data Transfer Objects)
### OrderDto
```typescript
{
createDate: Date; // Data de criação do pedido
storeId: string; // ID da loja
orderId: number; // ID do pedido
customerId: string; // ID do cliente
customerName: string; // Nome do cliente
sellerId: string; // ID do vendedor
sellerName: string; // Nome do vendedor
billingId: string; // ID da forma de pagamento
billingName: string; // Nome da forma de pagamento
planId: string; // ID do plano de pagamento
planName: string; // Nome do plano de pagamento
amount: number; // Valor total do pedido
installments: number; // Número de parcelas
amountPaid: number; // Valor total pago
}
```
### PaymentDto
```typescript
{
orderId: number; // ID do pedido
payDate: Date; // Data do pagamento
card: string; // Número do cartão
installments: number; // Número de parcelas
flagName: string; // Nome da bandeira
type: string; // Tipo de pagamento
amount: number; // Valor do pagamento
userId: string; // ID do usuário
nsu: string; // NSU da transação
auth: string; // Código de autorização
}
```
## 🧪 Testes
Para executar os testes:
```bash
npm run test
# ou
yarn test
```
## 📝 Licença
Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.
## 🤝 Contribuição
1. Faça o fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

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>