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:

```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.