Lição: Agenda e Agendamento

Esta lição prepara você para operar o módulo de Agenda do Sistema Rabi do zero: criar e confirmar agendamentos, acolher pacientes, gerar orçamentos e autorizações, bloquear horários e usar fila de espera e encaixe. Ao final, você deve conseguir executar as tarefas do dia a dia da recepção sem depender de ajuda.

🟢 Tudo nesta seção principal está EM PRODUÇÃO — pode usar como uso real do sistema. As regras marcadas como 🟠 Planejado (roadmap) ao final ainda NÃO estão disponíveis.

1. Objetivo do módulo e onde fica

O módulo de Agendamento é a agenda médica central da clínica. Nele, a recepção e os profissionais gerenciam consultas, exames e procedimentos, controlando o fluxo do paciente da marcação até o atendimento.

Menu: Agendamento (na barra lateral do sistema).
Rota principal: /portal/agenda
URL completa (produção): http://app.rabisistemas.com.br/portal/agenda

1.1. Telas do módulo

Tela	Rota	Para que serve
Agenda principal	`/portal/agenda`	Visualizar e criar agendamentos
Novo agendamento	`/portal/agenda/criar`	Formulário de marcação
Editar agendamento	`/portal/agenda/:id/editar`	Alterar um agendamento existente
Confirmação	`/portal/agenda/confirmacao`	Confirmar consultas em massa
Acolhimento	`/portal/agenda/acolhimento`	Registrar chegada do paciente (recepção)
Check-in	`/portal/agenda/acolhimento/:id/checkin`	Confirmar chegada e enviar à fila
Orçamentos	`/portal/agenda/orcamento`	Criar e gerenciar orçamentos
Bloqueio de agenda	`/portal/agenda/bloqueio`	Impedir agendamento em períodos
Autorizações	`/portal/agenda/autorizacao`	Solicitar e registrar autorização de convênio

2. Visualização da agenda

A agenda principla organiza os agendamentos de forma visual. Você pode alternar os modos de visualização e filtrar o que aparece.

2.1. Modos de visualização

Por dia — todos os agendamentos do dia corrente, por horário.
Por semana — agendamentos distribuídos nos dias da semana.

2.2. Filtros disponíveis

Profissional — filtra por médico, fisioterapeuta ou outro colaborador.
Especialidade — exibe apenas uma especialidade.
Local do agendamento — filtra por sala, consultório ou unidade.

Use as setas de navegação para avançar/recuar dias e semanas sem selecionar datas manualmente.

3. Status do agendamento

Cada agendamento tem um status, identificado por cor na grade. Conhecer os status é essencial: a prova cobra o significado de cada um.

Status	Cor	Significado
Aguardando	Cinza	Criado, aguardando confirmação do paciente ou da clínica. É o status inicial ao salvar.
Confirmado	Verde	Paciente/clínica confirmou. O atendimento está garantido.
Cancelado	Vermelho	Consulta cancelada. O horário volta a ficar livre.
Atendido	Azul	Atendimento concluído pelo profissional.
Em Atendimento	Laranja	Paciente sendo atendido no momento.
Acolhido	Roxo	Check-in feito. Paciente na fila aguardando ser chamado.
Remarcado	Amarelo	Transferido para nova data/horário.

