Épico 6 — Seleção de Clínica — Definição (v2.0)

Documentos deste épico: 01 - Definição (v2.0) · 02 - Especificação (v2.0) · 03 - Protótipo (v2.0, código executável em 03 - Protótipo v2.0.html) · 04 - Mapeamento de Banco de Dados (v2.0). Este épico faz parte do documento guarda-chuva Check-in de Usuários.

Nota desta revisão: apenas a Seção 1 (Definição) foi revista nesta versão. As Seções 2, 3 e 4 ainda descrevem a lista de clínicas como uma lista simples, sem o agrupamento por Cliente/Ambiente definido abaixo (RN-CIU-031) — atualização pendente, registrada na lista de pendências ao final.

SEÇÃO 1 — DEFINIÇÃO

Objetivo

Permitir que um profissional autenticado, com acesso a mais de uma clínica, escolha rapidamente em qual clínica quer entrar — mesmo quando essas clínicas pertencem a mais de um Cliente contratante, ou a diferentes Ambientes de trabalho de um mesmo Cliente (RN-CIU-031) — sem precisar entender essa estrutura para escolher certo. Quando há um convite pendente para uma nova clínica, permite aceitar esse convite sem sair da tela, sem repetir a leitura das regras básicas de uso já lidas no primeiro vínculo (RN-CIU-014, em CIU-E3).

Escopo

Dentro do escopo (nesta revisão):

Tela de seleção de clínica, exibida quando o roteamento pós-autenticação (RN-CIU-022, no guarda-chuva) chega a “acesso a mais de uma clínica” ou a “convite pendente + ao menos um vínculo ativo”
Card em destaque para convite pendente, com aceite direto (RN-CIU-025)
Indicação discreta, na lista de clínicas, de que clínicas pertencem ao mesmo Cliente contratante, e de que uma clínica está num Ambiente de testes temporário — sem exigir que o profissional entenda os conceitos de Cliente ou Ambiente para usar a tela (RN-CIU-031)
Ordenação da lista pelas clínicas acessadas mais recentemente pelo profissional, como aproximação de qual ele provavelmente vai escolher agora (RN-CIU-031)

Fora do escopo:

Layout e comportamento das telas de outros épicos do Check-in (E1, E2, E3, E4) — cada um documentado no seu próprio documento
Definição de quais perfis de acesso existem ou como são criados — pertence ao Contexto de Segurança; este épico apenas consome a verificação (RN-CIU-015, redação completa em CIU-E3)
Definição de quais Ambientes de trabalho um Cliente possui, qual deles é o de produção, ou quando um Ambiente de testes deixa de existir — pertence à administração do Cliente, fora do escopo deste épico; esta tela apenas reflete o resultado
Onde e como uma clínica é marcada como principal dentro de um Ambiente — usa uma marcação já existente, mantida pela gestão de Perfil de acesso (fora do escopo deste épico); esta tela apenas lê essa marcação para ordenar a lista (RN-CIU-031)
O algoritmo exato de contagem de acessos usado para ordenar a lista — apenas o critério de ordenação resultante é definido aqui (RN-CIU-031)

Personas

Profissional com acesso a mais de uma clínica — usa esta tela normalmente, toda vez que faz login, para escolher a clínica.
Profissional com acesso a exatamente 1 clínica e um convite pendente simultâneo — normalmente iria direto ao cockpit (RN-CIU-009, 1 clínica acessível); passa a ver esta tela só para poder aceitar o convite via card (RN-CIU-022, item 2).
Profissional que acaba de aceitar seu primeiro vínculo (nunca teve nenhum antes) e esse vínculo já dá acesso a mais de uma clínica — chega a esta tela pela primeira vez vindo da tela de aceite do E3 (RN-CIU-014), e não necessariamente de um login com convite pendente: a verificação de Perfil de acesso pós-aceite (RN-CIU-015, em CIU-E3) já resulta em mais de uma clínica para esse único vínculo. Se, além disso, esse profissional já tiver um segundo convite pendente de outra clínica, o card de convite aparece nesta mesma tela, junto com a lista (mesmo mecanismo do item 2, RN-CIU-022).
Profissional vinculado a mais de um Cliente contratante, cada um com sua própria estrutura de clínicas — precisa perceber, sem esforço, que duas clínicas de nomes parecidos (ou idênticos) pertencem a contratantes diferentes, e não pode confundir uma clínica de testes temporária com a clínica real onde de fato atende.

