LEW-ERP — Plano Vivo

1 Visão geral

ERP para sellers que vendem em marketplaces (Mercado Livre, Shopee e outros), inspirado no fluxo do SoftUp, mas com dois diferenciais-âncora que o concorrente não tem.

⭐ Conciliação de marketplace

Importa repasses, decompõe comissão/frete/taxas e mostra a margem real por pedido/SKU. A dor nº1 do seller, mal resolvida por ERPs genéricos.

⭐ Rede de fornecimento (dropship)

Produtor publica catálogo; afiliados revendem nas plataformas deles. Se ambos usam o LEW-ERP, o fluxo fecha 100% no sistema. Vira efeito de rede / moat.

⚠️ Separação total da Sellers Hub. Empresa e ecossistema independentes (restrição contratual). Nada de código, credenciais ou infra compartilhados — construção clean room.

2 Decisões travadas 🔒 fechado

Tema	Decisão
Posicionamento	Produto/empresa 100% separado da Sellers Hub (contratual)
Motor fiscal	PlugNotas (Tecnospeed) via adapter isolado — valida NF-e/NFC-e + venda à ordem + A1 multi-tenant
Marketplaces	Híbrido: ML/Shopee API direta + hub (Anymarket/Hub2b) só para cauda longa
Taxa do afiliado	Assinatura fixa (margem do revendedor = markup que ele cobra)
NF ao cliente final	Revendedor emite → venda à ordem (triangular); produtor emite remessa
Pagamento entre tenants	Por fora; sistema só registra "pago" e libera o pedido
Revendedor externo	Portal/painel leve para acompanhar e repassar pedidos
Arquitetura	Modular monolith (FastAPI), módulos donos das próprias tabelas
Multi-tenancy	Pool + Row-Level Security no Postgres; dedicado para whales
Auth	Zitadel atrás da interface `AuthProvider` (OIDC/JWKS) — LGPD: rota self-host SP. Ressalva AGPL no self-host
Fila/worker	Taskiq + Redis (Celery+async é armadilha); Outbox transacional em Postgres + poller, eventos versionados
Motor fiscal (detalhe)	Interface `FiscalEngine` + PlugNotas (1ª) + Focus NFe (fallback/barganha)
Gateway SaaS	Interface `PaymentProvider` isolada; assinatura do afiliado cobrada pela plataforma; gateway a escolher em M2 (Asaas recomendado)
Stack	FastAPI · Postgres+RLS · Redis · workers (Taskiq) · front Next.js · storage S3

✅ Correção F0 (revisão técnica 25/06): a aplicação conecta como role lewerp_app sem superuser/BYPASSRLS — superusuário ignora RLS mesmo com FORCE. O gate F0.4 agora roda como não-superusuário e prova o isolamento; em DEV a role é criada pelo init do Postgres (scripts/initdb).

3 Decisões em aberto 🔓 discutir

O que ainda precisamos bater o martelo. Vamos resolvendo nesta página.

#	Questão	Sugestão inicial
1	Preço do PlugNotas (bilhetagem) + 1 cert→N empresas + webhooks	Pedir proposta por volume agregado da plataforma
2	Gateway de cobrança (escolha em M2)	Asaas recomendado (split nativo, sem mensalidade); Pagar.me 2º
3	Hosting Zitadel: Cloud (região?) vs self-host SP + revisão jurídica AGPL	Depende da exigência LGPD do 1º seller grande
4	Branding / cores / nome comercial do produto	A definir
5	Validar com contador: ICMS-ST por UF na venda à ordem; NF remessa Full	Validar cedo (antes da F3)

💬 Me diga as respostas que você já tem e eu atualizo esta tabela (move para "travadas") a cada rodada.

4 Modelo de negócio — Rede de Fornecimento ⭐ diferencial

👤 Seller Produtor

Tem produto próprio. Mantém vitrine/catálogo com fotos, vende nos marketplaces e publica produtos para revenda. É quem fisicamente envia a mercadoria.

🤝 Revendedor / Afiliado

Paga assinatura fixa e revende os produtos do produtor nas contas de marketplace dele. Nunca toca no produto físico (dropship).

Receita

