Ocultação Condicional da Seção Forma de Pagamento - NH-150

Data de Implementação: 2025-11-14 Jira Issue: NH-150 Módulo: Comercial Tela: Adicionar/Editar Pedido (Cotação) Tipo: Feature - Melhoria de UX

Índice

Resumo
Contexto e Motivação
Comportamento Implementado
Detalhes Técnicos
Como Testar
Impacto no Sistema
Arquivos Modificados
Requisitos Atendidos
Referências

Resumo

Implementação de ocultação condicional da seção "Forma de Pagamento" na tela de criação/edição de pedidos (Cotação), baseada na configuração da Natureza de Operação selecionada.

Comportamento: - Quando a Natureza de Operação NÃO possui a flag SolicitarFormaPagamento habilitada → a seção "Forma de Pagamento" é ocultada (incluindo o botão que a expande) - Quando a Natureza de Operação possui a flag SolicitarFormaPagamento habilitada → a seção "Forma de Pagamento" é exibida normalmente

Contexto e Motivação

Problema Anterior

Antes desta implementação, a seção "Forma de Pagamento" era exibida para todas as naturezas de operação, independentemente da configuração. Quando uma natureza não requeria forma de pagamento, o sistema apenas desabilitava alguns campos, mas mantinha a seção visível, causando:

📊 Confusão visual: Vendedores visualizavam seções desnecessárias
⏱️ Perda de tempo: Usuários tentavam preencher campos que não eram relevantes
❌ Experiência inconsistente: Algumas seções eram ocultadas condicionalmente, outras não

Solicitação do Cliente

O cliente Nelmetais solicitou especificamente (Ticket NH-150) que a seção de Forma de Pagamento fosse completamente removida da interface quando a Natureza de Operação não solicitasse esse tipo de informação.

Justificativa do cliente:

"Para evitar que o vendedor informe dados desnecessários e ter uma interface mais limpa e objetiva."

Benefícios da Implementação

✅ Interface mais limpa e contextual ✅ Redução de erros operacionais ✅ Melhor experiência do usuário (UX) ✅ Consistência com outras seções condicionais do sistema ✅ Alinhamento com expectativas do cliente

Comportamento Implementado

Cenário 1: Natureza de Operação COM Solicitação de Forma de Pagamento

Exemplo: "Vendas de Produto", "Vendas de Matéria Prima", "Vendas do Imobilizado"

Comportamento: 1. ✅ Botão " Forma de Pagamento" é exibido 2. ✅ Seção com campos de forma de pagamento é exibida 3. ✅ Campos estão habilitados e podem ser preenchidos 4. ✅ Usuário pode expandir/colapsar a seção normalmente

Screenshot conceitual:

┌─────────────────────────────────────────┐
│  Natureza da Operação                   │
│  [Vendas de Produto          ▼]         │
├─────────────────────────────────────────┤
│  ▼ Forma de Pagamento    <-- VISÍVEL    │
│  ┌───────────────────────────────────┐  │
│  │ Momento de Pagamento:             │  │
│  │ ○ Antecipado ○ À Vista ○ À Prazo │  │
│  │ Tipo: [Selecione...        ▼]    │  │
│  │ ...                               │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Cenário 2: Natureza de Operação SEM Solicitação de Forma de Pagamento

Exemplo: "Transferência Estoque", "Transferência Venda", "Remessa de Embalagem"

Comportamento: 1. ❌ Botão " Forma de Pagamento" é ocultado 2. ❌ Seção com campos de forma de pagamento é ocultada 3. ✅ Interface fica mais limpa, sem elementos desnecessários

Screenshot conceitual:

┌─────────────────────────────────────────┐
│  Natureza da Operação                   │
│  [Transferência Estoque     ▼]          │
├─────────────────────────────────────────┤
│  (Seção Forma de Pagamento OCULTA)      │
│                                          │
│  ▼ Observação Pedido                    │
│  ...                                     │
└─────────────────────────────────────────┘

Cenário 3: Alternância Dinâmica

Comportamento: Ao mudar a Natureza de Operação, a visibilidade da seção é atualizada instantaneamente via JavaScript, sem necessidade de recarregar a página.

Fluxo: 1. Usuário seleciona "Vendas de Produto" → Seção aparece 2. Usuário muda para "Transferência Estoque" → Seção desaparece 3. Usuário volta para "Vendas de Produto" → Seção reaparece

Detalhes Técnicos

Propriedade de Controle

