# É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 (aceite do vínculo) Versão: 1.1 (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 prévio de CPF + e-mail de um profissional pelo administrador/RH da clínica, disparando um convite
- Envio de e-mail de convite com link de acesso
- Pré-preenchimento do auto-cadastro (E2) quando o convidado ainda não possui conta
- Roteamento para o login (E1) quando o convidado já possui conta
- Tela de aceite do vínculo — leitura das regras básicas do sistema e aceite explícito
- Criação do vínculo (UsuarioCliente) mediante aceite
- Verificação de Perfil de acesso associado ao vínculo recém-criado, com mensagem de bloqueio orientativa caso ausente
- Expiração e cancelamento de convites

### 1.2 Dependências

Este épico depende do E1 (Núcleo de Identidade e Autenticação) — reaproveita o mecanismo de autenticação e roteamento pós-login (Seção 4.1 do E1) para decidir, a cada login, se existe um convite pendente a ser tratado antes do roteamento padrão. Depende também do E2 (Auto-cadastro Público) — a tela de auto-cadastro é reaproveitada, com pré-preenchimento condicional, quando o convidado ainda não tem conta. A regra transversal RN-CIU-022 (documento guarda-chuva, Seção 5) é o ponto de integração entre os três épicos: ela decide, tanto após o auto-cadastro (E2) quanto após o login (E1), se existe convite pendente e direciona para a tela de aceite deste épico antes de qualquer outro destino.

### 1.3 Paralelização

Diferente de E1 e E2 (que podem ser construídos em paralelo entre si), o E3 depende de ambos já existirem — precisa do mecanismo de autenticação do E1 e do wizard de auto-cadastro do E2 para se integrar. O formulário de convite (visão do administrador) e a tela de aceite do vínculo podem ser desenvolvidos em paralelo entre si, mas a integração final (RN-CIU-022 reescrita) depende de E1 e E2 estarem finalizados — o que já é o caso.

---

## 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 — reaproveitada indiretamente quando o convite leva ao E2), 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 — reescrita nesta revisão para cobrir o mecanismo descrito neste épico) — redação completa no documento guarda-chuva (Check-In de usuários no sistema), Seção 5.

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

O administrador da clínica pode pré-cadastrar um profissional que ainda não possui vínculo com a clínica, informando no mínimo CPF e e-mail no cadastro de usuários da clínica. Esse cadastro prévio dispara um convite: um e-mail é enviado ao endereço informado, contendo um link de acesso ao Gemed.

Convite não é vínculo. O convite apenas registra a intenção da clínica de vincular a pessoa — o vínculo em si só é criado quando a pessoa aceita explicitamente (RN-CIU-014). Até o aceite, a pessoa convidada não tem qualquer acesso à clínica.

**[PROPOSTA de estrutura de dados — ver Seção 9.2].** A tabela UsuarioCliente (que hoje representa o vínculo) exige um UsuarioId já existente (campo NOT NULL) — por isso não pode representar um convite feito a alguém que ainda não tem conta. É necessária uma tabela nova para armazenar o convite antes do aceite.

**[PROPOSTA — não confirmado pelo solicitante]** No momento de criar o convite, o administrador pode opcionalmente já selecionar um Perfil de acesso a ser associado ao vínculo quando ele for criado. Se o administrador não selecionar, o vínculo é criado sem perfil no aceite, e a pessoa recebe a mensagem de bloqueio da RN-CIU-015 até que um perfil seja atribuído posteriormente.

### RN-CIU-012 — Pré-preenchimento do auto-cadastro via convite

Quando a pessoa convidada ainda não possui conta no Gemed, o link do e-mail de convite leva à tela inicial do auto-cadastro (E2, Seção 4.1, Etapa 1) com os campos CPF e e-mail já preenchidos conforme os dados informados pelo administrador no convite (RN-CIU-011).

**[PROPOSTA — não confirmado explicitamente pelo solicitante]** Os campos CPF e e-mail pré-preenchidos ficam bloqueados para edição nesta entrada específica, para preservar a correspondência entre o cadastro criado e o convite que o originou. Se a pessoa precisar corrigir um desses dados, deve entrar em contato com o administrador que criou o convite — não há campo de edição direta nesta tela.

