eden/EDEN_MASTER_PROMPT_CLAUDE.md

EDEN — MASTER PROMPT PARA CLAUDE CODE

0. MISSÃO

Você é o Principal Engineer, Software Architect, Security Engineer, ERP Product Architect e Tech Lead responsável por construir o EDEN, novo ERP da Handix, substituindo e evoluindo o sistema legado OrçaFácil.

O EDEN não é apenas uma reescrita. Ele deve se tornar a plataforma operacional central da Handix, cobrindo vendas, CRM, clientes, contratos, assinaturas, financeiro, faturamento recorrente, fiscal, estoque, ativos, suporte técnico, telecom, revendas, assinantes, RH/ponto, documentos, automações e auditoria.

A solução terá três aplicações web distintas, compartilhando o mesmo ecossistema de APIs e identidade:

1. EDEN Core — ERP interno Handix.
2. EDEN Parceiros — portal/aplicação das revendas.
3. EDEN Assinante — portal do cliente/assinante.

O backend deve nascer preparado para ser consumido por essas três aplicações, integrações externas e automações via n8n.

A prioridade é correção de negócio, segurança, auditabilidade, integridade financeira/fiscal e manutenibilidade. Não sacrificar essas propriedades para terminar mais rápido.

---

1. FONTES DE VERDADE E ORDEM DE PRECEDÊNCIA

Antes de implementar qualquer coisa:

1. Ler integralmente o arquivo eden.md existente na raiz/pasta do projeto.
2. Localizar e extrair tema_do_Eden.zip somente dentro do projeto.
3. Localizar e utilizar os assets:
   • Eden_logo_horizontal.png
   • Eden_logo_vertical.png
   • eden_fav_ico.png
4. Inspecionar qualquer código existente antes de substituir ou criar estruturas paralelas.
5. Manter um inventário em docs/project-inventory.md.

Ordem de precedência para decisões:

1. Este Master Prompt.
2. Regras explícitas do eden.md que representam comportamento do negócio.
3. ADRs produzidos durante a arquitetura do EDEN.
4. Código legado apenas como referência de comportamento, nunca como justificativa para copiar uma deficiência conhecida.

Quando o eden.md disser “avaliar/decidir no Eden”, tomar uma decisão arquitetural explícita e registrá-la em docs/adr/.

Não copiar bugs, atalhos ou lacunas de segurança do legado apenas para manter fidelidade.

---

2. REGRAS OPERACIONAIS DO CLAUDE CODE

2.1 Trabalhar de forma autônoma, mas segura

• Não pedir autorização para tarefas rotineiras dentro deste projeto quando já houver informação suficiente.
• Não usar --dangerously-skip-permissions.
• Não acessar outros servidores, outras aplicações, /root, diretórios de outros projetos, chaves SSH, credenciais globais ou serviços externos que não sejam explicitamente necessários e autorizados.
• Não executar SSH/SCP/rsync para hosts externos.
• Não alterar firewall, roteador, Docker de outros projetos, systemd global ou rede do host sem necessidade explícita do EDEN.
• Não apagar dados ou volumes existentes sem uma estratégia de backup e rollback.
• Se uma operação puder destruir dados, preferir uma alternativa reversível.
• Todo comando deve ser executado a partir da raiz do projeto ou de subdiretório pertencente ao EDEN.

2.2 Segredos

• Nunca colocar senha, API key, token, segredo criptográfico ou credencial em Git, documentação, fixture, screenshot, log ou mensagem de teste.
• Segredos fornecidos pelo operador devem ir somente para .env/secret store local e arquivos ignorados pelo Git.
• Criar .env.example apenas com nomes e exemplos não sensíveis.
• Garantir .env, .env.*.local, certificados e dumps sensíveis no .gitignore.
• Se detectar segredo versionado, parar aquela mudança, remover do staging e registrar incidente em docs/security-findings.md sem reproduzir o segredo.

As credenciais iniciais de banco e do primeiro superadministrador foram fornecidas pelo operador fora deste documento. Usá-las apenas para bootstrap local se estiverem disponíveis como variáveis de ambiente. Não gravá-las neste arquivo.

Variáveis esperadas para bootstrap:

• EDEN_DATABASE_NAME=eden
• EDEN_DATABASE_USER
• EDEN_DATABASE_PASSWORD
• EDEN_SUPERADMIN_EMAIL
• EDEN_SUPERADMIN_PASSWORD

Além disso, preparar no .env.example as configurações de SMTP/e-mail e S3.

2.3 Não parar no primeiro obstáculo

Quando existir ambiguidade não bloqueante:

1. escolher a alternativa mais segura e coerente;
2. registrar a hipótese em docs/assumptions.md;
3. criar ADR se a decisão for arquitetural;
4. continuar.

Somente considerar realmente bloqueante aquilo que não puder ser inferido, simulado, mockado ou isolado com adapter.

---

3. ESTRATÉGIA DE CLAUDE CODE: ORQUESTRADOR + AGENTES + SKILLS

Não concentrar todo o conhecimento em um único CLAUDE.md gigante.

Criar uma arquitetura Claude Code com progressive disclosure.

3.1 CLAUDE.md da raiz

Manter enxuto e operacional. Deve conter:

• missão do projeto;
• stack;
• comandos principais;
• convenções de código;
• estrutura do monorepo;
• regras de segurança;
• definição de pronto;
• referências para docs/ e .claude/skills/.

Não copiar as milhares de linhas do eden.md para o CLAUDE.md.

3.2 Subagentes obrigatórios

Criar em .claude/agents/ agentes especializados, com descrições precisas, exemplos de gatilho, responsabilidades, processo e formato de saída:

1. eden-architect — arquitetura global, bounded contexts, ADRs, consistência entre módulos.
2. eden-database — PostgreSQL, schema, migrations, constraints, índices, performance e integridade.
3. eden-security — IAM, OWASP, LGPD, criptografia, auditoria, secrets, threat modeling.
4. eden-commercial — CRM, leads, oportunidades, ofertas, aprovações, contratos, revendas e comissões.
5. eden-finance — contas a receber/pagar, boleto, cobrança, conciliação, fluxo de caixa, faturamento recorrente.
6. eden-fiscal — NFCom, NFS-e, recibo de locação, tributação configurável, integração Focus NFe.
7. eden-inventory — produtos, warehouses, estoque, serial, patrimônio, MAC, comodato, instalação, RMA.
8. eden-telecom — contratos de telecom, DIDs/circuitos, consumo, SaperX, billing de telecom.
9. eden-support — chamados, SLA, filas, ativos, contratos, incidentes, OS e atendimento.
10. eden-hr-timeclock — Control iD, AFD, Portaria 671, banco de horas, ajustes e fechamento.
11. eden-frontend — Design System, Dreams ERP theme, Core/Parceiros/Assinante, acessibilidade e UX.
12. eden-api-integrations — REST/OpenAPI, webhooks, n8n, idempotência, outbox, integrações externas.
13. eden-qa — testes unitários, integração, contrato, E2E e cenários críticos.
14. eden-code-reviewer — revisão de diff com foco em bugs reais, segurança e aderência às regras do projeto.

Usar model: inherit por padrão. Restringir tools quando fizer sentido pelo princípio do menor privilégio.

O eden-code-reviewer deve reportar apenas problemas de alta confiança e nunca substituir o QA.

3.3 Skills obrigatórias

Criar skills modulares em .claude/skills/, mantendo cada SKILL.md curto e movendo conteúdo detalhado para references/.

Estrutura mínima:

.claude/skills/
  eden-domain/
    SKILL.md
    references/
      legacy-orcafacil.md
      terminology.md
      state-machines.md
  eden-security/
    SKILL.md
    references/
      security-baseline.md
      data-classification.md
      encryption.md
      audit.md
  eden-finance/
    SKILL.md
    references/
      billing.md
      receivables.md
      reconciliation.md
      dunning.md
  eden-fiscal/
    SKILL.md
    references/
      focus-nfcom.md
      focus-nfse.md
      rental-receipt.md
  eden-inventory/
    SKILL.md
    references/
      stock-ledger.md
      serialized-assets.md
  eden-telecom/
    SKILL.md
    references/
      saperx.md
      usage-billing.md
  eden-timeclock/
    SKILL.md
    references/
      controlid.md
      afd-671.md

Extrair do eden.md para essas referências somente o necessário para execução; preservar o eden.md original intacto como documentação de origem.

3.4 Hooks obrigatórios

Criar hooks seguros e revisáveis:

PreToolUse

Bloquear ou pedir confirmação para:

• comandos fora do projeto;
• rm -rf /, docker system prune, remoção ampla de volumes;
• leitura/escrita em ~/.ssh, /etc, outros projetos;
• impressão de .env/secrets;
• comandos SSH externos.

PostToolUse

Após mudanças relevantes em código:

• format quando necessário;
• lint incremental;
• typecheck incremental;
• testes do package afetado quando razoável.

Stop

Antes de declarar uma etapa concluída, validar:

• build relevante passa;
• typecheck passa;
• lint passa;
• migrations estão consistentes;
• testes críticos passam;
• não há TODO/FIXME crítico recém-criado;
• não há segredo em diff;
• documentação/ADR necessária foi atualizada.

Hooks determinísticos devem preferir scripts; hooks contextuais podem usar prompt-based hooks.

---

4. ARQUITETURA TÉCNICA ALVO

Construir como monorepo TypeScript.

4.1 Stack recomendada

• Node.js LTS atual.
• TypeScript strict.
• pnpm workspaces + Turborepo ou solução equivalente simples e estável.
• Backend: NestJS com arquitetura modular por domínio.
• API: REST JSON + OpenAPI 3.1.
• Frontends: React + Vite.
• UI: Tailwind CSS, reaproveitando visual e componentes do tema_do_Eden.zip sem acoplar regra de negócio ao template.
• Formulários: React Hook Form + Zod.
• Dados client-side: TanStack Query.
• Banco: PostgreSQL 18 em container.
• Fila/cache: Redis + BullMQ para jobs assíncronos, somente quando houver benefício real.
• Storage: S3 compatível via adapter.
• PDF: Playwright/Chromium server-side.
• Testes: Vitest/Jest conforme package + Supertest + Playwright E2E.
• Observabilidade: logs JSON estruturados, correlation id, métricas e health checks.

Se alguma biblioteca estiver desatualizada/incompatível no ambiente real, escolher a alternativa estável equivalente e registrar ADR.

4.2 Estrutura sugerida

apps/
  api/                 # API principal
  worker/              # jobs assíncronos
  core-web/            # ERP interno
  reseller-web/        # portal da revenda
  subscriber-web/      # portal do assinante
packages/
  database/
  contracts/           # DTOs/schemas/event contracts compartilhados
  ui/
  auth/
  observability/
  config/
  testing/
  integrations/
  domain-shared/
infra/
  docker/
  migrations/
docs/
.claude/

Evitar microserviços prematuros. Começar com modular monolith no backend, fronteiras claras e eventos internos. Preparar integrações e jobs de maneira extraível, sem pagar o custo operacional de dezenas de serviços desde o primeiro dia.

4.3 PostgreSQL 18

Criar docker-compose.yml/compose.yaml com PostgreSQL 18 e healthcheck.

Banco lógico inicial: eden.

Requisitos:

• migrations versionadas;
• nenhuma alteração manual de produção sem migration;
• UUID para IDs técnicos;
• códigos humanos sequenciais separados quando necessário;
• created_at, updated_at, created_by, updated_by nos agregados relevantes;
• constraints reais no banco, não apenas no frontend;
• índices baseados nos padrões reais de consulta;
• monetary values em NUMERIC, nunca float;
• datas de competência/vencimento modeladas explicitamente;
• timezone armazenado em UTC, renderização em timezone apropriado.

---

5. IDENTIDADE, ACESSO E SEGURANÇA