Entidade: NaturezaOperacao (Nelmetais.SGE.Business.Models.Cadastros) Propriedade: bool SolicitarFormaPagamento

Esta propriedade é configurada no cadastro de Naturezas de Operação e determina se a forma de pagamento deve ser solicitada ao criar/editar pedidos.

Endpoint AJAX

URL: /comercial/pedido/buscar-natureza-da-operacao Método: GET Parâmetro: naturezaOperacaoId (int)

Resposta (JSON):

{
  "id": 24,
  "codigo": "TRANSF_EST",
  "descricao": "Transferencia Estoque",
  "solicitarFormaPagamento": false,
  "solicitarDestinatario": true,
  "solicitarTransportador": false,
  ...
}

Implementação JavaScript

Arquivo: src/Nelmetais.SGE.WebApp/Areas/Comercial/Views/Pedido/Shared/_ValidationScriptsPedidoPartial.cshtml

Função modificada: configurarNaturezaOperacao(naturezaOperacao) (linhas 163-179)

Código implementado:

if (naturezaOperacao.solicitarFormaPagamento) {
    // Exibir botão e seção quando solicitado
    $('#mostrarOcultarAgrupamentoFormaPagamento').show();
    $('#agrupamentoFormaPagamento').show();

    // Habilitar campo tipo forma de pagamento
    $('#PedidoFormaPagamento_TipoFormaPagamentoId').prop('disabled', false);
    $('#PedidoFormaPagamento_TipoFormaPagamentoId').trigger('change');
} else {
    // Ocultar botão e seção quando NÃO solicitado
    $('#mostrarOcultarAgrupamentoFormaPagamento').hide();
    $('#agrupamentoFormaPagamento').hide();

    // Desabilitar e limpar campo tipo forma de pagamento
    $('#PedidoFormaPagamento_TipoFormaPagamentoId').prop('disabled', true);
    $('#PedidoFormaPagamento_TipoFormaPagamentoId').prop('selectedIndex', 0);
}

Elementos HTML Controlados

Botão de expansão da seção:
ID: #mostrarOcultarAgrupamentoFormaPagamento
Classe: btn btn-link btn-lg
Controla o collapse da seção
Seção de forma de pagamento:
ID: #agrupamentoFormaPagamento
Classes: collapse show (quando expandida)
Contém todos os campos relacionados a forma de pagamento

Eventos

Trigger: Evento change no select #NaturezaOperacaoId

Fluxo de execução: 1. Usuário seleciona uma natureza no dropdown 2. Evento change dispara função buscarNaturezaOperacao() 3. AJAX busca dados da natureza no backend 4. Função configurarNaturezaOperacao(naturezaOperacao) é chamada 5. JavaScript oculta/exibe botão e seção baseado em solicitarFormaPagamento

Retrocompatibilidade

✅ Mantido: Comportamento existente de desabilitar o campo PedidoFormaPagamento_TipoFormaPagamentoId ✅ Adicionado: Ocultação da seção completa (comportamento novo) ✅ Sem breaking changes: Toda lógica existente foi preservada

Como Testar

Pré-requisitos

Aplicação rodando em http://localhost:8000
Usuário com permissão para criar/editar pedidos no módulo Comercial
Naturezas de operação configuradas no banco de dados

Teste Manual - Passo a Passo

Teste 1: Natureza que SOLICITA forma de pagamento

Acessar a tela:
URL: http://localhost:8000/comercial/adicionar-pedido?tipo=Cotacao
Fazer login se necessário
Selecionar natureza que solicita:
No campo "Natureza da Operação", selecione uma das opções:
- "Vendas de Produto"
- "Vendas de Matéria Prima"
- "Vendas do Imobilizado"
Validar comportamento:
✅ Botão " Forma de Pagamento" deve estar VISÍVEL
✅ Seção "Forma de Pagamento" deve estar VISÍVEL (pode estar expandida ou colapsada)
✅ Campos dentro da seção devem estar HABILITADOS

Teste 2: Natureza que NÃO solicita forma de pagamento

Selecionar natureza que NÃO solicita:
No campo "Natureza da Operação", selecione uma das opções:
- "Transferência Estoque"
- "Transferência Venda"
- "Remessa de Embalagem"
Validar comportamento:
❌ Botão " Forma de Pagamento" deve estar OCULTO (não aparece na lista)
❌ Seção "Forma de Pagamento" deve estar OCULTA (não aparece na tela)

Teste 3: Alternância dinâmica