### RN-CIU-023 — Convite para CPF já cadastrado

**[PROPOSTA — cenário não descrito explicitamente pelo solicitante; necessário para cobrir o caso de uma pessoa que já tem conta no Gemed e é convidada por uma nova clínica]**

Se o CPF informado no convite (RN-CIU-011) já corresponde a um usuário ativo no Gemed, o link do e-mail de convite leva à tela de login (E1) em vez do auto-cadastro (E2) — a pessoa já tem conta, não precisa criar uma nova. Após autenticação bem-sucedida, o roteamento por convite pendente (RN-CIU-022, documento guarda-chuva) direciona a pessoa para a tela de aceite do vínculo (RN-CIU-014), da mesma forma que ocorreria após um auto-cadastro novo.

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

Ao concluir o auto-cadastro (E2) ou o login (E1) havendo um convite pendente para o CPF do 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 do profissional — nunca implícito no simples fato de se cadastrar ou fazer login.

Ao aceitar, o sistema:

1. Cria o vínculo — um registro em UsuarioCliente associando o usuário à clínica (ClienteBDId) do convite
2. Atualiza o status do convite para "Aceito"
3. 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, recusa), o convite permanece pendente e ele pode aceitá-lo em um acesso futuro — a recusa não é tratada nesta versão como uma ação definitiva. **[PROPOSTA — comportamento de recusa explícita não descrito pelo solicitante; ver Seção 6, fluxo de exceção EX-E3-05]**

### 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 recém-criado (registro em ClientePerfilAcessoUsuario referenciando o UsuarioClienteId do vínculo):