Workflow do Profissional

Resumo: um profissional que atende em mais de uma clínica faz login uma única vez (E1) — a conta é global, compartilhada entre clínicas (RN-CIU-001, em CIU-E1). Depois do login, em vez de cair direto num cockpit, ele escolhe em qual clínica quer trabalhar naquele momento. Se uma clínica nova o convidou nesse meio tempo, ele quer ver e aceitar esse convite no mesmo lugar onde já escolhe a clínica — não numa tela separada, com leitura de regras que ele já leu. Quando esse profissional atende por mais de um Cliente contratante — situação mais comum do que parece, em redes ou grupos de clínicas que compartilham um mesmo profissional —, ele não pensa em termos de “Cliente” ou “Ambiente” (RN-CIU-031): pensa em “a clínica que eu uso todo dia” e, ocasionalmente, “aquela clínica de teste que o pessoal do financeiro me pediu para validar”.

Touchpoint — Seleção de clínica após login:

Momento do workflow: imediatamente após autenticar-se (E1), quando o roteamento (RN-CIU-022) resulta em acesso a mais de uma clínica, ou em convite pendente com ao menos um vínculo ativo. Também alcançado, sem passar pelo login, ao aceitar o primeiro vínculo no E3 (RN-CIU-014/015), quando esse vínculo já dá acesso a mais de uma clínica.
Necessidade do profissional: entrar rápido na clínica certa, sem passos extras; não confundir clínicas parecidas de contratantes diferentes; não entrar por engano num Ambiente de testes pensando que é o Ambiente real; e, se houver um convite novo, não ser forçado a uma tela cheia de regras que ele já conhece.
O que a funcionalidade oferece: lista das clínicas com vínculo ativo, agrupada visualmente por Cliente contratante e ordenada pela clínica acessada mais recentemente (RN-CIU-031); card em destaque para convite pendente, aceito com um clique.
Decisão de design justificada: clínicas do mesmo Cliente ficam próximas na lista, para que o profissional perceba a relação entre elas sem precisar ler o nome do contratante repetido em cada uma; confundir um Ambiente de testes com o de produção é o maior risco desta tela, respondido com um sinal visual sempre presente nas clínicas de teste — discreto, mas nunca ausente, para não virar ruído no caso comum (produção) nem se perder pela repetição de um alerta chamativo (RN-CIU-031); o card de convite fica separado da lista normal (destaque visual) porque representa uma ação pendente do profissional, não uma opção de navegação — evita que ele confunda “aceitar convite” com “selecionar clínica”.

Regras de Negócio

RN-CIU-022 (transversal, redação completa no guarda-chuva) — define quando o roteamento pós-autenticação chega a esta tela.
RN-CIU-025 — Aceite de convite pendente na tela de seleção de clínica (redação completa abaixo, específica deste épico).
RN-CIU-031 — Agrupamento e ordenação da lista de clínicas por Cliente e Ambiente (redação completa abaixo, específica deste épico).

RN-CIU-025 — Aceite de convite pendente na tela de seleção de clínica

Quando o profissional autenticado já tem ao menos um vínculo ativo e possui, ao mesmo tempo, um convite pendente para uma nova clínica, o aceite desse convite acontece nesta tela — não na tela de aceite do vínculo do E3 (RN-CIU-014, que a partir desta revisão só se aplica a quem não tem nenhum vínculo ativo). Isso vale mesmo quando o profissional tem acesso a exatamente 1 clínica — caso que, sem convite pendente, iria direto ao cockpit (RN-CIU-009) — pois é o único jeito de esse profissional ver e aceitar o convite (RN-CIU-022, item 2, no guarda-chuva).

A tela de seleção de clínica exibe:

As clínicas acessíveis (uma por clínica ativa e distinta, agregando todos os vínculos ativos do profissional), na lista normal de seleção, agrupada e ordenada conforme RN-CIU-031 — uma clínica desativada some da lista para todos os usuários hoje associados a ela.
Um card em destaque, separado da lista, para cada convite pendente.