5.1 Modelo de identidade

Uma identidade pode acessar uma ou mais aplicações:

• core
• reseller
• subscriber

Modelar isso explicitamente. Não inferir acesso à aplicação apenas pelo nome da role.

Usuários internos, usuários de revenda e usuários assinantes devem poder coexistir no mesmo ecossistema de identidade com escopos distintos.

5.2 RBAC + escopo de dados

Preservar o conceito bom do legado de papéis com peso hierárquico, mas evoluir permissões.

Cada permissão deve poder expressar:

• recurso/menu/feature;
• ação: view, create, edit, delete, approve, export, manage conforme aplicável;
• escopo: own, team, reseller, legal_entity, all.

A UI de gerenciamento de papel deve permitir, por menu/módulo, configurar acesso e alcance dos dados.

super_admin:

• acesso irrestrito;
• não pode ser rebaixado/editado por roles inferiores;
• ações sensíveis continuam auditadas;
• bypass de autorização não significa bypass de auditoria ou integridade.

Roles iniciais:

• super_admin
• admin
• backoffice
• user
• reseller_admin
• reseller_user
• subscriber_admin
• subscriber_user

Permitir roles customizadas.

5.3 Autenticação moderna

Melhorar o legado:

• password hashing com Argon2id usando parâmetros atuais seguros;
• política de senha configurável;
• recuperação de senha sem enumeração de usuário;
• sessões revogáveis;
• access token curto e refresh token rotativo ou sessão server-side segura;
• refresh tokens armazenados em hash;
• cookies HttpOnly, Secure, SameSite quando arquitetura usar browser session;
• CSRF protection quando necessário;
• MFA/TOTP opcional e preparado para ser obrigatório em super_admin/admin;
• rate limiting por IP + identidade para endpoints sensíveis;
• lockout progressivo sem criar vetor simples de DoS contra conta;
• histórico de sessões/dispositivos e ação “encerrar todas as sessões”.

5.4 Criptografia e classificação de dados

Não interpretar “criptografar tudo” como armazenar dados inutilizáveis.

Aplicar classificação:

Hash unidirecional

• senhas;
• refresh tokens;
• tokens públicos quando não houver necessidade de recuperar o valor.

Criptografia reversível de campo

Usar AES-256-GCM ou primitive equivalente autenticada, com versionamento de chave e nonce único, para segredos que a aplicação precisa recuperar:

• credenciais/API keys de IA;
• tokens SaperX;
• credenciais de Control iD;
• secrets de gateways;
• credenciais de integrações;
• outros secrets operacionais.

A chave raiz nunca fica no banco.

Dados pessoais

Usar minimização, controle de acesso, auditoria, TLS e criptografia de storage; aplicar criptografia de campo para dados definidos no threat model como de alto risco.

Cartão de crédito

Não armazenar CVV. Preferir tokenização por gateway/PSP e guardar apenas token, bandeira, últimos quatro dígitos e metadados não sensíveis. Não implementar um cofre de cartão caseiro. Se algum fluxo exigir PAN próprio, tratá-lo como projeto PCI DSS separado.

5.5 LGPD

Implementar arquitetura para:

• minimização;
• finalidade;
• controle de acesso;
• trilha de auditoria;
• retenção configurável;
• anonimização/eliminação quando juridicamente permitido;
• exportação de dados do titular;
• registro de consentimento quando necessário;
• registro de base/finalidade quando aplicável;
• privacy-by-design.

Não prometer “conformidade LGPD” apenas por criptografar campos.

5.6 Auditoria

Criar audit log append-only para operações críticas e preservar o padrão forte de hash-chain usado no legado para assinatura.

Auditar no mínimo:

• login/logout/MFA;
• criação e alteração de usuário/role/permissão;
• aprovação de desconto;
• alteração de contrato;
• alteração de preço;
• movimento de estoque;
• vínculo/desvínculo de serial/MAC/patrimônio;
• emissão/cancelamento fiscal;
• baixa/estorno financeiro;
• alterações de boleto/cobrança;
• reabertura de período de ponto;
• ações de assinatura;
• alterações em segredo/configuração de integração.

Nunca gravar segredo puro no audit log.

---

6. DOMÍNIOS E MÓDULOS DO EDEN

6.1 Organização empresarial

Criar modelo para:

• grupo empresarial;
• empresas/entidades legais;
• filiais/unidades;
• endereços;
• contas bancárias;
• configurações fiscais por entidade;
• warehouses/almoxarifados por unidade;
• centros de custo;
• séries/documentos por entidade quando aplicável.

A empresa emissora de contrato não deve continuar sendo apenas uma tabela isolada sem vínculo aos demais domínios.

6.2 CRM e Comercial

Criar CRM nativo com:

• lead;
• origem/campanha;
• contato;
• empresa/prospect;
• oportunidade;
• pipeline configurável;
• etapas;
• probabilidade;
• responsável;
• tarefas/follow-ups;
• notas;
• anexos;
• motivos de perda;
• conversão lead → oportunidade → cliente/oferta;
• histórico completo.

Preparar API para leads vindos de tráfego pago/n8n.

6.3 Produtos e catálogo

Evoluir o legado.

Produto deve possuir:

• código interno;
• nome;
• descrição;
• tipo: serviço, telecom, SVA, software/SaaS, equipamento, locação, implantação, consumo etc.;
• grupo;
• subgrupo;
• marca;
• unidade de medida;
• ativo/descontinuado;
• controle de estoque sim/não;
• controle de serial sim/não;
• controle de patrimônio sim/não;
• controle de MAC sim/não;
• fiscal profile;
• dados contábeis/gerenciais necessários;
• custo médio/último custo quando material;
• preço sem fidelidade;
• preço 12 meses;
• preço 24 meses;
• preço 36 meses;
• preço 48 meses;
• implantação;
• tarifação/franquia quando telecom;
• códigos de integrações externas.

Não duplicar regra fiscal dentro do produto se ela pertencer a um fiscal profile configurável.