✅ Novo — jul/2026 O agendamento remarcado passou a usar a cor do status normal na grade (#457). Entregue no ciclo de julho/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

🟠 Planejado (roadmap): o status "Pendente" (issue #375) — usado enquanto faltar orçamento/autorização — ainda NÃO existe em produção. Não escolha "Pendente" como status atual em prova.

4. Criar um novo agendamento (passo a passo)

Acesse /portal/agenda/criar ou clique em "Novo Agendamento" na agenda.

4.1. Campos de data e horário

Campo	Obrigatório?	Validação / Observação
Data	Obrigatório	Formato dd/mm/aaaa
Hora início	Obrigatório	Horário de início da consulta/procedimento
Hora fim	Obrigatório	Horário de término previsto

4.2. Paciente e dados do atendimento

Campo	Obrigatório?	Validação / Observação
Paciente	Obrigatório	Digite nome ou CPF; o sistema sugere em tempo real. Selecione na lista.
Convênio	Opcional	Preenchido automaticamente com o convênio do cadastro do paciente, se houver.
Plano	Opcional	Plano do convênio selecionado.
Especialidade	Obrigatório	Ex.: Cardiologia, Fisioterapia.
Profissional / Colaborador	Obrigatório	Responsável pelo atendimento.
Local do Agendamento	Opcional	Sala, consultório ou unidade.
Equipamentos	Opcional	Equipamentos necessários ao procedimento.
Tipo	Obrigatório	Normal (horário regular) ou Encaixe (fora do horário normal).
Guia Operadora	Opcional	Número da guia de autorização da operadora de convênio.
Observação	Opcional	Informações adicionais.

4.3. Sequência completa

Abra o formulário: "Novo Agendamento" ou /portal/agenda/criar.
Defina Data, Hora início e Hora fim.
Busque e selecione o Paciente por nome ou CPF. Se não estiver cadastrado, cadastre-o antes no módulo de Pacientes.
Informe Especialidade, Profissional e Tipo (Normal/Encaixe); complete convênio/plano/local/equipamentos se aplicável.
Confira a Lista de Contatos do paciente exibida no formulário.
Se necessário, anexe arquivos em Documentos / Anexos (pedidos, guias, laudos).
Clique em "Salvar". O agendamento aparece na agenda com status Aguardando.

4.4. Orçamento e autorização obrigatórios (parametrizável) ✅ Novo — jul/2026

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

Orçamento obrigatório (#373): conforme parametrização, o agendamento passa a exigir orçamento.
Autorização obrigatória (#374): conforme parametrização, o agendamento passa a exigir autorização do convênio.

4.5. Bloqueio e prazo de retorno ✅ Novo — jul/2026

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

Bloqueio de retorno (#414): o sistema controla o retorno do paciente conforme o prazo configurado.
Prazo de retorno configurável (#415): o prazo de retorno pode ser configurado por convênio e por serviço.

4.6. Guard de edição não salva ✅ Novo — jul/2026

Entregue no ciclo de julho/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização. Ao sair de uma tela com alterações não salvas, o sistema pede confirmação antes de descartar (guard de edição, #401/#404) — evita perder o preenchimento do formulário por clique acidental.

5. Confirmar agendamentos

A tela de Confirmação (/portal/agenda/confirmacao) permite confirmar consultas rapidamente, sem abrir cada uma.

Acesse Agendamento › Confirmação ou /portal/agenda/confirmacao.
A tela lista os agendamentos com status Aguardando.
Use os filtros de data, profissional e especialidade para localizar.
Marque as caixas de seleção de um ou mais agendamentos.
Clique em "Confirmar". O status muda para Confirmado.

Também dá para confirmar individualmente pela grade ou pela edição (/portal/agenda/:id/editar). Ao confirmar, o sistema pode gerar um lançamento financeiro automático, conforme a configuração da clínica.

6. Acolhimento e check-in

O Acolhimento (/portal/agenda/acolhimento) é o registro da chegada do paciente. Após o check-in, ele entra na fila de atendimento do profissional.

6.1. Fluxo completo

O paciente chega e se apresenta na recepção.
A recepcionista acessa /portal/agenda/acolhimento.
Localiza o paciente na lista do dia (busca por nome ou CPF).
Clica no agendamento para abrir o check-in (/portal/agenda/acolhimento/:id/checkin).
Confere os dados e clica em "Realizar Check-in".
O status muda para Acolhido e o paciente entra na fila do profissional.
O profissional chama o próximo da fila; o status passa a Em Atendimento.

A tela de acolhimento exibe, por agendamento do dia: nome do paciente, horário, profissional e especialidade, status atual e convênio.

7. Orçamentos

A tela de Orçamentos (/portal/agenda/orcamento) permite orçar procedimentos antes de virarem agendamento.

7.1. Criar

Acesse Agendamento › Orçamentos ou /portal/agenda/orcamento.
Clique em "Novo Orçamento" (/portal/agenda/orcamento/criar).
Selecione o paciente e informe os procedimentos.
Informe valores (formato R$ 1.234,56) e convênio, se aplicável.
Salve. O orçamento fica listado com status pendente.

7.2. Reabrir e converter

Reabrir cancelado: localize na lista, clique em "Reabrir", ajuste e salve.
Converter em agendamento: localize o orçamento aprovado, clique em "Converter em Agendamento"; o formulário abre com os dados preenchidos. Defina data, horário e profissional e salve.

8. Bloqueio de agenda

O Bloqueio (/portal/agenda/bloqueio) marca horários como indisponíveis, impedindo novos agendamentos. Use para feriados, férias/folga do profissional, reuniões e manutenção de equipamento.

Acesse Agendamento › Bloqueio de Agenda.
Clique em "Novo Bloqueio".
Selecione o profissional e o local a bloquear.
Informe data, horário de início e horário de fim.
Adicione uma descrição/motivo (ex.: "Reunião", "Folga").
Salve. O período aparece na agenda com indicação de indisponibilidade.

⚠️ Atenção: o bloqueio impede novos agendamentos, mas não cancela automaticamente os já existentes no período. Verifique antes de bloquear.

9. Autorizações de convênio

A tela de Autorizações (/portal/agenda/autorizacao) registra pedidos de autorização de procedimentos junto às operadoras.

Acesse Agendamento › Autorizações (/portal/agenda/autorizacao).
Clique em "Nova Autorização" (/portal/agenda/autorizacao/criar).
Selecione o paciente e o convênio.
Informe os procedimentos (código TUSS, descrição) e o profissional solicitante.
Registre o número da autorização quando a operadora fornecer.
Salve.

Depois, registre o número no campo "Guia Operadora" do agendamento. Autorizações registradas são usadas automaticamente no faturamento de guias.

10. Encaixe

Encaixe é um agendamento criado fora do horário regular, para urgências ou retornos rápidos. Para criar: em /portal/agenda/criar, no campo Tipo, selecione "Encaixe" (em vez de "Normal"), preencha os demais campos e salve. Encaixes recebem marcação visual diferenciada na grade.

✅ Novo — jul/2026 O encaixe agora aparece na hora na grade (correção de cache, #460). Entregue no ciclo de julho/2026; se ainda não apareceu no seu ambiente, chega na próxima atualização.

11. Recursos avançados em produção

Recurso	O que faz	Issue
Agendamento em série (repetição)	Cria uma série (semanal, quinzenal, mensal) numa só operação — útil para tratamentos longos. Ajuste fino ainda em desenvolvimento (#214).	#337
Bloqueio de agenda	Bloqueios totais (feriados, férias, manutenção); impede agendamento no período.	—
Encaixe manual	Encaixe em horário teoricamente cheio, autorizado pelo responsável.	—
Acolhimento (check-in)	Recepção registra chegada; paciente vai à fila do profissional.	—

11.1. Novidades de julho/2026 ✅ Novo — jul/2026

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

Limite de agendamentos por convênio na grade (#476) — a grade respeita o limite configurado por convênio.
Grade marca todos os convênios do médico (#461) — a visualização passa a sinalizar todos os convênios atendidos pelo profissional.
Correção "equipamentos insuficientes" (#458) — mensagem indevida ao agendar foi corrigida.
Campo expande (#501) — campos de texto do formulário se expandem para facilitar a digitação.
Serviço online: itens não habilitados ficam ocultos (#426), listas por contexto (#427), correção da tela de colaborador (#428) e ativação por SMS (#389).
Setas próximo/anterior no topo das telas (#459) e proteção anti-duplo-clique (idempotência, #408).

12. Integrações do módulo

Módulo	Como funciona a integração
Pacientes	O agendamento é vinculado ao cadastro; convênio, contato e carteira são herdados automaticamente.
Atendimento/Prontuário	O check-in cria a fila; o prontuário é aberto a partir do agendamento.
Financeiro	Ao confirmar, pode gerar lançamento financeiro conforme a configuração.
Faturamento	Agendamentos de convênio geram guias; o número de autorização é usado no faturamento.

Fluxo completo do paciente: Agendamento → Acolhimento → Prontuário → Financeiro → Faturamento.

13. Permissões necessárias

O modelo atual é papel (Role) + 4 ações fixas por módulo: VIEW, CREATE, UPDATE, DELETE. Para o módulo Agendamento (que cobre Agenda, Acolhimento, Confirmação, Bloqueio, Orçamento e Autorização):

Ação do usuário	Permissão necessária
Abrir/visualizar a agenda	VIEW
Criar agendamento, orçamento, autorização, bloqueio	CREATE
Editar / confirmar / remarcar / fazer check-in	UPDATE
Excluir agendamento	DELETE

Níveis: NONE < VIEW < CREATE < UPDATE < DELETE.

🟠 Planejado (roadmap): permissões granulares / refactor RBAC (#395) ainda NÃO estão em produção. Hoje as permissões são só os 4 níveis por módulo.

14. Erros comuns e como resolver

Situação	Causa provável	Solução
Paciente não aparece na busca	Ainda não cadastrado ou nome/CPF digitado errado	Cadastre no módulo Pacientes antes de agendar; confira a grafia/CPF.
Não consigo agendar em um horário	Horário bloqueado (feriado, folga, manutenção)	Verifique bloqueios; se justificado, use Encaixe autorizado pelo responsável.
Salvei mas não achei o agendamento	Filtros da agenda ativos (profissional/especialidade/data)	Limpe os filtros ou selecione o profissional/data corretos.
Convênio não trouxe automaticamente	Paciente sem convênio no cadastro	Selecione o convênio manualmente no formulário ou complete o cadastro do paciente.
Bloqueei mas há consultas no período	Bloqueio não cancela agendamentos existentes	Cancele/remarque manualmente as consultas afetadas.

15. 🟠 Planejado (roadmap) — ainda NÃO disponível

As regras abaixo foram levantadas na reunião de 18/06/2026 e estão no roadmap. NÃO fazem parte do comportamento atual do sistema.

Regra planejada	O que vai mudar	Issue
Status "Pendente"	Status intermediário enquanto faltar orçamento/autorização.	#375
Bloqueio de serviço por convênio	Convênio bloqueia serviços específicos.	#376
Avisos visuais na grade	Badges para colaborador indisponível, equipamento em manutenção, bloqueio total.	#377
Fila de espera	Paciente entra na fila quando o horário está cheio.	#405

✅ Novo — jul/2026 Saíram deste roadmap por terem sido entregues em julho/2026: orçamento obrigatório (#373), autorização obrigatória (#374), bloqueio/prazo de retorno (#414/#415) e guard de edição (#401/#404) — ver seções 4.4 a 4.6. O farol de resultado (#390/#434) também foi entregue — ver a lição de Orçamento.

Pontos-chave

A agenda fica em /portal/agenda; criar em /portal/agenda/criar.
Ao salvar, o agendamento nasce com status Aguardando; após confirmar vira Confirmado; após check-in vira Acolhido.
Campos obrigatórios do agendamento: Data, Hora início, Hora fim, Paciente, Especialidade, Profissional e Tipo. Convênio, plano, local, equipamentos, guia e observação são opcionais.
Datas em dd/mm/aaaa; valores em R$ 1.234,56.
Bloqueio impede novos agendamentos, mas não cancela os existentes.
Repetição (#337), bloqueio de agenda, encaixe manual e acolhimento estão em produção. Novidades de jul/2026: obrigatoriedades de orçamento/autorização (#373/#374), bloqueio/prazo de retorno (#414/#415) e guard de edição (#401). Seguem roadmap: status "Pendente" (#375), bloqueio de serviço por convênio (#376), avisos visuais na grade (#377) e fila de espera (#405).
Permissões: Role + VIEW/CREATE/UPDATE/DELETE por módulo.

O que a prova vai cobrar

Identificar o status inicial de um agendamento recém-criado (Aguardando) e a sequência de status até o atendimento.
Reconhecer quais campos do novo agendamento são obrigatórios e quais são opcionais.
Diferenciar as telas (Confirmação, Acolhimento, Bloqueio, Orçamento, Autorização) e suas rotas/finalidades.
Saber que o bloqueio de agenda não cancela consultas já marcadas.
Distinguir o que está em produção do que é roadmap: as obrigatoriedades de orçamento (#373) e autorização (#374) foram entregues em jul/2026; apenas o status "Pendente" (#375) segue planejado.