# Entidades — Plataforma

**Contextos:** Identity, Administration, Settings, Notifications, Plugins, Analytics  
**Versão:** 1.0.0

---

## Identity

### UserAccount

| Campo | Conteúdo |
|-------|----------|
| **Nome** | UserAccount |
| **Descrição** | Conta de pessoa física usuária da plataforma (não confundir com Person do catálogo público). |
| **Responsabilidade** | Representar identidade de login e perfil operacional do usuário. |
| **Principais atributos** | `user_id`, `email`, `display_name`, `status` (invited/active/disabled), `mfa_enabled`, `locale`, `created_at`, `last_login_at` |
| **Relacionamentos** | 1‑N Session; N‑N Role (via membership no Tenant); 1‑N Invitation enviadas; gera NotificationPreference |
| **Ciclo de vida** | Invited → Active → Disabled → (soft) Deleted/Anonymized (LGPD) |
| **Produz** | `identity.user_account.activated.v1`, `identity.user_account.disabled.v1`, `identity.user_account.anonymized.v1` |
| **Consome** | `administration.tenant.created.v1` (bootstrap admin); eventos de Invitation aceita |
| **Casos de uso** | UC-001, UC-002, UC-012 |
| **Regras** | E-mail único global ou por estratégia IdP; desabilitação revoga sessões; anonymization preserva AuditEvent com actor pseudonimizado |
| **Extensões** | Perfis externos OIDC, passkeys, device trust |

### Session

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Session |
| **Descrição** | Sessão autenticada de um UserAccount. |
| **Responsabilidade** | Controlar validade, MFA step-up e contexto de tenant ativo. |
| **Principais atributos** | `session_id`, `user_id`, `tenant_id` (ativo), `issued_at`, `expires_at`, `ip_hash`, `user_agent`, `amr` (auth methods) |
| **Relacionamentos** | N‑1 UserAccount; N‑1 Tenant |
| **Ciclo de vida** | Created → Refreshed → Expired / Revoked |
| **Produz** | `identity.session.created.v1`, `identity.session.revoked.v1` |
| **Consome** | — |
| **Casos de uso** | UC-002 |
| **Regras** | Timeout ocioso + absoluto; MFA obrigatório para admin; troca de tenant pode exigir revalidação |
| **Extensões** | Binding a dispositivo, risk-based auth |

### Role

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Role |
| **Descrição** | Papel autorizador dentro de um Tenant (ou papel de plataforma). |
| **Responsabilidade** | Agrupar permissões coerentes (Analista, Auditor, Admin Tenant, Platform Admin). |
| **Principais atributos** | `role_id`, `tenant_id?`, `code`, `name`, `permissions[]`, `system_defined` |
| **Relacionamentos** | N‑N UserAccount; referencia AccessPolicy |
| **Ciclo de vida** | Defined → Assigned → Deprecated |
| **Produz** | `identity.role.assigned.v1`, `identity.role.revoked.v1` |
| **Consome** | — |
| **Casos de uso** | UC-012 |
| **Regras** | Roles system_defined não editáveis; least privilege; mudança de role gera AuditEvent |
| **Extensões** | ABAC attributes, custom roles por plano |

### Invitation

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Invitation |
| **Descrição** | Convite para ingressar em um Tenant com role inicial. |
| **Responsabilidade** | Orquestrar onboarding de membros. |
| **Principais atributos** | `invitation_id`, `tenant_id`, `email`, `role_codes[]`, `token_hash`, `expires_at`, `status` |
| **Relacionamentos** | N‑1 Tenant; resolve para UserAccount |
| **Ciclo de vida** | Pending → Accepted / Expired / Revoked |
| **Produz** | `identity.invitation.sent.v1`, `identity.invitation.accepted.v1` |
| **Consome** | Quotas de seats (Administration) |
| **Casos de uso** | UC-001, UC-012 |
| **Regras** | Expira; não exceder Quota de seats; e-mail deve casar no accept |
| **Extensões** | Convite por domínio SSO JIT |

### ApiClient

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ApiClient |
| **Descrição** | Credencial M2M de integração enterprise. |
| **Responsabilidade** | Autenticar sistemas externos com scopes. |
| **Principais atributos** | `client_id`, `tenant_id`, `name`, `scopes[]`, `status`, `hashed_secret`, `rotated_at` |
| **Relacionamentos** | N‑1 Tenant; produz UsageEvent |
| **Ciclo de vida** | Active → Rotated → Revoked |
| **Produz** | `identity.api_client.created.v1`, `identity.api_client.revoked.v1` |
| **Consome** | Entitlements de API |
| **Casos de uso** | UC-014 |
| **Regras** | Segredo só em criação/rotação; scopes ⊆ entitlements; rate limit por client |
| **Extensões** | mTLS, IP allowlist |

---

## Administration

