eden/docs/glossary.md

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.