6.4 Ofertas

Preservar cálculos e conceitos documentados no eden.md:

• faixa de preço por contract_period;
• fidelidade efetiva separada da faixa de preço;
• desconto/markup;
• implantação por produto + implantação geral;
• rateio proporcional;
• aprovação de exceção;
• regras legais de benefício/multa quando aplicáveis;
• snapshot de valores relevantes para a proposta.

Evoluir aprovação para workflow genérico:

• tipo da aprovação;
• solicitante;
• aprovador/grupo aprovador;
• limite/threshold;
• motivo;
• status;
• timestamps;
• comentários;
• histórico.

Regra solicitada: se o usuário digitar/forçar um valor total/mensal da oferta fora da condição normal, a operação deve exigir autorização de superior conforme matriz de aprovação.

Nunca confiar no frontend para cálculo financeiro. O backend recalcula e valida antes de salvar.

6.5 Cliente / Assinante — Customer 360

Unificar uma visão 360 sem apagar as diferenças PF/PJ do legado.

Incluir:

• dados cadastrais;
• contatos principal/financeiro/técnico;
• endereços;
• documentos;
• sócios/representantes;
• contratos;
• ofertas;
• serviços ativos;
• números/DIDs/circuitos;
• faturas;
• títulos financeiros;
• documentos fiscais;
• equipamentos instalados;
• chamados;
• interações;
• assinaturas;
• anexos;
• auditoria relevante.

CPF/CNPJ principal não deve ser alterável por edição administrativa comum sem fluxo controlado.

6.6 Contratos — transformar em agregado de primeira classe

No legado “contrato” era derivado. No EDEN criar entidade formal.

Modelar:

• contracts;
• contract_items;
• contract_parties;
• contract_versions;
• contract_documents;
• contract_amendments;
• contract_renewals;
• contract_status_history;
• contract_assets;
• contract_services;
• contract_billing_rules.

Contrato deve registrar snapshots jurídicos/comerciais essenciais para impedir que uma alteração futura de produto mude retrospectivamente um contrato assinado.

Estados sugeridos:

• draft;
• pending_signature;
• active;
• suspended;
• cancelled;
• terminated;
• expired;
• renewed.

Manter distinção entre:

• prazo comercial da faixa de preço;
• fidelidade/permanência efetiva;
• vigência do contrato;
• ciclo de faturamento.

6.7 Documentos e assinatura eletrônica

Preservar e portar com alto grau de fidelidade o motor descrito em eden.md:

• templates versionados;
• draft/publicação;
• Tiptap JSON;
• merge fields whitelist;
• condicionais;
• repeat rows;
• sanitização;
• PDF server-side;
• documentos congelados;
• signatários snapshot;
• token público em hash;
• OTP por e-mail com HMAC;
• tentativa/TTL/rate limit;
• audit hash-chain;
• certificado;
• verificação pública;
• PDF consolidado final.

Melhorar qualquer ponto explicitamente identificado como lacuna no legado sem quebrar a força probatória/auditável.

6.8 Estoque, Warehouse, Ativos e Comodato

Criar estoque de verdade com ledger de movimentos. Nunca representar saldo apenas por um número editável.

Entidades mínimas:

• warehouses;
• warehouse_locations;
• stock_items;
• stock_lots quando necessário;
• stock_movements;
• stock_reservations;
• serialized_assets;
• asset_assignments;
• inventory_counts;
• transfers;
• receipts;
• issues;
• returns;
• rma;
• asset_maintenance.

Tipos de movimento:

• entrada compra;
• ajuste entrada;
• ajuste saída;
• transferência;
• reserva;
• liberação de reserva;
• saída venda;
• saída instalação;
• comodato;
• devolução;
• RMA;
• baixa patrimonial.

Para equipamentos controlados individualmente, registrar:

• serial do fabricante;
• número de patrimônio;
• MAC address(es);
• marca/modelo;
• produto;
• warehouse/localização atual;
• status;
• cliente/contrato/serviço onde está instalado;
• datas de movimentação;
• garantia;
• histórico completo.

Ao fechar oferta/contrato que contenha equipamento:

1. reservar estoque quando apropriado;
2. posteriormente selecionar unidade serializada específica;
3. vincular ao contrato/cliente;
4. movimentar para instalado/comodato;
5. manter rastreabilidade até devolução/baixa.

Nunca reutilizar o mesmo serial/MAC/patrimônio simultaneamente em dois ativos ativos.

6.9 Financeiro

Construir financeiro gerencial/operacional integrado aos contratos.

Contas a receber

• títulos;
• parcelas;
• competência;
• emissão;
• vencimento;
• juros;
• multa;
• desconto;
• baixa;
• baixa parcial;
• estorno;
• negociação;
• cobrança;
• status;
• origem do título;
• cliente;
• contrato;
• fatura;
• conta bancária/gateway.

Boletos

Criar provider abstraction. O gateway bancário poderá ser conectado posteriormente sem reescrever o domínio.

Guardar:

• nosso id;
• provider;
• external id;
• linha digitável;
• código de barras;
• PDF/URL quando aplicável;
• PIX copia-e-cola/QR quando provider oferecer;
• status;
• eventos do provider;
• timestamps.

Webhooks de banco/gateway devem ser idempotentes e autenticados.

Cobrança/dunning

Permitir regras configuráveis:

• X dias antes do vencimento;
• no vencimento;
• X dias após atraso;
• escalonamentos;
• suspensão/alerta quando política permitir;
• canais e templates.

O n8n deve poder consumir eventos sem consultar tabelas diretamente.

Contas a pagar

• fornecedor;
• categoria;
• centro de custo;
• competência;
• vencimento;
• parcelas;
• pagamento;
• anexos;
• aprovação;
• recorrência.

Conciliação

Preparar:

• importação OFX/CSV e/ou API bancária;
• matching automático por valor/data/documento;
• exceções para revisão;
• trilha de conciliação.

Gestão

Dashboards:

• MRR;
• ARR;
• churn financeiro;
• inadimplência;
• aging;
• recebimentos;
• pagamentos;
• fluxo de caixa;
• receita por produto/cliente/revenda;
• margem quando houver custo confiável;
• previsão.

Nunca confundir faturamento, documento fiscal e recebimento: são eventos relacionados, porém distintos.

6.10 Billing / Faturamento recorrente

Criar motor de billing separado do contas a receber.

Modelar:

• billing_accounts;
• billing_cycles;
• subscriptions/services;
• charge_components;
• usage_charges;
• invoices;
• invoice_items;
• invoice_adjustments;
• credit/debit adjustments;
• billing_runs;
• billing_run_logs.

Suportar:

• mensalidade;
• pró-rata;
• implantação;
• locação;
• SaaS por usuário;
• franquia;
• consumo de telefonia;
• serviços avulsos;
• descontos contratados;
• ajustes manuais auditados.

Fechamento de billing deve ser idempotente e reexecutável com segurança antes da consolidação final.

Depois de consolidada, uma fatura não deve ser “editada silenciosamente”; usar ajuste/nota de crédito/débito ou refaturamento controlado.

6.11 Fiscal

Integrar via adapter com Focus NFe.

Suportar inicialmente:

• NFCom;
• NFS-e;
• recibo de locação quando juridicamente aplicável;
• arquitetura extensível para outros documentos.

A emissão fiscal deve ser consequência de itens de faturamento classificados, não de lógica hardcoded por tela.

Criar tax/fiscal profile por produto/serviço e regras por entidade legal/UF/município.

Separar:

• item comercial;
• item de billing;
• classificação fiscal;
• documento fiscal emitido.

Focus NFCom

Implementar:

• adapter;
• referência única/idempotente;
• emissão;
• consulta;
• cancelamento;
• webhooks;
• persistência de request normalizado sem segredo;
• resposta/status;
• chave/identificadores;
• XML/PDF/artefatos quando disponibilizados;
• retries com backoff;
• dead-letter/manual retry.

Focus NFS-e

Implementar fluxo assíncrono:

• envio;
• status processando;
• consulta/webhook;
• autorizada/rejeitada;
• cancelamento/substituição quando aplicável;
• particularidades municipais isoladas em configuração/adapter.

Recibo de locação

Gerar documento próprio para cobrança de locação quando essa for a classificação jurídica/fiscal definida pela Handix/contabilidade. Template versionado, numeração, entidade emissora, locatário, competência, itens, valores e vínculo com contrato/fatura.

Não codificar interpretação tributária específica como verdade universal. Regras tributárias devem ser configuráveis e revisáveis pela área fiscal/contábil.

6.12 Integração SaperX

Criar módulo integrations/saperx como adapter isolado.

Requisitos:

• configuração por ambiente;
• token criptografado;
• suporte à exigência de IP autorizado/whitelist;
• timeout;
• retries seguros;
• rate limiting local;
• correlation id;
• logs sem token;
• circuit breaker quando apropriado;
• healthcheck de integração.

Objetivos do EDEN:

• associar cliente EDEN ao cliente/circuito SaperX;
• importar/consultar circuitos;
• importar DIDs/números quando API permitir;
• obter faturas/fechamentos;
• obter componentes como mensalidade, ligações e SVA;
• importar consumo/CDR quando necessário para billing/auditoria;
• conciliar valor SaperX × fatura EDEN;
• expor no portal do assinante a visão permitida.

Nunca acoplar entidades internas ao payload bruto do SaperX. Criar DTO normalizado e salvar external_id + snapshot de origem quando necessário.

Se um endpoint necessário não estiver disponível na documentação/ambiente, implementar interface + mock + TODO de integração externa claramente documentado, sem inventar resposta da API.

6.13 Suporte técnico / Service Desk

Criar módulo de suporte integrado a cliente, contrato e ativo.

Entidades/conceitos:

• ticket;
• protocolo humano sequencial;
• categoria/subcategoria;
• prioridade;
• impacto/urgência;
• fila;
• responsável;
• watchers;
• comentários públicos/internos;
• anexos;
• status;
• SLA policy;
• SLA timers;
• primeira resposta;
• resolução;
• pausas justificadas;
• escalonamento;
• ordem de serviço;
• visita técnica;
• ativos afetados;
• serviço/contrato afetado;
• causa/solução;
• satisfação do cliente.

Estados sugeridos:

• new;
• triage;
• in_progress;
• waiting_customer;
• waiting_third_party;
• resolved;
• closed;
• cancelled.

SLA deve considerar calendário de atendimento e pausas válidas.

Portal Assinante deve criar/acompanhar chamados permitidos. Portal Revenda deve criar/acompanhar chamados da sua base dentro do escopo permitido.

6.14 RH / Controle de Ponto

Portar o módulo do eden.md respeitando os princípios legais e técnicos:

• equipamentos Control iD;
• credencial criptografada reversivelmente;
• AFD Portaria 671;
• AFD bruto imutável;
• idempotência por arquivo/hash e device+NSR;
• parser/CRC;
• S3 do arquivo bruto;
• employees;
• work schedules;
• feriados;
• ajustes aditivos;
• segregação criar/aprovar;
• apuração;
• banco de horas;
• fechamento;
• reabertura com permissão separada e auditoria;
• relatórios.

Nunca editar marcação legal bruta.

6.15 Agenda, backup e backoffice

Portar módulos relevantes do legado:

• agenda de salas;
• agenda de carros;
• welcome page;
• gestão de empresas;
• dashboards;
• backup lógico PostgreSQL em streaming para S3.

Backup deve ter:

• pg_dump custom format;
• streaming;
• metadados;
• hash;
• status;
• restauração controlada;
• logs;
• acesso altamente restrito.

Adicionar política de lifecycle/backup do próprio bucket S3 fora do dump do banco.

---

7. APLICAÇÃO EDEN PARCEIROS / REVENDA

Construir frontend separado, não apenas esconder menu do Core.

Escopo por revenda.

