# É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: 3.1 Data: 27/08/2026

---

## 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 (confirmado pelo solicitante em 27/08/2026). 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.

**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): 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:** "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; confirmado pelo solicitante em 27/08/2026).

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.

---

## SEÇÃO 2 — ESPECIFICAÇÃO

### 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.

### Descrição Funcional Detalhada

#### 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. 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, edição de perfis, desativação — não é o foco deste épico, que documenta 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)
- 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) 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 vínculo (UsuarioCliente, Situacao = 'C') e o registro de token de convite, dispara o e-mail e exibe toast de sucesso MSG-S3-01

**Motivador:** o formulário inclui nome e celular além de CPF e e-mail porque o administrador normalmente tem esses dados em mãos no momento da contratação/onboarding, 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.

#### 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.

**Motivador:** 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.

#### Tela de Aceite do Vínculo

Propósito: permitir que o profissional aceite formalmente o vínculo com a clínica que o convidou (aplica-se apenas a quem não tem nenhum vínculo ativo — RN-CIU-014).

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)

**Motivador:** o aceite exige uma ação explícita porque o vínculo implica acesso a dados de pacientes da clínica.

#### Mensagem de Bloqueio — Sem Perfil de Acesso

Ícone de aviso (não de erro), texto MSG-I3-01, orientando a aguardar ou contatar o administrador da clínica.

### 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 vínculo (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, 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), não tenho nenhum vínculo ativo 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.

### 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 vínculo já existem), mas o e-mail não foi confirmado como enviado. Recuperação: administrador pode reenviar o convite (gera um novo token, mesmo vínculo).

**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. 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 (confirmado pelo solicitante em 27/08/2026): 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 — por isso 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.

### 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|

### 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)|

### Integração com Backend

|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 vínculos (UsuarioCliente) com Situacao = 'C' e RemovidoEm nulo para o usuário autenticado.

### Catálogo de Mensagens do Sistema e Termos de Interface (i18n)

**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."|

**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!"|

**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."|

**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."|

**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"|

**Rótulos de checkbox**

|ID|Elemento|pt-BR|en-US|es-419|
|---|---|---|---|---|
|MSG-C3-01|Checkbox (tela de aceite)|"Li e aceito o vínculo com [clínica]"|"I have read and accept the link with [clinic]"|"He leído y acepto el vínculo con [clínica]"|

### Conformidade SBIS (detalhamento)

**NGS1.03.08 — Gerenciamento de usuários** (estágio 1, obrigatório) — o cadastro de convite é o administrador da clínica gerenciando usuários diretamente pela aplicação: cria a conta do profissional (Usuario) e o vínculo com a clínica (UsuarioCliente).

**NGS1.03.03 — Gerenciamento de perfis** (estágio 1, obrigatório) — este épico consome o gerenciamento de perfis (ClientePerfilAcesso, presumivelmente gerenciado em funcionalidade própria do Contexto de Segurança) tanto na seleção de perfil ao criar o convite quanto na verificação pós-aceite (RN-CIU-015).

**NGS1.03.01 — Impedir acesso por pessoas não autorizadas** (estágio 1, obrigatório) — a mensagem de bloqueio (Descrição Funcional) aplica este requisito diretamente: vínculo aceito (Situacao = 'V') sem Perfil de acesso associado não concede acesso às funcionalidades da clínica.

**NGS1.03.09 — Identidade única da pessoa e responsabilização** (estágio 1, obrigatório) — RN-CIU-011 verifica CPF já cadastrado antes de criar um novo Usuario: o administrador nunca cria uma conta duplicada para uma pessoa que já existe no Gemed.

**ECF.17.19 — Mensagens do sistema** (estágio 1, obrigatório) — todas as mensagens exibidas ao usuário estão catalogadas acima, em linguagem não técnica, em português do Brasil, com suporte multilíngue para en-US e es-419.

---

## SEÇÃO 3 — PROTÓTIPO HTML

**Pendente.** Este épico ainda não tem protótipo HTML produzido — telas descritas apenas em Descrição Funcional Detalhada (Seção 2). Telas a prototipar: Cadastro de Convite, Tela de Conclusão de Cadastro, Tela de Aceite do Vínculo, Mensagem de Bloqueio.

---

## SEÇÃO 4 — MAPEAMENTO DE BANCO DE DADOS

### Tabelas existentes utilizadas

