Gemed 2.1 — Documentação

01 - Definição v3.3

Leitura de 16 min

⬇ Baixar .md

Épico 3 — Convite e Vínculo — Definição (v3.3)

Documentos deste épico: 01 - Definição (v3.3) · 02 - Especificação (v3.3) · Protótipo (Seção 3): pendente, ainda não produzido — telas a prototipar: Cadastro de Convite, Tela de Conclusão de Cadastro, Tela de Aceite do Vínculo, Mensagem de Bloqueio · 04 - Mapeamento de Banco de Dados (v3.3). Este épico faz parte do documento guarda-chuva Check-in de Usuários.

SEÇÃO 1 — DEFINIÇÃO

Objetivo

Permitir que uma clínica estabeleça o vínculo formal com um profissional — já cadastrado no Gemed ou não — através de um convite: o administrador cadastra a pessoa, o sistema cria (ou reaproveita) a conta e um vínculo em estado “convidado”, e o profissional confirma esse vínculo explicitamente antes de ganhar acesso a dados da clínica.

Escopo

Dentro do escopo:

  • Cadastro de um profissional pelo administrador/RH da clínica (CPF, nome, e-mail, celular), disparando um convite por e-mail
  • Reaproveitamento do usuário já existente quando o CPF informado já corresponde a uma conta ativa
  • Criação direta do registro de usuário (Usuario) e do vínculo em estado “convidado” (UsuarioCliente, Situacao = ‘C’)
  • Tela de conclusão de cadastro, para quando a conta foi criada pelo administrador e a pessoa ainda não definiu senha
  • Roteamento do link de convite para a tela de conclusão de cadastro ou para o login (E1), conforme a conta já tenha senha definida
  • Tela de aceite do vínculo — leitura das regras básicas do sistema e aceite explícito, aplicável a quem ainda não tem nenhum vínculo ativo
  • Verificação de Perfil de acesso associado ao vínculo, com mensagem de bloqueio orientativa caso ausente
  • Expiração e cancelamento de convites

Fora do escopo:

  • Aceite de convite quando o profissional já tem outro vínculo ativo — acontece na tela de seleção de clínica, não aqui (ver E6)
  • Gestão ampla de usuários da clínica (listagem, edição de perfis, desativação) — o cadastro de convite é uma ação dentro dessa tela mais ampla, não documentada neste épico

Personas

  • Administrador da clínica — cadastra o profissional e dispara o convite.
  • Profissional convidado — completa seu cadastro (se necessário), lê as regras básicas e aceita o vínculo.

Workflow do Profissional

Este épico implementa o touchpoint “Profissional foi convidado por uma clínica” do workflow transversal “Entrada do profissional no sistema”, documentado uma única vez no documento guarda-chuva (Seção 4.1) — não repetido aqui.

Touchpoint específico deste épico — Conclusão de cadastro e aceite do vínculo:

  • Momento do workflow: entre o administrador registrar o convite e o profissional ganhar acesso efetivo à clínica.
  • Necessidade do profissional: confirmar seus dados (corrigindo o que o administrador tenha digitado errado), definir uma senha se ainda não tiver, e formalizar o vínculo — sem repetir um cadastro completo do zero.
  • O que a funcionalidade oferece: uma tela de conclusão de cadastro mais enxuta que o auto-cadastro público (dados básicos já vêm preenchidos) e uma tela de aceite explícito do vínculo, com leitura das regras básicas.
  • Decisão de design justificada: os dois passos ficam separados — completar cadastro primeiro, aceitar vínculo depois — porque são decisões diferentes: uma é sobre os próprios dados da pessoa, a outra é sobre confiar numa clínica específica com acesso a eles.

Regras de Negócio

Este épico também aplica as regras transversais RN-CIU-005 (exclusão lógica), RN-CIU-006 (qualidade e histórico de senha), RN-CIU-007 (suporte multilíngue), RN-CIU-008 (comportamento de campos de input) e RN-CIU-022 (roteamento pós-autenticação conforme convite pendente) — redação completa no documento guarda-chuva, Seção 5.

Nota sobre RN-CIU-005 (exclusão lógica) aplicada a este épico: RemovidoEm nulo continua significando “o registro existe e não foi excluído” — isso vale tanto para um UsuarioCliente em estado convidado (Situacao = ‘C’) quanto vinculado (Situacao = ‘V’) quanto bloqueado (Situacao = ‘B’). “Existir” (RemovidoEm nulo) e “estar vinculado de fato” (Situacao = ‘V’) são coisas diferentes — ver RN-CIU-009 (E1).