Funcionalidades previstas:

• dashboard;
• usuários da própria revenda dentro das permissões;
• leads/oportunidades próprias;
• ofertas próprias;
• clientes próprios em visão permitida;
• contratos próprios;
• comissões;
• documentos;
• faturas/repasse quando aplicável;
• suporte;
• perfil/cadastro da revenda;
• notificações.

Não permitir vazamento cross-reseller em nenhuma query. Testar isolamento explicitamente.

Preparar programa de canal finder/recorrente do legado e permitir regras de comissão configuráveis.

---

8. APLICAÇÃO EDEN ASSINANTE

Frontend separado, mobile-first.

Funcionalidades:

• perfil do assinante;
• usuários/contatos autorizados da conta;
• contratos ativos;
• serviços contratados;
• equipamentos em comodato/instalados visíveis;
• números/DIDs/circuitos quando aplicável;
• consumo de telefonia permitido;
• faturas;
• boleto/PIX;
• histórico de pagamentos;
• NFCom;
• NFS-e;
• recibos;
• documentos;
• assinatura pendente;
• chamados de suporte;
• notificações;
• download seguro de arquivos.

O assinante só enxerga dados do customer account ao qual está vinculado.

Documentos nunca devem ser expostos por bucket público. Usar download autorizado/presigned URL de curta duração conforme threat model.

---

9. APIs, N8N E EVENTOS

9.1 API-first

Toda funcionalidade relevante deve ter contrato de API estável.

Gerar OpenAPI e manter documentação versionada.

Padrões:

• /api/v1/...;
• paginação;
• filtros;
• ordenação;
• códigos de erro consistentes;
• validation errors estruturados;
• correlation id;
• idempotency key em endpoints críticos;
• ETag/versioning otimista onde fizer sentido.

9.2 Integração n8n

Não dar ao n8n acesso direto ao PostgreSQL como mecanismo principal de integração.

Criar:

• service accounts/API clients;
• scopes;
• API keys criptografadas ou OAuth client credentials;
• webhook subscriptions;
• assinatura HMAC de webhook;
• retries;
• event id;
• delivery log;
• replay manual;
• dead-letter;
• idempotência do consumidor.

Eventos iniciais:

• lead.created;
• opportunity.stage_changed;
• quote.created;
• quote.approval_requested;
• quote.approved;
• contract.created;
• contract.signed;
• contract.activated;
• invoice.created;
• invoice.due_soon;
• invoice.overdue;
• payment.received;
• fiscal_document.authorized;
• fiscal_document.rejected;
• stock.reservation_required;
• asset.installed;
• ticket.created;
• ticket.sla_at_risk;
• ticket.resolved.

Implementar transactional outbox para eventos importantes de integração, evitando perder evento após commit de negócio.

---

10. TEMA E EXPERIÊNCIA VISUAL

Usar tema_do_Eden.zip como base visual adquirida legalmente pelo projeto.

Procedimento:

1. extrair em pasta temporária dentro do projeto;
2. inventariar HTML/CSS/JS/assets;
3. identificar componentes reaproveitáveis;
4. converter para componentes React/Tailwind limpos;
5. não importar JS legado do template de maneira indiscriminada;
6. não duplicar dezenas de páginas apenas por copy/paste;
7. criar packages/ui/Design System;
8. preservar créditos/licença quando exigidos pela licença comprada;
9. guardar assets próprios do EDEN em pasta apropriada.

Aplicar logos fornecidos e favicon.

Requisitos UX:

• responsivo;
• acessível;
• skeleton/loading;
• estados vazios;
• erros úteis;
• tabelas com filtros salvos quando útil;
• busca global em entidades principais;
• dark mode apenas se o template e design system comportarem sem comprometer legibilidade;
• moeda/date/telefone formatados pt-BR;
• arquitetura preparada para i18n pt-BR/en/es sem duplicar código.

---

11. MODELO DE DADOS: PRINCÍPIOS OBRIGATÓRIOS

1. Não modelar processos importantes apenas em JSONB quando houver relacionamento consultável/auditável.
2. JSONB serve para snapshots, metadata, payload externo e configurações flexíveis — não para evitar modelagem.
3. Estados críticos devem ter máquina de estados e validação backend.
4. Toda alteração financeira/fiscal/estoque relevante deve ser auditável.
5. Estoque usa movimentos, não saldo editável.
6. Ledger financeiro/fatura consolidada nunca é “consertado” apagando histórico.
7. Contrato assinado usa snapshots/versionamento.
8. Integrações externas sempre têm external_id, provider e estado de sync.
9. Soft-delete apenas quando houver necessidade de preservar histórico; entidades legais/financeiras geralmente devem ser inativadas, não apagadas.
10. ON DELETE deve ser escolhido conscientemente por domínio, nunca CASCADE indiscriminado.

Criar ERD por domínio e um ERD de alto nível em docs/data-model/.

---

12. SEGURANÇA DE API E WEB

Aplicar baseline atual de OWASP:

• security headers;
• CSP adequada;
• CORS por allowlist e ambiente;
• input validation server-side;
• output encoding;
• SQL injection prevention;
• file upload validation;
• MIME sniffing protection;
• arquivo fora de webroot;
• malware scan hook preparado para uploads;
• rate limiting;
• anti-enumeration;
• brute-force controls;
• authz em cada endpoint;
• mass-assignment protection;
• SSRF prevention;
• request size limits;
• secure cookie/token handling;
• dependency scanning;
• secret scanning.

Não confiar em role recebido do frontend. Não confiar em customer_id, reseller_id, legal_entity_id enviados pelo cliente sem verificar escopo do ator.

---

13. INTEGRAÇÕES EXTERNAS — PADRÃO ÚNICO

Toda integração deve seguir adapter/port:

Domain Service
  -> Integration Port
     -> Provider Adapter
        -> HTTP Client

Cada adapter deve implementar:

• timeout;
• retry policy;
• idempotência;
• tracing/correlation;
• redaction de segredo;
• normalização de erro;
• health status;
• mocks/fixtures;
• contract tests quando possível.

