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.

7.1. Trava de edição pós-aprovação ✅ Novo — set/2026

Entregue no ciclo de setembro/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

Orçamento aprovado não pode mais ser editado: depois da aprovação (pelo cliente ou pela assistência), a edição do orçamento fica bloqueada — isso garante que o valor aprovado pelo paciente é exatamente o que será executado e faturado.
Botão "Abrir Proposta" desabilitado: no orçamento aprovado, o botão "Abrir Proposta" fica desabilitado, impedindo reabrir a proposta de um orçamento já fechado com o paciente.
Cópia de documentos também na edição: os documentos anexados ao orçamento passam a ser copiados para o agendamento também quando o orçamento é editado — antes isso só acontecia na criação, e anexos incluídos depois não chegavam ao agendamento.

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

✅ Novo — ago/2026 O "nível de desconto" foi renomeado para "nível de alçada" (#557) e as aprovações por nível de alçada foram entregues (épico #571): a solicitação de aprovação notifica todos os usuários do nível e, quando um responde, a pendência é resolvida para todos (#558). Entregue no ciclo de agosto/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

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`.
Não consigo editar um orçamento aprovado / "Abrir Proposta" está desabilitado	✅ Novo — set/2026 Comportamento correto: orçamento aprovado (cliente ou assistência) fica travado para edição. Se precisar alterar, cancele e crie uma nova versão do orçamento.

✅ 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.

✅ Novo — ago/2026 Entregue no ciclo de agosto/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização:

Visão geral do farol (#435): lista de cruzamentos serviço×convênio e produto×convênio — saiu do "em breve".
Farol ROXO (#545): nova cor para erro de preço (sem custo ou sem receita), com bloqueio.
Farol considera taxas (#550): o farol do orçamento agora considera as taxas no cálculo.
Farol consolidado (#551/#552, épico #570): o farol do agendamento e da autorização passa a ser calculado sobre serviço + produto + taxa.
Crítica de quantidades (#553): a quantidade de produtos no agendamento passa a ser criticada a partir do orçamento/autorização, com totais previstos × agendados nas telas (#554).
Notificação de orçamentos solicitados (#446): com link para ver/aprovar e prazos.

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) — desde ago/2026 o nível chama-se "nível de alçada" (#557) e as aprovações notificam todos do nível, resolvendo para todos quando um responde (épico #571).
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.
Novidades de ago/2026: visão geral do farol/cruzamentos (#435), farol ROXO para erro de preço com bloqueio (#545), farol considerando taxas (#550), farol consolidado serviço+produto+taxa no agendamento e na autorização (#551/#552, épico #570), crítica de quantidades a partir do orçamento/autorização (#553/#554), aprovações por nível de alçada (épico #571) e notificação de orçamentos solicitados com link e prazos (#446).
Novidades de set/2026: orçamento aprovado não pode mais ser editado (trava pós-aprovação), o botão "Abrir Proposta" fica desabilitado no aprovado, e os documentos anexados são copiados para o agendamento também na edição do orçamento (não só na criação).

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. A visão geral de cruzamentos (#435) e o farol roxo de erro de preço (#545) foram entregues em ago/2026, e o farol passou a considerar taxas (#550).