Assinatura do SaaS (todos os tenants) + assinatura fixa dos afiliados. Pagamento da mercadoria revendedor→produtor acontece por fora (sistema só registra).

5 Fluxo de dropship (revendedor também é cliente LEW-ERP)

Venda no marketplace do revendedor. O pedido entra na conta dele dentro do LEW-ERP.

Revendedor paga o produtor por fora (PIX/banco) e registra o pagamento no sistema.

Pagamento registrado → libera o pedido. Um pedido de dropship aparece automaticamente na fila do produtor.

Emissão fiscal (venda à ordem). Revendedor emite NF de venda; produtor emite NF de remessa por conta e ordem.

Produtor envia direto ao cliente final e o rastreio volta ao revendedor.

🔓 A detalhar: estados exatos do pedido_dropship (aguardando pagamento → liberado → faturado → enviado → entregue → cancelado) e o que cada lado enxerga do outro (visibilidade cross-tenant).

6 Fiscal — venda à ordem (triangular)

PlugNotas cobre via CFOPs específicos + documento referenciado (refNFe). Validar campo exato na doc e o cenário com o contador (ICMS/ST varia por UF).

Nota	Quem emite	Para	CFOP
Venda ao consumidor	Revendedor	Cliente final	`5.120 / 6.120`
Venda ao revendedor	Produtor	Revendedor	`5.118-5.119 / 6.118-6.119`
Remessa por conta e ordem	Produtor	Cliente final (acompanha a mercadoria)	`5.923 / 6.923`

Certificado A1

Só A1 (.pfx/.p12). Upload retorna um ID reutilizável que pode ser vinculado a várias empresas → encaixa direto no multi-tenant (cada tenant cadastra seu A1).

7 Módulos & telas

16 módulos de fronteira rígida. Cada card traz funcionalidades obrigatórias, telas e a fase. ⭐ = diferencial.

M1 · IAM / Acesso F0

Tenants, login+2FA, papéis/permissões, auditoria, LGPD.

Telas: Login · Onboarding · Usuários · Papéis · Auditoria · Perfil

M2 · Plataforma & Billing F0/F1

Planos, assinatura SaaS, limites, faturas + assinatura dos afiliados.

Telas: Planos · Faturas · Uso vs. limite

M3 · Cadastros F0/F1

Produtos (SKU/variações/kits/NCM/CEST), pessoas, bases fiscais.

Telas: Lista/Cadastro de Produto (abas) · Pessoas · Cadastros fiscais

M4 · Catálogo & Vitrine F1/F4

Fotos, atributos, ficha; catálogo B2B para revenda.

Telas: Editor de vitrine · Galeria · Catálogo B2B

M5 · Integrações Marketplace F1

OAuth ML/Shopee/hub, importar anúncios/pedidos, sync estoque/preço.

Telas: Canais · De-para anúncio↔produto · Log de sync

M6 · Pedidos / OMS F1

Pedidos omnichannel, status unificado, expedição, devoluções. Inclui Checkout/bipagem com painel ao vivo.

Telas: Lista · Detalhe · Checkout (bipagem) · Expedição · Devoluções

M7 · Estoque F1

Multi-depósito, Full/FBM separado, reservas, ruptura, kardex.

Telas: Saldo · Movimentações · Ajuste/Inventário · Depósitos

M8 · Compras F2

Pedido de compra, recebimento, entrada por XML, custo.

Telas: Pedidos de Compra · Recebimento · Importar XML

M9 · Financeiro F2

A pagar/receber, categorias, centros de custo, conciliação bancária.

Telas: Movimentações · Categorias · Centros de Custo · Fluxo de Caixa

M10 · Conciliação Marketplace ⭐ F2

Repasses → comissão/frete/taxas → margem real por pedido/SKU.

Telas: Repasses · Conciliação por pedido · Margem real · Divergências

M11 · Fiscal (PlugNotas) F3

A1 por tenant, NF-e/NFC-e, venda à ordem, remessa Full, XML, contingência.

Telas: Emitente/Certificado · Emissão · Documentos · Download XML

M12 · Logística F3

Integrações logísticas, etiquetas, frete, rastreio.

Telas: Integrações · Etiquetas · Expedição · Rastreio

