# Épico 3 — Convite e Vínculo — Mapeamento de Banco de Dados (v3.3)

**Documentos deste épico:** [01 - Definição](./01%20-%20Defini%C3%A7%C3%A3o%20v3.3.md) (v3.3) · [02 - Especificação](./02%20-%20Especifica%C3%A7%C3%A3o%20v3.3.md) (v3.3) · Protótipo (Seção 3): **pendente**, ainda não produzido — telas a prototipar: Cadastro de Convite, Tela de Conclusão de Cadastro, Tela de Aceite do Vínculo, Mensagem de Bloqueio · [04 - Mapeamento de Banco de Dados](./04%20-%20Mapeamento%20de%20Banco%20de%20Dados%20v3.3.md) (v3.3). Este épico faz parte do documento guarda-chuva [Check-in de Usuários](../00%20-%20Guarda-chuva%20v2.11.md).

---

## SEÇÃO 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)|
|ClienteEmpresa|IpSeguranca|Id, Nome, CaminhoLogo, ClienteBDId (popula o multi-select de Clínica(s) no convite; cada registro é uma clínica dentro do Cliente/ClienteBD)|
|ClientePerfilAcessoUsuario|IpSeguranca|Id, ClientePerfilAcessoId, UsuarioClienteId, ClienteEmpresaId (consultado na RN-CIU-015; um registro por combinação Perfil de acesso + clínica, pode ser criado já no convite se o administrador pré-selecionar perfil e clínica(s))|
|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).

---

## Histórico de Versões

- **v3.1** (29/08/2026) — Arquivo criado pela divisão do documento único `(CIU-E3) Convite e Vínculo v3.1.md` em arquivos por seção (ver Skill Designer, "Organização Física: Pasta por Funcionalidade", Lição #18). Conteúdo sem alteração de substância em relação à v3.1 original — apenas reorganização física. Histórico de revisões anterior a esta divisão (v1.0 a v3.1) preservado integralmente no documento original arquivado.
- **v3.2** (14/09/2026) — adicionada `ClienteEmpresa` às tabelas existentes utilizadas; `ClientePerfilAcessoUsuario` passa a listar o campo `ClienteEmpresaId`, usado para escopar cada associação de Perfil de acesso a uma clínica específica (RN-CIU-011, Seção 1). Nenhuma tabela nova — ambas já existem em produção.
- **v3.3** (14/09/2026) — atualização de referência: 01-Definição e 02-Especificação deste épico foram revisadas para v3.3 (correção de RN-CIU-011/015 sobre o bloqueio quando Perfil de acesso/clínica ficam pendentes, e de uma referência cruzada obsoleta ao E1). Nenhum conteúdo desta Seção 4 foi alterado além da atualização do número de versão dos documentos irmãos no cabeçalho e do link para o guarda-chuva (v2.11).