ÉPICO 3 — CONVITE E VÍNCULO

Funcionalidade pai: Check-in de Usuários no Sistema Persona principal: Administrador da clínica (criação do convite) Persona secundária: Profissional convidado (conclusão de cadastro e aceite do vínculo) Versão: 2.0 (revisada) Data: 27/08/2026

1. Visão Geral do Épico

1.1 O que inclui

Este épico cobre o mecanismo pelo qual uma clínica estabelece o vínculo formal com um profissional — seja ele já cadastrado no Gemed, seja uma pessoa que ainda não tem conta. Ele contempla:

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 — o administrador nunca cria uma conta duplicada
Criação direta do registro de usuário (Usuario) e do vínculo em estado “convidado” (UsuarioCliente, Situacao = ‘C’), sem tabela intermediária
Tela de conclusão de cadastro — para quando a conta foi criada pelo administrador e a pessoa ainda não definiu uma 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, que transiciona o vínculo de “convidado” para “vinculado”
Verificação de Perfil de acesso associado ao vínculo, com mensagem de bloqueio orientativa caso ausente
Expiração e cancelamento de convites

Mudança de arquitetura em relação à v1.x deste épico (27/08/2026): a v1.x propunha uma tabela nova Convite, separada de UsuarioCliente, e reaproveitava o wizard de auto-cadastro do E2 (pré-preenchido) para quem ainda não tinha conta. O solicitante propôs uma solução mais simples, adotada nesta versão: o administrador cria o registro de Usuario diretamente (sem senha) e um registro de UsuarioCliente já no estado convidado, usando um novo valor de domínio no campo Situacao (que já existia na tabela, mas sem domínio documentado até agora). Isso elimina a tabela nova, elimina a cópia de dados entre “convite” e “vínculo” (é o mesmo registro, apenas muda de estado) e torna a verificação de convite pendente uma consulta direta em UsuarioCliente, sem entidade extra. Como consequência, o E2 deixa de ter qualquer participação neste fluxo — ver nota na Seção 1.2.

1.2 Dependências

Este épico depende do E1 (Núcleo de Identidade e Autenticação) — reaproveita o mecanismo de autenticação (Seção 4.1 do E1) e o roteamento pós-login, que passa a verificar 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 (Seção 4.2) é 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.

Correção em relação à versão anterior deste épico: na v1.x, a tela de auto-cadastro do E2 era reaproveitada com pré-preenchimento para quem viesse de um convite. Essa abordagem deixou de fazer sentido nesta versão: como o Usuario já existe desde a criação do convite (Seção 2, RN-CIU-011), nunca há um “auto-cadastro” a fazer — há apenas dados a completar e uma senha a definir. A dependência do E2 nesta versão é apenas de padrões reaproveitados (campos, validações, critérios de senha), não de fluxo.

1.3 Paralelização

Depende de E1 já existir (mecanismo de autenticação). Não depende mais de E2 em termos de fluxo — apenas reaproveita definições de campos já estabelecidas lá.

2. 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), redefinida nesta revisão.

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:

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).
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 (Seção 4.2).
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.
Em ambos os casos, cria um registro em UsuarioCliente associando o UsuarioId (novo ou existente) à clínica (ClienteBDId), com Situacao = ‘C’ (Convidado), e gera um token de convite com prazo de validade (RN-CIU-024).
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’.

[PROPOSTA — não confirmado pelo solicitante] 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) pode ser criada imediatamente, apontando para o UsuarioClienteId recém-criado — sem necessidade de copiar esse dado posteriormente no aceite.

Nota de modelagem — domínio do campo Situacao (UsuarioCliente): este campo já existia na tabela (EsquemaGemed21.csv), mas sem domínio documentado em nenhum documento deste projeto até esta revisão. O solicitante definiu, em 27/08/2026, o domínio: C = Convidado, V = Vinculado, B = Bloqueado. Esta é a primeira vez que esse domínio é registrado — 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 de UsuarioCliente correspondente (não expirado — RN-CIU-024 — e 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, Seção 4.2).
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).