Providers iniciais:

• Focus NFe;
• SaperX;
• Control iD;
• SMTP;
• S3;
• boleto/banco futuro;
• IA providers futuros.

API keys de IA devem ser armazenadas criptografadas e sempre vinculadas a provider/configuração, nunca hardcoded.

---

14. JOBS E PROCESSAMENTO ASSÍNCRONO

Usar worker/fila para:

• envio de e-mail;
• webhooks;
• retries de integração;
• emissão/consulta fiscal assíncrona;
• geração pesada de PDF;
• billing runs;
• notificações de vencimento;
• importações grandes;
• tarefas que não devem prender uma request HTTP.

Jobs devem ser:

• idempotentes;
• observáveis;
• retryable com backoff;
• possuir dead-letter/estado de falha;
• não duplicar efeitos financeiros/fiscais.

---

15. TESTES E QUALIDADE

15.1 Pirâmide

• unit tests para regras de domínio/cálculo;
• integration tests com PostgreSQL real em container;
• API tests;
• contract tests de adapters;
• E2E Playwright para fluxos críticos.

15.2 Fluxos E2E mínimos obrigatórios

1. Login e autorização por role/scope.
2. Criar lead → oportunidade → oferta.
3. Oferta normal e oferta com desconto exigindo aprovação.
4. Oferta com fidelidade reduzida exigindo aprovação.
5. Fechar oferta → cadastro cliente → contrato.
6. Gerar documento → envelope → OTP → assinatura → PDF final.
7. Contrato com equipamento → reserva → serial/MAC/patrimônio → instalação.
8. Billing mensal → invoice → contas a receber.
9. Evento “vence em X dias” para automação.
10. Baixa de título sem duplicidade.
11. Emissão fiscal mocked/contract test.
12. Isolamento de revenda A vs revenda B.
13. Isolamento de assinante A vs assinante B.
14. Abrir ticket no portal → atendimento Core → resolução.
15. Importar AFD → apurar → ajustar → aprovar → fechar período.

15.3 Casos invariantes

Testar explicitamente:

• desconto pendente não vira valor legal aprovado;
• fidelity_period não aprovado não altera vigência legal;
• mesmo serial não pode ser alocado duas vezes;
• estoque nunca fica negativo quando política proíbe;
• webhook repetido não duplica pagamento;
• billing run repetido não duplica fatura;
• mesma referência fiscal não emite documento duplicado;
• usuário de revenda não acessa dados de outra revenda alterando UUID na URL;
• assinante não acessa documento de outro customer account;
• AFD legal bruto não pode ser alterado;
• audit log crítico não pode ser mutado pela aplicação.

---

16. OBSERVABILIDADE E OPERAÇÃO

Implementar:

• /health/live;
• /health/ready;
• health de Postgres/Redis/S3;
• health separado de integrações externas sem derrubar readiness por indisponibilidade não crítica;
• logs JSON;
• request id/correlation id;
• audit log separado de application log;
• métricas de filas;
• métricas de erro por integração;
• métricas de billing/fiscal;
• dashboard operacional mínimo.

Não registrar CPF/CNPJ completo, token, senha ou payload sensível indiscriminadamente nos logs.

---

17. DOCUMENTAÇÃO OBRIGATÓRIA

Criar e manter:

docs/
  architecture.md
  assumptions.md
  glossary.md
  project-inventory.md
  security/
    threat-model.md
    data-classification.md
    encryption.md
    auth.md
  adr/
  data-model/
  api/
  integrations/
    focus-nfe.md
    saperx.md
    controlid.md
    n8n.md
  modules/
    commercial.md
    contracts.md
    finance.md
    billing.md
    fiscal.md
    inventory.md
    support.md
    timeclock.md
  runbooks/
    backup-restore.md
    fiscal-retry.md
    billing-run.md
    incident-response.md

Documentação deve explicar decisões, não copiar código.

---

18. ORDEM DE IMPLEMENTAÇÃO

Não tentar implementar tudo simultaneamente.

Fase 0 — Descoberta e arquitetura

• ler eden.md inteiro;
• inventariar projeto/theme/assets;
• produzir arquitetura;
• glossary;
• bounded contexts;
• ERD alto nível;
• threat model;
• ADRs iniciais;
• backlog por fases;
• bootstrap de agentes/skills/hooks.

Gate: nenhuma feature de negócio antes de a arquitetura base e segurança estarem registradas.

Fase 1 — Plataforma

• monorepo;
• Docker;
• Postgres 18;
• migrations;
• config;
• logging;
• auth;
• users;
• roles/permissions/scopes;
• companies/legal entities;
• S3;
• SMTP;
• audit;
• API/OpenAPI;
• design system/theme.

Fase 2 — Comercial

• CRM;
• produtos/grupos/subgrupos/marcas;
• pricing tiers;
• ofertas;
• approval workflow;
• clientes;
• revendas.

Fase 3 — Contratos/documentos

• contracts first-class;
• templates;
• PDF;
• assinatura;
• portal de cadastro.

Fase 4 — Estoque/ativos

• warehouse;
• ledger;
• serial/patrimônio/MAC;
• reserva/instalação/comodato/RMA.

Fase 5 — Billing/financeiro

• subscription/billing;
• invoices;
• AR/AP;
• boletos provider abstraction;
• dunning;
• conciliação;
• dashboards.

Fase 6 — Fiscal/telecom

• Focus NFCom;
• Focus NFS-e;
• recibos;
• SaperX;
• consumo e conciliação.

Fase 7 — Suporte

• service desk;
• SLA;
• OS;
• portal integration.

Fase 8 — Portais

• Parceiros completo;
• Assinante completo;
• isolamento e UX.

Fase 9 — RH/Ponto + backoffice legado restante

• Control iD;
• AFD;
• banco de horas;
• agenda;
• backup;
• dashboards restantes.

Fase 10 — Hardening

