Feat/expedicao

[virocha11]

Expedições: listagem, cadastro e integração com a API v2

Entrega o módulo de expedições no painel — tela de listagem e formulário de cadastro — integrado ao contrato da rota /api/v2/expedicoes (hcf-api, branch 532-cadastro-expedicoes).

São 8 commits, 22 arquivos, +1308/−3, reunindo o trabalho de feat/Expedicao, formulario-expedicao (PR #404) e 399-team-luiz-criar-página-de-listagem-de-expedições.

Listagem de expedições

Tela em /expedicoes, dividida em "Próximas expedições" e "Expedições realizadas", com paginação independente por seção e estados de carregamento, vazio e erro com botão de repetir. Cada card mostra período, destino, número de participantes e descrição.

Filtros por data de início, data de fim, cidade de destino e participante — os dois últimos como selects que exibem nome e submetem id.

Cadastro de expedição

Página em /expedicoes/novo, organizada em src/features/expedicoes/ com separação entre contrato de API, componentes de formulário e hooks:

• api/expedicaoContract.ts — tipos e a conversão do formulário para o payload da API
• components/ — campos de destino, participantes e rota
• hooks/useBuscaRemota.ts — busca remota com debounce de 300 ms, descarte de respostas fora de ordem e fixação das opções já selecionadas, para que não sumam quando o termo de busca muda
• hooks/useNovaExpedicaoPage.ts — orquestra o POST e revalida a listagem após o cadastro

Participantes e cidades são buscados sob demanda em /usuarios e /cidades, em vez de carregar as listas inteiras.

Integração com o contrato v2

Ajustes feitos após validação contra a API real:

• Ordenação: o parâmetro passou a ser order no formato "coluna:direção", substituindo order_column/order_direction. Os parâmetros antigos eram aceitos sem erro e ignorados, fazendo as duas seções caírem no default id:desc — a ordenação por data não estava funcionando. A API responde 400 a formato inválido.
• Destino: a listagem devolve cidade_nome e estado_sigla, lidos direto da resposta e exibidos como Piraquara/PR. Elimina a necessidade de indexar em memória as ~5.800 cidades só para resolver o nome.
• Datas: o payload preserva data/hora local com offset, sem conversão para UTC, evitando o deslocamento de um dia em expedições criadas perto da meia-noite.

Permissões

Novo recurso Expedicao em src/resources/permissions.ts, com read, create, update e delete concedidos ao Curador. Operador e Identificador não recebem regras. A rota de cadastro é protegida por auth.can('create', 'Expedicao'); listagem e detalhes exigem apenas usuário autenticado.

Internacionalização

Namespace novaExpedicaoPage registrado em src/i18n.ts, com traduções para pt-BR, en e es.

Correções incluídas

Hook de pre-push (a53d437, de @LuizGustavoNascimeto): o git mantém o stdin do hook aberto com a lista de refs, e os processos filhos do vitest herdavam esse pipe, travando a fila de testes. O exec < /dev/null desfaz a herança. Sem isso, git push ficava pendurado indefinidamente.

Interceptor do axios (src/setup.ts): a verificação de 401 acessava err.error.code sem proteção, lançando TypeError em qualquer erro sem corpo de resposta — rede, timeout, 502. Agora é opcional e também considera status === 401.

Testes

• test/pages/ListaExpedicoesScreen.spec.ts — montagem dos parâmetros por seção, transformação da resposta e fallback para Cidade #id
• test/features/expedicoes/expedicaoContract.spec.ts — endpoint, preservação do offset de data, omissão de campos vazios, normalização de descrição e extração de mensagem de erro da API

Pontos de atenção

• Depende da branch 532-cadastro-expedicoes da hcf-api. Contra a development atual da API, o parâmetro order e os campos cidade_nome/estado_sigla não existem, e a listagem não funciona como descrito.
• GET /usuarios exige perfil Curador. Para Operador e Identificador a rota responde 403 e o select de participantes fica vazio, com alerta na tela.
• Não existe filtro de situação na API. Os recortes são aproximados por data (data_inicio >= hoje e data_fim <= ontem), então uma expedição em andamento não aparece em nenhuma das seções.
• Editar e arquivar seguem desabilitados nos cards — a API ainda não oferece essas operações. A tela de detalhes é um placeholder.

Justificativa do merge

A entrega fecha o fluxo básico de expedições — listar, filtrar e cadastrar — que hoje não existe no painel. É funcionalidade nova e isolada: entra por rota própria, menu próprio e recurso de permissão próprio, sem alterar comportamento de telas existentes.

As duas mudanças que tocam código compartilhado são corretivas e de baixo risco. O ajuste no interceptor do axios remove um TypeError que já afetava qualquer erro sem corpo de resposta, em todo o painel. A correção do hook de pre-push desbloqueia o push para todo o time, e não faz sentido segurá-la em um branch.

A cobertura de testes acompanha as duas partes de maior risco — a tradução do formulário para o payload e a montagem dos parâmetros de listagem —, que são justamente onde divergências de contrato costumam passar despercebidas. As limitações restantes estão do lado da API e não bloqueiam o uso do que está entregue.