747 lines
38 KiB
Markdown
747 lines
38 KiB
Markdown
# Arcádia SOE — Sistema Operacional Empresarial
|
||
## Mapa Completo para Deploy em Servidor Dedicado
|
||
|
||
> Mapa da rota `/soe`: todos os arquivos do módulo, domínios de negócio,
|
||
> padrão de motor (adapter), tabelas PostgreSQL, APIs REST e dependências
|
||
> externas. Atualizado em: Março 2026.
|
||
|
||
---
|
||
|
||
## 1. O que é o SOE
|
||
|
||
O **Arcádia SOE (Sistema Operacional Empresarial)** é o **kernel central** da Arcádia Suite — o sistema que concentra todos os domínios canônicos de negócio. Enquanto apps como Varejo, Engenharia e Food Service adicionam experiências verticais, o SOE é a camada horizontal que todos compartilham.
|
||
|
||
**Princípio central:** O SOE **pensa e governa**; os motores (Plus, ERPNext) **executam e registram**.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ ARCÁDIA SOE — VISÃO GERAL │
|
||
│ │
|
||
│ URL: /soe │
|
||
│ API: /api/soe/* (alias backward-compatible → /api/erp/*) │
|
||
│ │
|
||
│ ┌──────── Domínios Canônicos ────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ Pessoas │ Produtos │ Vendas │ Compras │ Estoque │ │
|
||
│ │ Fiscal │ Financ. │ CRM │ Projetos │ Qualidade │ │
|
||
│ │ Governa. │ RH │ │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────── Motores (Adapters) ────────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ motor = "plus" → Arcádia Plus (Laravel :8080) │ │
|
||
│ │ motor = "erpnext" → ERPNext/Frappe (externo) │ │
|
||
│ │ motor = nativo → PostgreSQL local (default fallback) │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────── Apps que estendem o SOE ───────────────────────────┐ │
|
||
│ │ Varejo (Retail) │ Engenharia │ Food Service │ │
|
||
│ │ Assistência Tec │ Educação │ (outros segmentos) │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Arquivos do Módulo SOE — Lista Completa para Export
|
||
|
||
### 2.1 — Frontend (React/TypeScript)
|
||
|
||
| Arquivo | Função | Linhas |
|
||
|---------|--------|--------|
|
||
| `client/src/pages/SOE.tsx` | **Página principal** do SOE — 9 abas, CRUD completo | 2.414 |
|
||
| `client/src/pages/ERP.tsx` | Legacy ERP — mantido para referência histórica | 2.197 |
|
||
| `client/src/contexts/SoeMotorContext.tsx` | **Context do Motor** — gerencia plus/erpnext via localStorage | 63 |
|
||
| `client/src/contexts/ErpProfileContext.tsx` | Alias legacy do SoeMotorContext (backward compat.) | 52 |
|
||
|
||
### 2.2 — Backend (Node.js/TypeScript)
|
||
|
||
| Arquivo | Função | Linhas |
|
||
|---------|--------|--------|
|
||
| `server/erp/routes.ts` | **Rotas SOE core** — /api/erp/* (= /api/soe/*) | 1.343 |
|
||
| `server/erp/index.ts` | Setup do módulo + alias /api/soe → /api/erp | 210 |
|
||
| `server/retail/routes.ts` | **Rotas do Varejo** — /api/retail/* | 5.218 |
|
||
| `server/retail/index.ts` | Setup do módulo retail | — |
|
||
| `server/retail/sync-service.ts` | Sincronização retail ↔ Plus | — |
|
||
| `server/retail/plus-sync.ts` | Ponte retail → Arcádia Plus | — |
|
||
| `server/plus/client.ts` | **Cliente HTTP** para Arcádia Plus (:8080) | 376 |
|
||
| `server/plus/routes.ts` | Rotas de integração Plus | — |
|
||
| `server/plus/launcher.ts` | Iniciador do serviço Plus | — |
|
||
| `server/plus/proxy.ts` | Proxy transparente → Plus (:8080) | — |
|
||
| `server/plus/sso.ts` | Single Sign-On entre SOE e Plus | — |
|
||
| `server/erpnext/routes.ts` | Rotas de integração ERPNext | — |
|
||
| `server/erpnext/index.ts` | Setup do módulo ERPNext | — |
|
||
|
||
### 2.3 — Schema PostgreSQL (Drizzle ORM)
|
||
|
||
| Arquivo | Tabelas relacionadas ao SOE |
|
||
|---------|----------------------------|
|
||
| `shared/schema.ts` (L348) | `erp_connections` |
|
||
| `shared/schema.ts` (L3303) | `erp_segments`, `erp_config` |
|
||
| `shared/schema.ts` (L3367–3517) | `customers`, `suppliers`, `products`, `sales_orders`, `sales_order_items`, `purchase_orders`, `purchase_order_items` |
|
||
| `shared/schema.ts` (L5082–5617) | Tabelas retail (ver seção 5) |
|
||
| `shared/schema.ts` (L6204) | `persons`, `person_roles` |
|
||
| `shared/schema.ts` (L4372) | `fin_payment_methods`, `fin_payment_plans` |
|
||
|
||
---
|
||
|
||
## 3. Arquitetura de Arquivos
|
||
|
||
```
|
||
workspace/
|
||
│
|
||
├── client/src/
|
||
│ ├── pages/
|
||
│ │ ├── SOE.tsx ← Página principal (/soe)
|
||
│ │ └── ERP.tsx ← Legacy (mantido)
|
||
│ │
|
||
│ └── contexts/
|
||
│ ├── SoeMotorContext.tsx ← Motor context (plus | erpnext)
|
||
│ └── ErpProfileContext.tsx ← Alias backward-compat
|
||
│
|
||
├── server/
|
||
│ ├── erp/
|
||
│ │ ├── routes.ts ← /api/erp/* (= /api/soe/*)
|
||
│ │ └── index.ts ← Setup + alias soe→erp
|
||
│ │
|
||
│ ├── retail/
|
||
│ │ ├── routes.ts ← /api/retail/*
|
||
│ │ ├── index.ts
|
||
│ │ ├── sync-service.ts
|
||
│ │ └── plus-sync.ts
|
||
│ │
|
||
│ ├── plus/
|
||
│ │ ├── client.ts ← HTTP client → Plus :8080
|
||
│ │ ├── routes.ts
|
||
│ │ ├── proxy.ts
|
||
│ │ ├── launcher.ts
|
||
│ │ └── sso.ts
|
||
│ │
|
||
│ └── erpnext/
|
||
│ ├── routes.ts
|
||
│ └── index.ts
|
||
│
|
||
└── shared/
|
||
└── schema.ts ← Tabelas SOE + Retail
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Motor de Execução (Adapter Pattern)
|
||
|
||
O SOE usa um **padrão de adapter** para rotear operações para o motor correto:
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ SOEOMOTOR — ADAPTER PATTERN │
|
||
│ │
|
||
│ SoeMotorContext.tsx │
|
||
│ │
|
||
│ export type SoeMotor = "plus" | "erpnext" │
|
||
│ │
|
||
│ Persistência: localStorage["arcadia_soe_motor"] │
|
||
│ │
|
||
│ getApiUrl(localPath, plusPath, erpnextPath?) │
|
||
│ │
|
||
│ ┌──────── motor = "plus" ────────────────────────────────────┐ │
|
||
│ │ → /plus/api{plusPath} │ │
|
||
│ │ → Passa pelo proxy transparente do Plus │ │
|
||
│ │ → Arcádia Plus (Laravel) em :8080 │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────── motor = "erpnext" ─────────────────────────────────┐ │
|
||
│ │ → erpnextPath ou localPath │ │
|
||
│ │ → ERPNext API (ERPNEXT_URL env var) │ │
|
||
│ │ → Autenticado via ERPNEXT_API_KEY + ERPNEXT_API_SECRET │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────── motor = nativo (fallback) ─────────────────────────┐ │
|
||
│ │ → localPath (/api/erp/*) │ │
|
||
│ │ → PostgreSQL local via Drizzle ORM │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ Seleção na UI: SOE.tsx → Config tab → Dropdown de motor │
|
||
│ Plus ativo: isERPNextConnected verifica /api/erpnext/connections │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Domínios e Abas do SOE
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ SOE.tsx — 9 ABAS PRINCIPAIS │
|
||
│ │
|
||
│ ┌── Tab: dashboard ──────────────────────────────────────────┐ │
|
||
│ │ • Stats: clientes, produtos, pedidos, total vendas │ │
|
||
│ │ • Cards com indicadores-chave do negócio │ │
|
||
│ │ • Acesso rápido às seções │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: persons (Pessoas) ───────────────────────────────────┐ │
|
||
│ │ • Clientes, Fornecedores, Funcionários, Técnicos, Parceiros│ │
|
||
│ │ • Busca + filtro por papel (role) │ │
|
||
│ │ • Campos: nome, CPF/CNPJ, email, telefone, endereço │ │
|
||
│ │ • Tabelas: persons + person_roles │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: products (Produtos) ─────────────────────────────────┐ │
|
||
│ │ • Cadastro de produtos/serviços │ │
|
||
│ │ • Rastreamento: IMEI, Número de Série, sem rastreamento │ │
|
||
│ │ • Grupos de produto, unidades (UN/KG/M/L/CX/PC) │ │
|
||
│ │ • Estoque por produto, devices batch import │ │
|
||
│ │ • Tabela: products + mobile_devices │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: sales (Vendas) ──────────────────────────────────────┐ │
|
||
│ │ • Pedidos de venda │ │
|
||
│ │ • Status: draft → confirmed → delivered │ │
|
||
│ │ • Geração de NF-e a partir do pedido │ │
|
||
│ │ • Formas de pagamento: Dinheiro/Cartão/PIX/Boleto/Prazo │ │
|
||
│ │ • Tabelas: sales_orders + sales_order_items │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: purchases (Compras) ─────────────────────────────────┐ │
|
||
│ │ • Pedidos de compra │ │
|
||
│ │ • Associados a fornecedores │ │
|
||
│ │ • Tabelas: purchase_orders + purchase_order_items │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: financial (Financeiro) ──────────────────────────────┐ │
|
||
│ │ • Visão financeira consolidada │ │
|
||
│ │ • Planos de pagamento e parcelamento │ │
|
||
│ │ • Tabelas: fin_payment_methods + fin_payment_plans │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: crm ─────────────────────────────────────────────────┐ │
|
||
│ │ • Módulo CRM inline no SOE │ │
|
||
│ │ • Integrado via useTenantFeatures (feature: crm) │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: sync (Sincronização) ────────────────────────────────┐ │
|
||
│ │ • Status dos motores (Plus/ERPNext) │ │
|
||
│ │ • Módulos ativos/inativos do tenant │ │
|
||
│ │ • Botões de sync manual por entidade │ │
|
||
│ │ • Indica se Plus está online (:8080) │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌── Tab: config (Configuração) ───────────────────────────────┐ │
|
||
│ │ • Dados da empresa: razão social, CNPJ, regime tributário │ │
|
||
│ │ • Inscrição estadual/municipal │ │
|
||
│ │ • Segmento de negócio │ │
|
||
│ │ • Seletor de motor: Plus ou ERPNext │ │
|
||
│ │ • Tabela: erp_config + erp_segments │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Tabelas PostgreSQL — SOE Core
|
||
|
||
### 6.1 — erp_connections (Conexões com ERPs externos)
|
||
|
||
```
|
||
erp_connections
|
||
├── id serial PK
|
||
├── userId FK → users.id
|
||
├── erpType "erpnext" | "plus" | "omie" | etc.
|
||
├── name Nome da conexão
|
||
├── url URL do ERP
|
||
├── apiKey Chave de API
|
||
├── apiSecret Secret
|
||
├── isActive boolean
|
||
└── createdAt, updatedAt
|
||
```
|
||
|
||
### 6.2 — erp_segments (Segmentos de Negócio)
|
||
|
||
```
|
||
erp_segments
|
||
├── id serial PK
|
||
├── name Nome (Varejo, Serviços, Indústria, etc.)
|
||
├── description Descrição
|
||
├── icon Ícone
|
||
└── createdAt
|
||
```
|
||
|
||
### 6.3 — erp_config (Configuração da Empresa)
|
||
|
||
```
|
||
erp_config
|
||
├── id serial PK
|
||
├── userId FK → users.id
|
||
├── companyName Razão Social
|
||
├── tradeName Nome Fantasia
|
||
├── taxId CNPJ
|
||
├── taxRegime simples | lucro_presumido | lucro_real
|
||
├── stateRegistration Inscrição Estadual
|
||
├── cityRegistration Inscrição Municipal
|
||
├── segmentId FK → erp_segments.id
|
||
├── address Endereço completo
|
||
└── createdAt, updatedAt
|
||
```
|
||
|
||
### 6.4 — customers (Clientes)
|
||
|
||
```
|
||
customers
|
||
├── id serial PK
|
||
├── userId FK → users.id
|
||
├── code Código interno
|
||
├── name Nome
|
||
├── email E-mail
|
||
├── phone Telefone
|
||
├── document CPF/CNPJ
|
||
├── type company | individual
|
||
├── address Endereço
|
||
└── createdAt, updatedAt
|
||
```
|
||
|
||
### 6.5 — suppliers (Fornecedores)
|
||
|
||
```
|
||
suppliers
|
||
├── id serial PK
|
||
├── userId FK → users.id
|
||
├── code Código interno
|
||
├── name Nome/Razão Social
|
||
├── email, phone
|
||
├── document CNPJ/CPF
|
||
└── createdAt, updatedAt
|
||
```
|
||
|
||
### 6.6 — products (Produtos)
|
||
|
||
```
|
||
products
|
||
├── id serial PK
|
||
├── userId FK → users.id
|
||
├── code Código/SKU
|
||
├── name Nome do produto
|
||
├── description
|
||
├── price Decimal(10,2)
|
||
├── costPrice Preço de custo
|
||
├── unit UN | KG | M | L | CX | PC
|
||
├── stock Estoque atual
|
||
├── minStock Estoque mínimo
|
||
├── groupId Grupo de produto
|
||
├── requiresSerialTracking boolean
|
||
├── trackingType none | imei | serial
|
||
└── createdAt, updatedAt
|
||
```
|
||
|
||
### 6.7 — sales_orders + sales_order_items
|
||
|
||
```
|
||
sales_orders
|
||
├── id serial PK
|
||
├── userId FK → users.id
|
||
├── customerId FK → customers.id
|
||
├── orderNumber Número do pedido
|
||
├── status draft | confirmed | delivered | cancelled
|
||
├── total Decimal(10,2)
|
||
├── paymentMethod dinheiro | cartao_credito | pix | boleto | prazo
|
||
└── createdAt, updatedAt
|
||
|
||
sales_order_items
|
||
├── id serial PK
|
||
├── orderId FK → sales_orders.id
|
||
├── productId FK → products.id
|
||
├── quantity integer
|
||
├── unitPrice Decimal(10,2)
|
||
└── total Decimal(10,2)
|
||
```
|
||
|
||
### 6.8 — purchase_orders + purchase_order_items
|
||
|
||
```
|
||
purchase_orders
|
||
├── id serial PK
|
||
├── userId FK → users.id
|
||
├── supplierId FK → suppliers.id
|
||
├── orderNumber
|
||
├── status draft | confirmed | received | cancelled
|
||
├── total Decimal(10,2)
|
||
└── createdAt, updatedAt
|
||
|
||
purchase_order_items
|
||
├── id serial PK
|
||
├── orderId FK → purchase_orders.id
|
||
├── productId FK → products.id
|
||
├── quantity, unitPrice, total
|
||
```
|
||
|
||
### 6.9 — persons + person_roles (Cadastro Unificado)
|
||
|
||
```
|
||
persons
|
||
├── id serial PK
|
||
├── tenantId FK → tenants.id
|
||
├── fullName
|
||
├── cpfCnpj
|
||
├── email, phone
|
||
├── address, city, state, zipCode
|
||
├── type company | individual
|
||
└── notes, createdAt, updatedAt
|
||
|
||
person_roles
|
||
├── id serial PK
|
||
├── personId FK → persons.id
|
||
├── role customer | supplier | employee | technician | partner
|
||
└── isActive
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Tabelas PostgreSQL — Módulo Varejo (Retail)
|
||
|
||
### 7.1 — Estrutura Operacional
|
||
|
||
```
|
||
retail_stores → Lojas físicas
|
||
retail_warehouses → Depósitos/Almoxarifados
|
||
retail_payment_methods → Formas de pagamento
|
||
retail_sellers → Vendedores
|
||
retail_commission_plans → Planos de comissão
|
||
retail_seller_goals → Metas por vendedor
|
||
retail_store_goals → Metas por loja
|
||
```
|
||
|
||
### 7.2 — Estoque
|
||
|
||
```
|
||
stock_transfers → Transferências entre depósitos
|
||
stock_transfer_items → Itens da transferência
|
||
```
|
||
|
||
### 7.3 — Dispositivos Móveis (Eletrônicos)
|
||
|
||
```
|
||
mobile_devices
|
||
├── id serial PK
|
||
├── productId FK → products.id
|
||
├── imei varchar (único)
|
||
├── imei2 varchar (chip duplo)
|
||
├── serial Número de série
|
||
├── status em_estoque | vendido | locado | devolucao | avaliacao
|
||
├── color, storage, ram
|
||
├── purchasePrice, salePrice
|
||
└── supplierId, createdAt
|
||
|
||
device_evaluations → Avaliação de aparelhos usados
|
||
device_history → Histórico completo do dispositivo
|
||
```
|
||
|
||
### 7.4 — PDV (Ponto de Venda)
|
||
|
||
```
|
||
pos_sessions → Sessões de caixa (abertura/fechamento)
|
||
pos_sales → Vendas PDV
|
||
pos_sale_items → Itens das vendas PDV
|
||
```
|
||
|
||
### 7.5 — Planos de Pagamento
|
||
|
||
```
|
||
payment_plans → Planos parcelados
|
||
payment_plan_installments → Parcelas
|
||
lease_payments → Pagamentos de locação
|
||
```
|
||
|
||
---
|
||
|
||
## 8. API REST Completa (/api/soe/* = /api/erp/*)
|
||
|
||
> O alias `/api/soe/*` é convertido automaticamente para `/api/erp/*`
|
||
> no middleware do `server/erp/index.ts`.
|
||
|
||
### 8.1 — Conexões ERP
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/connections` | Lista conexões do usuário |
|
||
| POST | `/api/soe/connections` | Cria nova conexão |
|
||
| POST | `/api/soe/connections/:id/test` | Testa conectividade |
|
||
| DELETE | `/api/soe/connections/:id` | Remove conexão |
|
||
|
||
### 8.2 — Tarefas ERP (Sync Jobs)
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/tasks` | Lista tarefas de sync |
|
||
| POST | `/api/soe/tasks` | Cria nova tarefa |
|
||
| POST | `/api/soe/tasks/:id/execute` | Executa tarefa manualmente |
|
||
| DELETE | `/api/soe/tasks/:id` | Remove tarefa |
|
||
| GET | `/api/soe/tasks/:id/executions` | Histórico de execuções |
|
||
|
||
### 8.3 — Clientes
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/customers` | Lista clientes (paginado) |
|
||
| POST | `/api/soe/customers` | Cria cliente |
|
||
| PUT | `/api/soe/customers/:id` | Atualiza cliente |
|
||
| DELETE | `/api/soe/customers/:id` | Exclui cliente |
|
||
|
||
### 8.4 — Fornecedores
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/suppliers` | Lista fornecedores |
|
||
| POST | `/api/soe/suppliers` | Cria fornecedor |
|
||
| PUT | `/api/soe/suppliers/:id` | Atualiza |
|
||
| DELETE | `/api/soe/suppliers/:id` | Exclui |
|
||
|
||
### 8.5 — Pessoas (Cadastro Unificado)
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/persons` | Lista com filtro por role/search |
|
||
| GET | `/api/soe/persons/:id` | Detalhe + roles |
|
||
| POST | `/api/soe/persons` | Cria pessoa + roles |
|
||
| PUT | `/api/soe/persons/:id` | Atualiza pessoa + roles |
|
||
| DELETE | `/api/soe/persons/:id` | Exclui pessoa (cascade roles) |
|
||
|
||
### 8.6 — Produtos
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/products` | Lista produtos |
|
||
| POST | `/api/soe/products` | Cria produto |
|
||
| PUT | `/api/soe/products/:id` | Atualiza |
|
||
| DELETE | `/api/soe/products/:id` | Exclui |
|
||
| GET | `/api/soe/products/:id/devices` | Dispositivos do produto |
|
||
| POST | `/api/soe/products/:id/devices/batch` | Import batch de IMEIs |
|
||
| GET | `/api/soe/products/:id/stock-count` | Contagem de estoque |
|
||
|
||
### 8.7 — Pedidos de Venda
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/sales-orders` | Lista pedidos |
|
||
| POST | `/api/soe/sales-orders` | Cria pedido (com itens) |
|
||
| POST | `/api/soe/sales-orders/:id/confirm` | Confirma pedido |
|
||
| POST | `/api/soe/sales-orders/:id/generate-nfe` | Gera NF-e |
|
||
| DELETE | `/api/soe/sales-orders/:id` | Cancela/Exclui |
|
||
|
||
### 8.8 — Pedidos de Compra
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/purchase-orders` | Lista pedidos |
|
||
| POST | `/api/soe/purchase-orders` | Cria pedido |
|
||
| DELETE | `/api/soe/purchase-orders/:id` | Exclui |
|
||
|
||
### 8.9 — Dados e Configuração
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/stats` | Dashboard — totais de clientes/produtos/pedidos/receita |
|
||
| GET | `/api/soe/data/:connectionId/:dataType` | Dados via conexão ERP |
|
||
| GET | `/api/soe/segments` | Lista segmentos |
|
||
| POST | `/api/soe/segments` | Cria segmento |
|
||
| POST | `/api/soe/segments/seed` | Popula segmentos padrão |
|
||
| GET | `/api/soe/config` | Configuração da empresa |
|
||
| POST | `/api/soe/config` | Salva configuração |
|
||
|
||
### 8.10 — Módulos do Tenant
|
||
|
||
| Método | Endpoint | Função |
|
||
|--------|----------|--------|
|
||
| GET | `/api/soe/tenant/modules` | Módulos ativos do tenant atual |
|
||
| PUT | `/api/soe/tenant/modules` | Ativa/desativa módulos |
|
||
|
||
---
|
||
|
||
## 9. API REST — Módulo Varejo (/api/retail/*)
|
||
|
||
### 9.1 — Estrutura Operacional
|
||
|
||
| Módulo | Endpoints | Operações |
|
||
|--------|-----------|-----------|
|
||
| Activity Feed | `/activity-feed` | GET, mark-read |
|
||
| Payment Methods | `/payment-methods` | CRUD |
|
||
| Sellers | `/sellers` | CRUD |
|
||
| Commission Plans | `/commission-plans` | CRUD |
|
||
| Price Tables | `/price-tables` | CRUD |
|
||
| Promotions | `/promotions` | CRUD |
|
||
| Product Types | `/product-types` | CRUD + detail |
|
||
| Stores | `/stores` | CRU |
|
||
| Warehouses | `/warehouses` | CRUD |
|
||
|
||
### 9.2 — Estoque
|
||
|
||
| Módulo | Endpoints | Operações |
|
||
|--------|-----------|-----------|
|
||
| Warehouse Stock | `/warehouse-stock` | GET list + summary |
|
||
| Stock Movements | `/stock-movements` | GET + POST |
|
||
| Product Serials | `/product-serials` | CRUD |
|
||
| Stock Transfers | `/stock-transfers` | CRUD + status |
|
||
| Stock Alerts | `/stock-alerts` | GET |
|
||
| Inventories | `/inventories` | CRUD + count + apply |
|
||
|
||
### 9.3 — Dispositivos (Mobile/Eletrônicos)
|
||
|
||
| Módulo | Endpoints | Operações |
|
||
|--------|-----------|-----------|
|
||
| Devices | `/devices` | CRUD + IMEI lookup |
|
||
| Evaluations | `/evaluations` | CRUD + approve + reject |
|
||
|
||
### 9.4 — Serviços
|
||
|
||
| Módulo | Endpoints | Operações |
|
||
|--------|-----------|-----------|
|
||
| Service Orders | `/service-orders` | CRUD + complete-preparation + items |
|
||
| Warranties | `/warranties` | CRUD + check IMEI + claim |
|
||
|
||
### 9.5 — PDV
|
||
|
||
| Módulo | Endpoints | Operações |
|
||
|--------|-----------|-----------|
|
||
| POS Sessions | `/pos-sessions` | GET + open + close |
|
||
| Cash Movements | `/cash-movements` | GET + POST |
|
||
|
||
### 9.6 — Relatórios
|
||
|
||
| Endpoint | Descrição |
|
||
|----------|-----------|
|
||
| `/reports/os-by-status` | OS agrupadas por status |
|
||
| `/reports/os-by-technician` | OS agrupadas por técnico |
|
||
|
||
**Total: ~120 endpoints no módulo SOE (Core + Retail)**
|
||
|
||
---
|
||
|
||
## 10. Dependências Externas do SOE
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ DEPENDÊNCIAS DO SOE │
|
||
│ │
|
||
│ ┌──── Arcádia Plus (Laravel) ────────────────────────────────┐ │
|
||
│ │ Host: :8080 (mesmo servidor) ou externo │ │
|
||
│ │ Env: PLUS_URL (se externo) │ │
|
||
│ │ Proxy: /plus/* → :8080 │ │
|
||
│ │ SSO: token compartilhado via plus/sso.ts │ │
|
||
│ │ Sync: retail/plus-sync.ts + retail/sync-service.ts │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──── ERPNext/Frappe ─────────────────────────────────────────┐ │
|
||
│ │ Host: ERPNEXT_URL (env var no servidor) │ │
|
||
│ │ Auth: ERPNEXT_API_KEY + ERPNEXT_API_SECRET │ │
|
||
│ │ Entidades: Customer, Supplier, Item, Sales Order │ │
|
||
│ │ Rotas: server/erpnext/routes.ts → /api/erpnext/* │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──── Arcádia Fisco (:8002) ──────────────────────────────────┐ │
|
||
│ │ Geração de NF-e a partir do pedido de venda │ │
|
||
│ │ POST /api/soe/sales-orders/:id/generate-nfe │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──── PostgreSQL ─────────────────────────────────────────────┐ │
|
||
│ │ DATABASE_URL env var │ │
|
||
│ │ Motor padrão (nativo) sem Plus/ERPNext │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 11. Variáveis de Ambiente Necessárias para Deploy
|
||
|
||
```bash
|
||
# PostgreSQL (obrigatório)
|
||
DATABASE_URL=postgresql://user:pass@host:5432/arcadia
|
||
|
||
# ERPNext (opcional — apenas se motor = "erpnext")
|
||
ERPNEXT_URL=https://seu-erpnext.com
|
||
ERPNEXT_API_KEY=sua-chave
|
||
ERPNEXT_API_SECRET=seu-secret
|
||
|
||
# Arcádia Plus (opcional — apenas se motor = "plus")
|
||
PLUS_URL=http://localhost:8080 # ou URL externa do Plus
|
||
|
||
# Fisco (para geração de NF-e via SOE)
|
||
FISCO_URL=http://localhost:8002 # ou URL externa do Fisco
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Checklist de Export para Deploy Manual
|
||
|
||
### Frontend
|
||
- [ ] `client/src/pages/SOE.tsx`
|
||
- [ ] `client/src/pages/ERP.tsx`
|
||
- [ ] `client/src/contexts/SoeMotorContext.tsx`
|
||
- [ ] `client/src/contexts/ErpProfileContext.tsx`
|
||
|
||
### Backend
|
||
- [ ] `server/erp/routes.ts`
|
||
- [ ] `server/erp/index.ts`
|
||
- [ ] `server/retail/routes.ts`
|
||
- [ ] `server/retail/index.ts`
|
||
- [ ] `server/retail/sync-service.ts`
|
||
- [ ] `server/retail/plus-sync.ts`
|
||
- [ ] `server/plus/client.ts`
|
||
- [ ] `server/plus/routes.ts`
|
||
- [ ] `server/plus/proxy.ts`
|
||
- [ ] `server/plus/launcher.ts`
|
||
- [ ] `server/plus/sso.ts`
|
||
- [ ] `server/erpnext/routes.ts`
|
||
- [ ] `server/erpnext/index.ts`
|
||
|
||
### Schema e Banco
|
||
- [ ] `shared/schema.ts` (tabelas: L348, L3303–3517, L5082–5617, L6204)
|
||
- [ ] Rodar `drizzle-kit push` no servidor para criar as tabelas
|
||
- [ ] Verificar variável `DATABASE_URL` no servidor
|
||
|
||
### Configuração do Servidor
|
||
- [ ] `.env` com `DATABASE_URL` (obrigatório)
|
||
- [ ] `.env` com `ERPNEXT_*` (se usar motor ERPNext)
|
||
- [ ] `.env` com `PLUS_URL` (se usar motor Plus)
|
||
- [ ] Confirmar que `:8080` (Plus) está acessível se necessário
|
||
|
||
---
|
||
|
||
## 13. Resumo Visual do Módulo
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ ARCÁDIA SOE — STACK COMPLETO │
|
||
│ │
|
||
│ URL /soe → SOE.tsx (2.414L) │
|
||
│ │
|
||
│ 9 Abas: Dashboard │ Pessoas │ Produtos │ Vendas │ Compras │
|
||
│ Financeiro │ CRM │ Sync │ Config │
|
||
│ │
|
||
│ ┌─── Motor (Adapter) ────────────────────────────────────────┐ │
|
||
│ │ localStorage["arcadia_soe_motor"] = "plus" | "erpnext" │ │
|
||
│ │ │ │
|
||
│ │ plus → /plus/api/* → Arcádia Plus :8080 (Laravel) │ │
|
||
│ │ erpnext → ERPNext API → ERPNEXT_URL externo │ │
|
||
│ │ nativo → /api/soe/* → PostgreSQL local (Drizzle) │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─── Backend ────────────────────────────────────────────────┐ │
|
||
│ │ /api/soe/* → /api/erp/* (alias automático) │ │
|
||
│ │ server/erp/routes.ts (1.343L) → 35+ endpoints core │ │
|
||
│ │ server/retail/routes.ts (5.218L) → 85+ endpoints varejo │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─── Banco de Dados ─────────────────────────────────────────┐ │
|
||
│ │ Core: customers, suppliers, products, sales_orders, │ │
|
||
│ │ purchase_orders, persons, erp_config, erp_segments │ │
|
||
│ │ │ │
|
||
│ │ Retail: retail_stores, retail_warehouses, mobile_devices, │ │
|
||
│ │ device_evaluations, pos_sessions, pos_sales, │ │
|
||
│ │ stock_transfers, payment_plans (20+ tabelas) │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─── Integrações ────────────────────────────────────────────┐ │
|
||
│ │ Arcádia Plus :8080 │ ERPNext/Frappe │ Fisco :8002 │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|