🚚 MÓDULO LOGÍSTICO COMPLETO. Obrigatório consultar antes de mexer em Embarques, Entregas, Checkout do Motorista, Permissões de Entregador ou CheckoutEntregaModal.
⚠️ Este módulo cobre todo o ciclo logístico: formação de carga, despacho, checkout do motorista e auditoria financeira.
Pedido FATURADO (Conta Azul)
↓
PainelEmbarque → NovaCargaModal → Embarque criado (status PENDENTE)
↓
PainelMotorista ou RotaLeads (aba Entregas) → CheckoutEntregaModal
↓
Pedido com statusEntrega = ENTREGUE | ENTREGUE_PARCIAL | DEVOLVIDO
↓
AuditoriaEntregas (Admin) ou CaixaDiario (Motorista)
| Arquivo | Responsabilidade |
|---|
backend/routes/embarques.js | CRUD de Embarques, formação de carga, despacho |
backend/routes/entregas.js | CRUD de Entregas, checkout motorista, edição admin |
backend/routes/formasPagamentoEntrega.js | Formas de pagamento exclusivas para entrega |
| Arquivo | Responsabilidade |
|---|---|
frontend/src/pages/Admin/Embarques/PainelEmbarque.jsx | Lista e gerencia embarques ativos |
frontend/src/pages/Admin/Embarques/NovaCargaModal.jsx | Criação de nova carga (seleciona pedidos + motorista) |
frontend/src/pages/Admin/Embarques/AuditoriaEntregas.jsx | Auditoria financeira de entregas concluídas |
frontend/src/pages/Motorista/Entregas/PainelMotorista.jsx | Tela principal do motorista (app mobile) |
frontend/src/pages/Motorista/Entregas/CheckoutEntregaModal.jsx | Modal de baixa na entrega (motorista) |
frontend/src/pages/Rota/RotaLeads.jsx | Inclui abas Entregas e Entregues para motoristas que também fazem vendas |
frontend/src/services/entregasService.js | Serviço das rotas de entrega |
O campo permissoes do Vendedor é um JSON armazenado como STRING no banco. Os middlewares e o frontend DEVEM sempre fazer parse antes de checar flags.
// ERRADO (vai dar erro/false negativo sempre)
if (req.user.permissoes.admin) { ... }
// CERTO — buscar direto do banco e fazer parse
const getPerms = async (userId) => {
const vendedor = await prisma.vendedor.findUnique({
where: { id: userId },
select: { permissoes: true }
});
return typeof vendedor?.permissoes === 'string'
? JSON.parse(vendedor.permissoes)
: (vendedor?.permissoes || {});
};
Este helper
getPermsexiste emembarques.js,entregas.js,caixa.jsedespesas.js. Sempre reutilize este padrão.
{
"Pode_Acessar_Embarque": false, // Ver painel de embarques / expedição
"Pode_Executar_Entregas": false, // Ser motorista — ver e dar baixa em entregas
"Pode_Ver_Todas_Entregas": false, // Ver entregas de TODOS os motoristas (auditoria)
"Pode_Ajustar_Entregas": false // Editar/estornar lançamentos de entrega (admin financeiro)
}
| Permissão | O que libera |
|---|---|
admin: true | Tudo — bypassa todas as verificações |
Pode_Acessar_Embarque | Painel de Expedição (/admin/embarques) |
Pode_Executar_Entregas | App Motorista (/minhas-entregas) + abas Entregas/Entregues em RotaLeads |
Pode_Ver_Todas_Entregas | Ver entregas de QUALQUER motorista (combina com Pode_Executar_Entregas) |
Pode_Ajustar_Entregas | Estornar e editar lançamentos de entrega |
// Em AuthContext.jsx, hasPermission() trata flags booleanas diretas:
const podeEntregas = !!(user?.permissoes?.admin) || !!(user?.permissoes?.Pode_Executar_Entregas);
const podeAjustar = !!(user?.permissoes?.admin) || !!(user?.permissoes?.Pode_Ajustar_Entregas);
ATENÇÃO: O
refreshUser()foi adicionado aoAuthContext.jsxpara garantir que permissões salvas no banco apareçam imediatamente após login sem necessidade de logout/login. UserefreshUser()ao carregar telas de logística.
embarques.js)| Método | Path | Descrição |
|---|---|---|
GET | /api/embarques | Lista embarques ativos/recentes |
POST | /api/embarques | Cria novo embarque (formação de carga) |
GET | /api/embarques/:id | Detalhe do embarque com pedidos |
PATCH | /api/embarques/:id/despachar | Marca embarque como despachado |
DELETE | /api/embarques/:id | Remove embarque (somente PENDENTE) |
Para listar motoristas elegíveis na seleção, filtrar usuários com:
// Parse das permissoes (STRING no banco!)
const perms = typeof v.permissoes === 'string' ? JSON.parse(v.permissoes) : (v.permissoes || {});
return !!(perms.admin) || !!(perms.Pode_Executar_Entregas);
Buscar pedidos com statusEnvio = 'FATURADO' e embarqueId = null (ainda não despachados):