Testar transição de solicitado → não solicitado:
Selecione "Vendas de Produto" (seção aparece)
Mude para "Transferência Estoque" (seção desaparece)
Validar: Transição deve ser instantânea
Testar transição de não solicitado → solicitado:
Selecione "Transferência Estoque" (seção oculta)
Mude para "Vendas de Produto" (seção aparece)
Validar: Transição deve ser instantânea

Teste 4: Comportamento no carregamento da página

Carregar página com natureza pré-selecionada:
Editar um pedido existente que usa "Transferência Estoque"
Validar: Seção deve estar oculta desde o carregamento inicial

Naturezas de Teste Recomendadas

ID	Descrição	SolicitarFormaPagamento	Resultado Esperado
16	Vendas do imobilizado	✅ TRUE	Seção VISÍVEL
20	Vendas de Matéria Prima	✅ TRUE	Seção VISÍVEL
23	Vendas de Produto	✅ TRUE	Seção VISÍVEL
17	Remessa de Embalagem	❌ FALSE	Seção OCULTA
24	Transferência Estoque	❌ FALSE	Seção OCULTA
25	Transferência Venda	❌ FALSE	Seção OCULTA

Teste Automatizado (Conceitual)

Embora não tenhamos testes automatizados JavaScript no projeto, um teste Selenium/Playwright poderia ser:

// Pseudocódigo de teste E2E
test('Deve ocultar seção de Forma de Pagamento quando natureza não solicita', async () => {
  // Arrange
  await page.goto('http://localhost:8000/comercial/adicionar-pedido?tipo=Cotacao');
  await page.login('admin@nelmetais.com.br', 'Nelmetais*123');

  // Act
  await page.selectOption('#NaturezaOperacaoId', { label: 'Transferência Estoque' });

  // Assert
  await expect(page.locator('#mostrarOcultarAgrupamentoFormaPagamento')).toBeHidden();
  await expect(page.locator('#agrupamentoFormaPagamento')).toBeHidden();
});

test('Deve exibir seção de Forma de Pagamento quando natureza solicita', async () => {
  // Arrange
  await page.goto('http://localhost:8000/comercial/adicionar-pedido?tipo=Cotacao');
  await page.login('admin@nelmetais.com.br', 'Nelmetais*123');

  // Act
  await page.selectOption('#NaturezaOperacaoId', { label: 'Vendas de Produto' });

  // Assert
  await expect(page.locator('#mostrarOcultarAgrupamentoFormaPagamento')).toBeVisible();
  await expect(page.locator('#agrupamentoFormaPagamento')).toBeVisible();
});

Impacto no Sistema

Áreas Afetadas

✅ Módulo Comercial: - Tela: "Adicionar Pedido" (todos os tipos: Cotação, Pedido, etc.) - Tela: "Editar Pedido" - Partial: _ValidationScriptsPedidoPartial.cshtml

❌ Não afetadas: - Outros módulos (Financeiro, Faturamento, etc.) - Backend/Business logic (sem mudanças) - Banco de dados (sem mudanças) - APIs REST (sem mudanças)

Compatibilidade

✅ Retrocompatibilidade garantida: - Pedidos criados antes da mudança continuam funcionando - Lógica existente de desabilitar campos foi mantida - Nenhuma quebra de contrato ou API

Performance

📊 Impacto mínimo: - Operações JavaScript .show() / .hide() são extremamente rápidas (<1ms) - Sem requisições AJAX adicionais - Sem alteração no tempo de carregamento da página

Segurança

🔒 Sem impacto de segurança: - Mudança apenas visual (frontend) - Validações backend permanecem inalteradas - Dados não são expostos ou ocultados de forma insegura

Arquivos Modificados

JavaScript / View Razor

Arquivo:

src/Nelmetais.SGE.WebApp/Areas/Comercial/Views/Pedido/Shared/_ValidationScriptsPedidoPartial.cshtml

Linhas modificadas: 163-179

Tipo de mudança: - ➕ Adicionado: 4 linhas (2x .show(), 2x .hide()) - 📝 Mantido: Toda lógica existente

Diff conceitual:

  if (naturezaOperacao.solicitarFormaPagamento) {
+     $('#mostrarOcultarAgrupamentoFormaPagamento').show();
+     $('#agrupamentoFormaPagamento').show();
+
      $('#PedidoFormaPagamento_TipoFormaPagamentoId').prop('disabled', false);
      $('#PedidoFormaPagamento_TipoFormaPagamentoId').trigger('change');
  } else {
+     $('#mostrarOcultarAgrupamentoFormaPagamento').hide();
+     $('#agrupamentoFormaPagamento').hide();
+
      $('#PedidoFormaPagamento_TipoFormaPagamentoId').prop('disabled', true);
      $('#PedidoFormaPagamento_TipoFormaPagamentoId').prop('selectedIndex', 0);
  }

