# DICIONARIO_DE_DADOS_V2_FINAL

## Convenções gerais

- IDs: `CHAR(36)` com UUID gerado pela aplicação.
- Datas: `DATETIME(6)` em UTC.
- JSON: usado para metadata, payload e contexto; nunca como substituto de regra crítica.
- Integridade crítica: PK, FK, checks, colunas geradas, índices únicos condicionais, procedures e triggers.

---

## 1. Conta, identidade e segurança

### `clientes`
Conta/tenant da plataforma.  
Relaciona-se com assinaturas, faturas, acessos, convites, instâncias e integrações.

**Integridade:** código único; documento pode ser único; é a conta central, não o banco do ERP.

### `usuarios_plataforma`
Identidade do portal principal.  
Usado por login do portal, tokens, sessões, MFA e logs.

**Integridade:** e-mail normalizado único; `bloqueado_em` e `desabilitado_em` modelados; usuário local ativo/bloqueado/desabilitado exige `senha_hash`.

### `clientes_usuarios`
Membership entre usuário do portal e cliente.  
Resolve multiusuário por conta.

**Integridade:** `UNIQUE (cliente_id, usuario_id)`; índice condicional garante um único principal por cliente conforme regra de status.

### `convites_plataforma`
Convites por cliente para onboarding de usuário no portal.

**Integridade:** token em hash; convite pendente único por cliente + e-mail normalizado.

### `email_verification_tokens`
Tokens de verificação de e-mail.

**Integridade:** hash único; um token ativo por usuário.

### `password_reset_tokens`
Tokens de reset de senha.

**Integridade:** hash único; um token ativo por usuário; auditoria básica por IP e user-agent.

### `sessoes_plataforma`
Sessões/refresh tokens do portal.

**Integridade:** `refresh_token_hash` único; vínculo opcional ao contexto do cliente; índice em `familia_sessao_id` para revogação de família.

### `mfa_fatores`
Fatores de MFA do usuário do portal.

**Integridade:** um fator principal ativo por usuário; segredo pode ser referência externa ou versão cifrada; `mfa_habilitado` do usuário é sincronizado por trigger a partir desta tabela.

### `mfa_recovery_codes`
Códigos de recuperação de MFA.

**Integridade:** hash único por fator; status e consumo auditáveis.

### `segredos_plataforma`
Cadastro lógico de segredo sensível.

**Finalidade:** apontar para segredo externo ou servir de pai para versões cifradas.

**Escopos válidos na V2 FINAL:** `global`, `gateway_pagamento`, `produto`, `instancia_produto`, `mfa`.

**Integridade:** escopo global sem `escopo_id`; escopo não global com `escopo_id`; trigger valida existência real do destino.

### `segredos_plataforma_versoes`
Versões cifradas do segredo.

**Integridade:** versão única por segredo; apenas uma versão ativa por segredo; permite rotação e trilha de origem.

---

## 2. Catálogo, planos e preços

### `produtos`
Catálogo de sistemas/produtos da marca.

**Integridade:** código único; flags definem se o produto permite múltiplas assinaturas ou instâncias ativas.

### `modulos_produto`
Módulos internos comercializáveis de um produto.

**Integridade:** código único por produto.

### `planos`
Catálogo base de planos.

**Integridade:** código único; segmentação controlada por check.

### `plano_produto`
Oferta concreta de um plano para um produto.

**Integridade:** único por `produto_id + plano_id`; `sku` único; concentra limites comerciais e trial padrão.

### `plano_produto_modulos`
Módulos incluídos em um plano de produto.

**Integridade:** FKs compostas garantem que plano e módulo pertencem ao mesmo produto.

### `gateways_pagamento`
Cadastro dos gateways.

**Integridade:** código único; escolha explícita de estratégia de segredo.

### `precos_plano_produto`
Preço canônico da plataforma por oferta, ciclo e moeda.

**Integridade:** trigger impede sobreposição de vigência ativa por `plano_produto + ciclo + moeda`; regra fechada de recorrência:
- `unico` → `recorrente = false`
- demais ciclos → `recorrente = true`

### `precos_plano_produto_gateways`
Mapeia o preço canônico para price IDs/referências externas de gateway.

**Integridade:** uma referência externa por gateway; uma ligação única por preço + gateway.

---

## 3. Contratação, trial e instâncias

### `assinaturas`
Cabeçalho comercial da assinatura do cliente.

**Integridade:** código único; pertence a um cliente; status controlado por check.

### `assinatura_itens`
Itens contratados da assinatura; normalmente um item por produto/plano contratado.