Observação: por este 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:

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.
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á.
A pessoa define sua senha, seguindo os mesmos critérios de complexidade parametrizados (RN-CIU-006).
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

Ao concluir a tela de conclusão de cadastro (RN-CIU-012) ou o login (E1) havendo um convite pendente para o usuá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).

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:

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)
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): cockpit do seu tipo de profissional, ou apenas perfil + menu lateral se não houver cockpit específico definido.
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 seja associado.

Nota de terminologia (esclarecida com o solicitante em 27/08/2026): “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, ambos armazenados no próprio registro. [PROPOSTA — parâmetros não confirmados pelo solicitante] Prazo sugerido: 7 dias, parametrizável.

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. [PROPOSTA] Uma rotina periódica pode varrer 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.

3. Histórias de Usuário

US-CIU-004 — Administrador convida profissional

Como administrador da clínica, quero cadastrar o CPF, nome, e-mail e celular de um profissional e disparar um convite, para formalizar seu vínculo com a clínica assim que ele aceitar — reaproveitando a conta dele se ele já for cadastrado no Gemed.

US-CIU-005 — Profissional aceita vínculo com a clínica

Como profissional convidado, quero completar meu cadastro (se for a primeira vez) ou apenas fazer login (se já tiver conta), ler as regras básicas do sistema e aceitar explicitamente o vínculo com a clínica que me convidou, para começar a trabalhar nela assim que meu perfil de acesso for definido.

4. Descrição Funcional Detalhada

4.1 Cadastro de Convite (visão do administrador)

Propósito: Permitir que o administrador da clínica cadastre um profissional e dispare o convite de vínculo.

Nota de escopo: o cadastro de convite é uma ação dentro da tela mais ampla de “cadastro de usuários da clínica” (gestão de usuários pelo administrador). Essa tela mais ampla — listagem de usuários vinculados, edição de perfis, desativação — não é o foco deste épico; aqui documenta-se apenas o formulário mínimo do convite.

Layout (mobile first):

Campo “CPF” — input com máscara automática 000.000.000-00, validação de dígitos verificadores (reaproveita RN-CIU-004 do E2)
Campo “Nome completo” — input text, obrigatório (campo Nome é NOT NULL na tabela Usuario)
Campo “E-mail” — input email, validação de formato
Campo “Celular” — input com máscara parametrizada por país (RN-CIU-020, reaproveitada do E2)
[PROPOSTA] Campo “Perfil de acesso” (select, opcional) — lista de perfis (ClientePerfilAcesso) cadastrados para a clínica
Botão primário “Enviar convite” (MSG-B3-01)

Comportamento:

Ao sair do campo CPF, o sistema verifica se já existe um usuário ativo com esse CPF. Se existir, o formulário informa isso ao administrador (MSG-I3-02: “Este CPF já pertence a um usuário cadastrado no Gemed — o convite será associado à conta existente”) e desabilita a edição dos campos Nome/E-mail/Celular, que passam a exibir os dados já cadastrados (o administrador não pode alterar dados de uma conta que já existe só por estar convidando-a para sua clínica)
Ao sair do campo CPF, o sistema também verifica se já existe convite pendente (Situacao = ‘C’) para esse CPF nesta mesma clínica. Se existir, exibe MSG-E3-01 e impede o envio de um convite duplicado
Ao enviar: cria (ou reaproveita) o registro de Usuario, cria o registro de UsuarioCliente com Situacao = ‘C’ e o token de convite, dispara o e-mail e exibe toast de sucesso MSG-S3-01

Decisão de design: Diferente da v1.x deste épico, o formulário agora inclui nome e celular além de CPF e e-mail — o administrador normalmente tem esses dados em mãos no momento da contratação/onboarding (a burocracia de RH já aconteceu), e coletá-los aqui evita que o profissional precise redigitá-los na tela de conclusão de cadastro. Nome é obrigatório porque a tabela Usuario não permite esse campo vazio — não é uma escolha de UX, é uma restrição de dados.

4.2 Tela de Conclusão de Cadastro

Propósito: Permitir que um profissional, cuja conta foi criada pelo administrador mas ainda não tem senha, complete seus dados e defina sua senha.

