# É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.1 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:

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 (Seção 4.2).
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 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).
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'.

**[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:

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

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

Como é atendido: O cadastro de convite (Seção 4.1) é 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), atendendo ao requisito de forma mais direta do que a versão anterior deste épico (que só criava um registro de convite, não o usuário em si).

### NGS1.03.03 — Gerenciamento de perfis

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

Como é atendido: 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 (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

Como é atendido: A mensagem de bloqueio da Seção 4.4 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 (Clínica/ambulatório) — obrigatório

Como é atendido: 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, preservando 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.

---

## 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 — dois campos novos em UsuarioCliente, 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)|
|Tabelas utilizadas|4, todas existentes (Usuario, UsuarioCliente, ClientePerfilAcesso, ClientePerfilAcessoUsuario) — nenhuma tabela nova; 2 campos novos propostos em UsuarioCliente|
|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. Seleção opcional de Perfil de acesso no momento da criação do convite (RN-CIU-011)
2. Prazo de expiração de convite — sugestão de 7 dias, não confirmada (RN-CIU-024)
3. Rotina de exclusão lógica em cascata (Usuario + UsuarioCliente) quando o convite expira e o Usuario nunca teve senha definida (RN-CIU-024)
4. Conteúdo textual completo das "regras básicas de uso" na tela de aceite (MSG-T3-02)
5. Mecanismo de contato com o administrador na mensagem de bloqueio (Seção 4.4) — canal não especificado
6. Tratamento do CPF duplicado quando a pessoa tenta se auto-cadastrar pelo E2 tendo um convite pendente (EX-E3-07)
7. Os dois campos novos propostos em UsuarioCliente (TokenConvite, DataExpiracaoConvite) — nomes e tipos são proposta, não confirmação

---

## 13. 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 (Seção 4.2), 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) precisa ser corrigida para exigir Situacao = 'V' na definição de "vínculo ativo"; E2 deixa de mencionar convite (reversão das alterações da v1.5).
- **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).