|Tabela|Banco|Campos utilizados neste épico|
|---|---|---|
|Usuario|IpSeguranca|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|Id, UsuarioId, ClienteBDId, Situacao (domínio C/V/B — RN-CIU-011), RemovidoEm|
|ClientePerfilAcesso|IpSeguranca|Id, Nome, ClienteBDId (popula o select de Perfil de acesso no convite)|
|ClientePerfilAcessoUsuario|IpSeguranca|Id, ClientePerfilAcessoId, UsuarioClienteId (consultado na RN-CIU-015; pode ser criado já no convite se o administrador pré-selecionar um perfil)|
|UsuarioSenhaParametros|IpSeguranca|Nome, Valor, Tipo, Descrição — nova linha `DiasValidadeConviteVinculo` (Valor 7, Tipo Numero), consultada na criação do convite para calcular `UsuarioClienteConvite.DataExpiracao` (RN-CIU-024). Mesma tabela documentada em RN-CIU-006 (guarda-chuva) para parâmetros de senha — reaproveitada aqui|

### Tabela nova: UsuarioClienteConvite

**Descrição do propósito:** guarda o token de convite e seu prazo de validade, associados 1:1 a um vínculo (UsuarioCliente) em estado convidado. Substitui a proposta anterior de adicionar `TokenConvite` e `DataExpiracaoConvite` como colunas diretamente em `UsuarioCliente` — descartada porque token e expiração não são atributos do vínculo em si (o que `UsuarioCliente` representa, permanentemente, enquanto durar o vínculo entre `Usuario` e `Cliente`); são dados do processo de convite, relevantes só entre o administrador convidar e o profissional aceitar. Depois disso, nunca mais são usados — daí uma tabela complementar, não colunas na entidade principal.

|Campo|Tipo|Tamanho|Obrigatório|Valor padrão|
|---|---|---|---|---|
|UsuarioClienteId|uniqueidentifier|—|Sim (PK, FK)|—|
|Token|varchar|100|Sim|—|
|DataExpiracao|datetimeoffset|—|Sim|—|

- **Chave primária (PK):** UsuarioClienteId — 1 registro por vínculo em processo de convite (não 1 por pessoa: um profissional com convites pendentes de duas clínicas tem dois vínculos UsuarioCliente, logo dois registros aqui, cada um com seu próprio token e prazo).
- **Chave estrangeira (FK):** UsuarioClienteId → UsuarioCliente.Id, ON DELETE CASCADE.
- **Relacionamento:** 1:1 com UsuarioCliente (a PK da tabela nova é a própria FK, sem coluna Id própria).
- **Índices:** índice único sobre Token, para a busca por token na validação do link (RN-CIU-023) não depender de varredura.
- **Ciclo de vida:** criado quando o convite é enviado (RN-CIU-011); atualizado — mesmo registro, novo Token e nova DataExpiracao — ao reenviar o convite; excluído (delete físico, não lógico) quando o vínculo é aceito (RN-CIU-014), cancelado, ou varrido pela rotina de expiração (RN-CIU-024) — a informação não tem uso depois de qualquer um desses três desfechos.
- **Migrations:** Up — cria a tabela com a FK descrita acima. Down — remove a tabela.
- **Seeders:** nenhum para esta tabela — dados sempre gerados em tempo de execução, nunca por seed. A tabela existente `UsuarioSenhaParametros` recebe uma nova linha de seed (`DiasValidadeConviteVinculo`, Valor 7, Tipo Numero) como parte da implantação desta funcionalidade — não é uma tabela nova, mas é um dado que precisa existir antes do primeiro convite ser criado.
- **Impacto em dados existentes:** nenhum na tabela nova, sem dados legados a migrar. Em `UsuarioSenhaParametros` (tabela existente), o impacto é apenas a inserção da nova linha de parâmetro — sem alteração em linhas já existentes.

**Separação de bancos:** UsuarioClienteConvite pertence ao banco IpSeguranca, mesmo banco de UsuarioCliente — mantém a FK dentro do mesmo banco (evita referência lógica entre bancos, ao contrário do que acontece, por necessidade, em outras partes do projeto).

---

## 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|13 (CA-004.1 a CA-004.4, 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|5 existentes (Usuario, UsuarioCliente, ClientePerfilAcesso, ClientePerfilAcessoUsuario, UsuarioSenhaParametros) + 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

---

## HISTÓRICO DE VERSÕES DESTE ÉPICO