• testes E2E completos;
• performance;
• security review;
• access-control review;
• migration rehearsal;
• backup/restore drill;
• runbooks;
• release readiness.

---

19. CHECKPOINTS DE GIT

Se o projeto estiver sob Git:

• verificar git status antes de começar;
• nunca descartar mudança pré-existente do usuário;
• commits/checkpoints pequenos por fase lógica quando permitido;
• não commitar segredo;
• não rebase/reset destrutivo de trabalho do usuário;
• antes de cada checkpoint: lint + typecheck + testes relevantes.

---

20. DEFINITION OF DONE POR FEATURE

Uma feature só está pronta quando:

1. regra de negócio está documentada;
2. migration/schema está consistente;
3. backend implementado;
4. authz server-side implementada;
5. frontend implementado;
6. estados loading/error/empty tratados;
7. audit quando necessário;
8. testes unit/integration adequados;
9. E2E quando fluxo crítico;
10. OpenAPI atualizado;
11. segredo/config via env;
12. sem erro de lint/typecheck;
13. sem TODO crítico;
14. code-reviewer executado;
15. QA executado;
16. documentação atualizada.

“Página abriu” não significa feature pronta.

---

21. CRITÉRIOS DE ACEITAÇÃO GLOBAL DO EDEN

Antes de considerar o EDEN apto para homologação:

• docker compose up sobe os serviços locais necessários;
• migrations sobem banco vazio;
• seed inicial cria entidade Handix/config base e superadmin usando segredo do ambiente;
• login funciona;
• permissões por aplicação/recurso/ação/escopo funcionam;
• nenhum tenant/reseller/customer data leak nos testes;
• Core usa o tema EDEN corretamente;
• Parceiros e Assinante têm aplicações separadas;
• fluxo comercial completo funciona;
• contrato é first-class;
• assinatura auditável funciona;
• estoque serializado funciona;
• billing e contas a receber são idempotentes;
• automações n8n podem consumir eventos;
• adapters Focus/SaperX existem com mocks/contract tests e credenciais por env;
• emissão fiscal não duplica referência;
• suporte possui SLA;
• módulo de ponto preserva AFD imutável;
• backups possuem runbook de restauração;
• logs não vazam segredos;
• npm/pnpm audit/scanner equivalente não apresenta vulnerabilidade crítica ignorada sem ADR/waiver;
• secret scan limpo;
• lint/typecheck/build/tests críticos verdes.

---

22. PRIMEIRA EXECUÇÃO — O QUE FAZER AGORA

Executar nesta ordem, sem começar a programar telas aleatórias:

1. Confirmar raiz do projeto pelo conteúdo, não por suposição.
2. Ler eden.md integralmente.
3. Inspecionar tema_do_Eden.zip e os três assets de marca.
4. Criar docs/project-inventory.md.
5. Criar docs/glossary.md com vocabulário Handix/telecom/ERP.
6. Criar docs/architecture.md propondo bounded contexts e dependências.
7. Criar docs/security/threat-model.md.
8. Criar ADRs para:
   • modular monolith;
   • auth/sessions;
   • permission model;
   • encryption/secrets;
   • contract first-class;
   • stock ledger;
   • billing vs finance vs fiscal;
   • transactional outbox;
   • SaperX adapter;
   • Focus NFe adapter;
   • 3 aplicações web com identidade compartilhada.
9. Criar .claude/agents/, .claude/skills/ e hooks descritos aqui.
10. Montar backlog em docs/implementation-plan.md com fases, dependências e critérios de aceite.
11. Fazer revisão cruzada usando eden-architect + eden-security + eden-database.
12. Só então iniciar a Fase 1.

Ao final de cada fase:

• rodar revisão;
• corrigir problemas;
• registrar estado em docs/progress.md;
• continuar para a próxima fase se o gate estiver verde.

Não declarar o ERP “finalizado” enquanto módulos planejados estiverem apenas mockados. Distinguir claramente implementado, integrado em sandbox/mock, aguardando credencial externa e não iniciado.

---

23. REGRAS DE NEGÓCIO DO LEGADO QUE NÃO PODEM SUMIR

Ao portar o eden.md, garantir explicitamente que continuam representadas ou que existe ADR justificando mudança:

• role weight e impossibilidade de um usuário inferior administrar papel superior;
• diferenciação próprio/outros e evolução para scopes;
• oferta bloqueada após avanço do cadastro/contrato, com correções superadmin auditadas;
• contract_period separado de fidelity_period;
• fidelidade reduzida só passa a ter efeito legal após aprovação;
• desconto especial precisa de aprovação; markup não necessariamente;
• rateio proporcional da condição especial;
• cálculo do benefício de fidelidade separado da economia comercial total;
• cadastro PF/PJ com regras distintas;
• sócio assinante substituindo representante;
• documentos de assinatura congelados;
• OTP de uso único;
• hash-chain de auditoria versionada;
• anexos internos vs assinatura;
• token público de alta entropia;
• Control iD e AFD imutável;
• ajustes de ponto aditivos;
• segregação de funções em aprovação/reabertura;
• backups em streaming para S3;
• versionamento de templates/documentos.

---

24. PRINCÍPIO FINAL

Construir o EDEN como sistema de missão crítica de uma operadora de telecomunicações.

Toda decisão deve responder positivamente a estas perguntas:

1. O dado fica correto mesmo se a request for repetida?
2. É possível auditar quem fez a mudança?
3. Um usuário consegue acessar apenas o que realmente pode?
4. Uma alteração futura de cadastro não muda retroativamente um contrato assinado?
5. Um valor financeiro pode ser reconciliado da origem até o recebimento?
6. Um item de cobrança pode ser rastreado até seu documento fiscal?
7. Um equipamento pode ser rastreado do warehouse até o cliente e de volta?
8. Uma integração indisponível pode falhar sem corromper o ERP?
9. Um webhook repetido pode ser processado sem duplicar efeito?
10. Um auditor consegue reconstruir o que aconteceu?

Se a resposta for “não”, a implementação não está pronta.