RN-CIU-011 — Convite de profissional pela clínica

O administrador da clínica cadastra um profissional informando CPF, nome, e-mail e celular no cadastro de usuários da clínica. Ao confirmar:

  1. O sistema verifica se já existe um usuário ativo (RemovidoEm nulo) com o CPF informado (mesma verificação de RN-CIU-004, reaproveitada do E2).
  2. Se não existe — cria um novo registro em Usuario com os dados informados (CPF, Usuario/login = CPF, Nome, eMail, Telefone). Hash e Salt ficam nulos — a conta não tem senha até a pessoa concluir seu cadastro.
  3. Se já existe — reaproveita o UsuarioId existente. O administrador não cria uma conta duplicada; apenas formaliza um novo vínculo para um usuário que o Gemed já conhece.
  4. Em ambos os casos, cria um vínculo (UsuarioCliente) associando o usuário (novo ou existente) à clínica, com Situacao = ‘C’ (Convidado), e gera um token de convite com prazo de validade (RN-CIU-024; dados de token armazenados à parte — ver Seção 4).
  5. Dispara um e-mail ao endereço informado, com um link contendo o token.

Convite não é vínculo. Enquanto Situacao = ‘C’, a pessoa não tem qualquer acesso à clínica — apenas quando aceita explicitamente (RN-CIU-014) o vínculo passa a Situacao = ‘V’.

No mesmo formulário, o administrador pode opcionalmente já selecionar um Perfil de acesso a ser associado ao vínculo. Como o UsuarioCliente já existe desde a criação do convite, essa associação (ClientePerfilAcessoUsuario) é criada imediatamente, apontando para o UsuarioClienteId recém-criado — sem necessidade de copiar esse dado posteriormente no aceite.

Ao selecionar um Perfil de acesso, o administrador também escolhe a qual clínica (ou clínicas) da rede esse perfil se aplica — um Cliente pode compreender mais de uma ClienteEmpresa (por exemplo, filiais de uma mesma rede, ou clínicas de um conglomerado que não compartilham dados entre si), e o vínculo em si não concede acesso automático a todas elas. Cada combinação de Perfil de acesso + clínica gera um registro próprio em ClientePerfilAcessoUsuario, todos apontando para o mesmo UsuarioClienteId. Quando o administrador não seleciona nenhum Perfil de acesso no convite (opção permitida), a seleção de clínica(s) também fica pendente — nem uma coisa nem outra é definida nesse momento. O vínculo, quando aceito, permanece sem nenhuma clínica acessível até que o administrador associe, posteriormente, um Perfil de acesso e a(s) clínica(s) correspondentes (RN-CIU-015 apenas verifica e bloqueia enquanto isso não acontece — não define nada por conta própria; a ação de associar depois é da gestão de usuários da clínica, fora do escopo deste épico).

Nota de modelagem: o domínio do campo Situacao (UsuarioCliente) é C = Convidado, V = Vinculado, B = Bloqueado — vale para todos os épicos que consultam UsuarioCliente (E1, E2, E3).

RN-CIU-023 — Roteamento do link de convite conforme senha já definida

Ao acessar o link do e-mail de convite, o sistema valida o token contra o registro correspondente (não expirado — RN-CIU-024 — e o vínculo ainda em Situacao = ‘C’) e verifica se o Usuario associado já tem senha definida (campo Hash preenchido):

  • Hash nulo (o administrador criou a conta e a pessoa nunca definiu senha) — direciona para a tela de conclusão de cadastro (RN-CIU-012).
  • Hash preenchido (a pessoa já tinha conta — seja porque se auto-cadastrou antes pelo E2, seja porque já havia concluído um convite anterior de outra clínica) — direciona para a tela de login (E1). Após autenticar, o roteamento por convite pendente (RN-CIU-022) leva à tela de aceite do vínculo (RN-CIU-014) ou ao card de aceite no E6, conforme o profissional já tenha algum vínculo ativo.

Observação: pelo mesmo motivo (o Usuario já existe desde a criação do convite), uma pessoa nunca chega ao wizard de auto-cadastro público (E2) vinda de um link de convite — se tentasse se auto-cadastrar pelo E2 com o mesmo CPF de um convite pendente, a verificação de duplicidade do E2 (RN-CIU-004) já bloquearia por CPF existente. Ver fluxo de exceção EX-E3-07 para o tratamento recomendado desse caso.

