Como funciona a aprovação humana de ações do agente no Clinic Revenue OS

O que acontece entre a IA sugerir algo e essa sugestão virar ação de verdade?

A sugestão nasce no estado "pendente de aprovação" — ela existe como um registro no sistema, mas não dispara nenhuma comunicação ou mudança sozinha. Alguém com a permissão certa precisa revisar.

Só depois dessa revisão a ação muda de estado: aprovada, dispensada (rejeitada) ou, quando o caso permite, executada diretamente. Não existe caminho onde a sugestão pula essa etapa e chega ao paciente sem alguém ter olhado antes.

Quais estados uma ação do agente pode assumir?

O painel mostra a contagem em seis estados: pendente de aprovação, auto-aprovada, aprovada, bloqueada, concluída e dispensada — além de um sétimo, expirada, para ações que passaram do prazo sem decisão.

Essa granularidade existe para o gestor comercial enxergar não só "quantas ações a IA sugeriu", mas onde elas estão paradas — se o gargalo é aprovação, execução ou simplesmente prazo vencido.

Quem pode aprovar, dispensar ou executar uma ação?

As três operações exigem a mesma permissão específica de gestão de ações do agente — não é a mesma permissão de usar a IA no dia a dia. Ter acesso à IA para gerar sugestões não dá automaticamente o poder de aprová-las.

Essa separação existe para que a clínica possa decidir, por papel, quem sugere (recepção, usando IA) e quem decide (gestor ou dono, aprovando) — não precisam ser a mesma pessoa.

Toda sugestão da IA passa por aprovação manual, mesmo as óbvias?

Não. O estado "auto-aprovada" existe justamente para ações de baixo risco, onde exigir aprovação manual seria burocracia sem ganho de segurança real — a diferença fica visível e contada separadamente no painel, não escondida dentro de "aprovada".

Isso mantém o princípio geral do produto (freio humano em ação sensível) sem transformar toda sugestão de IA, até a mais trivial, em um item extra na fila de trabalho da recepção.

É possível duas pessoas aprovarem a mesma ação ao mesmo tempo, por engano?

Não. A transição de estado é atômica com guarda de status — o sistema só aceita a mudança se a ação ainda estiver no estado esperado (por exemplo, "pendente"). Se duas pessoas tentarem aprovar ao mesmo tempo, só uma transição é aceita.

A segunda tentativa recebe um erro específico de conflito de estado, distinto de "ação não encontrada" — o sistema não finge que deu certo quando na verdade a ação já tinha mudado de estado por outra pessoa.

O que fica registrado quando uma ação é aprovada, dispensada ou executada?

Cada uma dessas três operações grava um registro de auditoria: a ação tomada, o tipo de entidade, o id da ação, quem fez (usuário e papel) e quando. Isso não é opcional nem configurável — acontece em toda transição, sempre.

Esse registro alimenta o mesmo painel de auditoria usado para outras operações sensíveis do produto — não é um log paralelo só para IA, é parte da mesma trilha de auditoria da plataforma.

O valor financeiro de uma ação aparece pra qualquer pessoa que veja a fila?

Não necessariamente. O valor total estimado das ações pendentes é mascarado para quem não tem a permissão de ver estimativa financeira — a pessoa vê que existem ações e quantas, mas não o valor em reais, se a clínica decidir restringir o acesso financeiro dessa forma para aquele papel.

Essa é a mesma lógica de mascaramento em duas camadas usada no Modo Dono e no Painel de Dinheiro Vazando: acesso à existência da informação é uma permissão, acesso ao valor financeiro é outra.

Quem pode ver o histórico de auditoria, e é a mesma pessoa que aprova ação?

Não necessariamente. Ver o painel de auditoria exige uma permissão própria, separada da permissão de aprovar/dispensar/executar ação do agente — uma clínica pode dar a alguém (um gestor, um sócio) acesso só de leitura ao histórico, sem poder de decisão sobre as ações.

Essa separação segue o mesmo princípio do resto do produto: quem executa uma operação sensível e quem fiscaliza essa operação não precisam ser a mesma pessoa, nem ter a mesma permissão.

O que significa uma ação do agente ficar "expirada"?

É um estado próprio, diferente de "dispensada" — uma ação expirada não foi rejeitada por decisão de ninguém, ela simplesmente passou do momento em que a sugestão ainda fazia sentido sem que alguém decidisse a tempo.

O painel conta ações expiradas separadamente das dispensadas justamente para o gestor enxergar se o problema é "a IA sugere coisa que a equipe rejeita" ou "a equipe não está revisando a fila a tempo" — são dois problemas diferentes com soluções diferentes.

Esse padrão de estado com guarda de transição é só das ações do agente?

Não. O mesmo princípio aparece no Painel de Dinheiro Vazando: cada perda de receita tem status controlado (aberta, em andamento, resolvida, arquivada ou dispensada), e o Modo Dono só soma no total o que está aberto ou em andamento.

Isso não é coincidência de nomenclatura — é uma convenção deliberada do produto: qualquer coisa que representa dinheiro ou decisão sensível tem um ciclo de vida explícito, não um campo booleano solto de "resolvido sim/não".

Isso serve pra alguma coisa além de controle interno, tipo uma auditoria externa?

Serve. Como cada transição fica registrada com ator, papel, ação e timestamp, é possível reconstruir depois — para um auditor, para o próprio dono da clínica, ou em caso de questionamento — quem tomou qual decisão sobre qual sugestão de IA.

Isso é relevante especificamente para saúde, onde "a IA decidiu sozinha" não pode ser a resposta para nenhuma pergunta sobre uma ação que afetou um paciente.

Vale o mesmo raciocínio para o painel administrativo da plataforma: acesso entre clínicas diferentes (cross-tenant), quando existe, passa por funções guardadas e é auditado — não é um atalho silencioso fora da trilha normal de registro.