Essencialista Admin

Fluxo recomendado — integração ERP

Do tipo de conexão à ativação — API-first, revisão humana nos mapeamentos.

Passo 1
Escolher modo
cloud_db (recomendado), cloud_api ou agent on-premise.
Ver modos
Passo 2
Testar credenciais
POST /erp-connections/{id}/test antes de gerar mapeamentos.
API Explorer
Passo 3
Validar e ativar
generate → validate → PATCH status active + sync_interval.
Wizard referência /admin/settings/erp-connection

Princípios

ERP no aranduOS = API wizard + plugins custom. SSOT: docs/erp-integration.md

Regra	Detalhe
API-first	Teste, mapeamento e validação via REST — não só UI
Plugin por cliente	ERP complexo → extensions/ no repo cliente (Mirá implementa)
Credenciais seguras	Password/token só no body wizard; nunca reemitidos na API
LLM via LiteLLM	Geração de templates — llm.mira-dev.tech; fallback heurístico
Um ERP por tenant	Member isolado; platform monitora rede

Modos de conexão

Modo	Valor API	Quando usar
Cloud — banco de dados	cloud_db	PostgreSQL, MySQL ou SQL Server (recomendado)
Cloud — API REST	cloud_api	ERP com REST/OpenAPI documentado
Agent on-premise	agent	ERP na rede cliente — conexão de saída apenas

Introspecção SQL live + amostra de dados: PostgreSQL, MySQL e SQL Server.

Wizard — quatro passos

Passo	UX	API
1 — Tipo	cloud_db / cloud_api / agent	POST /erp-connections
2 — Credenciais	Host, DB, API URL, agent token	POST …/test
3 — Mapeamento	IA + edição manual	POST …/mappings/generate · …/validate
4 — Ativação	Intervalo sync	PATCH …/{id} status active

components/member/ERPWizard.tsx
Wizard multi-step (referência UX)
app/(member)/admin/settings/erp-connection
Member — configuração própria
app/(platform)/admin/settings/erp-connection
Platform — conta mãe
app/(platform)/admin/external-data
Monitoramento rede ERP

Operações mapeadas

Operação	Uso no commerce
get_price	Preço externo (external_data)
get_stock	Disponibilidade / inventário
create_order	Push pedido confirmado → ERP
update_order	Atualização pós-workflow
get_order_status	Reconciliação / polling

Cada linha: template SQL ou REST · confidence high/medium/low/manual · source_type sql|rest

Endpoints REST

Método	Path	Notas
GET	/erp-connections	inventory:read · platform ?tenant_id=
POST	/erp-connections	Criar conexão + mappings
GET/PATCH	/erp-connections/{id}	Detalhe / ativar
POST	/erp-connections/{id}/test	Credenciais no body (wizard)
POST	/erp-connections/{id}/mappings/generate	Descoberta + LiteLLM
POST	/erp-connections/{id}/mappings/validate	Executa templates live

Fluxo API

POST /v1/erp-connections
{ "mode": "cloud_db", "db_type": "postgres", "sync_interval": 60 }

POST /v1/erp-connections/{id}/test
{ "connection_type": "cloud_db", "host": "…", "password": "…", "ssl_enabled": true }

POST /v1/erp-connections/{id}/mappings/generate
→ { data: [...], meta: { used_llm, discovery_source, discovery_summary } }

POST /v1/erp-connections/{id}/mappings/validate
{ "rows": [...], "credentials": { … } }

PATCH /v1/erp-connections/{id}
{ "status": "active", "sync_interval": 300 }

Descoberta de schema

discovery_source	Origem
live_introspection	SQL real (Postgres information_schema)
openapi	OpenAPI do api_base_url
inferred	Heurística por modo/db
heuristic	Fallback sem credenciais live

SDK TypeScript

@mira/commerce-client-sdk

import {
  createErpConnection,
  testErpConnection,
  generateErpMappings,
  validateErpMappings,
} from "@mira/commerce-client-sdk"

const { data: conn } = await createErpConnection({
  client,
  body: { mode: "cloud_db", db_type: "postgres", sync_interval: 60 },
})

await testErpConnection({
  client,
  path: { connection_id: conn.id },
  body: { connection_type: "cloud_db", host: "…", password: "…" },
})

Facade: lib/commerce-client/domains/live/erp.ts · Catálogo SDK: /dev/experience/sdk

Extensão avançada (Fase 2b+)

SAP, TOTVS, Protheus ou regras fiscais → plugin Go no repo cliente.

IntegrationAdapter — ARCHITECTURE § Peça 1

capabilities:
  integrations:
    - erp.inventory_sync
  hooks:
    - integration.transform_outbound
    - integration.transform_inbound

// SyncInventory · SyncPrices · PushOrder · PushOrderStatus
// Protocolo: commerce.mira.dev/integration/erp/v1

Customização backend ERP: sempre equipe Mirá — ver extensibility-model.md

Estado de implementação

Componente	Documentado	Código	Notas
REST wizard (test / generate / validate)	Documentado	Documentado	internal/erp/
Wizard UX member + platform	Documentado	Documentado	ERPWizard.tsx
Introspecção SQL live + amostra (PG/MySQL/SQL Server)	Documentado	Documentado	catalog.go
Mapeamento LiteLLM	Documentado	Protótipo	Fallback heurístico sem LLM_API_URL
Motor sync / PushOrder plugin	Documentado	Documentado	IntegrationAdapter ligado: estoque/preço aplicados no catálogo + telemetria real
Agent on-premise (binário)	Protótipo	Planejado	UX protótipo; agent real backlog

Anti-patterns

Evitar	Preferir
Credenciais ERP no front-end	Wizard server-side + secrets cluster
SQL ad-hoc no React	Templates validados via API + plugin
Fork core para SAP	Plugin extensions/ + pin LTS
OPENAI direto no mapping	LLM_API_URL → llm.mira-dev.tech
Ativar sem validate	validate verde + sync_interval conservador

Checklist delivery

Modo cloud_db se DB acessível (readonly + allowlist)
test verde → generate → revisar confidence low
validate verde em staging
PATCH active com sync_interval ≥ 300s inicialmente
Monitorar /admin/external-data e alertas member
ERP complexo → ADR + plugin no repo cliente

API ExplorerWizard referência (painel) /admin/settings/erp-connectionMonitoramento ERP /admin/external-dataExtensibilidade (plugins)