RN-CIU-012 — Tela de conclusão de cadastro para convite

Quando o link de convite leva a uma conta sem senha definida (RN-CIU-023), o profissional acessa uma tela própria deste épico — não o wizard do E2 — para completar seu cadastro:

  1. Os dados já informados pelo administrador (CPF, nome, e-mail, celular) são exibidos e ficam disponíveis para correção pela própria pessoa, caso o administrador tenha cometido algum erro de digitação.
  2. A pessoa pode completar os demais campos definidos no E2 (complemento profissional, se aplicável — RN-CIU-017/019; dados avançados opcionais — RN-CIU-018/021), reaproveitando as mesmas definições de campos e validações já especificadas lá.
  3. A pessoa define sua senha, seguindo os mesmos critérios de complexidade parametrizados (RN-CIU-006).
  4. Ao concluir, o sistema atualiza o registro de Usuario (Hash, Salt, e os dados complementares informados) e autentica a pessoa automaticamente (RN-CIU-022), direcionando para a tela de aceite do vínculo (RN-CIU-014).

RN-CIU-014 — Tela de aceite do vínculo

Aplica-se quando o profissional não tem nenhum vínculo ativo (nenhum UsuarioCliente.Situacao = 'V') no momento do aceite — ou seja, ao concluir a tela de conclusão de cadastro (RN-CIU-012, sempre o caso: quem chega a essa tela nunca teve vínculo aceito antes) ou ao fazer login (E1) pela primeira vez, sem nenhum vínculo ativo anterior, havendo um convite pendente. Nesse cenário, o profissional é direcionado para a tela de aceite do vínculo antes de qualquer outro destino (cockpit, seleção de clínica ou Meu Perfil).

Quando o profissional já tem ao menos um vínculo ativo e recebe um novo convite, o aceite não passa por esta tela — acontece como um card na tela de seleção de clínica (E6, RN-CIU-025), sem a leitura das regras básicas: o profissional já as leu no momento em que aceitou seu primeiro vínculo, coberto por esta regra.

Nesta tela, o profissional lê as regras básicas de uso da aplicação e aceita explicitamente o vínculo com a clínica que o convidou. O aceite é uma ação intencional — nunca implícito no simples fato de concluir o cadastro ou fazer login.

Ao aceitar, o sistema:

  1. Atualiza o vínculo existente — UsuarioCliente.Situacao passa de ‘C’ para ‘V’ (não cria um registro novo; é o mesmo vínculo desde o convite)
  2. Executa a verificação de Perfil de acesso (RN-CIU-015) e direciona o profissional conforme o resultado

Se o profissional não aceitar (fecha a tela, opta por “Agora não”), o vínculo permanece em Situacao = ‘C’ e ele pode aceitá-lo em um acesso futuro, enquanto o convite não expirar (RN-CIU-024).

RN-CIU-015 — Verificação de Perfil de acesso pós-aceite

Imediatamente após o aceite do vínculo (RN-CIU-014), o sistema verifica se já existe um Perfil de acesso associado ao vínculo (registro em ClientePerfilAcessoUsuario referenciando o UsuarioClienteId):

  • Se existe — o profissional é direcionado para sua tela inicial, seguindo o mesmo mecanismo de roteamento por cockpit descrito em RN-CIU-009 (E1): direto para o cockpit do seu tipo de profissional quando esse vínculo (somado aos demais vínculos ativos do usuário) resulta em acesso a exatamente 1 clínica, ou para a tela de seleção de clínica (E6) quando resulta em mais de 1 — cada registro em ClientePerfilAcessoUsuario associado ao vínculo corresponde a uma ClienteEmpresa acessível.
  • Se não existe — o sistema exibe uma mensagem informando que o profissional ainda não tem um perfil de acesso definido, orientando-o a aguardar ou entrar em contato com o administrador da clínica. O acesso às funcionalidades da clínica permanece bloqueado até que um perfil (e ao menos uma clínica) seja associado. Esta é uma verificação e um bloqueio — não um mecanismo que define perfil e clínica por conta própria; quem os associa, mais tarde, é o administrador, pela gestão de usuários da clínica (fora do escopo deste épico).