Layout (mobile first), estrutura em 2 etapas (mais enxuta que o wizard do E2, pois os dados básicos já vêm preenchidos):

Etapa 1 — Confirmar dados e completar cadastro

CPF, Nome, E-mail, Celular — pré-preenchidos com os dados informados pelo administrador, editáveis (para o caso de erro de digitação do administrador)
Checkbox/Switch “Sou profissional de saúde” (MSG-C2-01, reaproveitada do E2) — se marcado, exibe o complemento profissional (mesmos campos e regras do E2, RN-CIU-017/019: tipo de profissional, conselho, especialidades, CBO)
Seção de dados avançados (opcional, mesmos campos do E2, RN-CIU-018/021) — colapsável, pode ser pulada

Etapa 2 — Definição de senha

Campos de senha e confirmação, indicador de força e lista de critérios — idênticos ao E2, Etapa 3 (RN-CIU-006)
Botão “Concluir cadastro” (MSG-B3-04)

Comportamento: ao concluir, o sistema atualiza o registro de Usuario existente (não cria um novo) com os dados confirmados/completados e a senha definida, autentica automaticamente (RN-CIU-022) e direciona para a tela de aceite do vínculo (Seção 4.3).

Decisão de design: a estrutura em 2 etapas (em vez das 3 do E2) reflete que os dados básicos já chegam preenchidos — não há necessidade de uma etapa dedicada só a eles. Os campos ficarem editáveis, mesmo pré-preenchidos, é uma salvaguarda contra erro de digitação do administrador — sem isso, um CPF ou e-mail errado ficaria sem correção possível pela própria pessoa.

4.3 Tela de Aceite do Vínculo

Propósito: Permitir que o profissional aceite formalmente o vínculo com a clínica que o convidou.

Layout (mobile first):

Nome e logo da clínica convidante (CaminhoLogo, tabela Cliente)
Texto com as regras básicas de uso da aplicação (MSG-T3-02) [PROPOSTA — conteúdo textual completo não fornecido pelo solicitante]
Checkbox de aceite obrigatório: “Li e aceito o vínculo com [nome da clínica]” (MSG-C3-01)
Botão primário “Aceitar vínculo” (MSG-B3-02) — desabilitado até o checkbox ser marcado
Link/botão secundário “Agora não” (MSG-B3-03)

Comportamento:

Ao marcar o checkbox, o botão “Aceitar vínculo” é habilitado
Ao clicar em “Aceitar vínculo”: atualiza UsuarioCliente.Situacao para ‘V’, executa a verificação de Perfil de acesso (RN-CIU-015) e direciona o profissional conforme o resultado
Se o profissional clicar em “Agora não”, retorna à sua página atual sem alterar o Situacao (permanece ‘C’); a tela de aceite volta a ser exibida no próximo login, enquanto o convite não expirar (RN-CIU-024)

Decisão de design: inalterada em relação à versão anterior — o aceite exige uma ação explícita porque o vínculo implica acesso a dados de pacientes da clínica.

4.4 Mensagem de Bloqueio — Sem Perfil de Acesso

Inalterada em relação à versão anterior deste épico: ícone de aviso (não de erro), texto MSG-I3-01, orientando a aguardar ou contatar o administrador da clínica.

5. Critérios de Aceitação

US-CIU-004 — Administrador convida profissional

CA-004.1: Dado que estou na tela de cadastro de convite, quando informo CPF, nome, e-mail e celular válidos e clico em “Enviar convite”, então o sistema cria o Usuario (sem senha) e o UsuarioCliente (Situacao = ‘C’), envia o e-mail e exibe o toast MSG-S3-01.

CA-004.2: Dado que informo um CPF que já pertence a um usuário ativo, quando saio do campo, então os campos Nome/E-mail/Celular são preenchidos com os dados existentes e ficam bloqueados para edição, e o convite reaproveita esse usuário em vez de criar um novo.

CA-004.3: Dado que já existe um convite pendente (Situacao = ‘C’) para o CPF informado nesta clínica, quando tento enviar um novo convite para o mesmo CPF, então o sistema exibe MSG-E3-01 e não cria um convite duplicado.