**Integridade:** FKs compostas fecham cliente/produto/plano; índice condicional bloqueia duplicidade ativa quando o produto não permite múltiplas assinaturas; trigger garante coerência entre `preco_plano_produto_id`, `plano_produto_id`, `ciclo_cobranca`, `moeda`, `valor_unitario` e `valor_setup`.

**Observação:** quando há `preco_plano_produto_id`, os valores monetários viram snapshot consistente do preço escolhido e não podem ser alterados manualmente sem troca do seletor do preço.

### `trials`
Histórico oficial de trial por cliente/produto.

**Integridade:** um trial ativo por cliente/produto; pode apontar para o item convertido.

**Fonte de verdade:** esta é a fonte oficial de trial.

### `instancias_produto_cliente`
Instâncias provisionadas do produto para o cliente.

**Integridade:** unicidade por `cliente + produto + codigo_instancia`; índice condicional bloqueia múltiplas instâncias ativas quando o produto não permite; trigger exige `codigo_instancia` quando o produto admite múltiplas instâncias.

---

## 4. Faturamento, pagamentos e descontos

### `faturas`
Documento de cobrança do cliente.

**Integridade:** código único; pertence a cliente; pode referenciar assinatura e gateway.

### `fatura_itens`
Itens cobrados na fatura.

**Integridade:** FK para fatura; pode apontar para `assinatura_item`; trigger garante coerência com `plano_produto_id` do item de assinatura.

### `cupons_desconto`
Cadastro do cupom.

**Integridade:** código normalizado único; percentual limitado a `0–100`; escopo fechado em `global`, `produto` ou `plano_produto`.

### `cupom_usos`
Aplicação efetiva do cupom sobre um alvo.

**Alvos válidos:** `item_assinatura` ou `fatura`.

**Integridade:** FKs garantem o cliente correto do alvo; chaves geradas e índices únicos impedem duplicidade ativa do mesmo cupom no mesmo alvo; triggers/procedure protegem cumulatividade, primeira compra e histórico de cancelamento/estorno.

**Regra importante:** cupom, cliente e alvo são imutáveis após criação.

### `webhooks_pagamento`
Eventos recebidos do gateway.

**Integridade:** idempotência por `gateway + evento_externo_id`; índices adicionais para reconciliação por gateway/tipo/status/tempo.

### `pagamentos`
Movimentos financeiros ligados à fatura.

**Integridade:** idempotência externa por gateway + transação + tipo de movimento; pode referenciar webhook de origem.

---

## 5. Entitlement e integração

### `acessos_produto`
Entitlement central de uso do produto/módulo.

**Integridade:** FK composta + trigger garantem que `usuario_id`, quando presente, pertence ao `cliente_id`; status do vínculo do usuário também é validado.

### `jobs_provisionamento_produto`
Fila persistente de provisionamento.

**Integridade:** pode referenciar assinatura item e instância; índice/gerada impede job aberto duplicado da mesma ação para o mesmo alvo.

### `eventos_outbox_integracao`
Outbox transacional de eventos de domínio.

**Integridade:** idempotência por destino + chave de idempotência; pronto para publicação assíncrona.

### `tentativas_webhook_saida`
Tentativas individuais de entrega de webhook de saída.

**Integridade:** uma tentativa numerada por evento outbox; guarda status HTTP e latência.

### `fila_dead_letter`
Mensagens/eventos mortos após falha persistente.

**Integridade:** impede múltiplas DLQs abertas para a mesma origem.

### `logs_integracao`
Log técnico de integrações.

**Integridade:** classifica origem e nível; ligado opcionalmente a cliente/produto.

---

## 6. Governança e operação

### `logs_plataforma`
Log administrativo e de segurança do portal.

**Integridade:** liga opcionalmente cliente, produto, usuário e sessão; `expira_em` prepara retenção/purge futuro.

### `configuracoes_plataforma`
Configuração polimórfica da plataforma.

**Escopos válidos:** `global`, `produto`, `cliente`, `gateway`, `instancia_produto`.

**Integridade:** regra explícita global vs não global; trigger valida existência do escopo; `tipo_valor = secret_ref` só pode ser interno/restrito; não armazena segredo bruto.

---

## 7. Observações finais de integridade

1. **ERP não foi acoplado ao banco central.**  
   O banco central modela identidade do portal, billing, entitlement e integração futura.

2. **Integridade multi-tenant não fica só na aplicação.**  
   Há FKs compostas, triggers de pertencimento e bloqueios de mutação indevida.

3. **Preço e faturamento foram fechados por trigger.**  
   O item de assinatura não pode carregar snapshot incoerente com o preço escolhido.

4. **Cupom agora suporta cenário real.**  
   Há distinção entre aplicação ativa e cancelamento/estorno histórico.

5. **Configuração e segredo deixaram de ser genéricos.**  
   Só aceitam escopos ancorados em entidades modeladas.