- **Se existe** — o profissional é direcionado para sua tela inicial, seguindo o mesmo mecanismo de roteamento por cockpit descrito em RN-CIU-009 (documento guarda-chuva/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 (perfil de acesso por clínica, ligado ao usuário 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, épico E2) — e não tem relação com o que é verificado aqui. O cockpit de destino (linha "Se existe", acima) é 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

**[PROPOSTA — parâmetros e comportamento não confirmados pelo solicitante]**

Convites possuem um prazo de validade parametrizável (sugestão inicial: 7 dias, a confirmar). Após o prazo expirar sem aceite, o convite deixa de ser válido — o link do e-mail não funciona mais, e a pessoa passa a ser tratada como se não houvesse convite pendente (ex.: se tentar se auto-cadastrar do zero pela tela pública do E2, segue o fluxo padrão, sem pré-preenchimento).

O administrador pode cancelar manualmente um convite pendente a qualquer momento antes do aceite. Convite cancelado também invalida o link do e-mail correspondente.

---

## 3. Histórias de Usuário

### US-CIU-004 — Administrador convida profissional

Como administrador da clínica, quero pré-cadastrar o CPF e e-mail de um profissional e disparar um convite, para formalizar seu vínculo com a clínica assim que ele aceitar.

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

Como profissional convidado, quero 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 com meu perfil de acesso definido pelo administrador.

---

## 4. Descrição Funcional Detalhada

### 4.1 Cadastro de Convite (visão do administrador)

Propósito: Permitir que o administrador da clínica pré-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. **[PROPOSTA]** A tela completa de gestão de usuários da clínica é matéria para um épico ou funcionalidade futura, fora do escopo do Check-in de Usuários.

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 "E-mail" — input email, validação de formato
- **[PROPOSTA]** Campo "Perfil de acesso" (select, opcional) — lista de perfis (ClientePerfilAcesso) cadastrados para a clínica, carregada dinamicamente. Se o administrador selecionar um perfil aqui, ele é associado ao vínculo automaticamente no momento do aceite (RN-CIU-011)
- Botão primário "Enviar convite" (MSG-B3-01)

Comportamento:

- Ao sair do campo CPF, o sistema verifica se já existe um convite pendente para o mesmo CPF nesta clínica. Se existir, exibe mensagem MSG-E3-01 e impede o envio de um convite duplicado
- Ao enviar, o sistema cria o registro de convite, gera um token único, dispara o e-mail com o link (contendo o token) e exibe toast de sucesso MSG-S3-01
- O botão "Enviar convite" fica desabilitado até CPF e e-mail estarem preenchidos e válidos

Decisão de design: O formulário de convite é deliberadamente mínimo (CPF + e-mail) para reduzir o atrito do administrador — a burocracia de contratação (que gera esses dados) já aconteceu fora do sistema; o Gemed só precisa do mínimo para identificar a pessoa e disparar o convite. O campo de Perfil de acesso é opcional para não obrigar o administrador a decidir isso no mesmo instante — ele pode formalizar o vínculo primeiro e atribuir o perfil depois, sem bloquear o convite.

### 4.2 Tela de Auto-cadastro Pré-preenchida (extensão do E2)

Reaproveita integralmente a tela de auto-cadastro do E2 ((CIU-E2), Seção 4.1), com as seguintes diferenças quando acessada via link de convite:

- Campos CPF e e-mail (Etapa 1) vêm preenchidos com os dados do convite e ficam bloqueados para edição (RN-CIU-012)
- Texto orientador adicional no topo da Etapa 1, informando que o cadastro está associado a um convite da clínica que o originou (MSG-T3-01) **[PROPOSTA — texto exato e exibição do nome da clínica não confirmados pelo solicitante; a exibição do nome da clínica depende de o backend do convite devolver o nome, não apenas o ClienteBDId]**
- Ao concluir o cadastro (Etapa 3, "Finalizar cadastro"), a autenticação automática (RN-CIU-022) direciona para a tela de aceite do vínculo (Seção 4.3 deste épico) em vez de Meu Perfil, pois há um convite pendente

Todo o restante do wizard (validações, etapas, catálogo de mensagens) permanece inalterado em relação ao E2.

### 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 das regras não foi fornecido pelo solicitante; aqui documenta-se apenas a existência do bloco de texto e o mecanismo de aceite, não seu conteúdo jurídico]**
- 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
- **[PROPOSTA]** Link/botão secundário "Agora não" — permite adiar o aceite sem recusar definitivamente o convite (ver RN-CIU-014, comportamento de não-aceite)

Comportamento:

- Ao marcar o checkbox, o botão "Aceitar vínculo" é habilitado
- Ao clicar em "Aceitar vínculo": cria o registro de vínculo (UsuarioCliente), atualiza o status do convite para "Aceito", executa a verificação de Perfil de acesso (RN-CIU-015) e direciona o profissional conforme o resultado — para o cockpit do seu tipo de profissional (se há perfil) ou para a tela de bloqueio (Seção 4.4, se não há perfil)
- Se o profissional clicar em "Agora não", retorna à sua página atual (Meu Perfil, se veio do auto-cadastro) sem criar o vínculo; o convite permanece pendente e 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: O aceite exige uma ação explícita (checkbox + botão) em vez de ser automático, porque o vínculo tem implicações reais de acesso a dados de pacientes da clínica — o profissional precisa confirmar conscientemente que está ciente disso, alinhado com o princípio de consentimento informado já aplicado a outras áreas do Gemed (ex.: consentimento de paciente, SBIS NGS1.11.05). A opção "Agora não" evita forçar uma decisão imediata em um momento potencialmente inconveniente (ex.: a pessoa só queria criar a conta e ainda não está pronta para se comprometer com a clínica).

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

Propósito: Informar o profissional, de forma clara e não alarmante, que o vínculo foi aceito mas o acesso à clínica ainda depende de uma etapa administrativa.

Layout:

- Ícone de aviso (não de erro — círculo amarelo/highlight, não vermelho/error)
- Texto: MSG-I3-01
- **[PROPOSTA — mecanismo de contato não especificado pelo solicitante]** Texto orientando a aguardar ou contatar o administrador da clínica, sem um canal de contato específico definido nesta versão (poderia ser e-mail, telefone ou chat — não documentado)

Comportamento: esta tela substitui o cockpit/perfil normalmente carregado após o roteamento pós-aceite. O profissional permanece com a conta ativa e pode navegar para Meu Perfil (E4), mas não tem acesso às funcionalidades da clínica que o convidou até que um Perfil de acesso seja associado ao seu vínculo.

Decisão de design: o ícone de aviso (não de erro) e o tom informativo evitam alarmar o profissional — a ausência de perfil não é uma falha do sistema nem do profissional, é uma etapa administrativa pendente do lado 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 um CPF válido e um e-mail válido e clico em "Enviar convite", então o sistema cria o convite, envia o e-mail e exibe o toast de sucesso MSG-S3-01.

**CA-004.2**: Dado que já existe um convite pendente para o CPF informado nesta clínica, quando tento enviar um novo convite para o mesmo CPF, então o sistema exibe a mensagem MSG-E3-01 e não cria um convite duplicado.

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

**CA-004.4**: Dado que não selecionei nenhum Perfil de acesso ao criar o convite, quando o profissional aceita o vínculo, então ele vê a mensagem de bloqueio orientando a aguardar ou contatar o administrador.

**CA-004.5**: Dado que o CPF do convite já corresponde a um usuário ativo no Gemed, quando o link do e-mail é acessado, então o sistema direciona para a tela de login (E1), não para o auto-cadastro (E2).

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

**CA-005.1**: Dado que concluí o auto-cadastro (E2) e havia um convite pendente para meu CPF, quando o cadastro é finalizado, então sou direcionado para a tela de aceite do vínculo, não para Meu Perfil.

**CA-005.2**: Dado que fiz login (E1) e havia um convite pendente para meu CPF, 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.3**: Dado que estou na tela de aceite do vínculo, quando marco o checkbox de aceite, então o botão "Aceitar vínculo" é habilitado.

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

**CA-005.5**: 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.6**: Dado que estou na tela de aceite do vínculo, quando clico em "Agora não", então o vínculo não é criado, o convite permanece pendente, e retorno à minha página atual.

**CA-005.7**: Dado que o convite associado ao meu CPF expirou (RN-CIU-024), quando acesso o sistema, então não sou mais direcionado para a tela de aceite — o convite é tratado como inexistente.

---

## 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 que já possui convite pendente 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, mas o e-mail não foi confirmado como enviado
- Recuperação: Administrador pode reenviar o convite (ação "Reenviar convite" — **[PROPOSTA]** não detalhada nesta versão)

### EX-E3-03 — Link de convite expirado

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

### 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 sem criar o vínculo. O convite permanece pendente
- Recuperação: A tela de aceite é exibida novamente no próximo login ou auto-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 criar o registro de vínculo (UsuarioCliente) 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

---

## 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 (mesma regra do RN-CIU-004)|MSG-E2-01 (reaproveitada do E2)|
|E-mail (convite)|Cadastro de convite|E-mail|Sim|Formato válido|MSG-E2-03 (reaproveitada do E2)|
|Perfil de acesso (convite)|Cadastro de convite|Select|Não|Lista de ClientePerfilAcesso da clínica|N/A|
|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 e e-mail (convite); CPF e e-mail pré-preenchidos e desabilitados na tela de auto-cadastro via convite|
|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), 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)|
|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|Warning|default|highlight-pure (#FFC400) — não error-pure, para não alarmar|Mensagem de bloqueio — sem Perfil de acesso (Seção 4.4)|

---

## 9. Integração com Backend

### 9.1 Convite e Aceite

|Função|Método|Path|Request Body|Response Body|Códigos HTTP|
|---|---|---|---|---|---|
|Criar convite|POST|/api/convites|{ cpf: string, email: string, clientePerfilAcessoId?: uuid }|{ id: uuid }|201, 400 (dados inválidos), 409 (convite duplicado pendente)|
|Validar token de convite|GET|/api/convites/validar?token={token}|—|{ valido: boolean, cpf: string, email: string, clienteNome: string, usuarioJaCadastrado: boolean }|200, 404 (token inválido), 410 (expirado ou cancelado)|
|Aceitar vínculo|POST|/api/convites/{id}/aceitar|{ token: string }|{ vinculoId: uuid, temPerfilAcesso: boolean }|200, 400, 404, 410 (expirado)|
|Cancelar convite|DELETE|/api/convites/{id}|—|{ success: true }|200, 404|
|**[PROPOSTA]** Reenviar convite|POST|/api/convites/{id}/reenviar|—|{ success: true }|200, 404, 410 (não é possível reenviar convite expirado — deve-se criar um novo)|

Nota sobre o endpoint de login (E1): conforme já documentado em (CIU-E1), Seção 9.1, a resposta do endpoint `/api/auth/login` inclui o campo `convitesPendentes: number`. Este épico é quem passa a consumir esse campo — se `convitesPendentes > 0`, o front-end direciona para a tela de aceite do vínculo (RN-CIU-022) antes de aplicar o roteamento padrão por vínculos.

### 9.2 Mapeamento de Tabelas

|Tabela|Banco|Situação|Campos utilizados neste épico|
|---|---|---|---|
|Usuario|IpSeguranca|Existente|Id, CPF, eMail (consulta para RN-CIU-023 — verificar se o CPF do convite já corresponde a um usuário)|
|UsuarioCliente|IpSeguranca|Existente|Id, UsuarioId, ClienteBDId, Situacao, RemovidoEm (criado no aceite do vínculo — RN-CIU-014)|
|ClientePerfilAcesso|IpSeguranca|Existente|Id, Nome, ClienteBDId (consultado para popular o select de Perfil de acesso no cadastro de convite)|
|ClientePerfilAcessoUsuario|IpSeguranca|Existente|Id, ClientePerfilAcessoId, UsuarioClienteId (consultado na verificação da RN-CIU-015; criado automaticamente no aceite se o administrador pré-selecionou um perfil no convite)|
|**Convite**|IpSeguranca|**[PROPOSTA — tabela nova, não existe em EsquemaGemed21.csv]**|Ver detalhamento abaixo|

**Detalhamento da tabela proposta `Convite` (IpSeguranca):**

Segue o mesmo padrão de auditoria observado em todas as tabelas existentes do banco IpSeguranca (Id uniqueidentifier, CriadoEm/AtualizadoEm/RemovidoEm datetimeoffset, UsuarioIdCriado/UsuarioIdAtualizado/UsuarioIdRemovido, IpInserido/IpAtualizado/IpRemovido, Latitude/Longitude ×3, Committed bit).

|Campo (proposto)|Tipo (proposto)|Observação|
|---|---|---|
|Id|uniqueidentifier|Chave primária, seguindo o padrão das demais tabelas|
|CPF|varchar(11)|CPF da pessoa convidada — pode ainda não existir em Usuario|
|eMail|varchar(50)|E-mail informado pelo administrador no convite, usado para envio e pré-preenchimento|
|ClienteBDId|uniqueidentifier|Clínica que originou o convite (mesmo padrão de campo usado em UsuarioCliente e ClientePerfilAcesso)|
|ClientePerfilAcessoId|uniqueidentifier, YES (nulo permitido)|Perfil pré-selecionado pelo administrador no momento do convite (RN-CIU-011) — opcional|
|TokenConvite|varchar(100)|Token único usado no link do e-mail de convite|
|Status|char(1)|P = Pendente, A = Aceito, E = Expirado, C = Cancelado (segue o padrão de campos char curtos já usado em Situacao/Status de outras tabelas)|
|DataExpiracao|datetimeoffset|Prazo de validade do convite (RN-CIU-024)|
|UsuarioClienteId|uniqueidentifier, YES (nulo permitido)|Preenchido no aceite, referenciando o vínculo criado (RN-CIU-014)|
|+ campos de auditoria padrão|—|Ver acima|

Esta proposta segue a convenção de nomenclatura e a estrutura de auditoria já observadas em todas as tabelas de IpSeguranca consultadas em EsquemaGemed21.csv, mas é uma criação nova — nenhuma tabela equivalente existe hoje no schema. Precisa de validação e ajuste na Fase 3/4 (Mapeamento de Banco de Dados) com a equipe responsável pelo banco.

---

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

### 10.4 Textos orientadores

|ID|Contexto|pt-BR|en-US|es-419|
|---|---|---|---|---|
|MSG-T3-01|Auto-cadastro via convite — texto orientador|"Você foi convidado por [clínica] para se cadastrar no Gemed. Complete seus dados para continuar."|"You were invited by [clinic] to register on Gemed. Complete your details to continue."|"Fue invitado por [clínica] para registrarse en Gemed. Complete sus datos para continuar."|
|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"|

### 10.6 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]"|

---

## 11. Conformidade SBIS

### NGS1.03.08 — Gerenciamento de usuários

Estágio: 1 (Clínica/ambulatório) — obrigatório

Descrição do requisito: "O S-RES deve permitir o gerenciamento (cadastro, ativação/inativação e alteração de cadastro) de usuários, por meio da aplicação."

Como é atendido neste épico: O cadastro de convite (Seção 4.1) é a porta de entrada do gerenciamento de usuários pelo administrador da clínica — permite que ele inicie o processo de vínculo de um novo profissional pela própria aplicação, sem intervenção externa.

### NGS1.03.03 — Gerenciamento de perfis

Estágio: 1 (Clínica/ambulatório) — obrigatório

Descrição do requisito: resumidamente, o S-RES deve permitir o gerenciamento de perfis e a atribuição de permissões específicas a eles.

Como é atendido: Este épico não implementa a tela de gerenciamento de perfis em si (ClientePerfilAcesso já existe no schema, presumivelmente gerenciado em uma funcionalidade do Contexto de Segurança, fora do escopo do Check-in de Usuários), mas consome esse gerenciamento diretamente — tanto na seleção de perfil ao criar o convite (Seção 4.1) quanto na verificação pós-aceite (RN-CIU-015).

### NGS1.03.01 — Impedir acesso por pessoas não autorizadas

Estágio: 1 (Clínica/ambulatório) — obrigatório

Descrição do requisito: "Todo acesso ou visualização de dados do S-RES deve ser realizado apenas por usuários previamente autorizados. Tal autorização deve ser provida por meio de permissões atribuídas a perfis de usuário."

Como é atendido: A mensagem de bloqueio da Seção 4.4 é a aplicação direta deste requisito — um profissional com vínculo aceito mas sem Perfil de acesso associado não recebe acesso às funcionalidades da clínica, mesmo estando autenticado e vinculado.

### NGS1.03.09 — Identidade única da pessoa e responsabilização

Estágio: 1 (Clínica/ambulatório) — obrigatório

Como é atendido: O convite reaproveita a validação de CPF (dígitos verificadores) já documentada em RN-CIU-004 (E2), e a verificação de CPF já cadastrado (RN-CIU-023) impede que a mesma pessoa acabe com duas contas — o roteamento para login em vez de auto-cadastro garante a unicidade de identidade mesmo no fluxo de convite.

### ECF.17.19 — Mensagens do sistema

Estágio: 1 (Clínica/ambulatório) — obrigatório

Como é atendido: Todas as mensagens exibidas ao usuário estão catalogadas na Seção 10, em linguagem não técnica, em português do Brasil, com suporte multilíngue para en-US e es-419.

### Requisito relacionado, não implementado neste épico

NGS1.03.07 (Atribuição de mais de um perfil para um usuário, estágio 1) e NGS1.03.11 (Restrição de autoconcessão de direitos, estágio 1) são requisitos relevantes ao tema de perfis de acesso, mas dizem respeito à gestão de perfis em si (múltiplos perfis simultâneos, controle contra autoconcessão), não ao fluxo de convite e aceite documentado aqui. Ficam registrados como referência para quando a funcionalidade de gerenciamento de perfis for especificada (fora do escopo do Check-in de Usuários).

---

## 12. 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 — introduz tabela nova (Convite), dois pontos de entrada (auto-cadastro e login), integração transversal com E1 e E2 via RN-CIU-022|
|Dependências|E1 (mecanismo de autenticação e roteamento), E2 (wizard de auto-cadastro, pré-preenchido)|
|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)|
|Paraleliza com|Parcialmente — formulário de convite e tela de aceite podem ser construídos em paralelo entre si, mas a integração final depende de E1 e E2|
|Histórias de usuário|2 (US-CIU-004, US-CIU-005)|
|Critérios de aceitação|12 (CA-004.1 a CA-004.5, CA-005.1 a CA-005.7)|
|Fluxos de exceção|6 (EX-E3-01 a EX-E3-06)|
|Endpoints|5 (4 confirmados + 1 proposto — reenviar convite)|
|Telas|3 (Cadastro de convite, Tela de aceite do vínculo, Mensagem de bloqueio — sem Perfil de acesso) + 1 extensão de tela existente (auto-cadastro pré-preenchido)|
|Tabelas utilizadas|4 existentes (Usuario, UsuarioCliente, ClientePerfilAcesso, ClientePerfilAcessoUsuario) + 1 proposta (Convite)|
|Mensagens catalogadas|11 (5 erros, 1 sucesso, 1 informativa, 2 textos orientadores, 3 rótulos de botão/link, 1 rótulo de checkbox — total 11, ver Seção 10)|
|Requisitos SBIS atendidos|4 (NGS1.03.08, NGS1.03.03, NGS1.03.01, NGS1.03.09) + ECF.17.19|
|Itens marcados [PROPOSTA]|9 — ver lista consolidada abaixo|