CA-004.4: Dado que selecionei um Perfil de acesso ao criar o convite, quando o profissional aceita o vínculo, então o perfil selecionado já está associado ao vínculo, sem exibir a mensagem de bloqueio da RN-CIU-015.

US-CIU-005 — Profissional aceita vínculo com a clínica

CA-005.1: Dado que cliquei no link de um convite e minha conta (criada pelo administrador) ainda não tem senha, quando acesso o link, então sou direcionado para a tela de conclusão de cadastro, não para o wizard de auto-cadastro público nem para o login.

CA-005.2: Dado que cliquei no link de um convite e minha conta já tem senha definida, quando acesso o link, então sou direcionado para a tela de login.

CA-005.3: Dado que concluí a tela de conclusão de cadastro (Seção 4.2), quando defino minha senha e confirmo, então sou autenticado automaticamente e direcionado para a tela de aceite do vínculo, não para Meu Perfil.

CA-005.4: Dado que fiz login (E1) e havia um convite pendente para meu usuário, quando a autenticação é bem-sucedida, então sou direcionado para a tela de aceite do vínculo antes de qualquer outro destino.

CA-005.5: Dado que estou na tela de aceite do vínculo, quando marco o checkbox e clico em “Aceitar vínculo”, então UsuarioCliente.Situacao passa para ‘V’ e o sistema verifica meu Perfil de acesso.

CA-005.6: Dado que cliquei em “Aceitar vínculo” e já existe Perfil de acesso associado, quando o aceite é processado, então sou direcionado para o cockpit do meu tipo de profissional.

CA-005.7: Dado que cliquei em “Aceitar vínculo” e não existe Perfil de acesso associado, quando o aceite é processado, então vejo a mensagem de bloqueio orientando a aguardar ou contatar o administrador.

CA-005.8: Dado que estou na tela de aceite do vínculo, quando clico em “Agora não”, então Situacao permanece ‘C’ e retorno à minha página atual.

CA-005.9: Dado que o convite associado ao meu usuário expirou (RN-CIU-024), quando acesso o link do e-mail, então o link não funciona mais e vejo a mensagem MSG-E3-03.

6. Fluxos de Exceção

EX-E3-01 — Convite duplicado para o mesmo CPF na mesma clínica

Gatilho: Administrador tenta criar um convite para um CPF com convite pendente (Situacao = ‘C’) na mesma clínica
Comportamento: Mensagem inline MSG-E3-01. Botão “Enviar convite” permanece desabilitado até o CPF ser alterado
Recuperação: Administrador cancela o convite existente antes de criar um novo, ou aguarda o aceite/expiração

EX-E3-02 — Falha no envio do e-mail de convite

Gatilho: Serviço de envio de e-mail indisponível ou falha ao entregar
Comportamento: Toast error MSG-E3-02 exibido para o administrador. O convite é criado no sistema (Usuario e UsuarioCliente já existem), mas o e-mail não foi confirmado como enviado
Recuperação: Administrador pode reenviar o convite (gera um novo token, mesmo registro de UsuarioCliente)

EX-E3-03 — Link de convite expirado

Gatilho: Pessoa acessa o link do e-mail após o prazo de validade do token (RN-CIU-024)
Comportamento: Página informativa exibindo MSG-E3-03, orientando a pessoa a contatar o administrador da clínica
Recuperação: Administrador cria um novo convite (novo token) para o mesmo vínculo ou reenvia

EX-E3-04 — Link de convite cancelado

Gatilho: Pessoa acessa o link do e-mail depois de o administrador ter cancelado o convite
Comportamento: Página informativa exibindo MSG-E3-04
Recuperação: Administrador cria um novo convite, se ainda desejar vincular a pessoa

EX-E3-05 — Profissional adia o aceite do vínculo

Gatilho: Profissional clica em “Agora não” na tela de aceite (Seção 4.3)
Comportamento: Retorna à página atual. Situacao permanece ‘C’
Recuperação: A tela de aceite é exibida novamente no próximo login ou conclusão de cadastro, enquanto o convite não expirar

