108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# Guia de Integração Frontend-Backend: Módulo GR Operações
|
|
|
|
Este documento serve como guia técnico para o desenvolvimento da API backend que alimentará o novo módulo de GR Operações. O frontend foi construído de forma modular, utilizando uma camada de abstração que permite alternar entre dados simulados (mocks) e a API real através de uma flag.
|
|
|
|
---
|
|
|
|
## 1. Arquitetura do Frontend
|
|
|
|
O frontend segue um padrão de 3 camadas:
|
|
1. **Views (React Components):** Interface do usuário. Não conhecem a origem dos dados.
|
|
2. **Hooks (useXXX):** Encapsulam a lógica de negócio, caching básico e chamadas aos services.
|
|
3. **Services (xxxService):** Camada de comunicação com a rede (Fetch/Axios). Contêm a lógica de Mock.
|
|
|
|
### Como ativar a API Real
|
|
Em cada arquivo dentro de `src/features/gr/services/`, existe uma constante:
|
|
```javascript
|
|
const USE_MOCK = true; // Altere para false para usar a API real
|
|
const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:3000';
|
|
```
|
|
Basta alterar `USE_MOCK` para `false` e configurar a URL da sua API no arquivo `.env`.
|
|
|
|
---
|
|
|
|
## 2. Contratos da API (Endpoints Esperados)
|
|
|
|
Abaixo estão os endpoints que os Services já tentam chamar quando `USE_MOCK = false`.
|
|
|
|
### 🚨 2.1 Monitoramento de Viagens
|
|
- **GET** `/api/gr/monitoring/requests`
|
|
- **Filtros (Query):** `status` (PENDING, LIBERADO, EM_ROTA, FINALIZADO)
|
|
- **POST** `/api/gr/monitoring/request/:id/attend`
|
|
- **Ação:** Marca supervisor como responsável pela análise.
|
|
- **POST** `/api/gr/monitoring/request/:id/approve`
|
|
- **Payload:** `{ cargoValue, cte, ae, pallet, routeImageUrl, customMessage }`
|
|
|
|
### 🛰️ 2.2 Telemetria e Rastreamento
|
|
- **GET** `/api/gr/telemetry/positions`
|
|
- **Retorno:** Array de veículos com `plate, lat, lng, speed, riskStatus, alert`.
|
|
- **GET** `/api/gr/telemetry/history/:plate`
|
|
- **Retorno:** Array de posições históricas (lat, lng, timestamp, speed).
|
|
|
|
### 📋 2.3 Checklist e Manutenção
|
|
- **GET** `/api/gr/checklist/vehicles`
|
|
- **Filtros:** `client`
|
|
- **POST** `/api/gr/checklist/renew/:id`
|
|
- **Ação:** Estende validade do checklist.
|
|
- **GET** `/api/gr/maintenance/orders`
|
|
- **Filtros:** `vehicleId`
|
|
- **POST** `/api/gr/maintenance/orders`
|
|
- **Payload:** `{ vehicleId, type, sensor, description }`
|
|
|
|
### 📄 2.4 Gestão de Documentos
|
|
- **GET** `/api/gr/documents`
|
|
- **Filtros:** `entityType` (MOTORISTA, VEÍCULO), `docType` (CNH, CRLV)
|
|
- **POST** `/api/gr/documents` (**Multipart/Form-Data**)
|
|
- **Payload:** `file, client, entityType, entityName, docType`
|
|
- **DELETE** `/api/gr/documents/:id`
|
|
|
|
### 📊 2.5 Planilhas e Importação
|
|
- **GET** `/api/gr/spreadsheets`
|
|
- **Filtros:** `clientId, archived` (boolean)
|
|
- **POST** `/api/gr/spreadsheets/import`
|
|
- **Payload:** `{ clientId, rows: [...] }`
|
|
- **PATCH** `/api/gr/spreadsheets/:id/archive`
|
|
|
|
---
|
|
|
|
## 3. Modelos de Dados (Exemplos JSON)
|
|
|
|
### Objeto de Solicitação de Monitoramento
|
|
```json
|
|
{
|
|
"id": "uuid",
|
|
"driverName": "String",
|
|
"plate": "AAA-0000",
|
|
"status": "PENDING",
|
|
"riskLevel": "LOW | MEDIUM | HIGH",
|
|
"cargoValue": 0,
|
|
"origin": "Cidade - UF",
|
|
"destination": "Cidade - UF"
|
|
}
|
|
```
|
|
|
|
### Objeto de Telemetria
|
|
```json
|
|
{
|
|
"id": "uuid",
|
|
"plate": "AAA-0000",
|
|
"lat": -22.90,
|
|
"lng": -43.17,
|
|
"speed": 80,
|
|
"riskStatus": "NORMAL | CRITICAL",
|
|
"alert": "EXCESS_SPEED | NO_SIGNAL"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## ⚡ 4. WebSockets (Socket.io)
|
|
|
|
O frontend está preparado para ouvir os seguintes eventos para atualizações em tempo real:
|
|
- `monitoring-update`: Quando uma nova solicitação chega.
|
|
- `positions-update`: Quando as posições de telemetria mudam.
|
|
- `request-approved`: Quando o status de uma viagem muda para LIBERADO.
|
|
|
|
---
|
|
*Documento gerado para auxiliar o time de backend na migração do módulo GR.*
|