Documentação

Novos arquivos: - .tasks/TASK-1731593947-forma-pagamento-config.md (Especificação TDD) - .tasks/exploration-notes-NH-150.md (Notas de exploração E2E) - docs/FORMA-PAGAMENTO-CONDICIONAL-NH-150.md (Este documento)

Requisitos Atendidos

Requisitos Funcionais

ID	Descrição	Status
RF01	Ocultar botão de Forma de Pagamento quando não solicitado	✅ Implementado
RF02	Ocultar seção de Forma de Pagamento quando não solicitado	✅ Implementado
RF03	Exibir botão de Forma de Pagamento quando solicitado	✅ Implementado
RF04	Exibir seção de Forma de Pagamento quando solicitado	✅ Implementado
RF05	Alternar visibilidade ao trocar Natureza de Operação dinamicamente	✅ Implementado

Regras de Negócio

ID	Descrição	Status
RN01	Propriedade `SolicitarFormaPagamento` controla visibilidade	✅ Implementado
RN02	Comportamento aplicado ao carregar página	✅ Implementado
RN03	Mantém comportamento de desabilitar campo `TipoFormaPagamentoId`	✅ Implementado
RN04	Colapso da seção não afeta visibilidade do botão	✅ Implementado

Critérios de Aceite

ID	Descrição	Status
CA01	Quando `SolicitarFormaPagamento = false`, botão "Forma de Pagamento" fica oculto	✅ Atendido
CA02	Quando `SolicitarFormaPagamento = false`, seção `#agrupamentoFormaPagamento` fica oculta	✅ Atendido
CA03	Quando `SolicitarFormaPagamento = true`, botão "Forma de Pagamento" fica visível	✅ Atendido
CA04	Quando `SolicitarFormaPagamento = true`, seção `#agrupamentoFormaPagamento` fica visível	✅ Atendido
CA05	Comportamento funciona ao carregar página e ao trocar natureza dinamicamente	✅ Atendido
CA06	Se seção estiver expandida e natureza trocar para não-solicitante, seção é ocultada	✅ Atendido

Referências

Links Úteis

Jira Issue: NH-150 - Carteira de Venda / Todas as Naturezas de Operações - Configuração de Forma de Pagamento
Branch Git: feature/forma-pagamento-config-NH-150
Especificação TDD: .tasks/TASK-1731593947-forma-pagamento-config.md
Notas de Exploração E2E: .tasks/exploration-notes-NH-150.md

Documentos Relacionados

docs/OCULTACAO-CAMPOS-ITEM-TERCEIRO.md (padrão similar de ocultação condicional)
docs/POLITICA_VENDA_NATUREZA_OPERACAO.md (configuração de naturezas)

Contatos

Desenvolvedor: Claude Code + Bruno Martins
Data de Implementação: 2025-11-14
Cliente: Nelmetais
Solicitante: Pamela Silva Filomeno (via Jira)

Notas Adicionais

Melhorias Futuras

💡 Sugestões para próximas iterações:

Função helper reutilizável:

function toggleSecaoCondicional(selectorBotao, selectorSecao, exibir) {
    $(selectorBotao).toggle(exibir);
    $(selectorSecao).toggle(exibir);
}

// Uso
toggleSecaoCondicional(
    '#mostrarOcultarAgrupamentoFormaPagamento',
    '#agrupamentoFormaPagamento',
    naturezaOperacao.solicitarFormaPagamento
);

Aplicar mesmo padrão em outras seções: Várias seções do pedido são condicionais. Podemos padronizar usando o mesmo approach.
Testes automatizados: Implementar testes E2E com Playwright/Selenium para validar automaticamente.
Animação suave: Adicionar efeito fade ao ocultar/exibir para melhor UX:
```
$('#elemento').fadeOut(200); // ou .fadeIn(200)
```

Histórico de Mudanças

Data	Versão	Alteração	Autor
2025-11-14	1.0	Implementação inicial da funcionalidade	Claude Code + Bruno Martins

Última atualização: 2025-11-14 Versão do documento: 1.0 Status: ✅ Implementado e documentado