EX-E3-06 — Erro ao processar o aceite do vínculo

Gatilho: Back-end retorna erro ao tentar atualizar Situacao durante o aceite
Comportamento: Toast error MSG-E3-05 exibido na tela de aceite. Botão “Aceitar vínculo” volta ao estado default
Recuperação: Profissional tenta novamente

EX-E3-07 — Tentativa de auto-cadastro público (E2) com CPF já convidado

Gatilho: Pessoa com um convite pendente (Situacao = ‘C’, Usuario ainda sem senha) tenta se auto-cadastrar pela tela pública do E2, em vez de usar o link do e-mail
Comportamento: [PROPOSTA — comportamento não descrito pelo solicitante] O E2 já bloquearia por CPF duplicado (RN-CIU-004, dialog MSG-E2-02: “Fazer login ou recuperar senha”). Como a conta não tem senha, nenhuma das duas opções funciona de fato. Sugestão: o dialog de CPF duplicado, ao detectar que o Usuario correspondente está em Situacao = ‘C’ com Hash nulo, exibe uma terceira orientação — “Você tem um convite pendente. Verifique seu e-mail para completar seu cadastro” — em vez de (ou além de) “Fazer login”/“Recuperar senha”
Recuperação: Pessoa localiza o e-mail de convite e usa o link correto

7. Validações de Campos

Campo	Tela	Tipo	Obrigatório	Formato/Regra	Mensagem de erro
CPF (convite)	Cadastro de convite	Texto com máscara	Sim	11 dígitos + validação de dígitos verificadores (RN-CIU-004)	MSG-E2-01 (reaproveitada do E2)
Nome (convite)	Cadastro de convite	Texto	Sim	Mínimo 3 caracteres (mesma regra do E2) — campo NOT NULL em Usuario	MSG-E2-07 (reaproveitada do E2)
E-mail (convite)	Cadastro de convite	E-mail	Sim	Formato válido	MSG-E2-03 (reaproveitada do E2)
Celular (convite)	Cadastro de convite	Texto com máscara	Sim	Máscara parametrizada por país (RN-CIU-020)	MSG-E2-10 (reaproveitada do E2)
Perfil de acesso (convite)	Cadastro de convite	Select	Não	Lista de ClientePerfilAcesso da clínica	N/A
Campos da Etapa 1 (conclusão de cadastro)	Tela de conclusão de cadastro	Diversos	Conforme RN-CIU-003/017-021	Mesmas regras do E2	Mesmas mensagens do E2 (catálogo Seção 10 do E2)
Senha (conclusão de cadastro)	Tela de conclusão de cadastro	Password	Sim	Mesmos critérios do RN-CIU-006	Indicador visual (reaproveitado do E2)
Checkbox de aceite	Tela de aceite do vínculo	Checkbox	Sim (para habilitar o botão)	Boolean	N/A — botão permanece desabilitado

8. Mapeamento de Componentes de Interface

