Matheus (Handix)
44510bd019
Fase 0 — descoberta e arquitetura:
- Inventário do projeto, glossário de domínio, arquitetura com bounded
contexts e topologia de containers, threat model inicial.
- 12 ADRs cobrindo modular monolith, topologia de containers (Postgres
isolado + eden-core/parceiros/assinante em containers e portas
distintos), auth/sessões, modelo de permissões, criptografia/segredos,
contrato first-class, stock ledger, separação billing/finance/fiscal,
outbox transacional, adapters SaperX e Focus NFe, e identidade
compartilhada entre as 3 apps.
- 14 subagentes e 7 skills especializados por domínio em .claude/.
- Hooks de segurança (PreToolUse/PostToolUse/Stop) testados via pipe.
Fase 1 — plataforma (em andamento):
- Monorepo pnpm workspaces + Turborepo: apps/{api,worker,core-web,
reseller-web,subscriber-web} + 9 packages compartilhados.
- apps/api: NestJS mínimo com /health/live e /health/ready (checando
Postgres real via @eden/database).
- 3 frontends Vite + React + TypeScript + Tailwind, com o favicon
oficial do EDEN.
- packages/database: migration baseline (node-pg-migrate) criando
roles/role_permissions/applications/users/user_applications/sessions/
audit_log — audit log append-only com hash-chain, testado ao vivo
(UPDATE/DELETE bloqueados pelo trigger).
- compose.yaml implementando a topologia da ADR-0002, validada de ponta
a ponta: os 6 containers sobem e ficam saudáveis com um único
`docker compose up`.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
59 lines
5.4 KiB
Markdown
59 lines
5.4 KiB
Markdown
# 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.
|