# Épico 3 — Convite e Vínculo — Definição (v3.3) **Documentos deste épico:** [01 - Definição](./01%20-%20Defini%C3%A7%C3%A3o%20v3.3.md) (v3.3) · [02 - Especificação](./02%20-%20Especifica%C3%A7%C3%A3o%20v3.3.md) (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](./04%20-%20Mapeamento%20de%20Banco%20de%20Dados%20v3.3.md) (v3.3). Este épico faz parte do documento guarda-chuva [Check-in de Usuários](../00%20-%20Guarda-chuva%20v2.11.md). --- ## 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 |Atributo|Valor| |---|---| |Prioridade|Must Have — sem este épico, profissionais convidados por clínicas não têm caminho formal de vínculo| |Complexidade|Alta — 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ências|E1 (autenticação, roteamento); reaproveita definições de campos do E2 sem depender do seu fluxo| |Regras transversais aplicadas|5 (RN-CIU-005, 006, 007, 008, 022)| |Regras específicas deste épico|6 (RN-CIU-011, 012, 014, 015, 023, 024)| |Histórias de usuário|2 (US-CIU-004, US-CIU-005)| |Critérios de aceitação|14 (CA-004.1 a CA-004.5, CA-005.1 a CA-005.9)| |Fluxos de exceção|7 (EX-E3-01 a EX-E3-07)| |Endpoints|6| |Telas|3 (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 utilizadas|6 existentes (Usuario, UsuarioCliente, ClientePerfilAcesso, ClientePerfilAcessoUsuario, UsuarioSenhaParametros, ClienteEmpresa) + 1 nova (UsuarioClienteConvite, 3 campos)| |Mensagens catalogadas|14 (5 erros, 1 sucesso, 2 informativas, 1 texto orientador, 4 rótulos de botão/link, 1 rótulo de checkbox)| |Requisitos SBIS atendidos|4 (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).