Tela de Pedidos — Conhecimentos Internos

---

Modo tempo real (detalhes técnicos)

Quando habilitado no contexto elegível:

• atualização automática da lista a cada 30 segundos
• janela de dados recentes das últimas 8 horas
• bloqueio da alteração manual de período
• indicador visual "Em tempo real" no cabeçalho
• ocultação da paginação visual em algumas combinações de tela

Elegibilidade:

• condicionado por regra de seller group no estado atual da aplicação

---

Feature flags — Tela de Pedidos e Side Panel

Este documento lista todas as feature flags que impactam a tela de Pedidos e o side panel (detalhes do pedido), onde são usadas e como afetam a percepção da tela.

As flags são configuradas por seller group (em user.seller_group.feature_config ou, no caso de simplified_danfe, via variável de ambiente). Quando uma flag está desligada, o elemento associado não é exibido ou o comportamento padrão é usado.

Resumo rápido

1. simplified_danfe

O que controla: Qual serviço de DANFE é usado ao abrir o comprovante fiscal (fluxo "Natura"/simplificado vs padrão).

Onde é usada:

• Tela de pedidos — ação em lote: ao clicar em DANFE na barra flutuante (pedidos selecionados), a URL aberta é:
  • Ligada: NX_MAIL_DANFE_URL_APP_RUNNER + /mail-danfe/v1/orders?trackings=...
  • Desligada: NX_MAIL_DANFE_URL + /v1/orders?trackings=...
• Menu da linha (⋮): opção Ver DANFE usa a mesma regra para abrir o link.
• Side panel — dropdown Ações: opção Ver DANFE usa a mesma regra.

Como afeta a percepção:

• O texto continua sendo "Ver DANFE" / "DANFE" em todos os lugares.
• A diferença é apenas o destino (domínio/backend) que abre na nova aba. Para o usuário a tela "parece" a mesma; apenas o conteúdo/URL do DANFE muda conforme a flag.
• A opção só é habilitada quando o pedido tem NF e chave de acesso; a flag não altera essa regra.

Detalhe técnico: além de feature_config, essa flag pode ser definida pela variável de ambiente NX_DANFE_SELLER_GROUP_ID (lista de IDs de seller group separados por vírgula). Se o seller_group_id do usuário estiver nessa lista, a flag é considerada ligada.

2. mark_as_collected

O que controla: Exibição da ação Marcar Coletado e do atalho de filtro para pedidos prontos para coleta.

Onde é usada:

• Tela de pedidos — barra flutuante: quando há linhas selecionadas, o botão Marcar Coletado só aparece se a flag estiver ligada. Ao clicar, navega para o fluxo mark-collected com os pedidos selecionados.
• Tela de pedidos — dropdown Atalhos: o botão Atalhos (ícone ListEnd) só é exibido se pelo menos uma das flags mark_as_collected ou order_supply_enabled estiver ligada. Com mark_as_collected ligada, dentro de Atalhos aparece o item Filtrar Pedidos Prontos Para Coleta, que aplica:
  • filtro de origem de criação HERMES-XML
  • filtro de status CREATED.

Como afeta a percepção:

• Desligada: não há botão "Marcar Coletado" na seleção múltipla e não há atalho para "prontos para coleta". Quem não tem a flag não vê esse fluxo de coleta nem o filtro rápido.
• Ligada: a tela ganha uma ação clara de "marcar como coletado" em lote e um atalho para focar nos pedidos prontos para coleta, mudando a percepção da tela para um fluxo mais orientado a coleta.

3. order_supply_enabled

O que controla: Visibilidade de conceitos de abastecimento (operação SUPPLY) na lista e no detalhe do pedido.

Onde é usada:

• Tela de pedidos — dropdown Atalhos: (junto com mark_as_collected) define se o botão Atalhos aparece. Com order_supply_enabled ligada, dentro de Atalhos aparece o item Filtrar Pedidos Abastecimento, que aplica filtro por tipo de operação SUPPLY.
• Side panel — seção Informações: o campo Ordem de Operação (operation: SUPPLY / DELIVERY) só é exibido quando a flag está ligada. Caso contrário, o campo fica oculto na seção Informações.

Como afeta a percepção:

• Desligada: não há atalho para "abastecimento", e no painel de detalhes o usuário não vê se o pedido é de operação SUPPLY ou DELIVERY. A tela parece "só entrega".
• Ligada: a tela passa a expor atalho para filtrar pedidos de abastecimento e, no side panel, o campo de operação deixa explícito o tipo (abastecimento vs entrega), reforçando a percepção de que há dois fluxos (abastecimento e entrega).

Nota: A seção Trecho de origem (pedido anterior / abastecimento) no side panel depende de o pedido ter previous_order (dado), não desta flag. A flag só controla o campo "Ordem de Operação" e o atalho de filtro.

4. order_external_id_search

O que controla: Exposição do ID externo do pedido na busca e na tabela.

Onde é usada:

• Tela de pedidos — busca assíncrona: nas sugestões de pedido (combobox de busca), cada item pode exibir a linha "ID Externo:" seguido do valor de order.external_id quando a flag está ligada e o pedido tem external_id.
• Tela de pedidos — colunas da tabela: é adicionada a coluna ID Externo (external_id) após a coluna do número do pedido. O conteúdo é exibido (ou vazio) conforme o dado do pedido.
• Lista de pedidos (versão v1): na página legada de listagem, a coluna external_id também é incluída quando a flag está ligada.

Como afeta a percepção:

• Desligada: a busca não mostra ID externo nas sugestões e a tabela não tem coluna "ID Externo". A tela parece centrada só em número de pedido, NF e rastreio.
• Ligada: o usuário passa a ver o identificador do sistema de origem (ERP, e-commerce etc.) na busca e na tabela, melhorando a percepção de rastreabilidade e integração com sistemas externos.

Flags relacionadas a "pedido" mas fora da tela de listagem / side panel

As flags abaixo não alteram diretamente a tela de Pedidos (lista) nem o side panel de detalhes; atuam em outros fluxos acessíveis a partir do contexto de pedidos:

Ou seja: quem só consulta a lista e o side panel não é afetado por essas duas; elas mudam a criação de pedidos (e, no caso do XML, o comportamento do upload).

Onde as flags são definidas

• Código: apps/seller-hermes/src/hooks/useSellerGroupFeatureFlag.ts — tipo FeatureFlag e função getSellerGroupFeatureFlag.
• Fonte do valor: em geral user.seller_group.feature_config[flag]. A exceção é simplified_danfe, que também pode ser ligada quando user.seller_group_id está em process.env['NX_DANFE_SELLER_GROUP_ID'] (lista separada por vírgula).

Documentar no código ou no backend quais seller groups têm cada flag evita dúvidas sobre por que um cliente vê ou deixa de ver cada comportamento descrito acima.