Componente	Variante	Estado(s)	Tokens aplicados	Onde aparece
Input (text)	Bordered	default, focus, error, disabled	input-height: 56px, radius-m (8px), neutral-light border (#BECADC), neutral-darker focus border (#01013B)	CPF, Nome, E-mail, Celular (convite e conclusão de cadastro)
Select	Default	default, open, selected	input-height: 56px, radius-m (8px), neutral-light border	Perfil de acesso (convite)
Button	Primary	default, hover, loading, disabled	btn-height: 40px, primary-pure bg (#00E676), base-pure text (#FFFFFF), radius-m (8px)	Enviar convite (MSG-B3-01), Concluir cadastro (MSG-B3-04), Aceitar vínculo (MSG-B3-02)
Button	Tertiary	default, hover	Transparent bg, primary-pure text (#00E676)	Agora não
Checkbox	Default	default, checked, disabled	20px box, primary-pure (#00E676) quando checked	Checkbox de aceite (MSG-C3-01), “Sou profissional de saúde” (reaproveitado do E2)
Toast	Success, Error	animation: toast-in (300ms)	secondary-dark bg (#0091EA) / error-pure bg (#F44336)	Convite enviado, erro de envio, erro ao aceitar vínculo
Banner/Ícone informativo	Info, Warning	default	secondary-pure (#40C4FF) para info / highlight-pure (#FFC400) para aviso	CPF já cadastrado (MSG-I3-02, informativo); mensagem de bloqueio sem Perfil de acesso (aviso, Seção 4.4)

9. Integração com Backend

9.1 Convite, Conclusão de Cadastro e Aceite

Função	Método	Path	Request Body	Response Body	Códigos HTTP
Criar convite	POST	/api/convites	{ cpf, nome, email, telefone, clientePerfilAcessoId? }	{ usuarioClienteId: uuid, usuarioReaproveitado: boolean }	201, 400, 409 (convite duplicado pendente)
Validar token de convite	GET	/api/convites/validar?token={token}	—	{ valido: boolean, usuarioClienteId: uuid, cpf, nome, email, temSenha: boolean, clienteNome: string }	200, 404 (token inválido), 410 (expirado ou cancelado)
Concluir cadastro via convite	POST	/api/convites/{usuarioClienteId}/completar-cadastro	{ token, nome?, tipoProfissional?, conselho?, dadosAvancados?, senha }	{ success: true }	200, 400, 410 (expirado)
Aceitar vínculo	POST	/api/convites/{usuarioClienteId}/aceitar	{ token }	{ situacao: ‘V’, temPerfilAcesso: boolean }	200, 400, 410 (expirado)
Cancelar convite	DELETE	/api/convites/{usuarioClienteId}	—	{ success: true }	200, 404
Reenviar convite	POST	/api/convites/{usuarioClienteId}/reenviar	—	{ success: true }	200, 404, 410

Nota sobre o endpoint de login (E1): a resposta do endpoint /api/auth/login inclui o campo convitesPendentes: number (já documentado em (CIU-E1), Seção 9.1), calculado como a contagem de UsuarioCliente com Situacao = ‘C’ e RemovidoEm nulo para o usuário autenticado.

9.2 Mapeamento de Tabelas

Tabela	Banco	Situação	Campos utilizados neste épico
Usuario	IpSeguranca	Existente	Id, CPF, Usuario, Nome, eMail, Telefone, Hash, Salt (criado ou reaproveitado pelo convite — RN-CIU-011; atualizado na conclusão de cadastro — RN-CIU-012)
UsuarioCliente	IpSeguranca	Existente, com domínio novo documentado nesta revisão	Id, UsuarioId, ClienteBDId, Situacao (domínio C/V/B — RN-CIU-011), RemovidoEm
ClientePerfilAcesso	IpSeguranca	Existente	Id, Nome, ClienteBDId (popula o select de Perfil de acesso no convite)
ClientePerfilAcessoUsuario	IpSeguranca	Existente	Id, ClientePerfilAcessoId, UsuarioClienteId (consultado na RN-CIU-015; pode ser criado já no convite se o administrador pré-selecionar um perfil)

[PROPOSTA — campos novos na tabela UsuarioCliente, não existentes em EsquemaGemed21.csv]

Campo (proposto)	Tipo (proposto)	Observação
TokenConvite	varchar(100), YES	Token único do convite, preenchido apenas enquanto Situacao = ‘C’
DataExpiracaoConvite	datetimeoffset, YES	Prazo de validade do convite (RN-CIU-024), preenchido apenas enquanto Situacao = ‘C’

Por que dois campos novos em UsuarioCliente, e não uma tabela nova ou o campo Token já existente em Usuario: Usuario já tem um campo Token (varchar 1000), mas é um único campo por pessoa — não comporta uma pessoa com convites pendentes de mais de uma clínica ao mesmo tempo, cada um com seu próprio prazo de validade. Como UsuarioCliente já é uma linha por relação usuário-clínica, os campos de token e expiração pertencem naturalmente a ela. Esta é uma proposta bem mais enxuta do que a tabela Convite cogitada na versão anterior deste épico — e substitui aquela proposta integralmente.

Correção de modelagem em relação à versão anterior: a versão 1.x deste épico propunha uma tabela nova chamada Convite. Essa proposta foi descartada nesta revisão, a pedido do solicitante — a solução adotada usa apenas a tabela UsuarioCliente já existente, com um domínio novo no campo Situacao e dois campos novos (acima). Nenhuma tabela nova é necessária.

10. Catálogo de Mensagens do Sistema (Multilíngue)

10.1 Mensagens de erro

ID	Contexto	pt-BR	en-US	es-419
MSG-E3-01	Convite duplicado pendente	”Já existe um convite pendente para este CPF nesta clínica."	"There is already a pending invitation for this CPF at this clinic."	"Ya existe una invitación pendiente para este CPF en esta clínica.”
MSG-E3-02	Falha no envio do e-mail de convite	”Não foi possível enviar o e-mail de convite. Tente novamente."	"Could not send the invitation email. Please try again."	"No fue posible enviar el correo de invitación. Inténtelo de nuevo.”
MSG-E3-03	Link de convite expirado	”Este convite expirou. Entre em contato com o administrador da sua clínica para receber um novo convite."	"This invitation has expired. Contact your clinic’s administrator to receive a new invitation."	"Esta invitación ha expirado. Comuníquese con el administrador de su clínica para recibir una nueva invitación.”
MSG-E3-04	Link de convite cancelado	”Este convite não é mais válido. Entre em contato com o administrador da sua clínica."	"This invitation is no longer valid. Contact your clinic’s administrator."	"Esta invitación ya no es válida. Comuníquese con el administrador de su clínica.”
MSG-E3-05	Erro ao aceitar vínculo	”Não foi possível concluir o vínculo com a clínica. Tente novamente."	"Could not complete the link with the clinic. Please try again."	"No fue posible completar el vínculo con la clínica. Inténtelo de nuevo.”

10.2 Mensagens de sucesso

ID	Contexto	pt-BR	en-US	es-419
MSG-S3-01	Convite enviado com sucesso	”Convite enviado com sucesso!"	"Invitation sent successfully!"	"¡Invitación enviada con éxito!“

10.3 Mensagens informativas

ID	Contexto	pt-BR	en-US	es-419
MSG-I3-01	Bloqueio — sem Perfil de acesso após aceite	”Seu vínculo com a clínica foi confirmado, mas você ainda não tem um perfil de acesso definido. Aguarde ou entre em contato com o administrador da clínica."	"Your link with the clinic has been confirmed, but you don’t have an access profile defined yet. Please wait or contact the clinic’s administrator."	"Su vínculo con la clínica ha sido confirmado, pero aún no tiene un perfil de acceso definido. Espere o comuníquese con el administrador de la clínica.”
MSG-I3-02	CPF já cadastrado (cadastro de convite)	“Este CPF já pertence a um usuário cadastrado no Gemed. O convite será associado à conta existente."	"This CPF already belongs to a registered Gemed user. The invitation will be linked to the existing account."	"Este CPF ya pertenece a un usuario registrado en Gemed. La invitación se asociará a la cuenta existente.”

10.4 Textos orientadores

ID	Contexto	pt-BR	en-US	es-419
MSG-T3-02	Tela de aceite — regras básicas (placeholder)	[PROPOSTA — texto completo não fornecido pelo solicitante] “Antes de continuar, leia as regras básicas de uso do Gemed."	"Before continuing, read the basic rules for using Gemed."	"Antes de continuar, lea las reglas básicas de uso de Gemed.”

10.5 Rótulos de botões e links

ID	Elemento	pt-BR	en-US	es-419
MSG-B3-01	Botão (cadastro de convite)	“Enviar convite"	"Send invitation"	"Enviar invitación”
MSG-B3-02	Botão (tela de aceite)	“Aceitar vínculo"	"Accept link"	"Aceptar vínculo”
MSG-B3-03	Link (tela de aceite)	“Agora não"	"Not now"	"Ahora no”
MSG-B3-04	Botão (conclusão de cadastro)	“Concluir cadastro"	"Complete registration"	"Finalizar registro”