Nota de terminologia: “Perfil de acesso” e “perfil profissional” são conceitos distintos, não intercambiáveis. Perfil de acesso é o conjunto de funcionalidades do sistema que o usuário pode acessar — corresponde à tabela ClientePerfilAcesso já existente no banco IpSeguranca, ligada ao vínculo via ClientePerfilAcessoUsuario, e é exatamente o que esta regra verifica. Perfil profissional são as características do profissional em si — tipo de profissional, conselho, especialidades (RN-CIU-017, RN-CIU-019, E2) — e não tem relação com o que é verificado aqui. O cockpit de destino é escolhido pelo tipo de profissional (perfil profissional); o próprio acesso ser concedido ou não depende do Perfil de acesso. Um vínculo pode ter perfil profissional definido (ex.: “enfermeira”) e ainda assim não ter Perfil de acesso associado (são bloqueios independentes).

RN-CIU-024 — Expiração e cancelamento de convite

Cada convite (UsuarioCliente em Situacao = ‘C’) tem um token único e um prazo de validade, mantidos em registro à parte (ver Seção 4) enquanto o convite estiver pendente. O prazo é parametrizável: DataExpiracao é calculada, no momento da criação do convite, como CriadoEm + DiasValidadeConviteVinculo dias — onde DiasValidadeConviteVinculo é um parâmetro na tabela IpSeguranca.UsuarioSenhaParametros, valor 7, tipo Numero (mesma tabela usada para os parâmetros de senha de RN-CIU-006, no guarda-chuva — reaproveitada aqui para um parâmetro de outra natureza).

Após o prazo expirar sem aceite, o link do e-mail deixa de funcionar (RN-CIU-023 trata o token como inválido). O vínculo permanece em Situacao = ‘C’ até uma ação explícita — ele não muda de estado sozinho só por ter expirado, mas deixa de ser acessível pelo link. Uma rotina periódica varre convites expirados e:

  • Se o Usuario associado já tinha senha definida antes do convite (ou seja, o convite era para alguém que já existia) — apenas marca o vínculo como excluído logicamente (RemovidoEm no UsuarioCliente), preservando o Usuario intacto.
  • Se o Usuario foi criado especificamente para este convite e nunca teve senha definida (Hash ainda nulo) e este era seu único vínculo — exclui logicamente também o Usuario (RemovidoEm), para não reter indefinidamente um cadastro pessoal que nunca chegou a ser confirmado pela própria pessoa. Esta distinção evita reter dados pessoais (nome, CPF, e-mail, celular) de alguém que nunca interagiu com o sistema, sem afetar contas de pessoas que já eram usuárias reais do Gemed.

O administrador pode cancelar manualmente um convite pendente a qualquer momento antes do aceite — mesmo efeito da expiração, aplicado imediatamente.

Premissas

  • O e-mail informado pelo administrador é o meio de contato válido para o convite — não há verificação prévia de que pertence à pessoa certa.
  • Um profissional pode ter convites pendentes de mais de uma clínica simultaneamente.

Dependências

Depende do E1 (Núcleo de Identidade e Autenticação) — reaproveita o mecanismo de autenticação e o roteamento pós-login, que verifica convite pendente antes de avaliar vínculos (RN-CIU-022, documento guarda-chuva). Reaproveita também os critérios de complexidade de senha (RN-CIU-006) e a estrutura de campos profissionais e avançados definida no E2 (RN-CIU-003, RN-CIU-017 a RN-CIU-021) — mas não invoca o wizard do E2: a tela de conclusão de cadastro é própria deste épico, pois lida com um Usuario que já existe (criado pelo administrador), não com a criação de um registro novo do zero. Depende de E1 já existir para ser desenvolvido; não depende do fluxo do E2, apenas de definições de campo já estabelecidas lá.

Requisitos SBIS Aplicáveis

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

Metadados do Épico