### Tenant

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Tenant |
| **Descrição** | Organização cliente que isola dados, usuários, casos e configurações. |
| **Responsabilidade** | Unidade raiz de multi-tenancy e billing lógica. |
| **Principais atributos** | `tenant_id`, `legal_name`, `slug`, `status` (trial/active/suspended), `plan_code`, `created_at`, `data_residency?` |
| **Relacionamentos** | 1‑N Workspace; 1‑N User memberships; 1‑N Quota/Entitlement; 1‑N Case; possui Settings |
| **Ciclo de vida** | Provisioning → Trial → Active → Suspended → Closed |
| **Produz** | `administration.tenant.created.v1`, `administration.tenant.suspended.v1`, `administration.tenant.closed.v1` |
| **Consome** | Eventos de billing externos (adapter) |
| **Casos de uso** | UC-001, UC-016 |
| **Regras** | Isolamento absoluto de Cases/Watch/Notes; suspensão bloqueia writes; fechamento inicia retenção/purge policy |
| **Extensões** | Hierarquia holding/filiais, white-label |

### Workspace

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Workspace |
| **Descrição** | Subespaço opcional dentro do Tenant (áreas, times, projetos). |
| **Responsabilidade** | Segmentar casos e watchlists sem criar novo tenant. |
| **Principais atributos** | `workspace_id`, `tenant_id`, `name`, `status` |
| **Relacionamentos** | N‑1 Tenant; 1‑N Case (opcional) |
| **Ciclo de vida** | Active → Archived |
| **Produz** | `administration.workspace.created.v1`, `administration.workspace.archived.v1` |
| **Consome** | — |
| **Casos de uso** | UC-007 (organização) |
| **Regras** | Pertence a um único tenant; archive não apaga audit |
| **Extensões** | ACL por workspace |

### Entitlement

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Entitlement |
| **Descrição** | Capacidade de produto liberada ao Tenant (ex.: API, path finding, SSO). |
| **Responsabilidade** | Gatear features independentemente de feature flags de release. |
| **Principais atributos** | `entitlement_code`, `tenant_id`, `enabled`, `limits` (JSON) |
| **Relacionamentos** | N‑1 Tenant; consultado por todos os contextos de produto |
| **Ciclo de vida** | Granted → Modified → Revoked |
| **Produz** | `administration.entitlement.changed.v1` |
| **Consome** | Mudanças de plano |
| **Casos de uso** | UC-016 |
| **Regras** | Código estável `ent_*`; domínio não hardcoda nome de plano |
| **Extensões** | Entitlements temporários (campanhas) |

### Quota

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Quota |
| **Descrição** | Limite quantitativo (seats, buscas/dia, tokens IA, profundidade de grafo). |
| **Responsabilidade** | Proteger custo e fairness multi-tenant. |
| **Principais atributos** | `quota_code`, `tenant_id`, `limit`, `period`, `consumed` |
| **Relacionamentos** | N‑1 Tenant; alimentada por UsageEvent |
| **Ciclo de vida** | Active → Exhausted → Reset (período) |
| **Produz** | `administration.quota.exhausted.v1`, `administration.quota.reset.v1` |
| **Consome** | `analytics.usage_event.recorded.v1` |
| **Casos de uso** | UC-005, UC-008, UC-016 |
| **Regras** | Enforce no application boundary; excedente nega ou enfileira conforme política |
| **Extensões** | Burst credits, soft vs hard quota |

### AuditEvent

| Campo | Conteúdo |
|-------|----------|
| **Nome** | AuditEvent |
| **Descrição** | Registro append-only de ação sensível (capacidade de accountability). |
| **Responsabilidade** | Permitir reconstrução de quem fez o quê, quando, em qual tenant. |
| **Principais atributos** | Ver política de auditoria (`docs/operacao/02-auditoria.md`) |
| **Relacionamentos** | Referencia actor, resource; correlaciona com CorrelationId |
| **Ciclo de vida** | Appended (imutável logicamente) → Retained → Anonymized (LGPD procedure) |
| **Produz** | N/A (é o próprio evento de auditoria) |
| **Consome** | Comandos de todos os contextos via porta de auditoria |
| **Casos de uso** | UC-011, UC-012, todos sensíveis |
| **Regras** | Sem UPDATE/DELETE de negócio; falha de escrita é severidade alta |
| **Extensões** | Hash chain, WORM export |

---

## Settings

### AccessPolicy

| Campo | Conteúdo |
|-------|----------|
| **Nome** | AccessPolicy |
| **Descrição** | Política configurável do Tenant (retenção de casos, MFA obrigatório, export allowlist). |
| **Responsabilidade** | Parametrizar comportamento de segurança e privacidade sem mudar código. |
| **Principais atributos** | `policy_id`, `tenant_id`, `key`, `value`, `updated_by`, `updated_at` |
| **Relacionamentos** | N‑1 Tenant |
| **Ciclo de vida** | Created → Updated → Deprecated |
| **Produz** | `settings.access_policy.updated.v1` |
| **Consome** | — |
| **Casos de uso** | UC-012, UC-015 |
| **Regras** | Keys versionadas; valores validados por schema; mudanças auditadas |
| **Extensões** | Policies por Workspace; herança corporativa |

