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