AtributoValor
PrioridadeMust Have — sem este épico, profissionais convidados por clínicas não têm caminho formal de vínculo
ComplexidadeAlta — uma tabela nova (UsuarioClienteConvite), domínio novo em Situacao, uma tela nova (conclusão de cadastro), integração transversal com E1 via RN-CIU-022 e RN-CIU-009
DependênciasE1 (autenticação, roteamento); reaproveita definições de campos do E2 sem depender do seu fluxo
Regras transversais aplicadas5 (RN-CIU-005, 006, 007, 008, 022)
Regras específicas deste épico6 (RN-CIU-011, 012, 014, 015, 023, 024)
Histórias de usuário2 (US-CIU-004, US-CIU-005)
Critérios de aceitação14 (CA-004.1 a CA-004.5, CA-005.1 a CA-005.9)
Fluxos de exceção7 (EX-E3-01 a EX-E3-07)
Endpoints6
Telas3 (Cadastro de convite, Tela de conclusão de cadastro, Tela de aceite do vínculo) + 1 (Mensagem de bloqueio — sem Perfil de acesso) — nenhuma ainda prototipada em HTML
Tabelas utilizadas6 existentes (Usuario, UsuarioCliente, ClientePerfilAcesso, ClientePerfilAcessoUsuario, UsuarioSenhaParametros, ClienteEmpresa) + 1 nova (UsuarioClienteConvite, 3 campos)
Mensagens catalogadas14 (5 erros, 1 sucesso, 2 informativas, 1 texto orientador, 4 rótulos de botão/link, 1 rótulo de checkbox)
Requisitos SBIS atendidos4 (NGS1.03.08, NGS1.03.03, NGS1.03.01, NGS1.03.09) + ECF.17.19

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

  1. Conteúdo textual completo das “regras básicas de uso” na tela de aceite (MSG-T3-02)
  2. Mecanismo de contato com o administrador na mensagem de bloqueio — canal não especificado
  3. Nome e tipos dos campos da tabela nova UsuarioClienteConvite (Token, DataExpiracao) — a existência da tabela em si foi decidida pelo solicitante; nome e tipos exatos dos campos são proposta deste documento
  4. Protótipo HTML (Seção 3) — ainda não produzido
  5. Exigência de selecionar Perfil de acesso e clínica(s) juntos (um não sem o outro) — a granularidade Cliente × ClienteEmpresa e a regra de o administrador escolher clínicas específicas foram confirmadas pelo solicitante; a exigência de ambos juntos, especificamente, é inferência deste documento
  6. Identificação visual (nome/logo) na tela de aceite do vínculo quando nenhuma ClienteEmpresa ainda está associada ao convite — proposto usar o Cliente como identificação de fallback, a confirmar

Histórico de Versões

  • v3.1 (29/08/2026) — Arquivo criado pela divisão do documento único (CIU-E3) Convite e Vínculo v3.1.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 à v3.1 original — apenas reorganização física. Histórico de revisões anterior a esta divisão (v1.0 a v3.1) preservado integralmente no documento original arquivado.
  • v3.2 (14/09/2026) — corrigida a RN-CIU-011: a seleção de Perfil de acesso pelo administrador, no convite, passa a exigir também a seleção da(s) clínica(s) (ClienteEmpresa) às quais aquele perfil se aplica — um vínculo (com um Cliente) não concede acesso automático a todas as ClienteEmpresa do Cliente, quando há mais de uma. Achado ao consultar a Biblioteca de Schema (DDL) a pedido do solicitante, que confirmou a granularidade Cliente × ClienteEmpresa e a exigência de seleção explícita. RN-CIU-015 ajustada para refletir que o roteamento pós-aceite (RN-CIU-009, E1) passa a depender da quantidade de ClienteEmpresa associadas ao vínculo, não apenas da existência de um Perfil de acesso. Consequência da mesma correção no E1 (v2.1) e no E6 (v1.1).
  • v3.3 (14/09/2026) — duas correções sobre a v3.2: (1) o final de RN-CIU-011 afirmava que, quando o convite fica sem Perfil de acesso/clínica selecionados, “ambas são definidas juntas, mais tarde, na verificação pós-aceite (RN-CIU-015)” — mas RN-CIU-015 nunca definiu nada; apenas verifica e bloqueia. Trecho reescrito para não prometer um mecanismo de definição conjunta que não existe: o vínculo fica bloqueado (RN-CIU-015) até o administrador associar Perfil de acesso e clínica(s) posteriormente, pela gestão de usuários da clínica (fora do escopo deste épico) — mesma correção espelhada na nota final de RN-CIU-015; (2) referência cruzada obsoleta corrigida em RN-CIU-024 e no restante do texto: menções a “confirmado pelo solicitante em 27/08/2026” dentro do corpo das regras foram removidas (a proveniência já está preservada nas entradas correspondentes deste Histórico de Versões — convenção de “corpo atemporal” da Skill Designer).

Visão de gráfico

Backlinks