Diferente da tela de aceite do E3 (RN-CIU-014), este card não exige a leitura das regras básicas de uso da aplicação — o profissional já as leu no momento em que aceitou seu primeiro vínculo. O aceite é uma ação direta no card (ex.: botão “Aceitar”). Não há, nesta revisão, uma ação explícita para recusar ou dispensar o convite sem aceitá-lo — ele permanece em destaque até ser aceito ou expirar (RN-CIU-024, em CIU-E3). [A DEFINIR] se deve existir uma recusa explícita — ainda não levantado pelo solicitante.

Ao aceitar:

O vínculo existente passa de convite pendente para vínculo ativo (mesmo mecanismo do item 1 de RN-CIU-014; não cria um vínculo novo).
O card sai da área de destaque; a clínica passa a fazer parte da lista normal de seleção — não é selecionada automaticamente. O profissional precisa de uma segunda ação, a seleção manual da clínica na lista, como faria com qualquer outra. Isso pressupõe que o convite já tinha ao menos uma clínica associada no momento do aceite; quando o convite foi criado sem Perfil de acesso/clínica selecionados (RN-CIU-011, em CIU-E3, permite deixar essa seleção pendente), o aceite acontece normalmente, mas nenhuma clínica nova entra na lista. Nesse caso, o profissional vê uma mensagem informativa própria, explicando que seu acesso ainda depende do administrador liberar uma clínica para ele.
O profissional só descobre se de fato tem acesso à clínica recém-aceita no momento em que a seleciona na lista — a verificação correspondente (RN-CIU-015) roda nesse momento, o mesmo em que rodaria para qualquer outra clínica selecionada, não no momento do aceite do card.

RN-CIU-031 — Agrupamento e ordenação da lista de clínicas por Cliente e Ambiente

Cada clínica que o profissional pode acessar existe dentro de um Ambiente de trabalho mantido por um Cliente contratante — um Cliente pode manter mais de um Ambiente ao mesmo tempo: sempre um único Ambiente de produção (o Ambiente real, usado no dia a dia), e eventualmente um ou mais Ambientes de testes, criados de forma temporária para validar alguma mudança antes dela valer em produção — o administrador pode revogar o acesso do profissional a um Ambiente de testes assim que a validação termina. Uma mesma clínica pode existir, com o mesmo nome, em mais de um Ambiente do mesmo Cliente.

A lista de clínicas reflete essa estrutura, mas sem transformá-la em informação de primeiro plano — o profissional não precisa entender os conceitos de Cliente ou Ambiente para escolher onde trabalhar:

Clínicas do mesmo Cliente ficam visualmente próximas entre si na lista, com o nome do Cliente indicado de forma discreta acima do grupo, sem repetir esse nome em cada clínica individualmente. Quando o profissional está vinculado a um único Cliente, esse rótulo não aparece — não há nada a diferenciar.
Dentro de cada Ambiente de um mesmo Cliente, a clínica marcada como principal aparece antes das demais desse Ambiente (ver Escopo, sobre onde essa marcação é feita).
Um Ambiente de testes recebe um sinal visual constante, presente em toda clínica daquele Ambiente, mas discreto — sem cor ou linguagem de alerta/erro. Um Ambiente de produção não recebe nenhuma marca adicional, por ser o caso comum.
Entre grupos de Cliente, e entre Ambientes de um mesmo Cliente, a ordem segue a clínica acessada mais recentemente pelo profissional — usada como aproximação de qual ele provavelmente vai escolher agora. [PROPOSTA] — janela de tempo considerada e o desempate entre clínicas com frequência de acesso equivalente ainda não foram validados com usuários reais.
Se a única clínica de um Ambiente deixar de estar acessível ao profissional (ex.: fim de uma validação de testes), o Ambiente inteiro sai da lista — não permanece um grupo vazio.

Motivador: confundir um Ambiente de testes com o Ambiente de produção é o erro de maior risco desta tela — mas a resposta a esse risco é um sinal sempre presente e discreto (item 3), não uma cor de alerta ou uma interrupção a cada acesso. A leitura da lista é o único momento em que o profissional realmente decide onde vai entrar, e ela se repete a cada login: um sinal chamativo tende a ser notado nas primeiras vezes e ignorado depois, enquanto um sinal discreto mas constante — presente em toda clínica de um Ambiente de testes, sem exceção — permanece reconhecível ao longo do tempo sem se tornar ruído visual no caso comum (produção).

