Appearance
Operação de doca — Regras de Negócio
RN-01 — Unicidade da tupla de operação
Cada operação de doca é identificada pela combinação única de:
- Doca (
loading_bay_id) - Modal (
modal_type) - Modalidade (
modality_id) - Tipo de carga (
cargo_type_id)
Não é possível criar duas operações com a mesma tupla para o mesmo tenant.
RN-02 — Criação sempre inicia desativada
Ao criar uma nova operação de doca, o campo is_active é enviado como false obrigatoriamente. O sistema não deve permitir criar uma operação já ativada pois ela so pode ser atividade despois de completa com a faixas de cep relacionadas com o serviço de transporte.
RN-03 — Sequência de preenchimento do formulário
O formulário é dividido em seções que seguem uma ordem lógica de dependência:
- Configuração operacional: armazém → doca (docas são filtradas pelo armazém escolhido)
- Tupla da operação: modal → modalidade → tipo de carga
- Cobertura de CEP: mapa de CEP (só publicados)
As seções Serviços e Serviço Referência CEP só ficam disponíveis após a operação ser salva e um configId existir.
RN-04 — Docas filtradas por armazém (hub)
A lista de docas disponíveis para seleção é sempre filtrada pelo armazém (hub logístico) selecionado na seção anterior. Não é possível selecionar uma doca sem antes selecionar um armazém.
Se o armazém selecionado não tiver docas cadastradas, o sistema exibe um aviso com link para o cadastro em /expedition?tab=docks.
RN-05 — Mapa de CEP: apenas publicados
Somente mapas de CEP com status === 'published' aparecem na seleção do formulário. Mapas em rascunho ou arquivados não são elegíveis.
RN-06 — Serviços filtrados pela tupla
Ao vincular um serviço à operação, a lista de serviços de transporte disponíveis é filtrada pelos três atributos da tupla da operação:
modal_typemodality_idcargo_type_id
Apenas serviços que coincidem com todos os três critérios são exibidos. Se nenhum serviço compatível existir, o sistema exibe um aviso com link para o cadastro em /transport?tab=carrier-service.
RN-07 — Vigência de serviço
Ao vincular um serviço, a vigência (validity_period) deve satisfazer a regra:
data_fim >= data_inícioA validação é feita via Zod no frontend antes do envio. As datas são enviadas como strings ISO ao backend.
RN-08 — Serviço criado como habilitado por padrão
Ao vincular um novo serviço à operação, o campo is_enabled é enviado como true por padrão.
RN-09 — Efeito de ativar / desativar operação
Ao ativar ou desativar uma operação de doca:
- Desativar: a operação deixa de aceitar novos serviços de transporte naquela doca.
- Ativar: a operação volta a aceitar novos serviços.
O modal de confirmação exibe esse aviso explicitamente ao usuário antes de aplicar a mudança.
RN-10 — Edição parcial por seção
Em modo de edição, cada seção do formulário pode ser salva independentemente. O backend aceita PATCH com apenas os campos da seção alterada. As demais seções não são afetadas.
RN-11 — Fluxo de upload da planilha de mapeamento CEP
O mapeamento de CEP segue um pipeline em três etapas obrigatórias e sequenciais:
| Etapa | Endpoint | Regra |
|---|---|---|
| 1. Validar erros | validate-errors | HTTP 204 = sem erros; HTTP 200 com blob = planilha de erros |
| 2. Validar avisos | validate-warnings | Blob vazio = sem avisos, pular direto para aplicar |
| 3. Aplicar mapeamento | apply-mapping | Só executado após erros zerados e avisos aceitos |
Não é possível chamar apply-mapping sem antes passar pelas etapas de validação com sucesso.
RN-12 — Tamanho máximo do arquivo de planilha
A planilha de mapeamento CEP aceita apenas formatos .xlsx e .xls com tamanho máximo de 10 MB.
RN-13 — Trocar mapeamento existente
Se já existem mapeamentos de CEP vinculados à operação, o sistema exibe a tabela paginada dos mapeamentos vigentes. O usuário pode iniciar um novo fluxo de upload clicando em "Trocar mapeamento", o que substitui os mapeamentos existentes.
RN-14 — Filtros de listagem
A tela de listagem suporta:
- Busca por nome com debounce de 500ms
- Filtro por status:
ativo/todos - Paginação: tamanhos de página disponíveis: 2, 5 e 10 itens
O estado dos filtros e da paginação é persistido na URL via nuqs.
RN-15 — Exclusão permanente
A exclusão de uma operação de doca é permanente e irreversível. O modal de confirmação deve ser confirmado explicitamente pelo usuário. Não há soft-delete: a operação é removida via DELETE.