---

## Notifications

### Notification

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Notification |
| **Descrição** | Mensagem endereçada a um usuário ou canal sobre evento relevante. |
| **Responsabilidade** | Entregar informação acionável (alerta Watch, convite, export pronto). |
| **Principais atributos** | `notification_id`, `tenant_id`, `recipient_user_id`, `channel` (in_app/email/webhook), `template_code`, `payload`, `status`, `created_at` |
| **Relacionamentos** | Originada por Alert, Invitation, Report, etc. |
| **Ciclo de vida** | Pending → Sent → Read / Failed |
| **Produz** | `notifications.notification.sent.v1`, `notifications.notification.failed.v1` |
| **Consome** | `watch.alert.raised.v1`, `identity.invitation.sent.v1`, `reports.export_package.ready.v1` |
| **Casos de uso** | UC-010, UC-001 |
| **Regras** | Respeita NotificationPreference; sem PII excessiva no e-mail; retry com backoff |
| **Extensões** | Digest diário, Slack/Teams |

### NotificationPreference

| Campo | Conteúdo |
|-------|----------|
| **Nome** | NotificationPreference |
| **Descrição** | Preferências de canal e categorias por usuário. |
| **Responsabilidade** | Evitar spam e cumprir preferências. |
| **Principais atributos** | `user_id`, `tenant_id`, `category`, `channel`, `enabled` |
| **Relacionamentos** | N‑1 UserAccount |
| **Ciclo de vida** | Upsert contínuo |
| **Produz** | `notifications.preference.updated.v1` |
| **Consome** | — |
| **Casos de uso** | UC-010 |
| **Regras** | Categorias security/admin podem ser mandatory |
| **Extensões** | Quiet hours |

---

## Plugins

### ConnectorPlugin

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ConnectorPlugin |
| **Descrição** | Extensão empacotada que coleta/normaliza uma fonte (ou família). |
| **Responsabilidade** | Isolar volatilidade de fontes públicas do core. |
| **Principais atributos** | `plugin_id`, `code`, `version`, `source_system_code`, `capabilities[]`, `config_schema`, `status` |
| **Relacionamentos** | Usa SourceSystem; produz RawPayload via Crawler/ETL; 1‑N PluginInstallation |
| **Ciclo de vida** | Registered → Enabled → Disabled → Retired |
| **Produz** | `plugins.connector_plugin.registered.v1`, `plugins.connector_plugin.retired.v1` |
| **Consome** | — |
| **Casos de uso** | UC-013 |
| **Regras** | Semver; schema de saída versionado; testes de contrato obrigatórios |
| **Extensões** | Marketplace sandbox, plugins de tenant (enterprise) |

### PluginInstallation

| Campo | Conteúdo |
|-------|----------|
| **Nome** | PluginInstallation |
| **Descrição** | Ativação de um ConnectorPlugin em escopo plataforma (ou tenant, futuro). |
| **Responsabilidade** | Ligar configuração operacional ao plugin. |
| **Principais atributos** | `installation_id`, `plugin_id`, `config`, `schedule`, `status` |
| **Relacionamentos** | N‑1 ConnectorPlugin |
| **Ciclo de vida** | Installed → Running/Paused → Uninstalled |
| **Produz** | `plugins.plugin_installation.changed.v1` |
| **Consome** | — |
| **Casos de uso** | UC-013 |
| **Regras** | Segredos de config em secret store, não no aggregate serializado em claro |
| **Extensões** | Install por tenant com BYO credentials |

---

## Analytics (produto / uso)

### UsageEvent

| Campo | Conteúdo |
|-------|----------|
| **Nome** | UsageEvent |
| **Descrição** | Evento de consumo mensurável (busca, expansão de grafo, tokens IA, export). |
| **Responsabilidade** | Alimentar quotas, billing e analytics de produto. |
| **Principais atributos** | `usage_id`, `tenant_id`, `actor_id`, `meter_code`, `quantity`, `occurred_at`, `resource_ref?` |
| **Relacionamentos** | Consumido por Quota/Billing; originado em Search/Graph/AI/Reports |
| **Ciclo de vida** | Recorded (imutável) |
| **Produz** | `analytics.usage_event.recorded.v1` |
| **Consome** | Sinais dos contextos de produto |
| **Casos de uso** | UC-016 |
| **Regras** | Idempotente; sem PII no payload; meter_codes estáveis |
| **Extensões** | Agregações OLAP, anomaly detection de abuso |