M13 · Rede de Fornecimento ⭐ F4

Parceria+assinatura, catálogo B2B, pedido dropship cross-tenant, portal externo.

Telas: Publicar catálogo · Parceiros · Fila dropship · Portal do revendedor

M14 · Precificação F1/F5

Listas/regras de preço por canal; reprecificação com IA própria (F5).

Telas: Listas de Preço · Regras por canal · Reprecificação

M15 · Relatórios & BI F1/F5

Dashboard, vendas/estoque/financeiro, curva ABC, DRE.

Telas: Dashboard · Relatórios · Curva ABC · Exportações

M16 · Notificações F1+

Alertas in-app/e-mail/webhooks (ruptura, NF rejeitada, repasse divergente).

Telas: Central de Notificações · Alertas · Webhooks

8 Arquitetura

Princípios

Modular monolith

1 deploy, módulos de fronteira rígida. Extrai serviço só quando um módulo precisar escalar sozinho.

Módulo = dono das tabelas

Ninguém faz JOIN no banco de outro. Conversa por API interna (service) ou evento (Outbox).

Multi-tenant pool + RLS

Banco compartilhado + Row-Level Security por tenant_id. Dedicado para whales sem mudar código.

Pesado = assíncrono

Sync de canal, fiscal e conciliação em workers/fila, com idempotência, retry e rate-limit por canal.

Adapters isolados

PlugNotas, ML, Shopee, hub, logística atrás de interfaces. O core não conhece a SEFAZ nem a API do canal.

Contratos = terceirização

Cada seta entre módulos é OpenAPI + schema de evento. Dá para contratar um fornecedor por módulo.

Camadas

Next.js (web) → BFF/Gateway → Módulos (domínio) → Adapters externos
                                   │                 (PlugNotas, ML, Shopee, hub, logística)
                                   └─ Outbox → Event Bus → Workers

Dependências entre módulos

M5 Canal ──(pedido.importado)──▶ M6 Pedidos ──▶ M7 Estoque (reserva)
M6 Pedidos ──(pedido.pago)──▶ M11 Fiscal ──▶ M12 Logística (etiqueta)
M6 ──(faturado)──▶ M9 Financeiro      repasse ──▶ M10 Conciliação ──▶ M15 Margem
M13 Rede ──(dropship.liberado)──▶ M6 do produtor + M11 (venda à ordem)
tudo ──(eventos)──▶ M16 Notificações

9 Roadmap por fases

Fundação
repos isoladoscloud própriaPostgres multi-tenant + RLSauth ZitadelTaskiq + Outboxbases fiscais

Cadastros + Marketplace (MVP)
produtos/variações/kitsestoque FullML+Shopeepedidosdashboard

Financeiro + Conciliação ⭐
a pagar/receberrepassesmargem real

Fiscal (PlugNotas)
A1NF-e/NFC-evenda à ordemremessa Full

Rede de Fornecimento (Dropship) ⭐
catálogo B2Bpedido cross-tenantportal externo

Avançado
IA própria (preço/alertas)hub cauda longaBI

10 Riscos

Escopo (poço sem fundo)

ERP cresce infinito. Disciplina de MVP é vida — não copiar o legado do SoftUp.

Fiscal venda à ordem

Triangular tem regra própria de NF/CFOP/ICMS por UF. Validar cedo com contador.

Complexidade cross-tenant

Pedido dropship cruza dois tenants: isolamento, permissões e visibilidade.

Reforma Tributária (CBS/IBS)

Em teste desde jan/2026 — motivo extra do motor de mercado; guardar dados fiscais suficientes.

Separação Sellers Hub

Guardrail contratual: zero reaproveitamento de código/infra entre as empresas.

Rate limit dos canais

ML/Shopee limitam por app/seller. Filas + backoff + idempotência desde o início.

Documento gerado em 2026-06-25 · plano vivo — atualizado a cada decisão. Decisões refinadas pela spec e ratificadas (Zitadel, Taskiq, Focus NFe, Asaas) + correção F0 do RLS. Fontes detalhadas: spec/ (requirements·design·tasks) · PLANEJAMENTO.md · COMPARATIVO-FISCAL.md · FUNCIONALIDADES-E-ARQUITETURA.md