# EDEN — Glossário de Domínio

Vocabulário Handix/telecom/ERP, preservado do legado OrçaFácil (`eden.md`) sempre que possível — não inventar sinônimos novos para conceitos já nomeados.

## Identidade e acesso

- **super_admin**: papel com bypass total, hardcoded (nunca passa por `role_permissions`), peso hierárquico fixo 100, nunca editável via UI.
- **role weight (peso de papel)**: inteiro 0–99 (super_admin = 100, fixo) que impede um ator de administrar/atribuir papel com peso maior que o seu, mesmo tendo a feature de gestão liberada.
- **feature key**: chave de tela/recurso gateável (`ofertas`, `clientes_todos`, `fiscal`, etc.), com dois níveis de acesso (`view`/`edit`) por papel.
- **scope (escopo de dados)**: no EDEN, evolução do padrão "próprio vs. todos" do legado para `own`/`team`/`reseller`/`legal_entity`/`all`.
- **token_version**: mecanismo legado de invalidação de sessão (incrementa a cada logout/reset de senha). No EDEN, substituído por refresh tokens revogáveis (ver ADR-0003), mas o *conceito* de "derrubar todas as sessões de um usuário" deve ser preservado.

## Comercial

- **contract_period (faixa de preço)**: período (0/12/24/36/48 meses) que determina qual coluna de preço do produto foi usada. Não é necessariamente o prazo de permanência real.
- **fidelity_period (fidelidade efetiva)**: prazo de permanência realmente assinado pelo cliente, quando **menor** que `contract_period`. Só produz efeito legal (vigência, multa, vencimento) depois de **aprovado**.
- **condição especial (`proposed_monthly_total`)**: valor mensal negociado diferente do total de tabela. Desconto exige aprovação; acréscimo (markup) não.
- **needsApproval**: `isDiscount OR hasReducedFidelity` — uma única aprovação cobre as duas exceções quando coexistem.
- **rateio proporcional**: distribuição de uma condição especial entre os itens da oferta, proporcional ao peso de cada item no total de tabela — nunca abate um item isolado.
- **oferta travada**: estado de uma oferta (`quotes`) após o cadastro de cliente ser iniciado (`client_registration_id` setado) — não editável exceto por `super_admin`.
- **deal_status**: estado do negócio (`orcamento`/`fechado`/`perdido`), distinto de `status` (estado do documento/proposta).
- **contrato (legado)**: no OrçaFácil não é tabela própria — é a junção de `client_registrations` ativos + `quotes`. No EDEN, torna-se agregado de primeira classe (`contracts`) — ver seção 6.6 do Master Prompt e ADR-0006.

## Cadastro / Cliente / Revenda

- **client_registrations**: cadastro completo (PF/PJ) de um cliente final, nascido de uma oferta fechada (ou "direto").
- **registration_status**: máquina de estados `rascunho → pendente_validacao → ativo ⇄ bloqueado/inativo`.
- **reaproveitar cadastro ativo**: atalho que copia identidade/endereço/contato de um cadastro já `ativo` para uma nova oferta, sem passar pelo formulário público de novo.
- **sócio assinante**: sócio (QSA) de uma PJ marcado como signatário — substitui inteiramente o bloco "Representante da Empresa".
- **Programa de Canais**: módulo de aprovação de revendas (`reseller_registrations`), com dois tipos: `finder` (pontual) e `recorrente` (com Termo de Adesão).

## Documentos e assinatura

- **document_template_versions**: versionamento imutável de template (Tiptap JSON); só 1 draft por vez; publicar é irreversível para aquela versão.
- **merge field**: variável de documento inserida via catálogo fechado (whitelist), nunca texto livre `{{...}}` no editor visual novo.
- **signature_envelope**: pacote de assinatura (documentos + signatários) com máquina de estados de 19 estágios (DRAFT → ... → COMPLETED).
- **hash-chain de auditoria**: cadeia SHA-256 append-only de eventos do envelope, com verificação em duas camadas (linkage + conteúdo).
- **OTP**: código de 6 dígitos, HMAC-SHA256 com segredo de servidor, TTL de 5 min, uso único.

## Fiscal

- **NFCom**: Nota Fiscal de Serviços de Comunicação (telecom).
- **NFS-e**: Nota Fiscal de Serviço eletrônica (ISS municipal).
- **fiscal profile (`product_fiscal_profiles`)**: liga um produto ao(s) código(s) fiscal(is) aplicável(is), separado por componente de faturamento (`RECURRING`/`IMPLEMENTATION`) — nunca duplicado dentro de `products`.
- **IBS/CBS**: tributos do "IVA dual" da reforma tributária brasileira — catálogos já modelados no legado, ainda sem motor de emissão.

## Ponto eletrônico

- **AFD**: Arquivo Fonte de Dados — formato legal (Portaria MTP 671/2021) de marcações de ponto, imutável uma vez importado.
- **NSR**: Número Sequencial de Registro — chave de idempotência por marcação, nunca inventado se ausente.
- **banco de horas**: livro-razão (crédito/débito em minutos) sem coluna de saldo persistida.
- **fechamento de período**: veto (não histórico paralelo) — mês `FECHADO` bloqueia recálculo/aprovação/lançamento manual até reabertura auditada.

## Plataforma / Infraestrutura

- **EDEN Core / Parceiros / Assinante**: as três aplicações web do ecossistema (ERP interno, portal de revenda, portal do assinante), compartilhando o mesmo backend de identidade/API.
- **outbox transacional**: padrão de persistência de eventos de domínio na mesma transação do negócio, para publicação confiável a integrações (n8n, webhooks) sem perda em caso de falha pós-commit.
- **adapter/port**: padrão de integração externa (Focus NFe, SaperX, Control iD) isolando domínio de detalhes de protocolo/provider.