Lição: Orçamento de Procedimentos

🟢 Em produção. O módulo de Orçamento está disponível e em uso real. Ele substitui o antigo processo manual de planilha e, ao aprovar, gera o agendamento automaticamente. A HU do módulo (#398) foi concluída em jul/2026.

1. Objetivo do módulo e onde fica

O módulo de Orçamento serve para montar, enviar e acompanhar orçamentos de procedimentos eletivos: cirurgias, planos de tratamento e atendimentos particulares. Você monta o orçamento com serviços, produtos consumidos, taxas e equipamentos; o paciente recebe um PDF; ao aprovar, o sistema converte o orçamento em agendamento e abre o fluxo financeiro — sem redigitar nada.

Onde fica (menu / rota): Agenda → Orçamento.

Tela	Rota `/portal/...`	Para que serve
Lista de orçamentos	`/portal/agenda/orcamento`	Consultar e filtrar orçamentos
Novo orçamento	`/portal/agenda/orcamento/criar`	Criar orçamento do zero
Ver / editar orçamento	`/portal/agenda/orcamento/:id`	Detalhar, editar, enviar, aprovar
Reabrir cancelado	`/portal/agenda/orcamento/:idOrcamentoCancelado/reabrir`	Voltar um orçamento cancelado ao fluxo

2. Como um orçamento é estruturado

Um orçamento tem um cabeçalho (paciente, local, profissional responsável, status, observação) e uma lista de Serviços. Cada serviço pode conter:

Produtos consumidos — ampolas, gases, materiais descartáveis etc.
Taxas — taxa de sala cirúrgica, taxa de equipamento etc.
Equipamentos utilizados — com grade de tempo de uso.
Profissional responsável pelo serviço.

Ou seja, o valor total do orçamento é a soma dos serviços, e cada serviço soma seus produtos, taxas e equipamentos.

3. Campos do orçamento

Os campos abaixo aparecem ao criar/editar (OrcamentoForm.tsx). Datas seguem o formato dd/mm/aaaa e valores em R$ 1.234,56.

Campo	Obrigatório?	Validação / observação
Paciente	Sim	Busca por nome ou CPF; o paciente precisa estar cadastrado
Local / Unidade	Sim	Onde o procedimento será realizado
Profissional responsável	Sim	Colaborador que responde pelo orçamento
Serviço (um ou mais)	Sim	Ao menos um serviço; puxa preço da tabela do convênio/tabela interna
Quantidade por serviço	Sim	Número inteiro maior que zero
Valor unitário	Sim (calculado)	Vem da tabela; só é editável com a permissão de override de valor
Produtos consumidos	Opcional	Por serviço; puxa do Estoque
Taxas	Opcional	Por serviço (sala, equipamento)
Equipamentos	Opcional	Por serviço, com tempo de uso
Desconto	Opcional	Validado por nível de permissão do colaborador (ver seção 8)
Observação	Opcional	Texto livre
Validade	Automática	Definida por `ParametrosOrcamento.diasValidos` (padrão 30 dias)

4. Status do orçamento (ciclo de vida)

O status muda conforme o orçamento avança. Decorar essa sequência é essencial.

Status	Significado
`RASCUNHO`	Em criação, ainda não enviado
`AGUARDANDO_APROVACAO`	Enviado ao paciente, aguardando resposta
`APROVADO_CLIENTE`	Paciente aprovou
`REJEITADO_CLIENTE`	Paciente rejeitou (com motivo)
`CONFIRMADO`	Agendamento gerado, fluxo iniciado
`AGENDADO`	Data marcada
`REALIZADO`	Procedimento executado
`CANCELADO`	Cancelado (guarda a `descricaoCancelamento`)
`EXPIRADO`	Validade vencida — marcado automaticamente por cron diário

5. Botões e ações

Ação	O que faz
Salvar	Grava o orçamento como `RASCUNHO`
Enviar ao paciente	Gera o PDF e passa para `AGUARDANDO_APROVACAO`
Aprovar	Registra aprovação do paciente e dispara a criação automática do agendamento
Rejeitar	Marca `REJEITADO_CLIENTE` exigindo motivo
Agendar	Abre a tela de agendamento pré-preenchida (orçamento vira `CONFIRMADO` ao salvar)
Cancelar	Marca `CANCELADO` com descrição do motivo
Reabrir	Traz um orçamento cancelado de volta ao fluxo
Aplicar desconto	Chama a validação de nível de permissão (ver seção 8)

6. Passo a passo — criar e aprovar um orçamento

Vá em Agenda → Orçamento e clique em Novo (/portal/agenda/orcamento/criar).
Busque e selecione o paciente (por nome ou CPF).
Informe local e profissional responsável.
Adicione um ou mais serviços; para cada um, informe a quantidade e, se preciso, os produtos, taxas e equipamentos.
Se houver desconto, aplique — o sistema validará seu nível de permissão.
Clique em Salvar (fica RASCUNHO) e revise o total.
Clique em Enviar ao paciente — gera o PDF e passa para AGUARDANDO_APROVACAO.
Quando o paciente responder, clique em Aprovar (ou Rejeitar). Ao aprovar, o sistema cria o agendamento automaticamente e o orçamento vira CONFIRMADO.
Com o procedimento executado e o atendimento fechado, o orçamento vira REALIZADO.

7. Aprovação vira agendamento (automático)

Ao aprovar (POST /orcamento/:id/aprovar), o sistema cria o agendamento automaticamente e abre o fluxo de atendimento — você não precisa recriar os dados. Sequência da conversão:

Orçamento APROVADO_CLIENTE → botão Agendar.
Sistema abre a tela de agendamento pré-preenchida.
Ao salvar o agendamento, o orçamento vira CONFIRMADO.
Na execução do atendimento, a MovimentacaoFinanceira é vinculada ao OrcamentoServicoMovimentacao.
Ao fechar o atendimento, o orçamento vira REALIZADO.

Orçamentos cancelados podem ser reabertos em /portal/agenda/orcamento/:idOrcamentoCancelado/reabrir.

✅ Novo — jul/2026 O caminho inverso também existe: é possível vincular o orçamento a partir do agendamento (#359). Entregue no ciclo de julho/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

8. Regras de negócio — descontos por nível

Ao aplicar desconto, o sistema chama o validacaoDescontoController, que confere o nível de permissão do colaborador via ParametrosDeDesconto:

Nível	Limite de desconto	Perfil típico
Nível 1	até 5%	Recepcionista
Nível 2	até 10%	Coordenador
Nível 3	até 20%	Gerente
Sem limite	qualquer	Diretor

9. Regras de negócio — validade e expiração

Todo orçamento tem validade em ParametrosOrcamento.diasValidos (padrão 30 dias). Um cron diário marca como EXPIRADO os orçamentos vencidos, automaticamente, sem ação manual. Também há versões: cada alteração relevante (valor ou escopo) gera uma nova versão para o cliente comparar antes de aprovar; o histórico fica preservado.

10. Permissões necessárias

Modelo atual: papel (Role) + ações por módulo. Além das quatro ações padrão, o Orçamento tem ações específicas:

Permissão	Permite
`ORCAMENTO.VIEW`	Consultar orçamentos
`ORCAMENTO.CREATE`	Criar orçamento
`ORCAMENTO.UPDATE`	Editar orçamento
`ORCAMENTO.APROVAR`	Confirmar a aprovação do paciente
`ORCAMENTO.CANCELAR`	Cancelar orçamento
`ORCAMENTO.REABRIR`	Reabrir um cancelado
`ORCAMENTO.OVERRIDE_VALOR`	Lançar valor manual acima da tabela

11. Erros comuns e como resolver

Situação	Como resolver
Não consigo aplicar o desconto desejado	Seu nível de permissão limita o percentual. Peça a um nível superior (Coordenador/Gerente/Diretor) para aplicar.
Orçamento sumiu / ficou EXPIRADO	Passou da validade (padrão 30 dias). Reabra a partir dele ou crie uma nova versão.
Preciso mudar o valor da tabela e o campo está bloqueado	É necessária a permissão `ORCAMENTO.OVERRIDE_VALOR`.
Aprovei mas o agendamento não apareceu	A aprovação gera o agendamento automaticamente; confira em Agenda. O bug de sessões (#386) foi corrigido em jul/2026 — veja a nota abaixo.
Orçamento cancelado por engano	Use Reabrir (`/orcamento/:id/reabrir`), se você tiver `ORCAMENTO.REABRIR`.

✅ Novo — jul/2026 Bug corrigido (#386): a validação sessoesRealizadas < sessoesAutorizadas, que rodava depois de incrementar e podia gerar agendamento além do autorizado, foi corrigida. Entregue no ciclo de julho/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

12. Farol de resultado — ENTREGUE ✅ Novo — jul/2026

Entregue no ciclo de julho/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização. O Farol de resultado 🟢🟡🔴 por convênio/serviço/produto (#390/#434) mostra cores + índice ao calcular o resultado: 🟢 verde segue direto, 🟡 amarelo alerta e 🔴 vermelho BLOQUEIA — a liberação no vermelho exige aprovação de nível superior. Apenas a visão geral/lista de cruzamentos (#435) ainda está em desenvolvimento (Sprint 3).

Pontos-chave

Orçamento fica em Agenda → Orçamento (/portal/agenda/orcamento) e está em produção.
Estrutura: cabeçalho + serviços; cada serviço agrega produtos, taxas e equipamentos.
Ciclo: RASCUNHO → AGUARDANDO_APROVACAO → APROVADO_CLIENTE → CONFIRMADO → AGENDADO → REALIZADO (ou REJEITADO_CLIENTE, CANCELADO, EXPIRADO).
Aprovar cria o agendamento automaticamente — não redigite os dados.
Desconto é validado por nível (5% / 10% / 20% / sem limite).
Validade padrão de 30 dias; cron diário marca EXPIRADO.
Farol de resultado (#390/#434) foi entregue em jul/2026: cores + índice; no 🔴 vermelho o sistema bloqueia e a liberação exige nível superior. Só a visão geral de cruzamentos (#435) segue em desenvolvimento.

O que a prova vai cobrar

A sequência dos status do orçamento e o que cada um significa.
Que a aprovação gera o agendamento automaticamente.
Os limites de desconto por nível de permissão.
Validade padrão (30 dias) e expiração automática por cron.
Saber que o Farol de resultado (#390/#434) foi entregue em jul/2026: cores + índice e bloqueio no vermelho com liberação por nível superior — apenas a visão geral de cruzamentos (#435) segue planejada.