# 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: ```text .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 ```text 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: ```text 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: ```text 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.