Premissas

O profissional só chega a esta tela depois de autenticado (E1) — esta tela nunca é o primeiro ponto de contato com o sistema.
Toda clínica com vínculo ativo listada aqui já foi aceita em algum momento (E3, RN-CIU-014, ou nesta própria tela, RN-CIU-025) — a tela não lida com convites de clínicas ainda não aceitas de nenhuma forma.
O profissional pode ter mais de um convite pendente simultâneo (de clínicas diferentes) — cada um exibido como um card separado.
Um Cliente contratante sempre tem exatamente um Ambiente de produção; pode ou não ter, além dele, um ou mais Ambientes de testes, cada um temporário.

Dependências

Depende do E1 (Núcleo de Identidade e Autenticação) — só é alcançada a partir do roteamento pós-autenticação (RN-CIU-022, documento guarda-chuva). Depende do E3 (Convite e Vínculo) para o mecanismo de aceite de convite (mesmo mecanismo do item 1 de RN-CIU-014) e para a verificação de Perfil de acesso pós-seleção (RN-CIU-015, redação completa em CIU-E3) — este épico reaproveita a regra, não a redefine. Depende da administração de Clientes e de seus Ambientes de trabalho (Contexto de Segurança, fora do escopo deste épico) para saber quais Ambientes existem, qual deles é o de produção, e qual clínica está marcada como principal em cada um — este épico apenas exibe o resultado dessa configuração.

Requisitos SBIS Aplicáveis

NGS1.03.01 (Impedir acesso por pessoas não autorizadas), NGS1.03.03 (Gerenciamento de perfis), ECF.17.19 (Mensagens do sistema) — todos estágio 1 (Clínica/ambulatório), obrigatórios. Detalhamento na Seção 2.

Metadados do Épico

Atributo	Valor
Prioridade	Must Have — sem esta tela, um profissional com acesso a mais de uma clínica não tem como escolher onde entrar, e um convite pendente com vínculo já ativo nunca seria visto
Complexidade	Média — reaproveita a estrutura e as regras já mapeadas em RN-CIU-014/015/024 (E3), mas passa a agrupar e ordenar a lista por Cliente/Ambiente, uma lógica de apresentação nova (RN-CIU-031)
Dependências	E1 (autenticação, roteamento pós-login); E3 (mecanismo de aceite de vínculo e verificação de Perfil de acesso, reaproveitados sem redefinição); administração de Clientes/Ambientes (Contexto de Segurança, fora do escopo)
Regras transversais aplicadas	1 (RN-CIU-022)
Regras específicas deste épico	2 (RN-CIU-025, RN-CIU-031)
Histórias de usuário	2 (US-CIU-006, US-CIU-007) — Seção 2 ainda não revista para refletir RN-CIU-031
Critérios de aceitação	9 (CA-006.1 a CA-006.4, CA-007.1 a CA-007.5) — Seção 2 ainda não revista para refletir RN-CIU-031
Fluxos de exceção	5 (EX-E6-01 a EX-E6-05)
Endpoints	3
Telas	1 (Seleção de clínica, com lista + área de destaque de convites) — protótipo (Seção 3) ainda não revisto para refletir RN-CIU-031
Tabelas utilizadas	6 existentes (UsuarioCliente, ClienteEmpresa, ClientePerfilAcesso, ClientePerfilAcessoUsuario, UsuarioClienteConvite, ClienteBD) — nenhuma nova
Mensagens catalogadas	Seção 2 ainda não revista para refletir a nova mensagem de RN-CIU-025, item 2
Requisitos SBIS atendidos	2 (NGS1.03.01, NGS1.03.03) + ECF.17.19

Lista consolidada de itens marcados [PROPOSTA] ou [A DEFINIR] nesta versão

Critério de ordenação da lista de clínicas — clínica acessada mais recentemente (RN-CIU-031); janela de tempo e desempate entre clínicas com frequência equivalente ainda não validados com usuários reais.
Identificação visual (nome/logo) do card de convite pendente quando o convite ainda não tem nenhuma clínica associada ao Perfil de acesso — proposto usar o Cliente como fallback (mesma proposta feita em CIU-E3), a confirmar.
[A DEFINIR] Recusa explícita de um convite pendente — não há, nesta revisão, uma forma de o profissional dispensar um card de convite sem aceitá-lo; permanece em destaque até ser aceito ou expirar (RN-CIU-025).
[A DEFINIR] Atualização das Seções 2 (Especificação), 3 (Protótipo) e 4 (Mapeamento de Banco de Dados) deste épico para refletir o agrupamento e a ordenação por Cliente/Ambiente definidos em RN-CIU-031 — ainda descrevem a lista como uma lista simples.