### Lista consolidada de itens marcados [PROPOSTA] neste épico

Para facilitar a revisão e confirmação pelo solicitante, todos os pontos que envolvem inferência ou decisão não explicitamente confirmada estão listados aqui:

1. Estrutura completa da tabela nova `Convite` (Seção 9.2) — campos, tipos e convenção de auditoria seguem o padrão observado no schema, mas a tabela em si não existe hoje
2. Seleção opcional de Perfil de acesso no momento da criação do convite (RN-CIU-011, Seção 4.1)
3. Bloqueio de edição dos campos CPF/e-mail pré-preenchidos no auto-cadastro via convite (RN-CIU-012)
4. Cenário completo de "convite para CPF já cadastrado" — roteamento para login em vez de auto-cadastro (RN-CIU-023)
5. Comportamento de "Agora não" / adiamento do aceite (RN-CIU-014, Seção 4.3)
6. Parâmetros e comportamento de expiração/cancelamento de convite (RN-CIU-024) — prazo de 7 dias é sugestão, não confirmação
7. Conteúdo textual completo das "regras básicas de uso" exibidas na tela de aceite (MSG-T3-02)
8. Mecanismo de contato com o administrador na mensagem de bloqueio (Seção 4.4) — canal não especificado
9. Endpoint de reenvio de convite (Seção 9.1) — não detalhado em profundidade

Nenhum destes itens contradiz o que foi descrito pelo solicitante — são extensões e detalhamentos necessários para completar o fluxo, e devem ser confirmados antes da implementação.

---

E3 v1.0 (27/08/2026): versão original, elaborada a partir da correção de RN-CIU-022 (documento guarda-chuva, v2.2).

E3 v1.1 (27/08/2026, mesmo dia): duas correções do solicitante aplicadas à RN-CIU-015 (Seção 2). Primeira: o projeto não possui o documento DOC-001 (Contexto Segurança) acessível — removida a referência a ele e à RN-SEG-003-B, que hedgeava a nota de terminologia sobre "Perfil de acesso". Segunda: esclarecido que "Perfil de acesso" e "perfil profissional" são conceitos distintos — Perfil de acesso é o conjunto de funcionalidades do sistema que o usuário pode acessar (tabela ClientePerfilAcesso); perfil profissional são as características do profissional (tipo, conselho — RN-CIU-017/019, E2). A nota de terminologia da RN-CIU-015 foi reescrita para deixar essa distinção clara, sem ressalva pendente.