- **v1.0** (27/08/2026) — versão original: propunha uma tabela nova `Convite`, separada de UsuarioCliente, e reaproveitava o wizard do E2 (pré-preenchido) para quem não tinha conta.
- **v1.1** (27/08/2026, mesmo dia) — duas correções pontuais: removida referência a DOC-001/RN-SEG-003-B (documento inexistente no projeto); esclarecida a distinção entre Perfil de acesso e perfil profissional (RN-CIU-015).
- **v2.0** (27/08/2026, mesmo dia) — reformulação de arquitetura proposta pelo solicitante: eliminada a tabela `Convite`; o administrador cria o Usuario diretamente (sem senha) e o UsuarioCliente já em estado convidado, usando um domínio novo no campo Situacao (C = Convidado, V = Vinculado, B = Bloqueado — definido pelo solicitante nesta revisão). O wizard do E2 deixa de ser reaproveitado — criada a tela de conclusão de cadastro, própria deste épico. RN-CIU-012 e RN-CIU-023 reescritas; RN-CIU-011 reescrita; RN-CIU-014 ajustada (atualiza Situacao em vez de criar registro). Formulário de convite ampliado para incluir Nome e Celular, a pedido do solicitante. Consequência em outros documentos: RN-CIU-009 (E1) corrigida para exigir Situacao = 'V' na definição de "vínculo ativo"; E2 deixou de mencionar convite.
- **v2.1** (27/08/2026, mesmo dia) — RN-CIU-014 escopada: passa a se aplicar só quando o profissional não tem nenhum vínculo ativo (primeiro convite aceito). Quando já há vínculo ativo e chega um novo convite, o aceite passa para a tela de seleção de clínica (E6, RN-CIU-025 — nova regra, dona do E6), como card, sem releitura das regras básicas. Decisão do solicitante, resolvendo a proposta sinalizada na RN-CIU-022 (guarda-chuva, v2.4) sobre estender a verificação de convite pendente ao login (E1).
- **v3.0** (27/08/2026, mesmo dia) — duas mudanças a pedido do solicitante: (1) reestruturação completa do documento para a Seção 1-4 da Skill Designer (Definição, Especificação, Protótipo, Mapeamento de BD), substituindo a estrutura própria de 12 itens usada até a v2.1 — conteúdo reorganizado, não reescrito; referências a versões anteriores espalhadas pelo corpo (v1.x, "correção em relação à versão anterior" etc.) removidas do corpo e mantidas só aqui, já cobertas pelas entradas acima. (2) proposta de `TokenConvite`/`DataExpiracaoConvite` como colunas em UsuarioCliente rejeitada pelo solicitante — token e prazo de validade não são atributos do vínculo (UsuarioCliente representa a relação Usuario↔Cliente, permanente enquanto durar o vínculo), são dados do processo de convite, úteis só entre o convite e o aceite. Substituída por uma tabela nova, UsuarioClienteConvite (1:1 com UsuarioCliente, excluída fisicamente ao aceitar/cancelar/expirar) — RN-CIU-011 e RN-CIU-024 ajustadas; Seção 4 (Mapeamento de BD) reescrita com a especificação completa da tabela nova.
- **v3.1** (27/08/2026, mesmo dia) — quatro propostas confirmadas pelo solicitante, removidas da lista de `[PROPOSTA]`: (1) seleção opcional de Perfil de acesso no cadastro de convite (RN-CIU-011, campo do formulário) — confirmada como descrita; (2) prazo de validade do convite — confirmado em 7 dias, mas não como valor fixo no texto da regra: passa a ser um parâmetro, `DiasValidadeConviteVinculo` (Valor 7, Tipo Numero), na tabela existente `IpSeguranca.UsuarioSenhaParametros` (mesma tabela de RN-CIU-006, reaproveitada para um parâmetro de outra natureza) — `UsuarioClienteConvite.DataExpiracao` passa a ser calculada a partir desse parâmetro, não mais um número solto no texto; (3) rotina periódica de exclusão lógica em cascata (Usuario + UsuarioCliente) para convites expirados sem senha nunca definida — confirmada como descrita (RN-CIU-024); (4) tratamento do CPF duplicado no auto-cadastro (E2) quando há convite pendente — confirmado como descrito (EX-E3-07). Seção 4 atualizada: `UsuarioSenhaParametros` adicionada às tabelas existentes utilizadas, com nota de seed (nova linha de parâmetro) na tabela `UsuarioClienteConvite`.

---

_Documento elaborado em 27 de agosto de 2026. As informações contidas são de responsabilidade do solicitante._