Itens resolvidos nesta revisão (removidos da lista de pendências desde a v1.3): fluxo de exceção EX-E6-05 (mantido como tratamento próprio, dedicado, e não como erro genérico) e a mensagem associada MSG-E6-04; identificação visual da clínica após aceite de convite sem nenhuma clínica associada (RN-CIU-025, item 2), agora resolvida com uma mensagem informativa própria.

Histórico de Versões

v1.0 (29/08/2026) — Arquivo criado pela divisão do documento único (CIU-E6) Seleção de Clínica v1.0.md em arquivos por seção (ver Skill Designer, “Organização Física: Pasta por Funcionalidade”, Lição #18). Conteúdo sem alteração de substância em relação à v1.0 original — apenas reorganização física (o protótipo HTML já era um arquivo separado desde a v1.0 original, só foi renomeado para a convenção nova). Histórico de revisões anterior a esta divisão (v0.1 a v1.0) preservado integralmente no documento original arquivado.
v1.1 (14/09/2026) — corrigido o gatilho desta tela e a Lista de Clínicas: o trocador considerava “mais de um vínculo ativo”; a granularidade correta é “mais de uma clínica (ClienteEmpresa) acessível”, já que um único vínculo pode compreender mais de uma ClienteEmpresa (filiais de uma mesma rede, ou clínicas de um conglomerado sem dados compartilhados). Achado ao consultar a Biblioteca de Schema (DDL) a pedido do solicitante, que confirmou a granularidade e a regra de o administrador escolher clínicas específicas por vínculo (RN-CIU-011, em CIU-E3). Trocada Cliente por ClienteEmpresa nas tabelas utilizadas. Consequência da mesma correção no E1 (v2.1) e no E3 (v3.2). O protótipo HTML (Seção 3) não precisou de alteração — já exibia um card por clínica individual, compatível com o modelo corrigido.
v1.2 (14/09/2026) — duas correções sobre a v1.1: (1) Personas e Workflow do Profissional passam a reconhecer explicitamente quem chega a esta tela ao aceitar seu primeiro vínculo (E3, RN-CIU-014/015), quando esse vínculo já dá acesso a mais de uma ClienteEmpresa — cenário que a RN-CIU-015 (CIU-E3) já previa como chegando ao E6, mas que este documento não citava como destino possível; (2) RN-CIU-025, item 2, deixava implícito que toda clínica saída de um card de convite aceito já tem uma ClienteEmpresa determinada — mas RN-CIU-011 (CIU-E3) permite deixar essa seleção pendente no convite. Esse caso de borda (convite aceito sem nenhuma ClienteEmpresa associada) foi identificado e registrado como pendência explícita [A DEFINIR], sem inventar um comportamento novo para ele.
v1.3 (14/09/2026) — confirmado pelo solicitante: uma ClienteEmpresa desativada some da lista de clínicas acessíveis para todos os usuários hoje associados a ela. RN-CIU-025 (item 1) e Especificação (“Lista de Clínicas”) atualizadas para filtrar apenas ClienteEmpresa ativas.
v2.0 (18/09/2026) — revisão completa da Seção 1, a pedido do solicitante (“repensar o fluxo do zero”), incorporando uma estrutura até então não documentada em nenhum épico do Check-in de Usuários: cada Cliente contratante mantém um ou mais Ambientes de trabalho (um único de produção, e eventualmente Ambientes de testes temporários), e cada clínica pertence a um desses Ambientes. Confirmado pelo solicitante e verificado na Biblioteca de Schema (DDL), IpSeguranca.sql: ClienteBD.ClienteId liga o Ambiente ao Cliente; ClienteEmpresa.ClienteBDId liga a clínica ao Ambiente; UsuarioCliente.ClienteBDId mostra que o próprio vínculo/convite já era, na estrutura de dados, escopado por Ambiente — consistente com o array convites do endpoint de listagem (02 - Especificação v1.3) já trazer um campo clienteBDId, mesmo antes deste esclarecimento de negócio; ClientePerfilAcessoUsuario.EmpresaPadrao (char(1), padrão 'N') é o campo que já registrava, sem nome de negócio até agora, qual clínica é a principal do profissional dentro de um Ambiente; ClienteBD.Tipo (char(1)) é o campo indicado pelo solicitante como o que diferencia produção de homologação — seus valores de domínio ainda não estão catalogados na Biblioteca de Schema, ficando como apuração pendente para quando a Seção 4 for revista. Nenhum dos três primeiros fatos exigiu mudança de schema, só nomeação e uso em tela. Nova regra RN-CIU-031 define o agrupamento visual por Cliente, a ordem “principal primeiro” dentro de um Ambiente, o sinal visual discreto (porém constante) para Ambientes de testes e o desaparecimento de um Ambiente cuja última clínica deixou de ser acessível. Critério de ordenação da lista (pendência desde a v1.0) resolvido como “clínica acessada mais recentemente”, a pedido do solicitante — ainda [PROPOSTA] quanto à janela de tempo exata e ao desempate. EX-E6-05 e a mensagem MSG-E6-04 associada, antes propostos como cenário de borda a confirmar, foram confirmados pelo solicitante como tratamento definitivo. RN-CIU-025, item 2 — caso do convite aceito sem nenhuma clínica associada, em aberto desde a v1.2 — resolvido com uma mensagem informativa própria; texto exato a catalogar na Seção 2. Decisões de visual (containers por Ambiente, borda picotada para Ambientes de testes, rótulo do Cliente, ordenação) foram exploradas com o solicitante em uma sequência de protótipos HTML de exploração, fora do arquivo de Protótipo oficial (Seção 3) — incluindo uma sessão de brainstorm de UX dedicada (rodada como subagente) para gerar alternativas de representação visual antes de convergir na proposta atual. Seções 2, 3 e 4 deste épico ainda não foram atualizadas para refletir RN-CIU-031 — registrado como [A DEFINIR] na lista de pendências. Revisão de crítico de negócio (Skill Designer, “Revisão por Dois Críticos”) rodada como subagente independente sobre esta versão candidata, encontrando 13 problemas, todos corrigidos antes de fechar esta versão: jargão técnico de banco de dados no corpo (UsuarioCliente.Situacao = 'V'/'C', nome de tabela ClienteEmpresa usado como conceito de negócio nas Personas e em RN-CIU-025) removido, substituído por linguagem de negócio (“vínculo ativo”, “convite pendente”, “clínica”); duas frases de proveniência de decisão (“confirmado pelo solicitante”, referência a “revisões anteriores deste documento”) removidas do corpo de RN-CIU-025; contradição entre o motivador de RN-CIU-031 (“maior risco desta tela”) e a escolha por um tratamento visual discreto para Ambientes de teste, resolvida explicitando que o sinal é discreto mas constante — nunca ausente —, e que essa escolha existe para evitar a fadiga de um alerta chamativo repetido a cada login, não para minimizar o risco; adicionada ao Escopo (Fora do escopo) a dependência, antes não declarada, de que a marcação de “clínica principal” usada por RN-CIU-031 é feita fora deste épico; suavizada a promessa do Escopo sobre a ordenação, de “mais provável” para “acessada mais recentemente, como aproximação”; registrada como [A DEFINIR] a ausência de uma ação de recusa explícita de convite, lacuna que já existia desde a v1.0 e só foi percebida nesta rodada; explicitado que o rótulo de Cliente não aparece para quem só tem um Cliente vinculado; ampliada a Persona 3 para cobrir o caso combinado de primeiro vínculo (E3) com apenas 1 clínica mais um segundo convite pendente simultâneo, antes não coberto por nenhuma persona; RN-CIU-025, item 3, reescrita do ponto de vista do que o profissional percebe, não do momento em que uma verificação interna roda; e a explicação de Cliente/Ambiente, antes repetida quase palavra por palavra em 4 seções, consolidada em RN-CIU-031 como fonte única, com as demais seções apenas referenciando-a.

Gemed 2.1 — Documentação

Explorador

01 - Definição v2.0