diff --git a/.env b/.env new file mode 100644 index 0000000..723e228 --- /dev/null +++ b/.env @@ -0,0 +1,20 @@ +PGPASSWORD=afefb610090de1646944b537f3054715ad5755665c90036c2bcd258c9ab52dd8 +SESSION_SECRET=092a26dcbebd6f7f5e7b9e020bdc4d4e966286c9780ef72e3426f437eb8d608b +SSO_SECRET=fbb87d1c5a14a6623d4e3dcc2b679bd68c46e59afb48dd6abd42b95cac945856 +LITELLM_API_KEY=e396b827cbeb5e77d85cce4eb9da0521114f57a8e799f7aa8febad08d776c07e +WEBUI_SECRET_KEY=76c7fc044f9e8d6e5eb60b67c82832b67e84739da4827ce1fa7c101ae1a055df +DOMAIN=suite.onboardbi.com.br +OLLAMA_BASE_URL=http://ollama-ia1upsekrad96at5hq97e4qa:11434 + +LLMFIT_BASE_URL=http://llmfit:8000 +LLMFIT_API_KEY=key-arcadia + +# ── Superset BI ─────────────────────────────────────────────── +SUPERSET_SECRET_KEY=421274b5ba360778a5398d528116a45ea962d1197e3dfc99f36a372ff1025a63 +SUPERSET_ADMIN_USERNAME=admin +SUPERSET_ADMIN_PASSWORD=arcadia1337 +SUPERSET_ADMIN_EMAIL=engenharia@ometas.com.br +COMPOSE_PROFILES=bi + +SUPERSET_HOST=superset +SUPERSET_PORT=8088 diff --git a/.env.example b/.env.example index 062142e..359d87e 100644 --- a/.env.example +++ b/.env.example @@ -1,70 +1,110 @@ -# ============================================== -# Arcádia Suite - Variáveis de Ambiente -# ============================================== -# Copie este arquivo para .env e preencha os valores +# ─── Arcádia Suite — Variáveis de Ambiente ──────────────────────────────────── +# Copie para .env e preencha os valores. +# NUNCA commite o arquivo .env real. -# ---- Banco de Dados PostgreSQL ---- -DATABASE_URL=postgresql://arcadia:SuaSenhaSegura@db:5432/arcadia -PGHOST=db +# ── Banco de dados ──────────────────────────────────────────────────────────── +DATABASE_URL=postgresql://arcadia:arcadia123@localhost:5432/arcadia +PGHOST=localhost PGPORT=5432 PGUSER=arcadia -PGPASSWORD=SuaSenhaSegura +PGPASSWORD=arcadia123 PGDATABASE=arcadia -# ---- Servidor ---- -NODE_ENV=production +# ── Aplicação ───────────────────────────────────────────────────────────────── +NODE_ENV=development PORT=5000 -SESSION_SECRET=gere-uma-chave-secreta-aleatoria-aqui +SESSION_SECRET=troque-por-string-aleatoria-segura-em-producao +SSO_SECRET=arcadia-sso-secret-2024-plus-integration-key-secure -# ---- SSO / Multi-tenant ---- -SSO_SECRET=gere-outra-chave-secreta-aqui +# ── Docker Mode (desativa spawn de processos filhos) ───────────────────────── +# Em produção com Docker, defina como "true" +DOCKER_MODE=false -# ---- Senha do Gerente (Retail) ---- -MANAGER_PASSWORD=sua-senha-de-gerente +# ── URLs dos microserviços Python ───────────────────────────────────────────── +# Em Docker: use nome do serviço (ex: http://contabil:8003) +# Em desenvolvimento local: use localhost +CONTABIL_PYTHON_URL=http://localhost:8003 +BI_PYTHON_URL=http://localhost:8004 +AUTOMATION_PYTHON_URL=http://localhost:8005 +FISCO_PYTHON_URL=http://localhost:8002 +PYTHON_SERVICE_URL=http://localhost:8001 -# ---- OpenAI (opcional - para funcionalidades de IA) ---- -OPENAI_API_KEY=sk-... -AI_INTEGRATIONS_OPENAI_API_KEY=sk-... -AI_INTEGRATIONS_OPENAI_BASE_URL=https://api.openai.com/v1 +# ── IA — OpenAI ─────────────────────────────────────────────────────────────── +# Deixe vazio se usar apenas Ollama (soberania total) +OPENAI_API_KEY= -# ---- ERPNext (opcional - integração ERP) ---- -ERPNEXT_URL=https://seu-erpnext.com +# ── IA — LiteLLM (gateway unificado — ÚNICA porta de entrada para LLMs) ────── +# Em Docker: http://litellm:4000 | Em dev local: http://localhost:4000 +LITELLM_BASE_URL=http://localhost:4000 +LITELLM_API_KEY=arcadia-internal + +# ── IA — Manus Agent (aponta para LiteLLM como gateway) ────────────────────── +# Em Docker: AI_INTEGRATIONS_OPENAI_BASE_URL=http://litellm:4000/v1 +# Em dev local: http://localhost:4000/v1 +AI_INTEGRATIONS_OPENAI_BASE_URL=http://localhost:4000/v1 +AI_INTEGRATIONS_OPENAI_API_KEY=arcadia-internal + +# ── IA — Ollama (LLMs locais — soberania total) ─────────────────────────────── +# Se Ollama está no host (fora do Docker): OLLAMA_BASE_URL=http://localhost:11434 +# Se Ollama está em outro servidor: OLLAMA_BASE_URL=http://IP_DO_SERVIDOR:11434 +OLLAMA_BASE_URL=http://localhost:11434 + +# ── IA — LLMFit (modelos fine-tuned locais — habilitar quando disponível) ───── +# LLMFit turbocharge: modelos treinados com dados do seu negócio +# Deixe vazio para desabilitar (LiteLLM cai para Ollama automaticamente) +LLMFIT_BASE_URL= + +# ── IA — Providers externos (opt-in — soberania: dados não saem sem configurar) +# Deixe vazio para operação 100% soberana (apenas Ollama + LLMFit) +OPENAI_API_KEY= +ANTHROPIC_API_KEY= +GROQ_API_KEY= + +# ── Open WebUI ──────────────────────────────────────────────────────────────── +WEBUI_SECRET_KEY=troque-por-string-aleatoria-segura + +# ── Arcádia Plus (Laravel/Fiscal) ───────────────────────────────────────────── +PLUS_URL=http://localhost:8080 +PLUS_PORT=8080 +PLUS_API_TOKEN= + +# ── Superset (BI avançado — Arcádia Insights) ──────────────────────────────── +SUPERSET_HOST=superset +SUPERSET_PORT=8088 +SUPERSET_SECRET_KEY=troque-por-string-aleatoria-segura # openssl rand -hex 32 +SUPERSET_ADMIN_USER=admin +SUPERSET_ADMIN_EMAIL=admin@arcadia.app +SUPERSET_ADMIN_PASSWORD=troque-senha-forte-em-prod +# URL do banco Arcádia para o Superset acessar os dados (idealmente read-only) +ARCADIA_DATABASE_URL=postgresql://arcadia:arcadia123@db:5432/arcadia + +# ── Redis ───────────────────────────────────────────────────────────────────── +REDIS_URL=redis://localhost:6379 + +# ── Domínio (produção) ──────────────────────────────────────────────────────── +DOMAIN=seudominio.com.br + +# ── ERPNext ──────────────────────────────────────────────────────────────────── +# Modo 1 — ERPNext em container Docker (perfil erpnext) +# Sobe com: docker compose --profile erpnext up +# Proxy ativado automaticamente em DOCKER_MODE=true +ERPNEXT_PROXY_ENABLED=false # true para forçar proxy mesmo fora do Docker +ERPNEXT_CONTAINER_HOST=erpnext # nome do serviço no docker-compose +ERPNEXT_CONTAINER_PORT=8080 +ERPNEXT_DB_ROOT_PASSWORD=erpnext-root-2026 # senha root do MariaDB +ERPNEXT_DB_PASSWORD=frappe2026 # senha do usuário frappe +ERPNEXT_ADMIN_PASSWORD=admin2026 # senha do Administrator no site + +# Modo 2 — ERPNext externo (instância existente) +# Em Docker: ERPNEXT_URL=http://erpnext:8080 (aponta pro container) +# Externo: ERPNEXT_URL=https://meuerpnext.com +ERPNEXT_URL= ERPNEXT_API_KEY= ERPNEXT_API_SECRET= -# ---- GitHub (opcional - integração DevCenter) ---- -GITHUB_TOKEN=ghp_... -GITHUB_OWNER=seu-usuario -GITHUB_REPO=seu-repositorio -GITHUB_DEFAULT_BRANCH=main +# GitHub (para sync de código) +GITHUB_TOKEN= +GITHUB_REPO= -# ---- Arcádia Plus - ERP Laravel (opcional) ---- -PLUS_URL=http://localhost:8080 -PLUS_API_TOKEN= - -# ---- Serviços Python (opcional) ---- -PYTHON_SERVICE_URL=http://localhost:8001 -FISCO_PYTHON_URL=http://localhost:8002 -FISCO_PORT=8002 -CONTABIL_PYTHON_URL=http://localhost:8003 -CONTABIL_PORT=8003 -PEOPLE_PYTHON_URL=http://localhost:8004 -PEOPLE_PORT=8004 - -# ---- Protocolos MCP/A2A (opcional) ---- -PROTOCOL_API_KEYS=sua-api-key-aqui - -# ---- Apache Superset — BI Visual (opcional, ativar com --profile bi) ---- -# Gerar chave: openssl rand -hex 32 -SUPERSET_SECRET_KEY=gere-com-openssl-rand-hex-32 -SUPERSET_ADMIN_USER=admin -SUPERSET_ADMIN_EMAIL=admin@arcadia.app -SUPERSET_ADMIN_PASSWORD=troque-em-producao -# Domínio público do Superset (apenas prod/Traefik) -SUPERSET_DOMAIN=bi.seudominio.com.br - -# Remover do .env se existirem (não são mais necessários): -# METABASE_HOST -# METABASE_PORT -# METASET_ADMIN_EMAIL -# METASET_ADMIN_PASSWORD +# WhatsApp (Baileys — sessões salvas no banco) +# Nenhuma variável adicional necessária — configurado via interface diff --git a/.gitignore b/.gitignore index cbb8d9b..0483d65 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,6 @@ node_modules/ dist/ .DS_Store -.env -.env.local -.env.production # Replit specific .cache/ @@ -63,18 +60,4 @@ attached_assets/ # Package lock (regenerated on install) package-lock.json - -# Documentation files (except essential) -MAPA_*.md -AUDITORIA_*.md -AVALIACAO_*.md -DOCUMENTATION.md -HOSPEDAGEM.md -PLANO_*.md -RELATORIO_*.md -REQUISITOS_*.md -*.pdf -*.txt -!README.md -!replit.md -.aider* +.claude/ diff --git a/.planning/FASE_4_OPENCLAW_PLAN.md b/.planning/FASE_4_OPENCLAW_PLAN.md new file mode 100644 index 0000000..b42b49d --- /dev/null +++ b/.planning/FASE_4_OPENCLAW_PLAN.md @@ -0,0 +1,475 @@ +# Fase 4: OpenClaw Embutido — Plano de Implementação + +**Fase:** 4 +**Data Início:** 2026-03-26 +**Prazo:** 2026-04-08 (Semanas 7-8) +**Status:** 🔄 Sprint 3 Pendente (Sprint 1 e 2 concluídos) + +--- + +## 1. OBJETIVO DA FASE + +Implementar **detecção proativa de padrões** e **sugestão emergente de skills**, transformando comportamentos repetitivos do usuário em automações reutilizáveis através de um widget conversacional flutuante. + +### Entregável Final +✅ Skills emergentes funcionando end-to-end: +- Usuário executa ação repetida → PatternDetector detecta → OpenClawWidget sugere → Blackboard gera DRAFT → Dev Center aprova → Skill disponível + +--- + +## 2. ARQUITETURA + +``` +FLUXO OPENCCLAW: + +1. USER INTERACTION + └─ Usuário usa Arcádia + └─ Learning API registra evento (já existe) + └─ Neo4j armazena interação + +2. PATTERN DETECTION (NOVO) + └─ PatternDetector analisa Learning API + └─ Identifica: 3+ ocorrências em 30 dias + └─ Calcula confiança (threshold 0.8+) + └─ Dispara evento no Socket.IO + +3. WIDGET SUGGESTION (NOVO) + └─ OpenClawWidget fica "ouvindo" + └─ Recebe evento de padrão detectado + └─ Exibe notificação flutuante + └─ Modal SkillSuggestion mostra preview + +4. SKILL GENERATION (NOVO) + └─ Usuário confirma + └─ OpenClawEngine chama Blackboard + └─ Blackboard gera código (DRAFT) + └─ Armazena em database + +5. APPROVAL FLOW (EXISTENTE - Dev Center) + └─ Skill DRAFT aparece em Dev Center + └─ Admin/Lead revisa e aprova + └─ Publica no tenant + └─ Skill fica disponível para reutilização +``` + +### Componentes para Implementar + +``` +BACKEND: +server/modules/openclaw/ +├── PatternDetector.ts ← [NOVO] Detecta padrões +├── SkillEmergence.ts ← [NOVO] Coordena criação +├── OpenClawEngine.ts ← [NOVO] Lógica central +├── config/ +│ └── arcadia.config.yaml ← [NOVO] Configuração + +FRONTEND: +client/src/components/openclaw/ +├── OpenClawWidget.tsx ← [NOVO] Widget flutuante +├── PatternDetector.ts ← [NOVO] Hook de detecção +├── SkillSuggestion.tsx ← [NOVO] Modal de sugestão +└── useAgentEmergence.ts ← [NOVO] Lógica de emergência +``` + +--- + +## 3. DEPENDÊNCIAS VERIFICADAS + +| Componente | Status | Localização | +|-----------|--------|-----------| +| **Skills Engine** | ✅ Pronto | `server/skills/engine.ts` | +| **Blackboard** | ✅ Pronto | `server/blackboard/service.ts` | +| **Dev Center** | ✅ Pronto | `client/src/pages/DevCenter.tsx` | +| **Learning API** | ✅ Existe | `/api/learning/*` | +| **Neo4j (KG)** | ✅ Running | Docker | +| **Socket.IO** | ✅ Configurado | `server/socket-io.ts` | +| **PostgreSQL** | ✅ Rodando | Docker | +| **Scientist (MiroFlow)** | ✅ Existe | `/api/manus/scientist/*` | + +**Conclusão:** Todas as dependências estão prontas ✅ + +--- + +## 4. TASKS DETALHADAS + +### SPRINT 1 (26-27/03): PatternDetector Backend — ✅ COMPLETO + +#### Task 1.1: Criar PatternDetector.ts ✅ +**Arquivo:** `server/modules/openclaw/PatternDetector.ts` +**Objetivo:** Analisar eventos de usuário e detectar padrões + +```typescript +// Pseudocódigo da estrutura +export class PatternDetector { + // Config + min_occurrences: 3; + time_window_days: 30; + confidence_threshold: 0.8; + + // Métodos + detectPattern(userId: string, action: string): Pattern | null + calculateConfidence(interactions: Interaction[]): number + storePattern(pattern: Pattern): Promise + emitEvent(pattern: Pattern): void +} +``` + +**Entrada:** Eventos do Learning API (`/api/learning/interactions`) +**Saída:** Pattern objects armazenados em Neo4j + Socket.IO event +**Dependência:** Learning API funcionando ✅ + +#### Task 1.2: Criar OpenClawEngine.ts ✅ +**Arquivo:** `server/modules/openclaw/OpenClawEngine.ts` +**Objetivo:** Orquestração central de OpenClaw + +```typescript +export class OpenClawEngine { + patternDetector: PatternDetector; + skillEmergence: SkillEmergence; + + // Métodos + async suggestSkill(pattern: Pattern): Promise + async onUserConfirmation(suggestion: SkillSuggestion): Promise + async checkPatternsPeriodicly(): Promise +} +``` + +**Entrada:** Padrões detectados +**Saída:** Sugestões + Skills gerados +**Evento:** Socket.IO broadcast `/openclaw/pattern-detected` + +#### Task 1.3: Criar SkillEmergence.ts ✅ +**Arquivo:** `server/modules/openclaw/SkillEmergence.ts` +**Objetivo:** Integração com Blackboard para codegen + +```typescript +export class SkillEmergence { + async generateSkillDraft(pattern: Pattern): Promise { + // 1. Montar prompt baseado no padrão + // 2. Chamar POST /api/blackboard/generate-skill + // 3. Receber código gerado + // 4. Salvar como DRAFT no database + // 5. Notificar Dev Center + // 6. Retornar skill DRAFT + } +} +``` + +**Integração:** POST `/api/blackboard/generate-skill` +**Database:** skills table (com status: 'draft') + +#### Task 1.4: Criar rotas OpenClaw ✅ +**Arquivo:** `server/modules/openclaw/routes.ts` +**Rotas:** +``` +POST /api/openclaw/detect-patterns ← Trigger manual de análise +GET /api/openclaw/patterns ← Listar padrões detectados +POST /api/openclaw/confirm-skill ← Usuário confirma sugestão +GET /api/openclaw/suggestions ← Histórico de sugestões +``` + +#### Task 1.5: Integrar em server/index.ts ✅ +**Arquivo:** `server/index.ts` +**Ação:** Importar rotas OpenClaw e carregá-las + +```typescript +import openclawRoutes from "./modules/openclaw/routes"; +app.use("/api/openclaw", openclawRoutes); +``` + +### SPRINT 2 (28-29/03): Frontend Widgets — ✅ COMPLETO (commit 5231166) + +#### Task 2.1: Criar OpenClawWidget.tsx ✅ +**Arquivo:** `client/src/components/openclaw/OpenClawWidget.tsx` +**Objetivo:** Widget flutuante que recebe notificações de padrões + +```typescript +export function OpenClawWidget() { + // Escutar Socket.IO event: /openclaw/pattern-detected + // Exibir notificação flutuante (canto inferior direito) + // Mostrar padrão detectado + // Botão "Ver Sugestão" abre modal + // Botão "Ignorar" descarta + + return ( +
+ {/* Widget flutuante */} +
+ ); +} +``` + +**Socket.IO:** Escuta evento `/openclaw/pattern-detected` +**Trigger:** Modal SkillSuggestion + +#### Task 2.2: Criar SkillSuggestion.tsx ✅ +**Arquivo:** `client/src/components/openclaw/SkillSuggestion.tsx` +**Objetivo:** Modal com preview da skill sugerida + +```typescript +export function SkillSuggestion({ pattern, suggestion }) { + // Modal mostra: + // 1. "Detectamos um padrão na sua utilização:" + // 2. Preview do padrão (ações repetidas) + // 3. Preview da automação gerada + // 4. Campo de nome (auto-preenchido) + // 5. Descrição (auto-gerada) + // 6. Botão "Criar Skill" ou "Cancelar" + + const handleCreate = async () => { + // POST /api/openclaw/confirm-skill + // Esperar resposta (skill DRAFT) + // Toast: "Skill criada! Vá para Dev Center para publicar" + }; +} +``` + +**Integração:** Chama `POST /api/openclaw/confirm-skill` +**Feedback:** Toast notification + +#### Task 2.3: Hook useAgentEmergence.ts ✅ +**Arquivo:** `client/src/hooks/useAgentEmergence.ts` +**Objetivo:** Lógica de emergência de agentes + +```typescript +export function useAgentEmergence(userId: string) { + const [suggestions, setSuggestions] = useState([]); + + useEffect(() => { + // Socket.IO listener + socket.on("openclaw:pattern-detected", (pattern) => { + // Filtrar por tenant, user prefs + // Atualizar suggestions state + setSuggestions([...suggestions, pattern]); + }); + }, []); + + return { suggestions, dismiss, confirm }; +} +``` + +#### Task 2.4: Integrar Widget em layout principal ✅ +**Arquivo:** `client/src/App.tsx` ou `client/src/layouts/MainLayout.tsx` +**Ação:** Adicionar OpenClawWidget ao layout persistente + +```typescript +import { OpenClawWidget } from "@/components/openclaw/OpenClawWidget"; + +export default function App() { + return ( + <> + {/* Conteúdo existente */} + {/* ← Adicionar aqui */} + + ); +} +``` + +### SPRINT 3 (30-31/03): Configuração e Integração — ⏳ PRÓXIMO + +#### Task 3.1: Criar arcadia.config.yaml +**Arquivo:** `server/modules/openclaw/config/arcadia.config.yaml` + +```yaml +openclaw: + enabled: true + + # Endpoints + arcadia_api_url: http://localhost:3000/api + arcadia_kg_url: http://localhost:7474 + blackboard_url: http://localhost:3000/api/blackboard + + # Tenant awareness + tenant_aware: true + + # Detecção de padrões + pattern_detection: + enabled: true + min_occurrences: 3 + time_window_days: 30 + confidence_threshold: 0.8 + scheduled_check_interval_minutes: 60 + + # Sugestões + suggestions: + enabled: true + auto_suggest: false # Sempre pedir confirmação do usuário + channels: ['widget', 'chat'] + priority_threshold: 0.85 + + # Skills emergentes + emergence: + create_as_draft: true # Sempre requer aprovação + auto_publish: false + notify_admins: true + skill_prefix: "emergent_" # Prefixo para skills auto-geradas + + # Logging + logging: + enabled: true + store_patterns: true + store_in_kg: true + audit_trail: true +``` + +#### Task 3.2: Integrar Socket.IO events +**Arquivo:** `server/socket-io.ts` +**Ação:** Adicionar listeners e emitters para OpenClaw + +```typescript +socket.on("openclaw:confirm-skill", async (data) => { + // Receber confirmação do usuário + // Chamar SkillEmergence.generateSkillDraft() + // Emitir "openclaw:skill-created" +}); + +// Emitter no PatternDetector +io.emit("openclaw:pattern-detected", pattern); +``` + +#### Task 3.3: Database schema para OpenClaw +**Arquivo:** `shared/schema.ts` (Drizzle ORM) +**Adicionar tabelas:** + +```typescript +// Padrões detectados +export const detectedPatterns = pgTable("detected_patterns", { + id: serial().primaryKey(), + tenant_id: uuid().notNull(), + user_id: uuid().notNull(), + action_type: varchar(255).notNull(), + occurrences: integer().notNull(), + confidence: numeric(3, 2).notNull(), + time_window_days: integer().notNull(), + created_at: timestamp().defaultNow(), + metadata: jsonb(), +}); + +// Sugestões geradas +export const skillSuggestions = pgTable("skill_suggestions", { + id: serial().primaryKey(), + pattern_id: integer().references(() => detectedPatterns.id), + skill_draft_id: uuid().references(() => skills.id), + status: varchar(50).notNull(), // 'suggested', 'accepted', 'rejected' + created_at: timestamp().defaultNow(), +}); +``` + +#### Task 3.4: Migration SQL +**Arquivo:** `migrations/0004_openclaw_tables.sql` + +```sql +CREATE TABLE detected_patterns ( + id SERIAL PRIMARY KEY, + tenant_id UUID NOT NULL, + user_id UUID NOT NULL, + action_type VARCHAR(255) NOT NULL, + occurrences INTEGER NOT NULL, + confidence NUMERIC(3,2) NOT NULL, + time_window_days INTEGER NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + metadata JSONB +); + +CREATE TABLE skill_suggestions ( + id SERIAL PRIMARY KEY, + pattern_id INTEGER REFERENCES detected_patterns(id), + skill_draft_id UUID REFERENCES skills(id), + status VARCHAR(50) NOT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +CREATE INDEX idx_detected_patterns_user_tenant + ON detected_patterns(user_id, tenant_id); +``` + +#### Task 3.5: Testes unitários +**Arquivo:** `tests/openclaw.test.ts` +- PatternDetector detecta padrão corretamente +- OpenClawEngine orquestra fluxo correto +- SkillEmergence integra com Blackboard +- Socket.IO emite eventos corretamente + +#### Task 3.6: Documentação +**Arquivo:** `DOCUMENTATION.md` (adicionar seção) +- Como OpenClaw funciona +- Configuração por tenant +- Troubleshooting + +--- + +## 5. TIMELINE + +| Data | Sprint | Tasks | Status | +|------|--------|-------|--------| +| 26-27/03 | 1 | PatternDetector backend | ✅ Completo | +| 26/03 | 2 | OpenClawWidget frontend | ✅ Completo (commit 5231166) | +| 26/03 | 3 | Migration DB + testes | ⏳ Próximo | +| 01-08/04 | Buffer | Refinamento, testes E2E | ⏳ Próximo | + +**Nota:** Trabalho em `/opt/arcadia_merged/` (diretório canônico do projeto). + +--- + +## 6. CRITÉRIOS DE SUCESSO + +✅ **PatternDetector funciona:** +- Detecta padrão após 3 ocorrências em 30 dias +- Confiança calculada corretamente +- Eventos emitidos para Socket.IO + +✅ **OpenClawWidget funciona:** +- Widget aparece quando padrão é detectado +- Modal mostra sugestão corretamente +- Usuário pode confirmar ou rejeitar + +✅ **SkillEmergence funciona:** +- Integra com Blackboard +- Gera skill como DRAFT +- Aparece em Dev Center para aprovação + +✅ **E2E funciona:** +- User faz ação 3x +- Widget sugere +- Approva +- Skill publicada +- Skill disponível para reutilização + +--- + +## 7. RISCOS E MITIGAÇÕES + +| Risco | Probabilidade | Mitigação | +|-------|--------------|-----------| +| Blackboard não retorna código correto | Média | Testar integração antes, ter fallback | +| Padrões detectados incorretamente | Média | Validar threshold, testes no KG | +| Socket.IO não emite em tempo real | Baixa | Já funciona em outras partes | +| Performance com muitos eventos | Média | Usar índices em PG, cache em Redis | + +--- + +## 8. BRANCH E COMMITS + +**Branch:** `Servidor` (deploy branch, conforme feedback anterior) +**Commit pattern:** +``` +feat(openclaw): PatternDetector backend +feat(openclaw): OpenClawWidget frontend +feat(openclaw): Integração Blackboard + esquema DB +docs(openclaw): Documentação e testes +``` + +--- + +## 9. PRÓXIMAS AÇÕES + +1. ✅ **26/03:** Sprint 1 concluído (PatternDetector, OpenClawEngine, SkillEmergence, routes, config) +2. ✅ **26/03:** Sprint 2 concluído (OpenClawWidget, SkillSuggestion, useAgentEmergence, App.tsx — commit 5231166) +3. ⏳ **Agora:** Sprint 3 — migration SQL + vitest + testes unitários em `/opt/arcadia_merged/` +4. ⏳ **01-08/04:** Refinamento e testes E2E + +--- + +*Fase 4: OpenClaw Embutido — Plano Executável* +*Data: 2026-03-26* +*Pronto para implementação ✅* diff --git a/.planning/quick/260326-kmz-implementar-skill-fabric-gerador-e-gesto/260326-kmz-PLAN.md b/.planning/quick/260326-kmz-implementar-skill-fabric-gerador-e-gesto/260326-kmz-PLAN.md new file mode 100644 index 0000000..bd150ff --- /dev/null +++ b/.planning/quick/260326-kmz-implementar-skill-fabric-gerador-e-gesto/260326-kmz-PLAN.md @@ -0,0 +1,71 @@ +# Quick Task 260326-kmz: Implementar Skill Fabric + +**Description:** Implementar Skill Fabric — gerador e gestor de skills da Arcádia Suite +**Date:** 2026-03-26 +**Mode:** quick + +--- + +## Task 1: Backend — Skill Fabric Module + +**Files:** +- `server/modules/skill-fabric/src/types/index.ts` +- `server/modules/skill-fabric/src/core/skill/Skill.entity.ts` +- `server/modules/skill-fabric/src/core/compiler/VisualCompiler.ts` +- `server/modules/skill-fabric/src/core/compiler/CodeCompiler.ts` +- `server/modules/skill-fabric/src/core/compiler/MarkdownCompiler.ts` +- `server/modules/skill-fabric/src/core/validator/ValidationPipeline.ts` +- `server/modules/skill-fabric/src/core/executor/SkillExecutor.ts` +- `server/modules/skill-fabric/src/core/executor/Sandbox.ts` +- `server/modules/skill-fabric/src/core/lifecycle/LifecycleManager.ts` +- `server/modules/skill-fabric/src/api/routes/skills.routes.ts` +- `server/modules/skill-fabric/src/api/controllers/skills.controller.ts` +- `server/modules/skill-fabric/index.ts` + +**Action:** Create the full backend Skill Fabric module with types, entity, compilers, validator pipeline, executor/sandbox, lifecycle manager, and API routes. The project uses TypeScript + Express + Drizzle ORM. Reuse existing `db` and `skills` schema from `../../shared/schema`. No new DB migration needed — extend existing skills table logic. + +**Context:** +- Existing `server/skills/routes.ts` has basic CRUD. The new module adds compilation, validation, execution, versioning, lifecycle. +- DB import: `import { db } from "@/db"` or `import { db } from "../../../db"` — check what works +- Existing schema: `skills`, `skillExecutions` from `../../shared/schema` +- Do NOT use vm2 (needs install) — use Node.js built-in `vm` module for sandbox +- Do NOT use ReactFlow/Monaco yet (frontend task) — backend only here + +**Done:** Files created, module compiles without errors + +--- + +## Task 2: Frontend — Skill Fabric UI + +**Files:** +- `client/src/modules/skill-fabric/index.ts` +- `client/src/modules/skill-fabric/types.ts` +- `client/src/modules/skill-fabric/api.ts` +- `client/src/modules/skill-fabric/code-ide/components/SkillCodeEditor.tsx` +- `client/src/modules/skill-fabric/markdown-studio/components/MarkdownEditor.tsx` +- `client/src/modules/skill-fabric/shared/components/SkillToolbar.tsx` +- `client/src/modules/skill-fabric/shared/components/VersionSelector.tsx` +- `client/src/modules/skill-fabric/shared/components/ValidationPanel.tsx` +- `client/src/pages/SkillFabricPage.tsx` + +**Action:** Create frontend Skill Fabric module. Use textarea-based code editor (Monaco not installed — don't add it). Use Tailwind CSS + shadcn/ui components matching the existing project style. Create a SkillFabricPage that lists skills, allows creating/editing (code + markdown modes), compiling, validating, and executing. Wire to the backend API routes from Task 1. + +**Context:** +- Check `client/src/components/` for existing UI patterns (shadcn components available) +- Check `client/src/App.tsx` to see how routes are registered — add the new page there +- The visual canvas (ReactFlow) is a stretch goal — skip it, implement code + markdown modes only +- API base: `/api/skills` (existing) + `/api/skill-fabric` (new from Task 1) + +**Done:** SkillFabricPage renders, skills can be listed and created + +--- + +## Task 3: Register Routes & Integration + +**Files:** +- `server/modules/loader.ts` +- `client/src/App.tsx` (or router file) + +**Action:** Register the new skill-fabric backend routes in `server/modules/loader.ts`. Add the SkillFabricPage route in the frontend router. Verify existing skills route still works. + +**Done:** `/api/skill-fabric/*` routes registered, frontend page accessible diff --git a/.replit b/.replit index 62928d4..16452d5 100644 --- a/.replit +++ b/.replit @@ -4,16 +4,12 @@ hidden = [".config", ".git", "generated-icon.png", "node_modules", "dist"] [nix] channel = "stable-24_05" -packages = ["glibcLocales", "libiconv", "libxcrypt", "openssl", "pkg-config", "unzip", "zlib", "zip"] +packages = ["cairo", "cargo", "ffmpeg-full", "freetype", "ghostscript", "gitFull", "glibcLocales", "gobject-introspection", "gtk3", "libiconv", "libxcrypt", "mysql80", "openssl", "php82", "php82Packages.composer", "pkg-config", "playwright-driver", "qhull", "rustc", "tcl", "tk", "unzip", "xcodebuild", "zlib", "jdk21"] [[ports]] localPort = 5000 externalPort = 80 -[[ports]] -localPort = 5904 -externalPort = 6800 - [[ports]] localPort = 8001 externalPort = 3001 @@ -53,7 +49,7 @@ PORT = "5000" deploymentTarget = "autoscale" build = ["npm", "run", "build"] publicDir = "dist/public" -run = ["npm", "run", "start"] +run = ["node", "./dist/index.cjs"] [workflows] runButton = "Project" diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..af4aedd --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,553 @@ +# Arcádia Suite - Documentação Técnica Completa + +**Versão:** 1.0 +**Data:** Janeiro 2026 +**Desenvolvido por:** Arcádia Technology + +--- + +## Sumário + +1. [Visão Geral](#visão-geral) +2. [Arquitetura do Sistema](#arquitetura-do-sistema) +3. [Módulos do Sistema](#módulos-do-sistema) +4. [Modelo de Dados](#modelo-de-dados) +5. [APIs e Endpoints](#apis-e-endpoints) +6. [Integrações Externas](#integrações-externas) +7. [Segurança e Autenticação](#segurança-e-autenticação) +8. [Guia de Implantação](#guia-de-implantação) + +--- + +## Visão Geral + +O **Arcádia Suite** é um Sistema Operacional Empresarial (Business Operating System) alimentado por Inteligência Artificial, projetado para revolucionar operações empresariais. O sistema integra cinco pilares fundamentais: + +### Os 5 Pilares + +1. **Knowledge Graph** - Grafo de conhecimento para dados empresariais interconectados +2. **Central Intelligence (Scientist)** - Módulo de IA para geração automática de soluções +3. **Manus (Agente Autônomo)** - Execução de tarefas e automação +4. **Centro de Comunicação Unificado** - Interação com clientes via múltiplas plataformas +5. **IDE Completa** - Ambiente de desenvolvimento multi-modal + +### Segmentação de Produtos + +| Produto | Público-Alvo | Stack Tecnológica | +|---------|-------------|-------------------| +| **Arcádia Plus** | Pequenas empresas | Node.js + Python + PostgreSQL | +| **Arcádia Next** | Médias/Grandes empresas | Frappe Framework + PostgreSQL | + +Ambos compartilham o **Arcádia Fisco** como motor fiscal centralizado. + +--- + +## Arquitetura do Sistema + +### Arquitetura em 4 Camadas + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CAMADA DE APRESENTAÇÃO │ +│ React 18 + TypeScript + Tailwind CSS + shadcn/ui │ +│ Interface estilo navegador com abas e omnibox │ +│ Porta: 5000 │ +└─────────────────────────────────────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ CAMADA DE ORQUESTRAÇÃO │ +│ Express.js + Socket.IO + Manus Agent │ +│ API REST + WebSocket em tempo real │ +│ Porta: 5000 │ +└─────────────────────────────────────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ CAMADA DE INTELIGÊNCIA │ +│ FastAPI (Python) + OpenAI API │ +│ Scientist, Embeddings, RPA, Workflows │ +│ Porta: 8001 (IA) / 8002 (Fisco) │ +└─────────────────────────────────────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ CAMADA DE DADOS │ +│ PostgreSQL + Knowledge Graph + ChromaDB │ +│ Drizzle ORM + Session Store │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Estrutura de Diretórios + +``` +arcadia-suite/ +├── client/ # Frontend React +│ └── src/ +│ ├── components/ # Componentes reutilizáveis +│ ├── hooks/ # React hooks customizados +│ ├── lib/ # Utilitários e configurações +│ └── pages/ # Páginas da aplicação +├── server/ # Backend Node.js +│ ├── admin/ # Rotas administrativas +│ ├── api-central/ # Central de APIs +│ ├── automations/ # Motor de automações +│ ├── bi/ # Business Intelligence +│ ├── chat/ # Chat interno +│ ├── compass/ # Process Compass (clientes/projetos) +│ ├── crm/ # Gestão de relacionamento +│ ├── email/ # Serviço de e-mail +│ ├── erp/ # Integração ERP +│ ├── fisco/ # Motor fiscal (NF-e) +│ ├── ide/ # IDE integrada +│ ├── learning/ # Sistema de aprendizado +│ ├── login-bridge/ # Bridge de autenticação +│ ├── manus/ # Agente autônomo +│ ├── production/ # Gestão de produção +│ ├── productivity/ # Hub de produtividade +│ ├── proxy/ # Proxy reverso +│ ├── python/ # Serviços Python (FastAPI) +│ ├── support/ # Central de suporte +│ ├── valuation/ # Precificação e valuation +│ └── whatsapp/ # Integração WhatsApp +└── shared/ # Código compartilhado + └── schema.ts # Schemas do banco de dados +``` + +--- + +## Módulos do Sistema + +### 1. Cockpit (Dashboard Principal) +**Arquivo:** `client/src/pages/Cockpit.tsx` + +Painel central com visão geral do sistema: +- Widgets configuráveis +- Métricas em tempo real +- Atividades recentes +- Atalhos para módulos + +### 2. Process Compass +**Arquivo:** `client/src/pages/ProcessCompass.tsx` +**API:** `/api/compass/*` + +Gestão completa de processos empresariais: +- **Clientes:** Cadastro, histórico, segmentação +- **Projetos:** Cronograma, tarefas, milestones +- **Contratos:** Gestão de contratos e renovações +- **Timesheet:** Controle de horas trabalhadas + +### 3. Comunicação Unificada +**Arquivo:** `client/src/pages/Comunicacao.tsx` +**API:** `/api/whatsapp/*` + +Centro de comunicação multi-canal: +- **WhatsApp Business:** Atendimento via Baileys +- **Chat Interno:** Comunicação da equipe +- **E-mail:** Integração IMAP/SMTP +- **Tickets:** Sistema de filas de atendimento + +### 4. CRM (Customer Relationship Management) +**Arquivo:** `client/src/pages/Crm.tsx` +**API:** `/api/crm/*` + +Gestão de relacionamento com clientes: +- Pipeline de vendas +- Funil de conversão +- Gestão de oportunidades +- Comissionamento automático +- Integração com Google Calendar + +### 5. Business Intelligence (Arcádia Insights) +**Arquivo:** `client/src/pages/BiWorkspace.tsx` +**API:** `/api/bi/*` + +Análise e visualização de dados: +- Upload de arquivos (CSV, Excel) +- Gráficos interativos (Recharts) +- Dashboards personalizáveis +- Conexão com múltiplas fontes + +### 6. Scientist (Central de Inteligência) +**Arquivo:** `client/src/pages/Scientist.tsx` +**API:** `/api/scientist/*` + +Módulo de auto-programação com IA: +- Análise de dados automatizada +- Geração de código (Python/SQL) +- Execução em sandbox +- Armazenamento de soluções reutilizáveis + +### 7. Manus (Agente Autônomo) +**Arquivo:** `client/src/pages/Agent.tsx` +**API:** `/api/manus/*` + +Executor de tarefas autônomo: +- Loop pensamento-ação-observação +- Ferramentas disponíveis: + - Busca web + - Consulta ao Knowledge Graph + - Consulta ERP + - Cálculos + - Envio de mensagens + - Geração de relatórios + - Agendamentos + +### 8. Arcádia Fisco (Motor Fiscal) +**Arquivo:** `client/src/pages/Fisco.tsx` +**API:** `/api/fisco/*` + +Motor fiscal centralizado para compliance brasileiro: +- **NCM:** Nomenclatura Comum do Mercosul +- **CFOP:** Código Fiscal de Operações +- **CEST:** Código Especificador da Substituição Tributária +- **Grupos de Tributação:** Configuração de impostos +- **Certificados Digitais:** Gestão de A1/A3 +- **NF-e/NFC-e:** Emissão de notas fiscais eletrônicas +- **IBS/CBS:** Campos para Reforma Tributária + +#### Integração nfelib (Python) +**Arquivo:** `server/python/fisco_service.py` + +Serviço FastAPI para processamento de NF-e: +- Geração de XML (layout 4.00) +- Assinatura digital com certificado A1 +- Comunicação com SEFAZ (homologação/produção) +- Consulta, cancelamento e inutilização + +### 9. Produção +**Arquivo:** `client/src/pages/Production.tsx` +**API:** `/api/production/*` + +Gestão de produção e manufatura: +- Ordens de produção +- Controle de estoque +- Rastreabilidade +- Custos de produção + +### 10. Valuation (Precificação) +**Arquivo:** `client/src/pages/Valuation.tsx` +**API:** `/api/valuation/*` + +Sistema de precificação inteligente: +- Cálculo de custos +- Margem de contribuição +- Markup +- Simulações de preço + +### 11. Suporte +**Arquivo:** `client/src/pages/Support.tsx` +**API:** `/api/support/*` + +Central de atendimento: +- Tickets de suporte +- Base de conhecimento +- SLA e prioridades +- Histórico de atendimentos + +### 12. Automações +**Arquivo:** `client/src/pages/Automations.tsx` +**API:** `/api/automations/*` + +Motor de automações: +- Triggers e ações +- Workflows visuais +- Integrações via webhooks +- Agendamentos (cron) + +### 13. Knowledge Base +**Arquivo:** `client/src/pages/Knowledge.tsx` +**API:** `/api/knowledge/*` + +Base de conhecimento: +- Artigos e documentação +- Categorização +- Busca semântica +- Integração com IA + +### 14. IDE +**Arquivo:** `client/src/pages/IDE.tsx` +**API:** `/api/ide/*` + +Ambiente de desenvolvimento integrado: +- Monaco Editor +- Terminal (Xterm.js) +- Execução de código +- Gerenciamento de arquivos + +### 15. Administração +**Arquivo:** `client/src/pages/Admin.tsx` +**API:** `/api/admin/*` + +Painel administrativo: +- **Usuários:** Gestão de contas +- **Perfis:** Controle de acesso +- **Parceiros:** Hierarquia multi-tenant +- **Módulos:** Configuração de funcionalidades +- **Configurações:** Parâmetros do sistema + +### 16. API Hub +**Arquivo:** `client/src/pages/ApiHub.tsx` + +Documentação interativa de APIs: +- Listagem de endpoints +- Testes em tempo real +- Exemplos de uso +- Geração de código + +--- + +## Modelo de Dados + +### Entidades Principais + +#### Usuários e Autenticação +```sql +users -- Usuários do sistema +profiles -- Perfis de acesso +roles -- Papéis (RBAC) +permissions -- Permissões granulares +role_permissions -- Associação papel-permissão +user_roles -- Associação usuário-papel +module_access -- Controle de acesso a módulos +``` + +#### Produtividade +```sql +workspace_pages -- Páginas estilo Notion +page_blocks -- Blocos de conteúdo +page_links -- Links bidirecionais +dashboard_widgets -- Widgets do dashboard +quick_notes -- Notas rápidas +activity_feed -- Feed de atividades +user_favorites -- Favoritos +command_history -- Histórico de comandos +``` + +#### Conversação e IA +```sql +conversations -- Conversas com agente +messages -- Mensagens +chat_attachments -- Anexos +knowledge_base -- Base de conhecimento +``` + +#### ERP e Integrações +```sql +erp_connections -- Conexões com ERPs +agent_tasks -- Tarefas do agente +task_executions -- Execuções de tarefas +``` + +#### Comunicação +```sql +chat_threads -- Threads de chat +chat_participants -- Participantes +chat_messages -- Mensagens de chat +whatsapp_sessions -- Sessões WhatsApp +whatsapp_contacts -- Contatos WhatsApp +whatsapp_messages -- Mensagens WhatsApp +whatsapp_queues -- Filas de atendimento +whatsapp_tickets -- Tickets de atendimento +``` + +#### Process Compass +```sql +compass_clients -- Clientes +compass_projects -- Projetos +compass_project_members -- Membros de projeto +compass_project_phases -- Fases de projeto +compass_contracts -- Contratos +compass_timesheet -- Timesheet +compass_invoices -- Faturas +compass_payments -- Pagamentos +``` + +#### CRM +```sql +crm_leads -- Leads +crm_opportunities -- Oportunidades +crm_activities -- Atividades +crm_pipelines -- Pipelines +crm_stages -- Estágios +crm_commissions -- Comissões +``` + +#### Fisco +```sql +fisco_ncm -- NCMs +fisco_cest -- CESTs +fisco_cfop -- CFOPs +fisco_grupos_tributacao -- Grupos de tributação +fisco_natureza_operacao -- Naturezas de operação +fisco_ibpt -- Tabela IBPT +fisco_certificados -- Certificados digitais +fisco_configuracoes -- Configurações fiscais +fisco_notas -- Notas fiscais +fisco_nota_itens -- Itens das notas +fisco_nota_eventos -- Eventos fiscais +``` + +#### Multi-Tenant +```sql +partners -- Parceiros +partner_invites -- Convites de parceiros +tenant_clients -- Clientes dos tenants +``` + +--- + +## APIs e Endpoints + +### Estrutura Base + +| Módulo | Base URL | Descrição | +|--------|----------|-----------| +| Admin | `/api/admin` | Administração do sistema | +| Compass | `/api/compass` | Process Compass | +| CRM | `/api/crm` | Gestão de relacionamento | +| WhatsApp | `/api/whatsapp` | Comunicação WhatsApp | +| Fisco | `/api/fisco` | Motor fiscal | +| BI | `/api/bi` | Business Intelligence | +| Production | `/api/production` | Gestão de produção | +| Valuation | `/api/valuation` | Precificação | +| Support | `/api/support` | Central de suporte | +| Automations | `/api/automations` | Automações | +| IDE | `/api/ide` | Ambiente de desenvolvimento | +| Learning | `/api/learning` | Sistema de aprendizado | + +### Exemplos de Endpoints + +#### Fisco - NF-e +``` +GET /api/fisco/nfe/service-status # Status do serviço +POST /api/fisco/nfe/validar-certificado # Validar certificado A1 +POST /api/fisco/nfe/gerar-xml # Gerar XML preview +POST /api/fisco/nfe/emitir # Emitir NF-e +POST /api/fisco/nfe/consultar # Consultar na SEFAZ +POST /api/fisco/nfe/cancelar # Cancelar NF-e +POST /api/fisco/nfe/inutilizar # Inutilizar numeração +``` + +#### Compass - Clientes +``` +GET /api/compass/clients # Listar clientes +GET /api/compass/clients/:id # Detalhes do cliente +POST /api/compass/clients # Criar cliente +PUT /api/compass/clients/:id # Atualizar cliente +DELETE /api/compass/clients/:id # Excluir cliente +``` + +#### Admin - Usuários +``` +GET /api/admin/users # Listar usuários +GET /api/admin/users/:id # Detalhes do usuário +POST /api/admin/users # Criar usuário +PUT /api/admin/users/:id # Atualizar usuário +DELETE /api/admin/users/:id # Excluir usuário +``` + +--- + +## Integrações Externas + +### OpenAI API +- **Uso:** Agente de IA, Scientist, auto-replies +- **Modelo:** gpt-4o-mini +- **Configuração:** Via Replit Secrets + +### Baileys (WhatsApp) +- **Uso:** Conexão multi-sessão WhatsApp +- **Recursos:** QR Code, mensagens em tempo real +- **Armazenamento:** Sessões no banco de dados + +### nfelib (Python) +- **Uso:** Emissão de NF-e/NFC-e +- **Recursos:** XML, assinatura digital, SEFAZ +- **Certificados:** A1 (PFX) + +### Frappe Framework +- **Uso:** Arcádia Next (futuro) +- **Recursos:** ERPNext integration + +### Google Calendar +- **Uso:** Sincronização de eventos CRM +- **OAuth:** Configurável por usuário + +--- + +## Segurança e Autenticação + +### Autenticação +- **Método:** Session-based com Passport.js +- **Hash:** bcrypt para senhas +- **Sessões:** PostgreSQL session store + +### Controle de Acesso (RBAC) +``` +Hierarquia: +├── Master (Arcádia) +│ └── Parceiros +│ └── Clientes +``` + +### Permissões +- Baseadas em módulos e ações +- Código formato: `modulo.recurso.acao` +- Exemplo: `compass.clients.write` + +### Certificados Digitais +- Tipo A1 (arquivo PFX) +- Armazenamento seguro com senha +- Validação de expiração + +--- + +## Guia de Implantação + +### Requisitos +- Node.js 20+ +- Python 3.11+ +- PostgreSQL 15+ +- Certificado SSL (produção) + +### Variáveis de Ambiente +```env +DATABASE_URL=postgresql://... +SESSION_SECRET=... +OPENAI_API_KEY=... +FISCO_PYTHON_URL=http://localhost:8002 +FISCO_PORT=8002 +``` + +### Comandos de Inicialização +```bash +# Instalar dependências +npm install + +# Iniciar em desenvolvimento +npm run dev + +# Serviço Python Fisco (separado) +cd server/python && python fisco_service.py +``` + +### Portas +| Serviço | Porta | +|---------|-------| +| Frontend + API | 5000 | +| Python Fisco | 8002 | +| Python IA | 8001 | + +--- + +## Changelog + +### Janeiro 2026 +- Integração nfelib para NF-e +- Módulo Fisco completo +- Sistema de aprendizado automático +- Validação Zod em todas as rotas fiscais + +--- + +**Arcádia Suite** - Transformando a gestão empresarial com Inteligência Artificial + +*Documentação gerada automaticamente pelo sistema.* diff --git a/MAPA_GERAL_RETAIL.md b/MAPA_GERAL_RETAIL.md new file mode 100644 index 0000000..f9e61ed --- /dev/null +++ b/MAPA_GERAL_RETAIL.md @@ -0,0 +1,705 @@ +# MAPA GERAL DO SISTEMA RETAIL - Arcádia Suite + +--- + +## 1. VISÃO MACRO DO MÓDULO + +``` +╔══════════════════════════════════════════════════════════════════════════════════╗ +║ ARCÁDIA RETAIL - MAPA GERAL ║ +║ Loja de Celulares e Assistência Técnica ║ +╠══════════════════════════════════════════════════════════════════════════════════╣ +║ ║ +║ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ║ +║ │DASHBOARD│ │ PDV │ │ PESSOAS │ │ ESTOQUE │ │SERVIÇOS │ ║ +║ │ (KPIs) │ │ (Caixa) │ │(Cadastro│ │(Depósito│ │ (O.S.) │ ║ +║ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ ║ +║ │ │ │ │ │ ║ +║ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ║ +║ │TRADE-IN │ │ COMPRAS │ │CADASTROS│ │RELATÓRIO│ │COMISSÕES│ ║ +║ │(Aval.) │ │(Aquis.) │ │ (Config)│ │(Reports)│ │ (Metas) │ ║ +║ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ ║ +║ │ │ │ │ │ ║ +║ └────────────┴────────────┴─────┬──────┴────────────┘ ║ +║ │ ║ +║ ┌─────────┴─────────┐ ║ +║ │ CONFIGURAÇÃO │ ║ +║ │ Plus / Empresas │ ║ +║ └───────────────────┘ ║ +╚══════════════════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## 2. FLUXO PRINCIPAL DE OPERAÇÕES + +``` + ┌──────────────────────────────────────────────┐ + │ ENTRADA DE MERCADORIA │ + └──────────────────────┬───────────────────────┘ + │ + ┌──────────────────────┬┴──────────────────────┐ + ▼ ▼ ▼ + ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ + │ COMPRA │ │ TRADE-IN │ │ CONSIGNAÇÃO │ + │ Fornecedor │ │ Cliente │ │ Parceiro │ + └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ + │ │ │ + │ ┌──────┴───────┐ │ + │ │ Avaliação │ │ + │ │ 19 itens │ │ + │ │ checklist │ │ + │ └──────┬───────┘ │ + │ │ │ + │ ┌──────┴───────┐ │ + │ │ Aprovação │ │ + │ │ Gera Crédito│ │ + │ │ Cria O.S. │ │ + │ └──────┬───────┘ │ + │ │ │ + │ ┌──────┴───────┐ │ + │ │ Revisão │ │ + │ │ O.S. Interna│ │ + │ │ Manutenção │ │ + │ └──────┬───────┘ │ + │ │ │ + ▼ ▼ ▼ + ┌─────────────────────────────────────────────────────┐ + │ ESTOQUE │ + │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ + │ │Depósito │ │Depósito │ │Depósito │ │ + │ │ Loja │ │ Central │ │Trânsito │ │ + │ └────┬────┘ └────┬────┘ └────┬────┘ │ + │ └────────────┼────────────┘ │ + │ │ │ + │ ┌────────────────┬┴──────────────────┐ │ + │ │ Dispositivos │ Produtos │ │ + │ │ (por IMEI) │ (por qtd/série) │ │ + │ └────────────────┴───────────────────┘ │ + └────────────────────┬────────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────────────┐ + │ PDV │ + │ │ + │ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ + │ │Dispositivos│ │ Produtos │ │ Faturar O.S. │ │ + │ │ (IMEI) │ │(Acessórios)│ │ (Serviços) │ │ + │ └─────┬──────┘ └─────┬──────┘ └──────┬───────┘ │ + │ └───────────────┼────────────────┘ │ + │ ▼ │ + │ ┌──────────────────┐ │ + │ │ CARRINHO │ │ + │ │ │ │ + │ │ Subtotal │ │ + │ │ - Desconto │ │ + │ │ - Trade-In │ │ + │ │ - Crédito │ │ + │ │ = TOTAL │ │ + │ └────────┬─────────┘ │ + │ ▼ │ + │ ┌──────────────────┐ │ + │ │ PAGAMENTO │ │ + │ │ 💵 Dinheiro │ │ + │ │ 💳 Débito │ │ + │ │ 💳 Crédito (Nx) │ │ + │ │ 📱 PIX │ │ + │ │ 🔀 Combinado │ │ + │ └────────┬─────────┘ │ + │ ▼ │ + │ ┌──────────────────┐ │ + │ │ VENDA │ │ + │ │ Impressão A4 │ │ + │ │ Sync Plus │ │ + │ │ NF-e/NFC-e │ │ + │ └──────────────────┘ │ + └─────────────────────────────────────────────────────┘ + │ + ┌────────────┼────────────────┐ + ▼ ▼ ▼ + ┌────────────┐ ┌─────────┐ ┌────────────┐ + │ COMISSÃO │ │RELATÓRIO│ │ DEVOLUÇÃO │ + │ Vendedor │ │Caixa │ │ Troca │ + │ Metas │ │Diário │ │ Crédito │ + └────────────┘ └─────────┘ └────────────┘ +``` + +--- + +## 3. CICLO DE VIDA DO DISPOSITIVO (IMEI) + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ JORNADA DO DISPOSITIVO POR IMEI │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ENTRADA │ +│ ═══════ │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ COMPRA │ │ TRADE-IN │ │ CONSIGNAÇÃO │ │ +│ │ Fornecedor │ │ Cliente │ │ Parceiro │ │ +│ │ condition: │ │ condition: │ │ condition: │ │ +│ │ new │ │ used/refurb │ │ varies │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ +│ │ │ │ │ +│ │ ┌──────┴───────┐ │ │ +│ │ │ AVALIAÇÃO │ │ │ +│ │ │ Checklist │ │ │ +│ │ │ 19 itens │ │ │ +│ │ └──────┬───────┘ │ │ +│ │ │ │ │ +│ │ ┌──────┴───────┐ │ │ +│ │ │ O.S. INT. │ │ │ +│ │ │ Revisão │ │ │ +│ │ │ Manutenção │ │ │ +│ │ └──────┬───────┘ │ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ ESTOQUE (status: in_stock) │ │ +│ │ │ │ +│ │ IMEI: 35XXXXXXXXXXXXX │ │ +│ │ Marca: Samsung | Modelo: S24 Ultra │ │ +│ │ Cor: Preto | Storage: 256GB | RAM: 12GB │ │ +│ │ Condição: refurbished │ │ +│ │ Preço Compra: R$ 2.500 | Preço Venda: R$ 3.500 │ │ +│ │ Depósito: Loja Centro │ │ +│ └──────────────────────┬──────────────────────────────┘ │ +│ │ │ +│ MOVIMENTAÇÕES │ │ +│ ═══════════════ │ │ +│ │ │ +│ ┌──────────┐ ┌──────┴──────┐ ┌──────────────┐ │ +│ │TRANSFER. │◄───│ DISPONÍVEL │───►│ ASSISTÊNCIA │ │ +│ │Entre lojas│ │ para venda │ │ O.S. cliente│ │ +│ │in_transit │ │ in_stock │ │ in_service │ │ +│ └──────────┘ └──────┬──────┘ └──────┬───────┘ │ +│ │ │ │ +│ │ │ (retorna após reparo) │ +│ │ └──────────┐ │ +│ │ │ │ +│ SAÍDA ▼ ▼ │ +│ ═════ ┌──────────────┐ ┌──────────────┐ │ +│ │ VENDA │ │ DE VOLTA AO │ │ +│ │ PDV + NF-e │ │ ESTOQUE │ │ +│ │ status:sold │ │ in_stock │ │ +│ └──────┬───────┘ └──────────────┘ │ +│ │ │ +│ ┌──────┴───────┐ │ +│ │ DEVOLUÇÃO? │ │ +│ │ returned │──────────► Volta ao estoque │ +│ └──────────────┘ │ +│ │ +│ RASTREAMENTO: device_history + imei_history (kardex completo) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 4. FLUXO DO TRADE-IN (4 ETAPAS DETALHADAS) + +``` +╔═══════════════════════════════════════════════════════════════════════════╗ +║ TRADE-IN - FLUXO COMPLETO ║ +╠═══════════════════════════════════════════════════════════════════════════╣ +║ ║ +║ ETAPA 1: AVALIAÇÃO ║ +║ ══════════════════ ║ +║ ║ +║ ┌────────────────────────────────────────────────────────────┐ ║ +║ │ Cliente chega com dispositivo usado │ ║ +║ │ │ ║ +║ │ 1. Identificar cliente (busca por nome/CPF) │ ║ +║ │ 2. Registrar IMEI, Marca, Modelo │ ║ +║ │ 3. Preencher Checklist (19 itens): │ ║ +║ │ │ ║ +║ │ ┌──────────────────────────────────────────────────────┐ │ ║ +║ │ │ ☐ Liga corretamente ☐ Sensores/NFC │ │ ║ +║ │ │ ☐ Sem avarias/fantasma ☐ Face ID/Touch ID │ │ ║ +║ │ │ ☐ Sem manchas na tela ☐ Microfones │ │ ║ +║ │ │ ☐ Botões funcionando ☐ Áudio auricular │ │ ║ +║ │ │ ☐ Marcas de uso ☐ Alto-falante │ │ ║ +║ │ │ ☐ Wi-Fi ☐ Carregamento │ │ ║ +║ │ │ ☐ Chip ☐ Câmeras │ │ ║ +║ │ │ ☐ 4G/5G ☐ Flash │ │ ║ +║ │ │ ☐ Possui carregador ☐ 3uTools OK │ │ ║ +║ │ │ 🔋 Bateria: ____% │ │ ║ +║ │ └──────────────────────────────────────────────────────┘ │ ║ +║ │ │ ║ +║ │ 4. Listar peças necessárias (se houver) │ ║ +║ │ 5. Definir valor estimado │ ║ +║ │ 6. Assinatura digital do cliente │ ║ +║ │ 7. Imprimir comprovante │ ║ +║ │ │ ║ +║ │ Status: PENDING │ ║ +║ └────────────────────────────────────────────┬───────────────┘ ║ +║ │ ║ +║ ▼ ║ +║ ETAPA 2: APROVAÇÃO ║ +║ ══════════════════ ║ +║ ║ +║ ┌────────────────────────────────────────────────────────────┐ ║ +║ │ Gerente revisa avaliação e decide: │ ║ +║ │ │ ║ +║ │ [APROVAR] [REJEITAR] │ ║ +║ │ │ │ │ ║ +║ │ ▼ ▼ │ ║ +║ │ Automaticamente: Avaliação │ ║ +║ │ ✅ Gera CRÉDITO para cliente rejeitada. │ ║ +║ │ (R$ do valor estimado) Sem ações. │ ║ +║ │ ✅ Cria O.S. INTERNA │ ║ +║ │ (INT2602XXXXXX) │ ║ +║ │ ✅ Registra no IMEI History │ ║ +║ │ │ ║ +║ │ Status: APPROVED │ ║ +║ └────────────────────────────────────────────┬───────────────┘ ║ +║ │ ║ +║ ▼ ║ +║ ETAPA 3: REVISÃO / MANUTENÇÃO ║ +║ ═════════════════════════════ ║ +║ ║ +║ ┌────────────────────────────────────────────────────────────┐ ║ +║ │ Técnico trabalha na O.S. Interna: │ ║ +║ │ │ ║ +║ │ 1. Diagnóstico técnico │ ║ +║ │ 2. Troca de peças (registra peças + custos) │ ║ +║ │ 3. Limpeza e preparação │ ║ +║ │ 4. Teste de qualidade │ ║ +║ │ 5. Preenche checklist de conclusão │ ║ +║ │ 6. Finaliza O.S. Interna │ ║ +║ │ │ ║ +║ │ Custos: │ ║ +║ │ ├── Peças utilizadas: R$ XXX │ ║ +║ │ ├── Mão de obra: R$ XXX │ ║ +║ │ └── Total reparo: R$ XXX │ ║ +║ │ │ ║ +║ │ Status O.S.: COMPLETED │ ║ +║ └────────────────────────────────────────────┬───────────────┘ ║ +║ │ ║ +║ ▼ ║ +║ ETAPA 4: ENTRADA NO ESTOQUE ║ +║ ═══════════════════════════ ║ +║ ║ +║ ┌────────────────────────────────────────────────────────────┐ ║ +║ │ Ao finalizar O.S. Interna: │ ║ +║ │ │ ║ +║ │ ✅ Cria dispositivo no estoque (mobile_devices) │ ║ +║ │ condition: "refurbished" │ ║ +║ │ acquisitionType: "trade_in" │ ║ +║ │ │ ║ +║ │ 💰 Cálculo do preço sugerido: │ ║ +║ │ Custo aquisição = Valor Trade-In + Custo Reparo │ ║ +║ │ Preço sugerido = Custo × (1 + Margem%) │ ║ +║ │ Ex: R$1500 + R$300 = R$1800 × 1.30 = R$ 2.340 │ ║ +║ │ │ ║ +║ │ ✅ Registra no IMEI History │ ║ +║ │ ✅ Registra no Activity Feed │ ║ +║ │ ✅ Disponível no PDV para venda │ ║ +║ │ │ ║ +║ │ Status: IN_STOCK (pronto para venda) │ ║ +║ └────────────────────────────────────────────────────────────┘ ║ +╚═══════════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## 5. MAPA DO PDV (PONTO DE VENDA) + +``` +╔═══════════════════════════════════════════════════════════════════════╗ +║ PDV - PONTO DE VENDA ║ +╠═══════════════════════════════════════════════════════════════════════╣ +║ ║ +║ BARRA SUPERIOR ║ +║ ┌──────────────────────────────────────────────────────────────────┐ ║ +║ │ 🏪 Empresa: Loja Centro 👤 Vendedor: João Silva │ ║ +║ │ │ ║ +║ │ [Sangria] [Reforço] [Devolução] [Selecionar Cliente] [Limpar] │ ║ +║ └──────────────────────────────────────────────────────────────────┘ ║ +║ ║ +║ ┌───────────────────────────────────┬──────────────────────────────┐ ║ +║ │ CATÁLOGO (3 colunas) │ CARRINHO (2 colunas) │ ║ +║ │ │ │ ║ +║ │ ┌──────────┬──────────┬────────┐ │ ┌──────────────────────────┐│ ║ +║ │ │📱Disposit│📦Produtos│🔧Fat.OS│ │ │ Samsung S24 Ultra ││ ║ +║ │ └──────────┴──────────┴────────┘ │ │ IMEI: 35XXX 📱Celular ││ ║ +║ │ │ │ R$ 3.500,00 ││ ║ +║ │ [🔍 Buscar... ] │ ├──────────────────────────┤│ ║ +║ │ │ │ Capinha Silicone ││ ║ +║ │ ┌──────────────────────────────┐ │ │ 2x R$ 45,00 ││ ║ +║ │ │ Samsung S24 Ultra │ │ │ R$ 90,00 ││ ║ +║ │ │ 256GB | Preto | IMEI: 35XX │ │ ├──────────────────────────┤│ ║ +║ │ │ 🟢 Novo 📦 Loja Centro │ │ │ O.S. #OS2602ABC ││ ║ +║ │ │ R$ 3.500,00 │ │ │ Troca de tela 🔧Serviço ││ ║ +║ │ │ [+ Adicionar] │ │ │ R$ 450,00 ││ ║ +║ │ ├──────────────────────────────┤ │ ╞══════════════════════════╡│ ║ +║ │ │ iPhone 15 Pro │ │ │ Subtotal R$ 4.040,00 ││ ║ +║ │ │ 128GB | Branco | IMEI: 86XX │ │ │ Desconto -R$ 40,00 ││ ║ +║ │ │ 🔵 Recond 📦 Loja Centro │ │ │ Trade-In -R$ 1.500,00 ││ ║ +║ │ │ R$ 4.200,00 │ │ │ Crédito -R$ 200,00 ││ ║ +║ │ │ [+ Adicionar] │ │ │─────────────────────────││ ║ +║ │ ├──────────────────────────────┤ │ │ TOTAL R$ 2.300,00 ││ ║ +║ │ │ Xiaomi 14 │ │ │ ││ ║ +║ │ │ 512GB | Azul | IMEI: 86XX │ │ │ 💙 Crédito: R$ 200,00 ││ ║ +║ │ │ 🟡 Usado 📦 Loja Centro │ │ │ ││ ║ +║ │ │ R$ 2.800,00 │ │ │ [↕️ Trade-In] ││ ║ +║ │ │ [+ Adicionar] │ │ │ [💰 FINALIZAR VENDA] ││ ║ +║ │ └──────────────────────────────┘ │ └──────────────────────────┘│ ║ +║ └───────────────────────────────────┴──────────────────────────────┘ ║ +║ ║ +║ MODAL DE PAGAMENTO ║ +║ ┌──────────────────────────────────────────────────────────────────┐ ║ +║ │ Total: R$ 2.300,00 │ ║ +║ │ │ ║ +║ │ [Dinheiro ✓] [Débito] [Crédito] [PIX] [Combinado] │ ║ +║ │ │ ║ +║ │ Valor: [R$ 2.300,00] Parcelas: [1x] │ ║ +║ │ │ ║ +║ │ Desconto: [___]% ou [R$ ___] │ ║ +║ │ │ ║ +║ │ [CONFIRMAR PAGAMENTO] │ ║ +║ └──────────────────────────────────────────────────────────────────┘ ║ +╚═══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## 6. FLUXO DA ORDEM DE SERVIÇO (12 ESTADOS) + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ORDEM DE SERVIÇO - FLUXO DE STATUS │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ │ +│ │ ABERTA │ ◄── Cliente entrega dispositivo │ +│ │ open │ │ +│ └────┬─────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ DIAGNÓSTICO │ ◄── Técnico analisa problema │ +│ │ diagnosis │ │ +│ └──────┬──────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ ORÇAMENTO │ ◄── Técnico elabora orçamento │ +│ │ quote │ │ +│ └──────┬──────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────────┐ │ +│ │ AGUARD. APROVAÇÃO │ ◄── Enviado para cliente │ +│ │ pending_approval │ │ +│ └─────┬────────┬─────┘ │ +│ │ │ │ +│ APROVOU │ │ REJEITOU │ +│ ▼ ▼ │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ APROVADA │ │ REJEITADA│ ──► FIM │ +│ │ approved │ │ rejected │ │ +│ └────┬─────┘ └──────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────┐ │ +│ │ EM REPARO│ ◄── Técnico inicia trabalho │ +│ │in_repair │ │ +│ └────┬─────┘ │ +│ │ │ +│ ┌──────────┼──────────┐ │ +│ │ │ │ +│ ▼ │ │ +│ ┌──────────────┐ │ │ +│ │ AGUARD. PEÇAS│ │ ◄── Se precisar de peça │ +│ │waiting_parts │───────────────┘ │ +│ └──────────────┘ (peça chegou, volta para reparo) │ +│ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ QUALIDADE │ ◄── Verificação pós-reparo │ +│ │quality_check │ │ +│ └──────┬───────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ PRONTO PARA │ ◄── Disponível para retirada │ +│ │ RETIRADA │ (aparece no PDV p/ faturar) │ +│ │ ready_pickup │ │ +│ └──────┬───────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ CONCLUÍDA │ ◄── Cliente retirou + pagou │ +│ │ completed │ (faturada no PDV) │ +│ └──────────────┘ │ +│ │ +│ Em qualquer momento: ──────────► ┌──────────────┐ │ +│ │ CANCELADA │ │ +│ │ cancelled │ │ +│ └──────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 7. MAPA DE RELATÓRIOS + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ RELATÓRIOS DO RETAIL │ +├──────────────┬──────────────────────────────────────────────────────┤ +│ │ │ +│ OS POR │ Status │ Qtd │ Valor Total │ +│ STATUS │ open │ 12 │ R$ 5.400 │ +│ │ in_repair │ 8 │ R$ 3.200 │ +│ │ completed │ 45 │ R$ 22.500 │ +│ │ │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ │ │ +│ OS POR │ Técnico │ Total │ Concl. │ Andamento │ Receita │ +│ TÉCNICO │ Carlos │ 15 │ 12 │ 3 │ R$8.500 │ +│ │ Pedro │ 10 │ 8 │ 2 │ R$5.200 │ +│ │ │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ │ │ +│ VENDAS POR │ Vendedor │ Vendas │ Receita │ Ticket │ Dias │ +│ VENDEDOR │ João │ 28 │ R$45.000 │ R$1607 │ 22 │ +│ │ Maria │ 22 │ R$38.000 │ R$1727 │ 20 │ +│ │ │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ │ │ +│ MARGEM │ Dispositivo │ IMEI │ Custo │ Venda │ Margem │ +│ POR IMEI │ S24 Ultra │ 35XXX │ R$2500 │ R$3500 │ 40.0% │ +│ │ iPhone 15 │ 86XXX │ R$3800 │ R$4200 │ 10.5% │ +│ │ │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ │ │ +│ CAIXA │ ┌────────────────────────────────────────────┐ │ +│ DIÁRIO │ │ Total Vendas: R$ 12.500 (8 vendas) │ │ +│ │ │ Dinheiro: R$ 4.200 │ Cartão: R$ 5.800 │ │ +│ │ │ PIX: R$ 2.500 │ Combinado: R$ 0 │ │ +│ (4 queries) │ │ Sangrias: -R$ 500 │ Reforços: +R$ 200 │ │ +│ │ │ Saldo Caixa: R$ 3.900 │ │ +│ │ └────────────────────────────────────────────┘ │ +│ │ │ +│ │ POR VENDEDOR: │ +│ │ ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ +│ │ │Vendedor│Vendas│Dinh. │Déb. │Créd.│ PIX │TOTAL │ │ +│ │ │João │ 5 │R$2100│R$1500│R$800│R$1200│R$5600│ │ +│ │ │Maria │ 3 │R$2100│R$1300│R$600│R$1300│R$6900│ │ +│ │ │TOTAL │ 8 │R$4200│R$2800│R$1400│R$2500│R$12.5│ │ +│ │ └──────┴──────┴──────┴──────┴──────┴──────┴──────┘ │ +│ │ │ +├──────────────┼──────────────────────────────────────────────────────┤ +│ │ │ +│ GIRO DE │ Produto │ Estoque │ Vendas 30d │ Turnover │ +│ ESTOQUE │ Capinha │ 50 │ 35 │ 0.70 │ +│ │ Película │ 80 │ 42 │ 0.53 │ +│ │ │ +└──────────────┴──────────────────────────────────────────────────────┘ +``` + +--- + +## 8. ARQUITETURA TÉCNICA + +``` +╔═══════════════════════════════════════════════════════════════════════╗ +║ ARQUITETURA DO MÓDULO RETAIL ║ +╠═══════════════════════════════════════════════════════════════════════╣ +║ ║ +║ FRONTEND (React + TypeScript + Tailwind + shadcn/ui) ║ +║ ═══════════════════════════════════════════════════ ║ +║ ║ +║ client/src/pages/ArcadiaRetail.tsx ──── 10.067 linhas ║ +║ │ ║ +║ ├── Dashboard (KPIs, Feed, Alertas) ║ +║ ├── PDV (Carrinho, Catálogo, Pagamento) ║ +║ ├── Pessoas (CRUD, Papéis, Histórico) ║ +║ ├── Estoque (Depósitos, Séries, Inventário) ║ +║ ├── Serviços (O.S. CRUD, Checklist) ║ +║ ├── Trade-In (Avaliações, Fluxo 4 etapas) ║ +║ ├── Compras (Pedidos, Recebimento) ║ +║ ├── Cadastros (Pagamento, Vendedores, Promoções) ║ +║ ├── Relatórios (6 sub-abas) ║ +║ ├── Comissões (Dashboard, Metas, Fechamento) ║ +║ └── Configuração (Plus, Empresas, Sync) ║ +║ ║ +║ client/src/components/TradeInForm.tsx ─── 988 linhas ║ +║ └── Formulário completo c/ checklist + assinatura ║ +║ ║ +║ ───────────────────────────────────────────────────────────── ║ +║ API (fetch → /api/retail/*) ║ +║ ───────────────────────────────────────────────────────────── ║ +║ ║ +║ BACKEND (Express.js + Drizzle ORM) ║ +║ ══════════════════════════════════ ║ +║ ║ +║ server/retail/routes.ts ──── 5.218 linhas (~130 endpoints) ║ +║ │ ║ +║ ├── CRUD: Devices, Evaluations, ServiceOrders, ║ +║ │ Persons, Products, Warehouses, etc. ║ +║ ├── PDV: Sessions, Sales, Payments, CashMovements ║ +║ ├── Trade-In: Approve, Process, FullFlow, Stock ║ +║ ├── Reports: OsStatus, OsTech, SalesSeller, ║ +║ │ MarginIMEI, DailyCash, StockTurnover ║ +║ ├── Returns: Search, Process, Credits ║ +║ └── Commissions: Plans, Goals, Calculate, Close ║ +║ ║ +║ server/retail/plus-sync.ts ──── 542 linhas ║ +║ └── Sync: Customers, Sales+Items, NF-e ║ +║ ║ +║ ───────────────────────────────────────────────────────────── ║ +║ Drizzle ORM → PostgreSQL ║ +║ ───────────────────────────────────────────────────────────── ║ +║ ║ +║ BANCO DE DADOS (PostgreSQL + 40 tabelas) ║ +║ ════════════════════════════════════════ ║ +║ ║ +║ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ║ +║ │ Dispositivos │ │ Vendas │ │ Estoque │ ║ +║ │ mobile_devices│ │ pos_sales │ │ warehouses │ ║ +║ │ device_history│ │pos_sale_items│ │warehouse_stk │ ║ +║ │ imei_history │ │pos_sessions │ │stock_movem. │ ║ +║ └──────────────┘ │cash_movements│ │transfers │ ║ +║ └──────────────┘ │serials │ ║ +║ ┌──────────────┐ │inventories │ ║ +║ │ Trade-In │ ┌──────────────┐ └──────────────┘ ║ +║ │ evaluations │ │ Serviços │ ║ +║ │ checklist_* │ │service_orders│ ┌──────────────┐ ║ +║ │ acquisitions │ │ so_items │ │ Cadastros │ ║ +║ │ transfer_doc │ │ warranties │ │payment_meth. │ ║ +║ └──────────────┘ └──────────────┘ │ sellers │ ║ +║ │ comm_plans │ ║ +║ ┌──────────────┐ ┌──────────────┐ │ promotions │ ║ +║ │ Créditos │ │ Devoluções │ │ price_tables │ ║ +║ │customer_cred.│ │return_exch. │ │product_types │ ║ +║ └──────────────┘ │return_items │ └──────────────┘ ║ +║ └──────────────┘ ║ +║ ║ +║ ───────────────────────────────────────────────────────────── ║ +║ ║ +║ INTEGRAÇÃO PLUS (Laravel ERP - Porta 8080) ║ +║ ══════════════════════════════════════════ ║ +║ ║ +║ ┌───────────┐ ┌───────────┐ ┌───────────┐ ║ +║ │Proxy Rev. │ │ SSO │ │Auto-Start │ ║ +║ │/plus/* → │ │HMAC-SHA256│ │php artisan│ ║ +║ │:8080 │ │Token │ │serve │ ║ +║ └───────────┘ └───────────┘ └───────────┘ ║ +║ │ ║ +║ ▼ ║ +║ ┌─────────────────────────────────────────────────┐ ║ +║ │ Plus (Laravel) │ ║ +║ │ ├── NF-e / NFC-e (SEFAZ) │ ║ +║ │ ├── Clientes / Fornecedores │ ║ +║ │ ├── Vendas / Faturamento │ ║ +║ │ └── Fiscal completo │ ║ +║ └─────────────────────────────────────────────────┘ ║ +║ ║ +╚═══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## 9. SEGURANÇA MULTI-TENANT + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ CAMADAS DE SEGURANÇA │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ CAMADA 1: AUTENTICAÇÃO │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ Passport.js Session → req.isAuthenticated() │ │ +│ │ Todas as rotas /api/retail/* exigem login │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ CAMADA 2: TENANT SCOPING │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ req.user.tenantId → obrigatório │ │ +│ │ Se ausente → 403 "Tenant not identified" │ │ +│ │ WHERE tenant_id = $tenantId em TODAS as queries │ │ +│ │ Dados de um tenant NUNCA vazam para outro │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ CAMADA 3: MODULE GATING │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ requireModule('retail') → verifica tenants.features.retail │ │ +│ │ Se módulo inativo → 403 "Módulo não habilitado" │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ CAMADA 4: OPERAÇÕES SENSÍVEIS │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ Devoluções → Exige senha do GERENTE │ │ +│ │ Sangrias → Registra responsável + autorizador │ │ +│ │ Exclusões → Soft delete quando possível │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ CAMADA 5: AUDITORIA │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ retail_activity_feed → Todas as operações relevantes │ │ +│ │ device_history → Movimentação de IMEI │ │ +│ │ imei_history → Kardex completo por IMEI │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 10. MAPA DE INTEGRAÇÕES + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ INTEGRAÇÕES DO RETAIL │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────┐ │ +│ │ ARCÁDIA RETAIL │ │ +│ │ (Express) │ │ +│ └────────┬─────────┘ │ +│ │ │ +│ ┌───────────────────┼───────────────────┐ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ PLUS (PHP) │ │ ERPNEXT │ │ POSTGRESQL │ │ +│ │ :8080 │ │ (API ext.) │ │ (Drizzle) │ │ +│ │ │ │ │ │ │ │ +│ │ ▸ NF-e/NFC-e│ │ ▸ Clientes │ │ ▸ 40+ tabelas│ │ +│ │ ▸ Clientes │ │ ▸ Fornecedor │ │ ▸ Retail │ │ +│ │ ▸ Vendas │ │ ▸ Estoque │ │ ▸ Multi-ten. │ │ +│ │ ▸ Fiscal │ │ ▸ Financeiro │ │ │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ SEFAZ │ │ +│ │ NF-e / NFC-e (via Plus Laravel + nfelib) │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +**Métricas Finais:** +- **16.800+ linhas** de código +- **40+ tabelas** no banco +- **~130 endpoints** REST +- **11 abas** na interface +- **19 itens** no checklist de avaliação +- **12 estados** de O.S. +- **4 etapas** no fluxo de Trade-In +- **5 formas** de pagamento +- **4 queries** no caixa diário diff --git a/MAPA_PLUS_ARCADIA.md b/MAPA_PLUS_ARCADIA.md new file mode 100644 index 0000000..adc3fb9 --- /dev/null +++ b/MAPA_PLUS_ARCADIA.md @@ -0,0 +1,676 @@ +# Arcádia Plus - Mapa Completo dentro do Arcádia Suite + +## O que é o Plus? + +O **Arcádia Plus** é o **Motor de Execução Fiscal e Operacional** da plataforma Arcádia Suite. Enquanto o Arcádia Suite pensa, governa e orienta, o Plus executa, registra e obedece. É um ERP completo construído em Laravel/PHP que serve como backend fiscal para emissão de documentos eletrônicos (NF-e, NFC-e, CT-e, MDF-e) e operações comerciais. + +--- + +## Posição na Arquitetura + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ ARCÁDIA SUITE (Cérebro) │ +│ Express.js - Porta 5000 │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ SOE - Sistema Operacional Empresarial │ │ +│ │ Domínios: Pessoas, Produtos, Vendas, Financeiro, Fiscal │ │ +│ │ Decisão + Governança + IA │ │ +│ └────────────────────┬───────────────────────────────────────┘ │ +│ │ │ +│ │ SSO + Proxy (/plus) │ +│ ▼ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ ARCÁDIA PLUS (Motor de Execução) │ │ +│ │ Laravel/PHP - Porta 8080 │ │ +│ │ Execução: NFe, NFCe, CTe, MDFe, PDV, Estoque, OS │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ Outros Motores: │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│ +│ │Contábil │ │ Fiscal │ │ BI │ │Automação │ │ Comm ││ +│ │ 8003 │ │ 8002 │ │ 8004 │ │ 8005 │ │ 8006 ││ +│ │ Python │ │ Python │ │ Python │ │ Python │ │ Node.js ││ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘│ +└──────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Integração Suite ↔ Plus + +### 1. Proxy Reverso (`server/plus/proxy.ts`) + +O Arcádia Suite atua como gateway. Todas as requisições para `/plus/*` são redirecionadas para o Laravel na porta 8080: + +``` +Navegador → /plus/vendas → Suite (5000) → Proxy → Laravel (8080/vendas) +Navegador → /plus/nfe → Suite (5000) → Proxy → Laravel (8080/nfe) +``` + +**Comportamentos do proxy:** +- `/plus` ou `/plus/` → redireciona para `/empresas` (home do Laravel) +- `/plus/home` → redireciona para `/empresas` +- Headers `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Forwarded-Prefix` repassados +- Respostas Location reescritas para manter o prefixo `/plus` +- Timeout: 60 segundos +- Status endpoint: `GET /api/plus/status` + +### 2. SSO - Single Sign-On (`plus/app/Http/Controllers/Auth/SsoController.php`) + +Login unificado: o usuário entra pelo Arcádia Suite e é autenticado automaticamente no Plus. + +``` +┌─────────────────┐ Token JWT (Base64) ┌──────────────────┐ +│ Arcádia Suite │ ──────────────────────────▶ │ Arcádia Plus │ +│ (Node.js) │ sig = HMAC-SHA256 │ (Laravel) │ +│ │ ts = timestamp │ │ +│ Gera token com: │ │ Valida: │ +│ - email │ │ - iss = arcadia │ +│ - name │ │ - aud = plus │ +│ - role │ │ - timestamp ±5m │ +│ - username │ │ - HMAC signature │ +└─────────────────┘ └──────────────────┘ + │ + ▼ + Auto-cria usuário + se não existir +``` + +**Segurança SSO:** +- Segredo compartilhado: `SSO_SECRET` (variável de ambiente) +- Expiração do token: 5 minutos (300 segundos) +- Assinatura: HMAC-SHA256 +- Validação de issuer (`arcadia-suite`) e audience (`arcadia-plus`) +- Provisionamento automático: se o email não existe no Plus, cria o usuário + +### 3. Launcher (`server/plus/launcher.ts`) + +O Suite inicia o Laravel automaticamente na inicialização: + +``` +Suite inicia → Verifica PHP disponível → spawn php artisan serve --port=8080 + │ + ┌───────┴───────┐ + │ PHP existe? │ + ├── Sim → Inicia│ + └── Não → Pula │ +``` + +**Verificações:** +- `which php` - PHP instalado? +- `plus/artisan` existe? +- Timeout: 15 segundos para iniciar + +--- + +## Números do Plus + +| Métrica | Quantidade | +|---------|-----------| +| Controllers | 376 | +| Models | 320 | +| Services | 12 | +| Views (Blade) | 1.194 | +| Migrations | 260 | +| Rotas Web | 912 | +| Rotas API | 634 | +| **Total de Rotas** | **1.546** | + +--- + +## Módulos do Plus - Detalhamento Completo + +### 1. FISCAL - Documentos Eletrônicos + +O coração do Plus. Emissão e gestão de todos os documentos fiscais brasileiros. + +#### NF-e (Nota Fiscal Eletrônica) +| Componente | Arquivo | +|-----------|---------| +| Controller Web | `NfeController.php` | +| Controller API | `API/NFeController.php` | +| Painel API | `API/NFePainelController.php` | +| Service | `NFeService.php` | +| Service API | `NFeServiceApi.php` | +| Model | `Nfe.php`, `ItemNfe.php`, `FaturaNfe.php` | +| Views | `nfe/*.blade.php` | +| XML | `NfeXmlController.php` | +| Entrada XML | `NfeEntradaXmlController.php`, `NfeImportaXmlController.php` | + +**Funcionalidades NF-e:** +- Emissão, cancelamento, carta de correção +- Importação de XML de entrada +- Download de XML/DANFE +- Manifesto do destinatário (DFe) +- Inutilização de numeração +- Contingência offline + +#### NFC-e (Nota Fiscal do Consumidor) +| Componente | Arquivo | +|-----------|---------| +| Controller Web | `NfceController.php` | +| Controller API | `API/NFCeController.php` | +| Painel API | `API/NFCePainelController.php` | +| Service | `NFCeService.php` | +| Service API | `NFCeServiceApi.php` | +| Model | `Nfce.php`, `ItemNfce.php`, `FaturaNfce.php` | +| Views | `nfce/*.blade.php` | +| Contingência | `NfceContigenciaController.php` | +| Impressão | `ImprimirNfceController.php` | + +#### CT-e (Conhecimento de Transporte) +| Componente | Arquivo | +|-----------|---------| +| Controller Web | `CteController.php` | +| Controller API | `API/CTeController.php` | +| CT-e OS | `CteOsController.php`, `API/CTeOsPainelController.php` | +| Service | `CTeService.php`, `CTeOsService.php` | +| Model | `Cte.php`, `MedidaCte.php`, `ComponenteCte.php` | +| Views | `cte/*.blade.php` | + +#### MDF-e (Manifesto de Documentos Fiscais) +| Componente | Arquivo | +|-----------|---------| +| Controller Web | `MdfeController.php` | +| Controller API | `API/MdfeController.php` | +| Service | `MDFeService.php` | +| Model | `Mdfe.php`, `Percurso.php`, `UnidadeCarga.php` | +| Views | `mdfe/*.blade.php` | + +#### Nota de Serviço (NFS-e) +| Componente | Arquivo | +|-----------|---------| +| Controller Web | `NotaServicoController.php` | +| Controller API | `API/NotaServicoController.php` | +| Config | `NotaServicoConfigController.php` | +| Webhook | `API/NfseWebHookController.php` | + +#### Configurações Fiscais +| Componente | Descrição | +|-----------|-----------| +| `NaturezaOperacaoController.php` | Naturezas de operação (CFOP) | +| `NcmController.php` | NCM - Nomenclatura Comum do Mercosul | +| `IbptController.php` / `IbptService.php` | IBPT - Carga tributária | +| `DifalController.php` | DIFAL - Diferencial de alíquota | +| `SpedController.php` / `SpedConfigController.php` | SPED Fiscal | +| `SintegraController.php` | SINTEGRA | +| `ContigenciaController.php` | Contingência NF-e/NFC-e | +| `InutilizacaoController.php` | Inutilização de numeração | + +--- + +### 2. VENDAS E PDV + +| Controller | Descrição | +|-----------|-----------| +| `VendaController.php` | Vendas completas | +| `API/VendaController.php` | API de vendas | +| `API/PDV/*.php` | Ponto de Venda (LoginController, ClienteController) | +| `API/FrontBoxController.php` | Frontend do caixa | +| `FrontBoxController.php` | Interface do caixa Web | +| `OrcamentoController.php` | Orçamentos | +| `API/PreVendaController.php` | Pré-vendas | +| `TrocaController.php` | Devoluções/trocas | +| `DevolucaoController.php` | Devoluções formais | +| `CupomDescontoController.php` | Cupons de desconto | +| `CashBackConfigController.php` | Configuração de cashback | + +--- + +### 3. ESTOQUE E PRODUTOS + +| Controller | Descrição | +|-----------|-----------| +| `ProdutoController.php` | Cadastro de produtos | +| `EstoqueController.php` | Controle de estoque | +| `EstoqueLocalizacaoController.php` | Localização no estoque | +| `StockEntryController.php` | Entrada de estoque | +| `StockEntryService.php` | Serviço de entrada | +| `StockSaleService.php` | Serviço de saída por venda | +| `TransferenciaEstoqueController.php` | Transferências | +| `InventarioController.php` | Inventários | +| `VariacaoController.php` | Variações de produto | +| `ListaPrecoController.php` | Listas de preço | +| `ComboController.php` | Combos/kits | +| `UnidadeMedidaController.php` | Unidades de medida | +| `MarcaController.php` | Marcas | +| `ImportadorController.php` | Importação de produtos | +| `ImeiTrackingController.php` | Rastreamento de IMEI | +| `API/ImeiUnitController.php` | Unidades IMEI via API | + +--- + +### 4. FINANCEIRO + +| Controller | Descrição | +|-----------|-----------| +| `ContaPagarController.php` | Contas a pagar | +| `ContaReceberController.php` | Contas a receber | +| `CaixaController.php` | Controle de caixa | +| `SangriaController.php` | Sangrias de caixa | +| `SuprimentoController.php` | Suprimentos de caixa | +| `BoletoController.php` | Boletos | +| `ContaBoletoController.php` | Contas com boleto | +| `FinanceiroBoletoController.php` | Financeiro boletos | +| `FinanceiroDashboardController.php` | Dashboard financeiro | +| `FinanceiroPlanoController.php` | Planos financeiros | +| `TaxaCartaoController.php` | Taxas de cartão | +| `ApuracaoMensalController.php` | Apuração mensal | +| `FechamentoMensalController.php` | Fechamento mensal | +| `CategoriaContaController.php` | Categorias contábeis | +| `ContaEmpresaController.php` | Contas bancárias | +| `AsaasController.php` | Integração Asaas (pagamentos) | +| `API/PaymentController.php` | API de pagamentos | + +--- + +### 5. CLIENTES E CRM + +| Controller | Descrição | +|-----------|-----------| +| `ClienteController.php` | Cadastro de clientes | +| `ClienteDeliveryController.php` | Clientes de delivery | +| `ClienteScoreController.php` | Score/pontuação de clientes | +| `CrmController.php` | CRM completo | +| `MensagemPadraoCrmController.php` | Mensagens padrão CRM | +| `MensagemCrmLogController.php` | Log de mensagens CRM | +| `ConvenioController.php` | Convênios | +| `ContratoConfigController.php` | Contratos | +| `AssinarContratoController.php` | Assinatura de contratos | +| `API/CrmController.php` | API CRM | +| `API/EnvioFaturaWppController.php` | Envio de fatura via WhatsApp | + +--- + +### 6. FOOD SERVICE (Restaurantes, Pizzarias, Bares) + +| Controller | Descrição | +|-----------|-----------| +| **Cardápio Digital** | | +| `ConfigCardapioController.php` | Configuração do cardápio | +| `CarrosselCardapioController.php` | Carrossel do cardápio | +| `AvaliacaoCardapioController.php` | Avaliações | +| `API/Cardapio/*.php` | API do cardápio (carrinho, produtos) | +| **Delivery** | | +| `API/Delivery/*.php` | API delivery (carrinho, clientes, pedidos, produtos) | +| `FuncionamentoDeliveryController.php` | Horários de delivery | +| **Comanda** | | +| `API/Comanda/*.php` | Sistema de comandas (7 controllers) | +| **Atendimento** | | +| `AtendimentoController.php` | Atendimentos | +| `AtendimentoGarcomController.php` | Atendimento garçom | +| `MesaController.php` | Gestão de mesas | +| **Pizza** | | +| `TamanhoPizzaController.php` | Tamanhos de pizza | +| `AdicionalController.php` | Adicionais | +| `CategoriaAdicionalController.php` | Categorias de adicionais | +| **iFood** | | +| `IfoodConfigController.php` | Configuração iFood | +| `IfoodCatalogoController.php` | Catálogo iFood | +| `IfoodPedidoController.php` | Pedidos iFood | +| `IfoodProdutoController.php` | Produtos iFood | + +--- + +### 7. SERVIÇOS E ORDENS DE SERVIÇO + +| Controller | Descrição | +|-----------|-----------| +| `ServicoController.php` | Cadastro de serviços | +| `CategoriaServicoController.php` | Categorias | +| `OrdemServicoController.php` | Ordens de serviço | +| `API/OrdemServicoController.php` | API de OS | +| `AgendamentoController.php` | Agendamentos | +| `ConfiguracaoAgendamentoController.php` | Config agendamento | +| `FuncionamentoController.php` | Horários | +| `InterrupcoesController.php` | Interrupções | +| `GarantiaController.php` | Garantias | + +--- + +### 8. PRODUÇÃO + +| Controller | Descrição | +|-----------|-----------| +| `GestaoProducaoController.php` | Gestão de produção | +| `API/GestaoProducaoController.php` | API produção | +| `API/OrdemProducaoController.php` | Ordens de produção | +| `ApontamentoController.php` | Apontamentos | +| `CustoConfiguracaoController.php` | Configuração de custos | +| `API/PlanejamentoCustoController.php` | Planejamento de custos | + +--- + +### 9. TRANSPORTE E LOGÍSTICA + +| Controller | Descrição | +|-----------|-----------| +| `TransportadoraController.php` | Transportadoras | +| `FreteController.php` | Fretes | +| `TipoDespesaFreteController.php` | Tipos de despesa | +| `VeiculoController.php` | Veículos | +| `ManutencaoVeiculoController.php` | Manutenção | +| `MotoboyController.php` | Motoboys | +| `LocalizacaoController.php` | Localização/rastreamento | +| `ManifestoController.php` | Manifestos de carga | + +--- + +### 10. E-COMMERCE E MARKETPLACE + +| Controller | Descrição | +|-----------|-----------| +| **WooCommerce** | | +| `WoocommerceConfigController.php` | Configuração | +| `WoocommerceCategoriaController.php` | Categorias | +| `WoocommerceProdutoController.php` | Produtos | +| `WoocommercePedidoController.php` | Pedidos | +| **Mercado Livre** | | +| `MercadoLivreAuthController.php` | Autenticação OAuth | +| `MercadoLivreConfigController.php` | Configuração | +| `MercadoLivreProdutoController.php` | Produtos | +| `MercadoLivrePerguntaController.php` | Perguntas | +| **NuvemShop** | | +| `NuvemShopController.php` | Integração NuvemShop | +| **VendiZap** | | +| `VendiZapConfigController.php` | Configuração | +| `VendiZapProdutoController.php` | Produtos | +| `VendiZapPedidoController.php` | Pedidos | +| `VendiZapCategoriaController.php` | Categorias | +| **Marketplace Próprio** | | +| `MarketPlaceConfigController.php` | Configuração | +| `DestaqueMarketPlaceController.php` | Destaques | +| `ServicoMarketPlaceController.php` | Serviços | +| `SegmentoController.php` | Segmentos | +| **E-commerce Próprio** | | +| `EcommerceConfigController.php` | Configuração | +| `API/EcommerceController.php` | API e-commerce | + +--- + +### 11. RH E COLABORADORES + +| Controller | Descrição | +|-----------|-----------| +| `FuncionarioController.php` | Funcionários | +| `FuncionarioEventoController.php` | Eventos de funcionário | +| `EventoFuncionarioController.php` | Registro de eventos | +| `ComissaoController.php` | Comissões | +| `MargemComissaoController.php` | Margens de comissão | +| `MetaResultadoController.php` | Metas e resultados | +| `ControleAcessoController.php` | Controle de acesso | +| `RoleController.php` | Permissões/roles | + +--- + +### 12. SEGMENTOS ESPECIALIZADOS + +#### Ótica +| Controller | Descrição | +|-----------|-----------| +| `FormatoArmacaoOticaController.php` | Formatos de armação | +| `TipoArmacaoController.php` | Tipos de armação | +| `LaboratorioController.php` | Laboratórios óticos | +| `TratamentoOticaController.php` | Tratamentos de lente | +| `MedicoController.php` | Médicos/oftalmologistas | + +#### Hotelaria +| Controller | Descrição | +|-----------|-----------| +| `AcomodacaoController.php` | Acomodações | +| `CategoriaAcomodacaoController.php` | Categorias | +| `ReservaController.php` | Reservas | +| `ConfigReservaController.php` | Configuração | +| `FrigobarController.php` | Frigobar | +| `EstacionamentoController.php` | Estacionamento | + +--- + +### 13. COMPRAS E FORNECEDORES + +| Controller | Descrição | +|-----------|-----------| +| `CompraController.php` | Compras | +| `ComprasIAController.php` | Compras com IA | +| `FornecedorController.php` | Fornecedores | +| `CotacaoController.php` | Cotações | +| `CotacaoRespostaController.php` | Respostas de cotação | + +--- + +### 14. ADMINISTRAÇÃO MULTI-TENANT + +| Controller | Descrição | +|-----------|-----------| +| `EmpresaController.php` | Gestão de empresas | +| `UsuarioController.php` | Usuários | +| `UsuarioEmissaoController.php` | Usuários de emissão | +| `ContadorController.php` | Contador | +| `ContadorAdminController.php` | Admin do contador | +| `ContadorEmpresaController.php` | Empresas do contador | +| `ImpersonateController.php` | Impersonar usuário | +| `GerenciarPlanoController.php` | Gestão de planos | +| `UpgradePlanoController.php` | Upgrade de planos | +| `ConfiguracaoSuperController.php` | Config super admin | +| `BackupController.php` | Backups | +| `SistemaController.php` | Sistema | +| `LogController.php` | Logs | + +--- + +### 15. TEF (Transferência Eletrônica de Fundos) + +| Controller | Descrição | +|-----------|-----------| +| `TefConfigController.php` | Configuração TEF | +| `TefController.php` | Operações TEF | +| `TefRegistroController.php` | Registros TEF | +| Model: `TefMultiPlusCard.php` | Multi Plus Card | + +--- + +### 16. INTELIGÊNCIA ARTIFICIAL + +| Componente | Descrição | +|-----------|-----------| +| `ComprasIAController.php` | Sugestões de compra via IA | +| `FinancePrevisaoService.php` | Previsão financeira com IA | + +--- + +## Models (320 entidades) + +### Categorias Principais + +| Grupo | Models Exemplo | +|-------|---------------| +| **Core** | `User`, `Empresa`, `Cidade`, `Config` | +| **Produtos** | `Produto`, `ProdutoVariacao`, `ProdutoComposicao`, `ProdutoAdicional`, `Marca`, `CategoriaProduto`, `UnidadeMedida` | +| **Vendas** | `Venda`, `ItemVenda`, `Orcamento`, `PreVenda`, `VendaSuspensa`, `Troca`, `Devolucao` | +| **Fiscal NF-e** | `Nfe`, `ItemNfe`, `FaturaNfe`, `NaturezaOperacao`, `PadraoTributacaoProduto` | +| **Fiscal NFC-e** | `Nfce`, `ItemNfce`, `FaturaNfce`, `Inutilizacao` | +| **CT-e** | `Cte`, `MedidaCte`, `ComponenteCte`, `ChaveNfeCte` | +| **MDF-e** | `Mdfe`, `Percurso`, `UnidadeCarga`, `ValePedagio`, `Ciot` | +| **Financeiro** | `ContaPagar`, `ContaReceber`, `Caixa`, `SangriaCaixa`, `SuprimentoCaixa`, `Pagamento` | +| **Estoque** | `Estoque`, `MovimentacaoProduto`, `StockMove`, `TransferenciaEstoque`, `ItemInventario` | +| **Pessoas** | `Cliente`, `Fornecedor`, `Funcionario`, `Transportadora`, `Motoboy` | +| **Food Service** | `Pedido`, `ItemPedido`, `Adicional`, `TamanhoPizza`, `ConfiguracaoCardapio`, `CarrosselCardapio` | +| **CRM** | `CrmAnotacao`, `MensagemPadraoCrm`, `CupomDesconto`, `CashBackConfig` | +| **E-commerce** | `WoocommerceConfig`, `WoocommercePedido`, `WoocommerceItemPedido`, `VendiZapConfig` | +| **Agendamento** | `Agendamento`, `ItemAgendamento`, `Servico`, `Funcionamento`, `Interrupcao` | +| **OS** | `OrdemServico`, `ServicoOs`, `RelatorioOs`, `FuncionarioOs`, `ProdutoOs` | +| **Produção** | `OrdemProducao`, `Apontamento`, `CustoConfiguracao` | +| **Hotelaria** | `Acomodacao`, `Reserva`, `Frigobar` | +| **Ótica** | `OticaOs`, `Laboratorio`, `TratamentoOtica`, `FormatoArmacao`, `TipoArmacao` | + +--- + +## Services (Motor de Negócios) + +| Service | Responsabilidade | +|---------|-----------------| +| `NFeService.php` | Emissão/cancelamento/CC de NF-e via Cloud-DFE SDK | +| `NFeServiceApi.php` | API externa de NF-e | +| `NFCeService.php` | Emissão de NFC-e (consumidor final) | +| `NFCeServiceApi.php` | API externa de NFC-e | +| `CTeService.php` | CT-e para transportadoras | +| `CTeOsService.php` | CT-e OS (ordem de serviço de transporte) | +| `MDFeService.php` | MDF-e para manifestos de carga | +| `DFeService.php` | Manifesto do Destinatário | +| `StockEntryService.php` | Entrada automática de estoque por NF-e | +| `StockSaleService.php` | Baixa automática de estoque por venda | +| `IbptService.php` | Consulta IBPT para carga tributária | +| `SpeedService.php` | SPED fiscal | +| `FinancePrevisaoService.php` | Previsão financeira com IA | + +--- + +## Migrations (260 tabelas) + +### Evolução Cronológica + +| Período | Tabelas Criadas | Destaque | +|---------|----------------|----------| +| 2022 | `users`, `empresas`, `produtos`, `clientes`, `caixas` | Core do sistema | +| 2023 Q2 | `nves` (NF-e), `nfces`, `item_nves` | Módulo fiscal | +| 2023 Q3 | `pagamentos`, `inutilizacaos` | Financeiro | +| 2023 Q4 | `ctes`, `conta_pagars`, `conta_recebers`, `mdves`, `ordem_servicos`, `pedidos` | Transporte, OS, Food | +| 2024 Q1 | `cte_os`, `ordem_producaos`, `produto_composicaos` | Produção | +| 2024 Q2 | `cotacaos`, `ifood_*`, `woocommerce_*`, `mercado_livre_*` | E-commerce | +| 2024 Q3 | `stock_moves`, `imei_units`, `crm_anotacaos` | IMEI, CRM | +| 2024 Q4 | `otica_os`, `laboratorios`, `acomodacaos`, `reservas` | Ótica, Hotelaria | +| 2025 | `item_inventarios`, `tef_*`, `nuvem_shop_*` | Inventário, TEF, NuvemShop | + +--- + +## Docker Infrastructure + +```yaml +# plus/docker-compose.yml +services: + app: # PHP 8.2 FPM + build: . + volumes: .:/var/www + networks: [controlplus] + + web: # Nginx 1.25 + image: nginx:1.25-alpine + ports: "8080:80" + depends_on: [app] + + db: # MySQL 8.0 + image: mysql:8.0 + volumes: db_data:/var/lib/mysql + environment: + MYSQL_DATABASE: controlplus +``` + +**Dockerfile:** +- Base: `php:8.2-fpm` +- Extensions: GD, BCMath, PDO, Zip, Intl, Soap +- Node.js 18 (para assets frontend) +- Composer para dependências PHP + +--- + +## Fluxo de Dados Suite ↔ Plus + +``` +┌────────────────────────────────────────────────────────────────┐ +│ FLUXO COMPLETO │ +│ │ +│ 1. Usuário acessa Arcádia Suite (porta 5000) │ +│ 2. Navega para módulo Plus (/plus) │ +│ 3. Suite gera token SSO com dados do usuário │ +│ 4. Proxy envia requisição para Laravel (porta 8080) │ +│ 5. Laravel valida SSO, auto-login, exibe interface │ +│ 6. Operações fiscais (NF-e/NFC-e) executadas no Plus │ +│ 7. Dados sincronizados via SOE Motor Adapter │ +│ 8. Suite consome dados para BI, dashboards, governança │ +│ │ +│ SUITE (Inteligência) PLUS (Execução) │ +│ ├── Decide o que vender ├── Emite NF-e/NFC-e │ +│ ├── Analisa tendências ├── Controla estoque │ +│ ├── Gera relatórios BI ├── Processa pagamentos │ +│ ├── Automatiza processos ├── Gerencia caixa │ +│ └── Governa políticas └── Registra movimentações │ +└────────────────────────────────────────────────────────────────┘ +``` + +--- + +## APIs do Plus + +### Rotas Web (912 rotas) - Agrupadas + +| Grupo | Rotas | Exemplos | +|-------|-------|---------| +| Dashboard | ~10 | `/home`, `/empresas` | +| Produtos | ~60 | `/produtos/*`, `/estoque/*`, `/marcas/*` | +| Vendas/PDV | ~50 | `/vendas/*`, `/pdv/*`, `/orcamento/*` | +| Fiscal | ~80 | `/nfe/*`, `/nfce/*`, `/cte/*`, `/mdfe/*` | +| Financeiro | ~70 | `/conta-pagar/*`, `/conta-receber/*`, `/caixa/*` | +| Clientes/CRM | ~40 | `/clientes/*`, `/crm/*` | +| Food Service | ~80 | `/cardapio/*`, `/delivery/*`, `/comanda/*`, `/pedidos/*` | +| E-commerce | ~60 | `/woocommerce/*`, `/mercado-livre/*`, `/nuvem-shop/*` | +| OS/Serviços | ~40 | `/ordem-servico/*`, `/agendamento/*`, `/servicos/*` | +| Transporte | ~50 | `/cte/*`, `/mdfe/*`, `/veiculos/*`, `/motoboy/*` | +| Admin | ~100 | `/usuarios/*`, `/empresa/*`, `/configuracao/*` | +| Contabilidade | ~60 | `/sped/*`, `/apuracao/*`, `/fechamento/*` | +| Outros | ~212 | Reservas, ótica, laboratórios, tickets, etc. | + +### Rotas API (634 rotas) - Agrupadas + +| Grupo | Prefixo | Descrição | +|-------|---------|-----------| +| PDV | `/api/pdv/*` | Ponto de venda mobile | +| Cardápio | `/api/cardapio/*` | Cardápio digital | +| Delivery | `/api/delivery/*` | Delivery app | +| Comanda | `/api/comanda/*` | Sistema de comandas | +| Kotlin App | `/api/kotlin/*` | App mobile nativo | +| Fiscal | `/api/nfe/*`, `/api/nfce/*` | Emissão fiscal | +| CRM | `/api/crm/*` | CRM mobile | +| Estoque | `/api/stock-entry/*` | Entrada de estoque | +| E-commerce | `/api/woocommerce/*`, `/api/mercadolivre/*` | Integrações | +| iFood | `/api/ifood/*` | Integração iFood | + +--- + +## Resumo Visual + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ ARCÁDIA PLUS - ERP COMPLETO │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐│ +│ │ FISCAL │ │ VENDAS │ │ ESTOQUE │ │ FINANCEIRO ││ +│ │ NF-e/NFC-e │ │ PDV/Caixa │ │ IMEI Track │ │ Contas P/R ││ +│ │ CT-e/MDF-e │ │ Orçamentos │ │ Inventário │ │ Boletos ││ +│ │ NFS-e/SPED │ │ Trocas │ │ Transf. │ │ TEF ││ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘│ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐│ +│ │ FOOD │ │ E-COMMERCE │ │ SERVIÇOS │ │ TRANSPORTE ││ +│ │ Cardápio │ │ WooCommerce│ │ O.S. │ │ CT-e ││ +│ │ Delivery │ │ Merc.Livre │ │ Agendament │ │ MDF-e ││ +│ │ iFood │ │ NuvemShop │ │ Garantias │ │ Logística ││ +│ │ Comandas │ │ VendiZap │ │ │ │ ││ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘│ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐│ +│ │ CRM │ │ RH │ │ PRODUÇÃO │ │ SEGMENTOS ││ +│ │ Clientes │ │ Comissões │ │ Ordens │ │ Ótica ││ +│ │ Score │ │ Metas │ │ Apontament │ │ Hotelaria ││ +│ │ Contratos │ │ Roles │ │ Custos │ │ Marketplace││ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘│ +│ │ +│ 376 Controllers │ 320 Models │ 12 Services │ 1.194 Views │ +│ 260 Migrations │ 912 Web Routes │ 634 API Routes │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +*Arcádia Plus v2.0 - O Motor de Execução do Arcádia Suite* diff --git a/MAPA_SISTEMA_ARCADIA.md b/MAPA_SISTEMA_ARCADIA.md new file mode 100644 index 0000000..a11bd81 --- /dev/null +++ b/MAPA_SISTEMA_ARCADIA.md @@ -0,0 +1,469 @@ +# Arcádia Suite - Mapa Geral do Sistema + +## Visão Geral + +**Arcádia Suite** é o Escritório Estratégico para a Empresa Moderna. Uma plataforma que centraliza produtividade, inteligência, tomada de decisão e governança, orquestrando ERPs, pessoas e dados. + +**Princípio Central:** Separação absoluta entre decisão e execução. +- Arcádia **pensa, governa e orienta** +- ERPs **executam, registram e obedecem** + +--- + +## Arquitetura de 4 Camadas + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ CAMADA DE APRESENTAÇÃO │ +│ React 18 + TypeScript + Tailwind CSS + shadcn/ui │ +│ Interface tipo browser com abas + omnibox │ +│ 66 páginas/módulos │ +└─────────────────────────────────────────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ CAMADA DE ORQUESTRAÇÃO │ +│ Express.js + Socket.IO + Manus Agent │ +│ Porta 5000 (API + WebSocket) │ +│ 38 arquivos de rotas / 23 ferramentas registradas │ +└─────────────────────────────────────────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ CAMADA DE INTELIGÊNCIA │ +│ FastAPI (Contábil 8003, BI 8004, Automação 8005) │ +│ Communication Engine (Node 8006) │ +│ OpenAI GPT-4o (Manus/Dev Center) + GPT-4o-mini (WhatsApp) │ +└─────────────────────────────────────────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ CAMADA DE DADOS │ +│ PostgreSQL + Drizzle ORM │ +│ Knowledge Graph + ChromaDB (embeddings) │ +│ Session Store + Multi-tenant │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Mapa de Portas + +| Porta | Serviço | Tecnologia | +|-------|---------|-----------| +| 5000 | API Principal + Frontend | Express.js + React | +| 8002 | Motor Fiscal (Fisco) | FastAPI (Python) | +| 8003 | Motor Contábil | FastAPI (Python) | +| 8004 | Motor BI (Insights) | FastAPI (Python) | +| 8005 | Motor Automação | FastAPI (Python) | +| 8006 | Motor Comunicação | Node.js/Express | +| 8080 | Arcádia Plus (Laravel) | PHP/Laravel | + +--- + +## Módulos do Frontend (66 páginas) + +### Núcleo & Administração +| Página | Rota | Descrição | +|--------|------|-----------| +| Home | `/` | Dashboard principal | +| SOE | `/soe` | Sistema Operacional Empresarial | +| ERP | `/erp` | Módulo ERP legado | +| Admin | `/admin` | Administração do sistema | +| SuperAdmin | `/super-admin` | Gestão multi-tenant | + +### Módulos de Negócio +| Página | Rota | Descrição | +|--------|------|-----------| +| Financeiro | `/financeiro` | Contas a pagar/receber, fluxo de caixa | +| Contábil | `/contabil` | Contabilidade, DRE, balancetes | +| Fiscal | `/fisco` | NF-e, NFC-e, CFOP, NCM, CEST | +| CRM | `/crm` | Gestão de relacionamento com cliente | +| People | `/people` | RH, colaboradores, folha | +| Production | `/production` | Ordens de produção | +| Quality | `/quality` | Controle de qualidade | + +### Varejo & Comércio +| Página | Rota | Descrição | +|--------|------|-----------| +| Retail | `/retail` | Varejo (celulares, assistência técnica) | +| RetailReports | `/retail-reports` | Relatórios do varejo | +| Marketplace | `/marketplace` | Marketplace integrado | +| Valuation | `/valuation` | Avaliação de trade-in | + +### Comunicação +| Página | Rota | Descrição | +|--------|------|-----------| +| WhatsApp | `/whatsapp` | Multi-sessão WhatsApp | +| Chat | `/chat` | Chat interno | +| XOS Inbox | `/xos/inbox` | Caixa de entrada unificada | +| XOS CRM | `/xos/crm` | CRM unificado | +| XOS Campaigns | `/xos/campaigns` | Campanhas de marketing | +| XOS Tickets | `/xos/tickets` | Sistema de tickets | + +### Inteligência & IA +| Página | Rota | Descrição | +|--------|------|-----------| +| Scientist | `/scientist` | Auto-programação com IA | +| Knowledge | `/knowledge` | Base de conhecimento/grafo | +| BI Workspace | `/bi` | Business Intelligence | +| Manus | `/agent` | Agente autônomo central | + +### Desenvolvimento & DevOps +| Página | Rota | Descrição | +|--------|------|-----------| +| IDE | `/ide` | Editor Monaco + Terminal | +| Dev Center | `/dev-center` | Centro de desenvolvimento XOS | +| XOS Pipeline | `/xos/pipeline` | Pipeline autônomo de código | +| XOS Governance | `/xos/governance` | Governança e políticas | +| API Hub | `/api-hub` | Central de APIs | +| API Tester | `/api-tester` | Testador de APIs | +| DocType Builder | `/doctype-builder` | Construtor de tipos | +| Page Builder | `/page-builder` | Construtor de páginas | +| Workflow Builder | `/workflow-builder` | Construtor de workflows | + +### Operações & Engenharia +| Página | Rota | Descrição | +|--------|------|-----------| +| Engineering Hub | `/engineering` | Hub de engenharia | +| Field Operations | `/field-ops` | Operações de campo | +| Process Compass | `/compass` | Bússola de processos | +| Suppliers Portal | `/suppliers` | Portal de fornecedores | + +### Plataforma +| Página | Rota | Descrição | +|--------|------|-----------| +| Engine Room | `/engine-room` | Casa de Máquinas (status dos motores) | +| Automations | `/automations` | Motor de automações | +| Plus | `/plus` | ERP Laravel (proxy) | +| LMS | `/lms` | Sistema de aprendizagem | +| Communities | `/communities` | Comunidades | +| Support | `/support` | Central de suporte | +| Migration | `/migration` | Migração de dados | +| Central APIs | `/central-apis` | APIs centrais | + +--- + +## APIs do Backend (38 grupos de rotas) + +### Core +| Rota Base | Arquivo | Descrição | +|-----------|---------|-----------| +| `/api/login`, `/api/register` | `server/auth.ts` | Autenticação | +| `/api/admin/*` | `server/admin/routes.ts` | Administração | +| `/api/erp/*` | `server/erp/routes.ts` | ERP principal | +| `/api/soe/*` | `server/erp/routes.ts` | SOE (alias) | +| `/api/users/*` | `server/routes.ts` | Gestão de usuários | + +### Negócio +| Rota Base | Arquivo | Descrição | +|-----------|---------|-----------| +| `/api/financeiro/*` | `server/financeiro/routes.ts` | Financeiro | +| `/api/contabil/*` | `server/contabil/routes.ts` | Contabilidade | +| `/api/fisco/*` | `server/fisco/routes.ts` | Fiscal | +| `/api/crm/*` | `server/crm/routes.ts` | CRM | +| `/api/people/*` | `server/people/routes.ts` | RH/Pessoas | +| `/api/production/*` | `server/production/routes.ts` | Produção | +| `/api/quality/*` | `server/quality/routes.ts` | Qualidade | +| `/api/retail/*` | `server/retail/routes.ts` | Varejo | +| `/api/valuation/*` | `server/valuation/routes.ts` | Avaliação trade-in | +| `/api/marketplace/*` | `server/marketplace/routes.ts` | Marketplace | + +### Comunicação +| Rota Base | Arquivo | Descrição | +|-----------|---------|-----------| +| `/api/whatsapp/*` | `server/whatsapp/routes.ts` | WhatsApp multi-sessão | +| `/api/chat/*` | `server/chat/routes.ts` | Chat interno | +| `/api/email/*` | `server/email/routes.ts` | E-mail | +| `/api/comm/*` | proxy | Motor de Comunicação | +| `/api/xos/*` | `server/xos/routes.ts` | XOS CRM unificado | + +### Inteligência +| Rota Base | Arquivo | Descrição | +|-----------|---------|-----------| +| `/api/manus/*` | `server/manus/routes.ts` | Agente Manus IA | +| `/api/knowledge/*` | `server/learning/routes.ts` | Knowledge Graph | +| `/api/bi/*` | `server/bi/routes.ts` | Business Intelligence | +| `/api/bi/metaset/*` | `server/metaset/routes.ts` | Motor BI MetaSet | +| `/api/scientist/*` | `server/routes.ts` | Cientista de dados | + +### Desenvolvimento +| Rota Base | Arquivo | Descrição | +|-----------|---------|-----------| +| `/api/ide/*` | `server/ide/routes.ts` | IDE integrada | +| `/api/dev-center/*` | `server/blackboard/routes.ts` | Dev Center/Blackboard | +| `/api/xos/pipeline` | `server/blackboard/routes.ts` | Pipeline autônomo | +| `/api/governance/*` | `server/governance/routes.ts` | Governança | +| `/api/lowcode/*` | `server/lowcode/routes.ts` | Low-code engine | + +### Protocolos de Interoperabilidade +| Rota Base | Arquivo | Descrição | +|-----------|---------|-----------| +| `/api/mcp/v1/*` | `server/mcp/routes.ts` | Model Context Protocol | +| `/api/a2a/v1/*` | `server/routes.ts` | Agent to Agent Protocol | +| `/api/api-central/*` | `server/api-central/routes.ts` | Central de APIs | + +### Infraestrutura +| Rota Base | Arquivo | Descrição | +|-----------|---------|-----------| +| `/api/engine-room/*` | `server/engine-room/routes.ts` | Casa de Máquinas | +| `/api/automations/*` | `server/automations/routes.ts` | Motor de Automação | +| `/api/modules/*` | `server/modules/loader.ts` | Módulos dinâmicos | +| `/api/login-bridge/*` | `server/login-bridge/routes.ts` | SSO Bridge | +| `/api/migration/*` | `server/migration/routes.ts` | Migração | + +--- + +## Motores (Engines) + +### Motor IA - Manus (Node.js, porta 5000) +- **Modelo:** GPT-4o (Dev Center), GPT-4o-mini (WhatsApp) +- **Agentes:** 6 agentes autônomos (Architect, Generator, Validator, Executor, Researcher, Evolution) +- **Ferramentas:** 23 ferramentas registradas (GitHub, filesystem, BI, git) +- **Pipeline:** Design → Codegen → Validation → Staging → Evolution + +### Motor Fiscal - Fisco (Python, porta 8002) +- NF-e / NFC-e via nfelib +- NCMs, CFOPs, CESTs, grupos tributários +- Certificados digitais +- Comunicação com SEFAZ + +### Motor Contábil (Python, porta 8003) +- Plano de contas +- Lançamentos contábeis +- DRE, Balanço Patrimonial + +### Motor BI - Insights (Python, porta 8004) +- Execução SQL +- Geração de gráficos +- Análise com Pandas +- Cache inteligente + +### Motor Automação (Python, porta 8005) +- Cron scheduler +- Event bus +- Executor de workflows + +### Motor Comunicação (Node.js, porta 8006) +- Unifica XOS CRM + WhatsApp + Email +- Contatos, threads, mensagens unificados +- Filas de atendimento +- Eventos para Knowledge Graph + +### Arcádia Plus - ERP Laravel (PHP, porta 8080) +- NF-e/NFC-e/CT-e/MDF-e +- PDV (ponto de venda) +- Cardápio digital +- Ordens de serviço +- Estoque com rastreabilidade +- Integrações e-commerce (WooCommerce, Mercado Livre, NuvemShop) +- Integrações delivery (iFood) + +--- + +## Dev Center XOS - 6 Agentes Autônomos + +``` +Prompt em Português + │ + ▼ +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Architect │ ──▶ │ Generator │ ──▶ │ Validator │ +│ (Design) │ │ (Codegen) │ │ (Typecheck) │ +└──────────────┘ └──────────────┘ └──────────────┘ + │ + ▼ +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Evolution │ ◀── │ Researcher │ ◀── │ Executor │ +│ (Aprende) │ │ (Pesquisa) │ │ (Staging) │ +└──────────────┘ └──────────────┘ └──────────────┘ +``` + +--- + +## Módulo Retail (Varejo de Celulares) + +### Funcionalidades Core +- **Vendas com IMEI:** Rastreamento individual de aparelhos +- **Trade-in:** Avaliação com checklist de 19 itens +- **Ordens de Serviço:** Gestão completa de assistência técnica +- **Garantia:** Controle de garantias por IMEI +- **Caixa Diário:** Reconciliação de caixa com fechamento +- **Comissões:** Cálculo automático por vendedor + +### Checklist Trade-in (19 itens) +1. Liga normalmente +2. Problemas na tela +3. WiFi funcionando +4. Bluetooth funcionando +5. Câmera frontal +6. Câmera traseira +7. Microfone +8. Alto-falante +9. Botões físicos +10. Sensor biométrico +11. Carregamento +12. Bateria saudável +13. GPS funcionando +14. Giroscópio +15. Acelerômetro +16. NFC +17. Resistência à água +18. Face ID / reconhecimento facial +19. Vibração + +--- + +## Banco de Dados (PostgreSQL + Drizzle ORM) + +### Tabelas Principais +| Grupo | Tabelas | +|-------|---------| +| **Identidade** | `users`, `profiles`, `tenants` | +| **Produtividade** | `workspace_pages`, `page_blocks`, `dashboard_widgets`, `quick_notes` | +| **Comunicação** | `conversations`, `messages`, `chat_threads`, `chat_messages` | +| **WhatsApp** | `whatsapp_sessions`, `whatsapp_contacts`, `whatsapp_messages`, `whatsapp_tickets` | +| **ERP Core** | `applications`, `erp_connections`, `agent_tasks`, `task_executions` | +| **Conhecimento** | `knowledge_base`, `knowledge_graph_nodes`, `knowledge_graph_edges` | +| **Governança** | `xos_governance_*`, `xos_job_queue`, `xos_agent_metrics` | +| **Pipeline** | `xos_staging_changes`, `xos_dev_pipelines` | +| **Comunicação Unificada** | `comm_contacts`, `comm_threads`, `comm_messages`, `comm_channels` | +| **Varejo** | Via módulos dinâmicos (`/api/modules/retail-reports`) | +| **Financeiro** | Contas, lançamentos, conciliação | +| **Fiscal** | NCMs, CFOPs, notas fiscais | + +--- + +## Integrações Externas + +| Serviço | Uso | +|---------|-----| +| **OpenAI** | GPT-4o (Manus, Dev Center), GPT-4o-mini (WhatsApp) | +| **GitHub** | Commits automáticos, análise de repositórios | +| **ERPNext** | Integração com ERP externo (clientes, produtos, vendas) | +| **WhatsApp/Baileys** | Multi-sessão de atendimento | +| **SEFAZ** | NF-e/NFC-e via nfelib | +| **Cloud-DFE** | SDK fiscal (NF-e, NFC-e, CT-e, MDF-e) | +| **WooCommerce** | E-commerce integration | +| **Mercado Livre** | Marketplace | +| **NuvemShop** | E-commerce | +| **iFood** | Delivery (pedidos, cardápio) | +| **Asaas** | Pagamentos, boletos | + +--- + +## Protocolos de Interoperabilidade + +| Protocolo | Rota | Descrição | +|-----------|------|-----------| +| **MCP** | `/api/mcp/v1/` | Model Context Protocol - exposição de ferramentas | +| **A2A** | `/api/a2a/v1/` | Agent to Agent - comunicação bidirecional | +| **AP2** | Planejado | Agent Payment Protocol | +| **UCP** | Planejado | Unified Commerce Protocol | + +--- + +## Como Rodar Localmente + +### Pré-requisitos +- Node.js 20+ +- Python 3.11+ +- PostgreSQL 16+ +- PHP 8.2+ (opcional, para Arcádia Plus) + +### Instalação + +```bash +# 1. Extrair o backup +tar xzf arcadia-suite-backup.tar.gz + +# 2. Instalar dependências Node +npm install + +# 3. Instalar dependências Python +pip install fastapi uvicorn pandas numpy psycopg2-binary nfelib lxml cryptography + +# 4. Configurar variáveis de ambiente +cp .env.example .env +# Editar .env com suas credenciais: +# DATABASE_URL=postgresql://user:pass@localhost:5432/arcadia +# OPENAI_API_KEY=sk-... +# GITHUB_TOKEN=ghp_... + +# 5. Criar banco de dados +createdb arcadia + +# 6. Executar migrations +npx drizzle-kit push + +# 7. Iniciar em desenvolvimento +npm run dev +``` + +### Variáveis de Ambiente Necessárias +| Variável | Descrição | +|----------|-----------| +| `DATABASE_URL` | URL de conexão PostgreSQL | +| `OPENAI_API_KEY` | Chave da API OpenAI | +| `GITHUB_TOKEN` | Token GitHub para integrações | +| `ERPNEXT_URL` | URL do ERPNext (opcional) | +| `ERPNEXT_API_KEY` | Chave API ERPNext (opcional) | +| `ERPNEXT_API_SECRET` | Segredo API ERPNext (opcional) | +| `SESSION_SECRET` | Segredo para sessões Express | + +### Credenciais Padrão +- **Usuário:** admin +- **Senha:** admin +- **Role:** master + +--- + +## Estrutura de Diretórios + +``` +arcadia-suite/ +├── client/ # Frontend React +│ ├── src/ +│ │ ├── pages/ # 66 páginas +│ │ ├── components/ # Componentes reutilizáveis +│ │ ├── hooks/ # Custom hooks +│ │ └── lib/ # Utilitários +│ └── public/ # Assets estáticos +├── server/ # Backend Express +│ ├── admin/ # Administração +│ ├── autonomous/ # Ferramentas autônomas +│ ├── bi/ # Business Intelligence +│ ├── blackboard/ # Dev Center (6 agentes) +│ ├── chat/ # Chat interno +│ ├── communication/ # Motor de comunicação +│ ├── contabil/ # Motor contábil +│ ├── crm/ # CRM +│ ├── engine-room/ # Casa de Máquinas +│ ├── erp/ # ERP/SOE +│ ├── financeiro/ # Financeiro +│ ├── fisco/ # Fiscal +│ ├── governance/ # Governança XOS +│ ├── ide/ # IDE integrada +│ ├── integrations/ # Integrações externas +│ ├── learning/ # Knowledge Graph +│ ├── manus/ # Agente Manus +│ ├── mcp/ # Model Context Protocol +│ ├── modules/ # Módulos dinâmicos +│ ├── people/ # RH +│ ├── plus/ # Proxy Laravel +│ ├── production/ # Produção +│ ├── python/ # Scripts Python +│ ├── quality/ # Qualidade +│ ├── retail/ # Varejo +│ ├── whatsapp/ # WhatsApp +│ └── xos/ # XOS unificado +├── shared/ # Código compartilhado +│ ├── schema.ts # Schema principal (Drizzle) +│ └── schemas/ # Schemas modulares +├── plus/ # ERP Laravel (PHP) +├── python-service/ # Serviço Python +├── db/ # Configuração do banco +├── migrations/ # Migrations Drizzle +└── docs/ # Documentação +``` + +--- + +*Arcádia Suite v2.0 - O Escritório Estratégico para a Empresa Moderna* diff --git a/PLANO_BI_SUPERSET.md b/PLANO_BI_SUPERSET.md new file mode 100644 index 0000000..5a74ae6 --- /dev/null +++ b/PLANO_BI_SUPERSET.md @@ -0,0 +1,787 @@ +# PLANO BI — Substituição Metabase → Apache Superset +## Análise Real + Plano de Migração +### Versão 1.0 — Março 2026 + +--- + +## 1. DIAGNÓSTICO — ESTADO ATUAL + +### 1.1 O que foi descoberto no código + +O documento do Replit referenciava **Metabase** (Java, :8088) como o pilar visual do BI. Ao analisar o código real, a situação é diferente: + +| Componente | Nome no doc | Nome real no código | Status | +|---|---|---|---| +| Plataforma BI Visual | "Metabase" | **"MetaSet"** (alias) | Metabase por baixo | +| Proxy | `/metabase/*` | `server/metabase/proxy.ts` | Funcional | +| Auth | Metabase session | `server/metaset/routes.ts` (autologin) | Funcional | +| Client | MetabaseClient | `server/metaset/client.ts` | Funcional | +| UI | Advanced tab iframe | `/api/bi/metaset/autologin` → `/metabase/` | Funcional | +| **Superset** | Não mencionado | **`docker-compose.yml` linha 165** | **JÁ CONFIGURADO** | + +**Descoberta crítica:** O Apache Superset **já está no docker-compose.yml**: +```yaml +superset: + image: apache/superset:4.1.0 + restart: unless-stopped + environment: + SUPERSET_SECRET_KEY: ${SUPERSET_SECRET_KEY:-superset-secret-change-in-prod} + DATABASE_URL: postgresql://arcadia:arcadia123@db:5432/arcadia_superset + ports: + - "8088:8088" + depends_on: + db: + condition: service_healthy + profiles: [bi] +``` + +O Superset está configurado, mas **não integrado ao gateway Node.js**. O que falta é a ponte. + +### 1.2 Arquivos que precisam mudar vs o que fica igual + +**Mudam:** +``` +server/metabase/proxy.ts → substituir por server/superset/proxy.ts +server/metaset/routes.ts → substituir por server/superset/routes.ts +server/metaset/client.ts → substituir por server/superset/client.ts +client/src/pages/BiWorkspace.tsx (Advanced tab apenas) +docker-compose.yml (Superset config + init) +docker-compose.prod.yml (adicionar Superset) +.env.example (novas variáveis) +``` + +**NÃO mudam (ficam exatamente iguais):** +``` +server/python/bi_engine.py ← Motor Python :8004 continua intacto +server/bi/routes.ts ← CRUD de datasets/charts/dashboards +server/bi/upload.ts ← ETL pipeline +server/bi/staging.ts ← Staging +server/bi/engine-proxy.ts ← Proxy para BI Engine Python +client/src/pages/BiWorkspace.tsx (7 de 8 tabs ficam iguais) +Todas as tabelas do banco (bi_datasets, bi_charts, etc.) +``` + +--- + +## 2. POR QUE SUPERSET É MELHOR PARA O CASO + +### 2.1 Metabase vs Superset + +| Critério | Metabase | Apache Superset | +|---|---|---| +| Runtime | Java (JVM, 500MB+ RAM) | Python/Flask (mais leve) | +| Embedding | Iframe com cookie de sessão | **Guest Token JWT** (seguro, sem credenciais) | +| "Qualquer tela" | Iframe estático, limitado | **`@superset-ui/embedded-sdk`** — componente React nativo | +| REST API | Limitada e não documentada | **REST API v1 completa e documentada** | +| Consistência de stack | Java (fora do padrão) | Python (mesmo stack dos motores existentes) | +| Docker image | `metabase/metabase` ~700MB | `apache/superset` ~400MB | +| SQL Lab | Básico | **Poderoso** (autocomplete, histórico, salvar queries) | +| Alertas | Básico | **Avançado** (webhooks, Slack, email) | +| Tipos de chart | ~20 | **50+** (incluindo mapas, sunburst, funnel) | +| Banco de metadados | H2/Postgres separado | **Mesmo PostgreSQL** da Arcádia | + +### 2.2 A feature que o usuário pediu: "funcionar em qualquer tela" + +O Superset resolve isso com **Guest Token + Embedded SDK**: + +``` +Fluxo atual (Metabase): + BiWorkspace → iframe → /metabase/ → autologin com cookie + ❌ Só funciona na tab Advanced do BiWorkspace + ❌ Cookie expira, precisa re-autenticar + ❌ Não embeda em outras páginas facilmente + +Fluxo novo (Superset): + QUALQUER página React → + ✅ Funciona no Dashboard principal (/) + ✅ Funciona no SOE (/soe tab Financeiro) + ✅ Funciona no /contabil + ✅ Funciona no /financeiro + ✅ Funciona em qualquer tela do Arcádia + ✅ Guest Token renovado automaticamente (sem re-login) +``` + +--- + +## 3. ARQUITETURA COM SUPERSET + +### 3.1 Diagrama atualizado + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ USUÁRIO / FRONTEND │ +│ │ +│ BiWorkspace.tsx (8 tabs — 7 iguais, Advanced → Superset) │ +│ + QUALQUER outra página pode embedar um dashboard Superset │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ Componente React reutilizável em QUALQUER rota │ │ +│ └────────────────────────────────────────────────────────────┘ │ +└─────────────────────────┬────────────────────────────────────────────┘ + │ + ┌───────────────┼──────────────────────┐ + │ │ │ + ▼ ▼ ▼ +┌──────────────┐ ┌────────────────┐ ┌──────────────────────┐ +│ API BI Node │ │ BI Engine Py │ │ Superset (Python) │ +│ /api/bi/* │ │ /api/bi-engine │ │ /superset/* │ +│ (sem mudança)│ │ :8004 (igual) │ │ :8088 │ +│ │ │ │ │ │ +│ + novo: │ │ │ │ REST API v1 │ +│ /api/superset│ │ │ │ Guest Token JWT │ +│ /guest-token │ │ │ │ SQL Lab │ +│ │ │ │ │ 50+ chart types │ +└──────────────┘ └────────────────┘ └──────────┬───────────┘ + │ + ▼ + ┌──────────────────────┐ + │ PostgreSQL │ + │ arcadia (dados SOE) │ + │ arcadia_superset │ + │ (metadados Superset) │ + └──────────────────────┘ +``` + +### 3.2 Dois bancos PostgreSQL + +``` +Banco: arcadia → Dados do SOE (persons, products, sales_orders, etc.) + Superset conecta aqui em READ-ONLY para criar charts +Banco: arcadia_superset → Metadados do Superset (dashboards, queries, users) + Superset usa internamente +``` + +Ambos no mesmo servidor PostgreSQL, bancos separados. O docker-compose.yml já referencia `arcadia_superset`. + +--- + +## 4. O QUE CONSTRUIR — Passo a Passo + +### 4.1 Configuração do Superset (docker-compose.yml) + +O container já existe. Faltam: init script, volumes, configuração de embedding. + +```yaml +# docker-compose.yml — seção superset (expandida) + +superset: + image: apache/superset:4.1.0 + restart: unless-stopped + environment: + SUPERSET_SECRET_KEY: ${SUPERSET_SECRET_KEY:-superset-secret-change-in-prod} + DATABASE_URL: postgresql://${PGUSER:-arcadia}:${PGPASSWORD:-arcadia123}@db:5432/arcadia_superset + SUPERSET_WEBSERVER_PORT: 8088 + PYTHONPATH: /app/pythonpath + # Para embedding funcionar: + FEATURE_FLAGS: '{"EMBEDDED_SUPERSET": true, "ENABLE_TEMPLATE_PROCESSING": true}' + ports: + - "8088:8088" + volumes: + - ./docker/superset/superset_config.py:/app/pythonpath/superset_config.py + - ./docker/superset/init.sh:/app/docker/init.sh + - superset_home:/app/superset_home + depends_on: + db: + condition: service_healthy + command: ["/bin/bash", "/app/docker/init.sh"] + profiles: [bi] + networks: + - arcadia +``` + +### 4.2 Arquivo de Configuração Superset + +```python +# docker/superset/superset_config.py + +import os + +# Chave secreta (mesma do .env) +SECRET_KEY = os.environ.get("SUPERSET_SECRET_KEY", "change-in-production") + +# Banco de metadados do Superset +SQLALCHEMY_DATABASE_URI = os.environ.get( + "DATABASE_URL", + "postgresql://arcadia:arcadia123@db:5432/arcadia_superset" +) + +# CORS — permite o gateway Arcádia (:5000) chamar a API +ENABLE_CORS = True +CORS_OPTIONS = { + "supports_credentials": True, + "allow_headers": ["*"], + "resources": {r"/api/*": {"origins": "*"}}, +} + +# Embedding habilitado +FEATURE_FLAGS = { + "EMBEDDED_SUPERSET": True, + "ENABLE_TEMPLATE_PROCESSING": True, + "ALERT_REPORTS": True, # Alertas automáticos + "DRILL_TO_DETAIL": True, # Drill-down em charts +} + +# Timeout de queries (30s por default, aumentar para análises pesadas) +SUPERSET_WEBSERVER_TIMEOUT = 300 + +# Cache (Redis se disponível, senão in-memory) +CACHE_CONFIG = { + "CACHE_TYPE": "SimpleCache", + "CACHE_DEFAULT_TIMEOUT": 300, # 5 min +} + +# Tema/branding Arcádia (logo, cores) +APP_NAME = "Arcádia Insights" +APP_ICON = "/static/arcadia-logo.png" +``` + +### 4.3 Init Script do Superset + +```bash +#!/bin/bash +# docker/superset/init.sh — roda ao iniciar o container + +set -e + +echo "[Superset Init] Iniciando configuração..." + +# Aguarda PostgreSQL +until psql "${DATABASE_URL}" -c "SELECT 1" > /dev/null 2>&1; do + echo "[Superset Init] Aguardando PostgreSQL..." + sleep 2 +done + +# Cria banco arcadia_superset se não existir +psql "postgresql://${PGUSER:-arcadia}:${PGPASSWORD:-arcadia123}@db:5432/postgres" \ + -c "CREATE DATABASE arcadia_superset OWNER arcadia;" 2>/dev/null || true + +# Inicializa banco do Superset +superset db upgrade + +# Cria usuário admin (só se não existir) +superset fab create-admin \ + --username "${SUPERSET_ADMIN_USER:-admin}" \ + --firstname "Arcádia" \ + --lastname "Admin" \ + --email "${SUPERSET_ADMIN_EMAIL:-admin@arcadia.app}" \ + --password "${SUPERSET_ADMIN_PASSWORD:-arcadia2026}" 2>/dev/null || true + +# Carrega exemplos (opcional, comentar em prod) +# superset load_examples + +# Inicializa roles e permissões +superset init + +# Registra conexão com o banco Arcádia (dados do SOE) +python - <<'PYEOF' +from superset import create_app +from superset.extensions import db +from superset.models.core import Database +import os + +app = create_app() +with app.app_context(): + existing = db.session.query(Database).filter_by( + database_name="Arcádia Suite" + ).first() + if not existing: + arcadia_db = Database( + database_name="Arcádia Suite", + sqlalchemy_uri=os.environ.get( + "ARCADIA_DATABASE_URL", + "postgresql://arcadia:arcadia123@db:5432/arcadia" + ), + expose_in_sqllab=True, + allow_run_async=True, + allow_csv_upload=False, + ) + db.session.add(arcadia_db) + db.session.commit() + print("[Superset Init] Banco 'Arcádia Suite' registrado!") + else: + print("[Superset Init] Banco 'Arcádia Suite' já existe.") +PYEOF + +echo "[Superset Init] Iniciando servidor..." +gunicorn \ + --bind "0.0.0.0:${SUPERSET_WEBSERVER_PORT:-8088}" \ + --access-logfile "-" \ + --error-logfile "-" \ + --workers 4 \ + --timeout 120 \ + --limit-request-line 0 \ + --limit-request-field_size 0 \ + "superset.app:create_app()" +``` + +### 4.4 Proxy Superset (substitui server/metabase/proxy.ts) + +```typescript +// server/superset/proxy.ts + +import { Express, Response } from "express"; +import { createProxyMiddleware } from "http-proxy-middleware"; + +const SUPERSET_HOST = process.env.SUPERSET_HOST || "localhost"; +const SUPERSET_PORT = parseInt(process.env.SUPERSET_PORT || "8088", 10); +const SUPERSET_TIMEOUT = 60000; + +export function setupSupersetProxy(app: Express): void { + const target = `http://${SUPERSET_HOST}:${SUPERSET_PORT}`; + + const supersetProxy = createProxyMiddleware({ + target, + changeOrigin: true, + timeout: SUPERSET_TIMEOUT, + proxyTimeout: SUPERSET_TIMEOUT, + pathRewrite: { "^/superset": "" }, + on: { + error: (err, _req, res) => { + console.error("[Superset Proxy] Error:", err.message); + if (res && typeof (res as Response).status === "function") { + (res as Response).status(502).json({ + error: "Superset indisponível", + message: "O Superset está iniciando. Tente novamente em alguns segundos.", + target, + }); + } + }, + proxyRes: (proxyRes) => { + const location = proxyRes.headers["location"]; + if (location && typeof location === "string" && location.startsWith("/")) { + proxyRes.headers["location"] = `/superset${location}`; + } + }, + }, + }); + + app.use("/superset", supersetProxy); + console.log(`[Superset Proxy] Configurado -> /superset/* => ${target}`); +} +``` + +### 4.5 Rotas Superset — Guest Token para Embedding + +Esta é a peça-chave para "funcionar em qualquer tela": + +```typescript +// server/superset/routes.ts + +import type { Express, Request, Response } from "express"; + +const SUPERSET_HOST = process.env.SUPERSET_HOST || "localhost"; +const SUPERSET_PORT = parseInt(process.env.SUPERSET_PORT || "8088", 10); +const SUPERSET_URL = `http://${SUPERSET_HOST}:${SUPERSET_PORT}`; +const SUPERSET_ADMIN_USER = process.env.SUPERSET_ADMIN_USER || "admin"; +const SUPERSET_ADMIN_PASS = process.env.SUPERSET_ADMIN_PASSWORD || "arcadia2026"; + +// Cache do token de serviço (expira em 50 min) +let serviceToken: string | null = null; +let serviceTokenExpiry = 0; + +async function getServiceToken(): Promise { + if (serviceToken && Date.now() < serviceTokenExpiry) return serviceToken; + + const resp = await fetch(`${SUPERSET_URL}/api/v1/security/login`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + username: SUPERSET_ADMIN_USER, + password: SUPERSET_ADMIN_PASS, + provider: "db", + refresh: true, + }), + }); + + if (!resp.ok) throw new Error("Falha ao autenticar no Superset"); + const data = await resp.json(); + serviceToken = data.access_token; + serviceTokenExpiry = Date.now() + 50 * 60 * 1000; // 50 min + return serviceToken!; +} + +export function registerSupersetRoutes(app: Express): void { + + // Guest Token — para embedding em qualquer tela + // O frontend chama este endpoint para obter um token temporário + // e renderiza o dashboard via @superset-ui/embedded-sdk + app.post("/api/superset/guest-token", async (req: Request, res: Response) => { + try { + if (!req.isAuthenticated()) return res.status(401).json({ error: "Not authenticated" }); + + const { dashboardId } = req.body; + if (!dashboardId) return res.status(400).json({ error: "dashboardId obrigatório" }); + + const token = await getServiceToken(); + + // Solicita guest token ao Superset + const guestResp = await fetch(`${SUPERSET_URL}/api/v1/security/guest_token/`, { + method: "POST", + headers: { + "Content-Type": "application/json", + "Authorization": `Bearer ${token}`, + }, + body: JSON.stringify({ + user: { + username: `arcadia_${req.user?.id}`, + first_name: req.user?.name?.split(" ")[0] || "User", + last_name: req.user?.name?.split(" ")[1] || "", + }, + resources: [{ type: "dashboard", id: dashboardId }], + rls: [], // Row Level Security (futuro: por tenantId) + }), + }); + + if (!guestResp.ok) { + const err = await guestResp.text(); + return res.status(502).json({ error: "Falha ao gerar guest token", detail: err }); + } + + const { token: guestToken } = await guestResp.json(); + res.json({ token: guestToken, supersetUrl: "/superset" }); + } catch (err: any) { + res.status(502).json({ error: err.message }); + } + }); + + // Lista dashboards disponíveis (para o seletor na UI) + app.get("/api/superset/dashboards", async (req: Request, res: Response) => { + try { + if (!req.isAuthenticated()) return res.status(401).json({ error: "Not authenticated" }); + + const token = await getServiceToken(); + const resp = await fetch(`${SUPERSET_URL}/api/v1/dashboard/?q=(order_column:changed_on_delta_humanized,order_direction:desc)`, { + headers: { "Authorization": `Bearer ${token}` }, + }); + + if (!resp.ok) return res.status(502).json({ error: "Superset indisponível" }); + const data = await resp.json(); + res.json(data.result || []); + } catch (err: any) { + res.status(502).json({ error: err.message }); + } + }); + + // Health check + app.get("/api/superset/health", async (_req: Request, res: Response) => { + try { + const resp = await fetch(`${SUPERSET_URL}/health`); + res.json({ online: resp.ok, url: SUPERSET_URL }); + } catch { + res.json({ online: false, url: SUPERSET_URL }); + } + }); +} +``` + +### 4.6 Componente React — SupersetDashboard (reutilizável em QUALQUER tela) + +```typescript +// client/src/components/SupersetDashboard.tsx + +import { useEffect, useRef, useState } from "react"; +import { embedDashboard } from "@superset-ui/embedded-sdk"; + +interface SupersetDashboardProps { + dashboardId: string; + height?: string | number; + className?: string; +} + +export function SupersetDashboard({ + dashboardId, + height = "calc(100vh - 300px)", + className = "", +}: SupersetDashboardProps) { + const containerRef = useRef(null); + const [error, setError] = useState(null); + const [loading, setLoading] = useState(true); + + useEffect(() => { + if (!containerRef.current) return; + + let mounted = true; + setLoading(true); + setError(null); + + embedDashboard({ + id: dashboardId, + supersetDomain: window.location.origin + "/superset", + mountPoint: containerRef.current, + + // Busca guest token do gateway Arcádia + fetchGuestToken: async () => { + const resp = await fetch("/api/superset/guest-token", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ dashboardId }), + credentials: "include", + }); + if (!resp.ok) throw new Error("Falha ao obter token"); + const { token } = await resp.json(); + return token; + }, + + dashboardUiConfig: { + hideTitle: true, // Título próprio no Arcádia + hideChartControls: false, // Manter controles de chart + filters: { + visible: true, // Mostrar filtros + expanded: false, + }, + }, + }).then(() => { + if (mounted) setLoading(false); + }).catch((err) => { + if (mounted) { + setError(err.message); + setLoading(false); + } + }); + + return () => { mounted = false; }; + }, [dashboardId]); + + if (error) { + return ( +
+ Superset indisponível: {error} +
+ ); + } + + return ( +
+ {loading && ( +
+
+
+

Carregando Arcádia Insights...

+
+
+ )} +
+
+ ); +} +``` + +**Uso em QUALQUER página:** +```tsx +// Exemplo: na página /financeiro +import { SupersetDashboard } from "@/components/SupersetDashboard"; + +// Dashboard financeiro embeddado diretamente no módulo Financeiro + + +// Exemplo: na página /contabil + + +// Exemplo: no Dashboard principal (/) + +``` + +### 4.7 BiWorkspace.tsx — Advanced tab (única mudança na UI) + +```tsx +// Substituir a tab Advanced (linhas 2918-2945) + + +
+
+
+

Arcádia Insights — Apache Superset

+

+ SQL Lab avançado, 50+ tipos de gráfico, dashboards interativos +

+
+ + Abrir em Nova Aba + +
+ + {/* Dashboard selecionável */} + +
+ +``` + +--- + +## 5. TABELAS E VARIÁVEIS + +### 5.1 Nenhuma tabela nova no schema Arcádia + +O Superset usa seu próprio banco (`arcadia_superset`) para metadados internos. As tabelas do Arcádia não mudam. + +### 5.2 Novas variáveis de ambiente + +```bash +# .env — adicionar/substituir: + +# Superset (substitui METABASE_*) +SUPERSET_HOST=superset # nome do container Docker +SUPERSET_PORT=8088 +SUPERSET_SECRET_KEY= # gerar: openssl rand -hex 32 +SUPERSET_ADMIN_USER=admin +SUPERSET_ADMIN_EMAIL=admin@arcadia.app +SUPERSET_ADMIN_PASSWORD= # senha forte em prod + +# URL do banco Arcádia para o Superset acessar (read-only ideal) +ARCADIA_DATABASE_URL=postgresql://arcadia_ro:pass@db:5432/arcadia + +# Remover (não são mais necessários): +# METABASE_HOST +# METABASE_PORT +# METASET_ADMIN_EMAIL +# METASET_ADMIN_PASSWORD +``` + +--- + +## 6. ROADMAP — Fases de Implementação + +### Fase 1 — Infraestrutura (2-3 dias) +``` +[ ] Criar docker/superset/superset_config.py +[ ] Criar docker/superset/init.sh +[ ] Atualizar docker-compose.yml (expandir seção superset existente) +[ ] Adicionar volumes: superset_home no docker-compose +[ ] Testar: docker compose --profile bi up superset +[ ] Verificar: banco arcadia_superset criado, admin funciona, :8088 acessível +``` + +### Fase 2 — Gateway (1-2 dias) +``` +[ ] Criar server/superset/proxy.ts (substitui server/metabase/proxy.ts) +[ ] Criar server/superset/routes.ts (guest token, lista dashboards, health) +[ ] Registrar no server/routes.ts: setupSupersetProxy() + registerSupersetRoutes() +[ ] Remover/comentar setupMetabaseProxy() e registerMetaSetRoutes() +[ ] Testar: GET /api/superset/health → { online: true } +[ ] Testar: POST /api/superset/guest-token → token JWT +``` + +### Fase 3 — Frontend (2-3 dias) +``` +[ ] npm install @superset-ui/embedded-sdk +[ ] Criar client/src/components/SupersetDashboard.tsx +[ ] Atualizar BiWorkspace.tsx Advanced tab (substituir iframe MetaSet) +[ ] Testar: dashboard embeddado na Advanced tab +[ ] Criar 3 dashboards base no Superset: + - executive-summary (KPIs gerais) + - financial-overview (Financeiro) + - dre-mensal (DRE) +``` + +### Fase 4 — Embedding em outras telas (1 semana) +``` +[ ] Embedar SupersetDashboard no /financeiro (tab Análise) +[ ] Embedar SupersetDashboard no /contabil (tab DRE/Balanço) +[ ] Embedar SupersetDashboard no SOE (tab Dashboard) +[ ] Embedar SupersetDashboard no Home / Dashboard principal +[ ] RLS por tenantId (Row Level Security nos dashboards) +``` + +### Fase 5 — Migração de dashboards (conforme necessário) +``` +[ ] Recriar no Superset os dashboards que existiam no MetaSet (se houver) +[ ] Configurar alertas automáticos (Superset Alerts & Reports) +[ ] Criar dashboards para cada domínio do SOE: + - Vendas, Compras, Fiscal, Pessoas, Estoque +``` + +--- + +## 7. DIAGRAMA BI ATUALIZADO (completo) + +``` +┌────────────────────────────────────────────────────────────────────┐ +│ ARCÁDIA BI STACK v2 │ +│ │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ FRONTEND REACT — Pode usar em QUALQUER rota │ │ +│ │ │ │ +│ │ BiWorkspace.tsx → 8 tabs (7 iguais + Advanced=Superset) │ │ +│ │ → componente reutilizável │ │ +│ │ Guest Token API → /api/superset/guest-token │ │ +│ └────────────────────────────┬─────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────────┼──────────────────────┐ │ +│ │ │ │ │ +│ ┌──────▼──────┐ ┌────────▼───────┐ ┌─────────▼──────────┐ │ +│ │ API BI │ │ BI Engine │ │ Apache Superset │ │ +│ │ (Node.js) │ │ Python:8004 │ │ Python:8088 │ │ +│ │ sem mudança│ │ sem mudança │ │ │ │ +│ │ │ │ │ │ SQL Lab │ │ +│ │ CRUD │ │ SQL+Charts │ │ 50+ chart types │ │ +│ │ Upload/ETL │ │ Micro-BI │ │ Guest Token (embed) │ │ +│ │ Staging │ │ Análise Pandas │ │ Alerts & Reports │ │ +│ │ Backups │ │ Cache 5min │ │ REST API v1 │ │ +│ └─────┬───────┘ └────────┬───────┘ └─────────┬───────────┘ │ +│ │ │ │ │ +│ └──────────────────────┼─────────────────────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ PostgreSQL │ │ +│ │ │ │ +│ │ arcadia │ ← Dados SOE (read-only) │ +│ │ arcadia_superset │ ← Metadados Superset │ +│ └────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ CIENTISTA (Python) — IA/ML: análise, padrões, insights │ │ +│ │ ASSISTENTE BI (GPT) — chat sobre dados │ │ +│ │ (ambos sem mudança) │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 8. RESUMO — O que muda, o que fica + +| Componente | Ação | Esforço | +|---|---|---| +| `server/metabase/proxy.ts` | Substituir por `server/superset/proxy.ts` | 30 min | +| `server/metaset/routes.ts` | Substituir por `server/superset/routes.ts` | 2h | +| `server/metaset/client.ts` | Remover (lógica vai para routes.ts) | 5 min | +| `docker-compose.yml` Superset | Expandir configuração existente | 1h | +| `docker/superset/superset_config.py` | Criar (novo arquivo) | 30 min | +| `docker/superset/init.sh` | Criar (novo arquivo) | 1h | +| `BiWorkspace.tsx` Advanced tab | Substituir iframe MetaSet | 1h | +| `SupersetDashboard.tsx` | Criar componente (novo) | 2h | +| `npm install @superset-ui/embedded-sdk` | Instalar dependência | 5 min | +| BI Engine Python (:8004) | **Não muda nada** | — | +| API BI Node /api/bi/* | **Não muda nada** | — | +| Upload/ETL/Staging | **Não muda nada** | — | +| 7 tabs do BiWorkspace | **Não muda nada** | — | +| Tabelas do banco | **Não muda nada** | — | + +**Total estimado: 1-2 dias de implementação real** (a infra já está 80% pronta). + +--- + +## 9. VANTAGEM ESTRATÉGICA + +> O Apache Superset não é apenas "trocar Metabase". +> +> É a virada de chave que permite que o BI deixe de ser uma página separada +> e vire um **componente vivo** que aparece **dentro de cada módulo do Arcádia**: +> +> - O usuário está no módulo Financeiro → vê o dashboard financeiro ali mesmo +> - O usuário está no módulo Contábil → vê o DRE ali mesmo +> - O usuário está no SOE → vê os KPIs do negócio ali mesmo +> +> Sem abrir nova aba. Sem sair do contexto. Sem re-autenticar. +> O Superset renderiza no lugar exato onde o usuário está. + +--- + +*PLANO_BI_SUPERSET.md — Arcádia Suite v3.0* +*Gerado em: 2026-03-16 — Baseado na análise do MAPA_BI_ARCADIA.md (Replit) + código real* diff --git a/PLANO_EVOLUCAO_ARCADIA.md b/PLANO_EVOLUCAO_ARCADIA.md new file mode 100644 index 0000000..8268535 --- /dev/null +++ b/PLANO_EVOLUCAO_ARCADIA.md @@ -0,0 +1,421 @@ +# PLANO ESTRATÉGICO DE EVOLUÇÃO +## Arcádia Suite → Frappe Framework +### Versão 1.0 - Janeiro 2026 + +--- + +## 1. VISÃO GERAL + +### 1.1 Objetivo +Evoluir o Arcádia Suite para um **Business Operating System** completo, inspirado em três referências: + +| Referência | O que Inspira | +|------------|---------------| +| **Notion** | Blocos modulares, banco de dados relacional, personalização | +| **Replit** | IDE no navegador, colaboração em tempo real, deploy instantâneo | +| **Discord** | Comunidades, canais contextuais, comunicação em tempo real | + +### 1.2 Estratégia de Migração: Strangler Fig + +A estratégia Strangler Fig permite: +- Manter WhatsApp, Manus, CRM funcionando durante toda a migração +- Construir o novo sistema em paralelo +- Migrar módulo a módulo até o sistema legado "desaparecer" + +``` +Sistema Atual (Express/React) continua funcionando + ↓ +Você vai adicionando "camadas Frappe" por cima + ↓ +Cada módulo migrado substitui o antigo + ↓ +No final, o "núcleo antigo" sumiu naturalmente +``` + +### 1.3 Stack Técnico + +| Camada | Atual | Futuro | +|--------|-------|--------| +| Frontend | React 18 + TypeScript | Frappe Desk + React | +| Backend | Express.js | Frappe Framework | +| Database | PostgreSQL | PostgreSQL (mesmo) | +| Real-time | Socket.IO | Frappe Realtime + Socket.IO | +| WhatsApp | Baileys | Frappe App (Baileys) | +| IDE | Monaco + Terminal | IDE 3 Modos | + +--- + +## 2. ESTRUTURA MULTI-TENANT + +### 2.1 Hierarquia de 3 Níveis + +``` +NÍVEL 1: MASTER (Arcádia) +═════════════════════════ +• Equipe de desenvolvimento +• Acesso total ao sistema +• IDE Pro-Code completa +• Central de Bibliotecas (publica apps) +• Suporte N3 (acessa tenants para debug) +• Gerencia parceiros e planos + │ + ├───────────────────────┬───────────────────────┐ + ▼ ▼ ▼ +NÍVEL 2: PARCEIROS +══════════════════ +• Consultorias, integradores, revendas +• IDE Low-Code +• Gerencia seus clientes +• Comissões sobre vendas +• Suporte N2 aos clientes +• Baixa apps da biblioteca + │ + ┌────┴────┐ + ▼ ▼ +NÍVEL 3: CLIENTES +═════════════════ +• Empresas usuárias finais +• Cockpit personalizado +• CRM/ERP operacional +• WhatsApp (N sessões conforme plano) +• BI próprio +• Manus com tools básicas +``` + +### 2.2 Matriz de Permissões por Tipo de Tenant + +| Módulo | Master | Parceiro | Cliente | +|--------|--------|----------|---------| +| **IDE Pro-Code** | ✅ | ❌ | ❌ | +| **IDE Low-Code** | ✅ | ✅ | ❌ | +| **IDE No-Code** | ✅ | ✅ | ✅ (se habilitado) | +| **Central de Bibliotecas** | ✅ Publicar | ✅ Baixar | ❌ | +| **Central de APIs** | ✅ Gerenciar | ⚠️ Seus conectores | ⚠️ Leitura | +| **WhatsApp** | ✅ Ilimitado | ✅ N sessões | ✅ N sessões | +| **CRM/ERP** | ✅ Global | ✅ Próprio | ✅ Próprio | +| **Manus (IA)** | ✅ Todas tools | ✅ Tools permitidas | ✅ Básicas | +| **BI/Relatórios** | ✅ Global | ✅ Próprio | ✅ Próprio | +| **Suporte N3** | ✅ Acessa tenants | ❌ | ❌ | +| **Ver Parceiros** | ✅ | ✅ Seus clientes | ❌ | +| **Comissões** | ✅ Gerencia | ✅ Visualiza suas | ❌ | + +### 2.3 Alterações no Schema + +```sql +-- Alterações na tabela tenants +ALTER TABLE tenants ADD COLUMN tenant_type TEXT DEFAULT 'client'; +-- master = Arcádia, partner = Parceiros, client = Clientes + +ALTER TABLE tenants ADD COLUMN parent_tenant_id INTEGER REFERENCES tenants(id); +-- Referência ao tenant pai (hierarquia) + +ALTER TABLE tenants ADD COLUMN partner_code TEXT; +-- Código do parceiro para rastreamento + +ALTER TABLE tenants ADD COLUMN max_users INTEGER DEFAULT 5; +ALTER TABLE tenants ADD COLUMN max_storage_mb INTEGER DEFAULT 1000; +ALTER TABLE tenants ADD COLUMN features JSONB; +ALTER TABLE tenants ADD COLUMN commission_rate NUMERIC(5,2); +ALTER TABLE tenants ADD COLUMN trial_ends_at TIMESTAMP; + +-- Nova tabela: Planos +CREATE TABLE tenant_plans ( + id SERIAL PRIMARY KEY, + code TEXT NOT NULL UNIQUE, + name TEXT NOT NULL, + tenant_type TEXT NOT NULL, + max_users INTEGER DEFAULT 5, + max_storage_mb INTEGER DEFAULT 1000, + features JSONB, + monthly_price INTEGER DEFAULT 0, + yearly_price INTEGER DEFAULT 0, + is_active TEXT DEFAULT 'true', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- Nova tabela: Relacionamento Parceiro-Cliente +CREATE TABLE partner_clients ( + id SERIAL PRIMARY KEY, + partner_id INTEGER NOT NULL REFERENCES tenants(id), + client_id INTEGER NOT NULL REFERENCES tenants(id), + commission_rate NUMERIC(5,2), + status TEXT DEFAULT 'active', + started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + ended_at TIMESTAMP +); + +-- Nova tabela: Comissões +CREATE TABLE partner_commissions ( + id SERIAL PRIMARY KEY, + partner_id INTEGER NOT NULL REFERENCES tenants(id), + client_id INTEGER NOT NULL REFERENCES tenants(id), + reference_month TEXT NOT NULL, + client_plan_value INTEGER NOT NULL, + commission_rate NUMERIC(5,2) NOT NULL, + commission_value INTEGER NOT NULL, + status TEXT DEFAULT 'pending', + paid_at TIMESTAMP, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +``` + +--- + +## 3. CRONOGRAMA GERAL (6-9 Meses) + +``` + Mês 1 Mês 2 Mês 3 Mês 4 Mês 5 Mês 6+ + ├──────────┼──────────┼──────────┼──────────┼──────────┼────────► + +FASE 0 ████████████████████ + FUNDAÇÃO + Setup + Tenants + SSO + +FASE 1 ████████████████████████████ + INFRAESTRUTURA + CRM/ERP + Central APIs + Manus + +FASE 2 ████████████████████████████████ + EXPERIÊNCIA + Cockpit + Comunidades + IDE + +FASE 3 ████████████████████► + AUTOMAÇÃO + WhatsApp + RPA + Decommission +``` + +--- + +## 4. FASE 0: FUNDAÇÃO (Semanas 1-8) + +### 4.1 Objetivo +Preparar a base técnica sem quebrar nada do sistema atual. + +### 4.2 Entregas + +| # | Entrega | Descrição | Semana | +|---|---------|-----------|--------| +| 0.1 | **Setup Frappe Bench** | Instalar Frappe em servidor paralelo | 1-2 | +| 0.2 | **Hierarquia de Tenants** | Novos campos e tabelas no PostgreSQL | 2-3 | +| 0.3 | **SSO Bridge** | Login unificado (usuário loga uma vez) | 3-4 | +| 0.4 | **CDC Pipeline** | Sincronização de dados PostgreSQL ↔ Frappe | 4-6 | +| 0.5 | **Vault de Secrets** | Gerenciamento seguro de API keys | 5-6 | +| 0.6 | **Feature Flags** | Sistema de features por plano/tenant | 6-7 | +| 0.7 | **Planos e Preços** | Tabela de planos (free, starter, pro, enterprise) | 7-8 | + +### 4.3 Resultado +- ✅ Frappe rodando em paralelo +- ✅ Hierarquia master/partner/client funcionando +- ✅ Login único nos dois sistemas +- ✅ Dados sincronizados em tempo real +- ✅ Planos e features configuráveis + +--- + +## 5. FASE 1: INFRAESTRUTURA (Semanas 6-16) + +### 5.1 Objetivo +Migrar dados mestres e criar a Central de APIs. + +### 5.2 Entregas + +| # | Entrega | Descrição | Semana | +|---|---------|-----------|--------| +| 1.1 | **DocTypes CRM** | Clientes, Leads, Oportunidades no Frappe | 6-8 | +| 1.2 | **DocTypes ERP** | Produtos, Pedidos, Faturas no Frappe | 8-10 | +| 1.3 | **Central de APIs (MVP)** | Dashboard visual de integrações | 9-12 | +| 1.4 | **Conectores Básicos** | Interface para SEFAZ, Bancos (dados demo) | 12-14 | +| 1.5 | **Manus Frappe** | Agente IA via background jobs | 13-15 | +| 1.6 | **Knowledge Graph** | Migração do grafo para DocTypes | 14-16 | + +### 5.3 Central de APIs - Detalhamento + +**IMPORTANTE:** A Central de APIs é uma interface visual de gerenciamento. Os dados de integrações (SEFAZ, Bancos, Mercado Livre) são ILUSTRATIVOS/DEMO. Não fazemos integração real com APIs externas nesta fase. + +O que construímos: +- ✅ Interface visual (React) +- ✅ CRUD de conectores (cadastrar, editar, remover) +- ✅ Status visual (online, warning, error) +- ✅ Logs fictícios para demonstração +- ✅ Configurações por conector +- ✅ Permissões por tenant type + +O que NÃO fazemos: +- ❌ Conectar à SEFAZ real +- ❌ Conectar a bancos reais +- ❌ Chamadas API externas + +### 5.4 Resultado +- ✅ CRM/ERP acessível via Frappe Desk +- ✅ Central de APIs funcionando (dados demo) +- ✅ Manus consultando dados do Frappe +- ✅ Knowledge Graph migrado + +--- + +## 6. FASE 2: EXPERIÊNCIA (Semanas 12-24) + +### 6.1 Objetivo +Construir a nova interface (Cockpit, Comunidades, IDE). + +### 6.2 Entregas + +| # | Entrega | Descrição | Semana | +|---|---------|-----------|--------| +| 2.1 | **Cockpit PARA** | Navegação Projetos/Áreas/Recursos/Arquivo | 12-15 | +| 2.2 | **Dashboard Tríade** | Importante/Urgente/Circunstancial | 14-16 | +| 2.3 | **Widgets Sistema** | Tarefas, Calendário, Gráficos | 15-17 | +| 2.4 | **Comunidades MVP** | Canais por projeto (Socket.IO via Frappe) | 16-19 | +| 2.5 | **IDE No-Code** | DocType Builder visual | 18-20 | +| 2.6 | **IDE Low-Code** | Templates de scripts | 20-22 | +| 2.7 | **IDE Pro-Code** | Monaco + Terminal + Live Preview | 21-23 | +| 2.8 | **Central de Bibliotecas** | Repositório de apps Frappe | 22-24 | + +### 6.3 Cockpit PARA + Tríade + +O Cockpit é a interface principal do usuário, baseado em duas metodologias: + +**Método PARA (Tiago Forte):** +- **P**rojetos: Todos os projetos ativos com metas e prazos +- **Á**reas: Áreas de responsabilidade contínua (Vendas, Financeiro, RH) +- **R**ecursos: Base de conhecimento, templates, manuais +- **A**rquivo: Tudo concluído ou inativo, para consulta futura + +**Tríade do Tempo (Christian Barbosa):** +- 🟢 **Importante** (70% do tempo): Atividades que geram valor +- 🟡 **Urgente** (20% do tempo): Atividades com prazo apertado +- 🔴 **Circunstancial** (10% do tempo): Atividades que não agregam + +### 6.4 IDE 3 Modos + +| Modo | Quem Usa | O que Faz | +|------|----------|-----------| +| **No-Code** | Clientes | Criar formulários arrastando, workflows visuais, relatórios com filtros | +| **Low-Code** | Parceiros | Server Scripts com templates, validações, webhooks, fórmulas | +| **Pro-Code** | Arcádia | Monaco Editor completo, Terminal, Git, Deploy de apps | + +### 6.5 Resultado +- ✅ Cockpit PARA + Tríade funcionando +- ✅ Comunidades com canais por projeto +- ✅ IDE com 3 modos operando +- ✅ Central de Bibliotecas publicando apps + +--- + +## 7. FASE 3: AUTOMAÇÃO E DECOMMISSION (Semana 20+) + +### 7.1 Objetivo +Migrar serviços restantes e desligar o legado. + +### 7.2 Entregas + +| # | Entrega | Descrição | Semana | +|---|---------|-----------|--------| +| 3.1 | **WhatsApp Frappe App** | Reconstruir Baileys como app nativo | 20-24 | +| 3.2 | **Motor de Workflows** | Automações visuais (RPA) | 22-26 | +| 3.3 | **Scientist Frappe** | Migrar para Frappe Workers | 24-28 | +| 3.4 | **Validação de Paridade** | Testes A/B, métricas | 26-30 | +| 3.5 | **Decommission Express** | Desligar endpoints legados | 30+ | + +### 7.3 Resultado +- ✅ Sistema 100% unificado no Frappe +- ✅ Express/React desligado +- ✅ Uma única plataforma para manter + +--- + +## 8. MAPEAMENTO DE MÓDULOS + +| Módulo Atual | O que Acontece | Fase | +|--------------|----------------|------| +| **users, tenants** | Expande com hierarquia | 0 | +| **profiles, roles, permissions** | Migra para Frappe RBAC | 0 | +| **whatsapp_contacts, messages, tickets** | Mantém → Migra na Fase 3 | 3 | +| **pc_crm_leads, stages, opportunities** | Migra para Frappe DocTypes | 1 | +| **pc_clients, projects, tasks** | Migra para Frappe DocTypes | 1 | +| **graph_nodes, graph_edges** | Migra para Frappe Knowledge Graph | 1 | +| **internal_chat_*** | Evolui para Comunidades | 2 | +| **manus_*** | Integra via background jobs | 1 | +| **bi_*** | Mantém + novos widgets Cockpit | 2 | +| **ide_*** | Evolui para 3 modos | 2 | + +--- + +## 9. RISCOS E MITIGAÇÕES + +| Risco | Probabilidade | Impacto | Mitigação | +|-------|---------------|---------|-----------| +| **Drift de dados** | Média | Alto | CDC com validação contínua | +| **Performance chat** | Média | Médio | Load test antes de migrar | +| **Tokens WhatsApp** | Baixa | Alto | Vault de secrets | +| **Curva aprendizado Frappe** | Alta | Médio | Treinamento na Fase 0 | +| **Regressões funcionais** | Média | Alto | Testes A/B, telemetria | +| **Resistência usuários** | Média | Médio | Piloto gradual: Master → Partners → Clients | + +--- + +## 10. QUICK WINS (Entregas Rápidas) + +| Item | Tempo | Valor | +|------|-------|-------| +| **Hierarquia de Tenants** | 2 semanas | Estrutura para parceiros | +| **SSO unificado** | 2 semanas | Login único | +| **Central de APIs (UI)** | 3 semanas | Visibilidade integrações | +| **Dashboard Tríade** | 2 semanas | Consciência sobre tempo | +| **Planos e Features** | 2 semanas | Monetização estruturada | + +--- + +## 11. OS 5 PILARES DO SISTEMA + +### Pilar 1: Knowledge Graph +- Todos os dados do negócio conectados e pesquisáveis +- Navegação visual entre entidades relacionadas +- Base para IA contextual + +### Pilar 2: Central Intelligence (Scientist) +- IA que aprende com interações do sistema +- Gera e executa código automaticamente +- Detecta padrões e sugere otimizações + +### Pilar 3: Autonomous Agent (Manus) +- Executa tarefas multi-step de forma autônoma +- Acessa ferramentas e APIs +- Deep research com planejamento + +### Pilar 4: Unified Communication +- WhatsApp integrado com CRM +- Chat interno com canais por projeto +- Email (futuro) +- Todos os canais em um lugar + +### Pilar 5: Complete IDE +- 3 modos de desenvolvimento (No/Low/Pro Code) +- Central de Bibliotecas +- Deploy integrado + +--- + +## 12. DOCUMENTOS DE REFERÊNCIA + +Os documentos originais que basearam este plano estão em: +- `attached_assets/cocpti_docs/cocpti/` - Cockpit e DNA Notion +- `attached_assets/cocpti_docs/Ide Arcadia/` - Proposta IDE +- `attached_assets/cocpti_docs/Rota de desenvolviento/` - Roadmap original +- `attached_assets/cocpti_docs/Central de API/` - Central de APIs + +--- + +## 13. PRÓXIMOS PASSOS + +1. [ ] Implementar hierarquia de tenants no schema +2. [ ] Criar tabelas de planos e comissões +3. [ ] Documentar arquitetura CDC +4. [ ] Provisionar servidor Frappe +5. [ ] Implementar Central de APIs (UI com dados demo) +6. [ ] Construir Cockpit PARA + Tríade + +--- + +*Documento criado em Janeiro 2026* +*Última atualização: Janeiro 2026* diff --git a/PLANO_SOE_CENTRAL.md b/PLANO_SOE_CENTRAL.md new file mode 100644 index 0000000..921b731 --- /dev/null +++ b/PLANO_SOE_CENTRAL.md @@ -0,0 +1,733 @@ +# PLANO SOE CENTRAL — Arcádia Suite +## Orquestração Inteligente: Plus + ERPNext invisíveis, Central visível +### Versão 1.0 — Março 2026 + +--- + +## 1. ONDE ESTAMOS (Orientação Geral) + +### O Projeto nasceu no Replit como… +- Uma plataforma de **escritório empresarial com IA central** (Manus Agent) +- Com proxy para o **Arcádia Plus** (Laravel/PHP, porta 8080) — ERP fiscal completo +- Com integração ao **ERPNext/Frappe** via API +- Stack principal: **React 18 + Express.js + PostgreSQL + FastAPI (Python)** + +### O que JÁ existe e funciona: +| Componente | Status | Onde vive | +|---|---|---| +| Manus Agent (IA, 30+ tools) | ✅ Funcionando | `server/manus/` | +| Arcádia Plus (Laravel ERP) | ✅ Funcionando | `plus/` → porta 8080 | +| SSO Plus ↔ Suite | ✅ Funcionando | `server/plus/` | +| Motor Fiscal (nfelib) | ✅ Funcionando | `server/python/` → porta 8002 | +| Motor Contábil | ✅ Funcionando | `server/python/` → porta 8003 | +| Motor BI | ✅ Funcionando | `server/python/` → porta 8004 | +| Motor Automação | ✅ Funcionando | `server/python/` → porta 8005 | +| Motor Comunicação (Comm) | ✅ Funcionando | porta 8006 | +| Dev Center XOS (6 agentes) | ✅ Funcionando | `server/blackboard/` | +| LiteLLM Gateway | ✅ Configurado | porta 4000 | +| CRM, WhatsApp, Chat | ✅ Funcionando | `server/crm/`, `server/whatsapp/` | +| ERPNext integração | ⚠️ Parcial | `server/erp/routes.ts` | + +### O que FALTA para o plano atual: +| Componente | Status | +|---|---| +| **SOE Central (Regras Unificadas)** | ❌ Não existe — este é o plano | +| Fiscal rules centralizadas (acima do Plus) | ❌ Dispersas no Plus | +| ERPNext rules centralizadas | ❌ Não existe camada de abstração | +| Contábil Avançado (lançamentos automáticos) | ❌ Motor existe, regras não | +| Financeiro Avançado (previsão, DRE automático) | ❌ Motor existe, regras não | +| Testes automatizados / CI-CD | ❌ | +| Monitoramento (APM, Sentry) | ❌ | + +--- + +## 2. O PROBLEMA QUE VAMOS RESOLVER + +### Situação Atual (problemática) +``` +Usuário → Arcádia Suite + ├── /plus → acessa Laravel diretamente (usuário VÊ o Plus) + ├── /erp → acessa ERPNext diretamente (usuário VÊ o ERPNext) + └── Regras fiscais ficam dentro do Plus + Regras contábeis ficam no Motor 8003 + Regras ERP ficam no ERPNext + → Fragmentado, sem governança central +``` + +### Situação Desejada (SOE Central) +``` +Usuário → Arcádia Suite (SOE) + │ + ▼ [Central de Regras SOE] + ├── Fiscal: regras unificadas (CFOP, NCM, tributação, NF-e, CT-e...) + ├── ERP: regras de negócio (pedidos, estoque, compras...) + ├── Contábil: regras de lançamentos, plano de contas, DRE... + └── Financeiro: regras de fluxo, provisões, conciliação... + │ + ▼ [Execução invisível] + ├── Plus → emite documentos, registra no banco + └── ERPNext → executa operações, registra no banco + + O usuário NUNCA VÊ o Plus nem o ERPNext. + Só vê a Central SOE do Arcádia. +``` + +--- + +## 3. ARQUITETURA SOE CENTRAL + +### 3.1 Diagrama Completo + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ ARCÁDIA SUITE (Frontend React) │ +│ /financeiro /contabil /fisco /erp /people /production /bi │ +│ Usuário nunca acessa /plus ou ERPNext diretamente │ +└───────────────────────────────┬─────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ SOE — SISTEMA OPERACIONAL EMPRESARIAL (Nova Camada) │ +│ Express.js / porta 5000 / server/soe/ │ +│ │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ CENTRAL FISCAL │ │ CENTRAL ERP │ │ +│ │ server/soe/fiscal/ │ │ server/soe/erp/ │ │ +│ │ │ │ │ │ +│ │ • Regras NCM/CFOP │ │ • Regras de pedidos │ │ +│ │ • Políticas tribut. │ │ • Regras de estoque │ │ +│ │ • Emissão NF-e/NFC-e │ │ • Regras de compras │ │ +│ │ • Cancelamento │ │ • Regras de pessoas │ │ +│ │ • SPED/SINTEGRA │ │ • Integrações ext. │ │ +│ └──────────┬───────────┘ └──────────┬─────────────┘ │ +│ │ │ │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ CENTRAL CONTÁBIL │ │ CENTRAL FINANCEIRO │ │ +│ │ server/soe/contabil/│ │ server/soe/financ/ │ │ +│ │ │ │ │ │ +│ │ • Plano de contas │ │ • Fluxo de caixa │ │ +│ │ • Regras de lanç. │ │ • Contas a P/R │ │ +│ │ • DRE automático │ │ • Conciliação │ │ +│ │ • Balancete │ │ • Previsão (IA) │ │ +│ │ • Fechamento │ │ • Impostos │ │ +│ └──────────┬───────────┘ └──────────┬─────────────┘ │ +│ │ │ │ +│ └────────────┬─────────────┘ │ +│ ▼ │ +│ ┌─────────────────────────────────┐ │ +│ │ SOE RULE ENGINE (Núcleo) │ │ +│ │ server/soe/rule-engine.ts │ │ +│ │ │ │ +│ │ • Resolução de conflitos │ │ +│ │ • Aplicação de políticas XOS │ │ +│ │ • Audit trail de todas regras │ │ +│ │ • Manus consulta este engine │ │ +│ └─────────────────┬───────────────┘ │ +└────────────────────────────┼────────────────────────────────────────────┘ + │ + ┌──────────────┼───────────────┐ + ▼ ▼ ▼ +┌─────────────────┐ ┌──────────────┐ ┌──────────────────┐ +│ ARCÁDIA PLUS │ │ ERPNEXT │ │ MOTORES PYTHON │ +│ Laravel :8080 │ │ Frappe : │ │ 8002 Fiscal │ +│ (invisível) │ │ (invisível) │ │ 8003 Contábil │ +│ │ │ │ │ 8004 BI │ +│ Emite docs │ │ Executa ERP │ │ 8005 Automação │ +│ fiscais │ │ operacional │ │ │ +└─────────────────┘ └──────────────┘ └──────────────────┘ +``` + +--- + +## 4. CENTRAL FISCAL — Detalhamento + +### 4.1 O que ela resolve +O Plus tem **376 controllers** e **1.546 rotas** — tudo fiscal/operacional. A Central Fiscal **não substitui** o Plus, ela **orquestra** o Plus com regras definidas no SOE. + +### 4.2 Regras que vão para a Central (tiradas do Plus) + +```typescript +// server/soe/fiscal/rules.ts — Exemplo de estrutura + +interface FiscalRule { + id: string + nome: string + trigger: 'pre_emissao' | 'pos_emissao' | 'cancelamento' | 'validacao' + condicao: FiscalCondition + acao: FiscalAction + prioridade: number + ativo: boolean +} + +// Exemplos de regras: +const REGRAS_FISCAIS: FiscalRule[] = [ + { + id: 'NFE_CFOP_INTERESTADUAL', + nome: 'Ajusta CFOP para operação interestadual', + trigger: 'pre_emissao', + condicao: { uf_emitente: '!=', uf_destinatario: true }, + acao: { ajustar_cfop: 'interestadual' }, + prioridade: 1, + ativo: true + }, + { + id: 'NFE_SIMPLES_NACIONAL', + nome: 'Aplica tributação Simples Nacional', + trigger: 'pre_emissao', + condicao: { regime_tributario: 'simples_nacional' }, + acao: { aplicar_cst: 'tabela_simples', remover_pis_cofins: true }, + prioridade: 2, + ativo: true + }, + { + id: 'NFE_VALIDACAO_NCM', + nome: 'Valida NCM obrigatório para NF-e', + trigger: 'validacao', + condicao: { tipo_documento: 'nfe' }, + acao: { validar_campo: 'ncm', obrigatorio: true }, + prioridade: 1, + ativo: true + } +] +``` + +### 4.3 Fluxo de Emissão via SOE Central + +``` +Usuário clica "Emitir NF-e" no Arcádia + │ + ▼ +POST /api/soe/fiscal/emitir-nfe + │ + ▼ +SOE Rule Engine: aplica REGRAS_FISCAIS (pre_emissao) + • Verifica regime tributário + • Aplica CFOP correto + • Calcula impostos (ICMS, PIS, COFINS, IPI) + • Valida NCM obrigatório + • Adiciona dados da empresa emitente + │ + ▼ +SOE envia para Plus via API interna (invisível) + POST http://plus:8080/api/nfe/emitir + + token SSO automático + │ + ▼ +Plus emite via Cloud-DFE → SEFAZ + │ + ▼ +SOE recebe retorno + • Registra no banco SOE (tabela soe_fiscal_eventos) + • Dispara lançamento contábil automático + • Notifica via WebSocket o frontend + │ + ▼ +Usuário vê resultado no Arcádia (nunca soube do Plus) +``` + +### 4.4 Tabelas SOE para Fiscal + +```sql +-- Tabelas a criar no schema Arcádia (PostgreSQL) + +CREATE TABLE soe_fiscal_regras ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + nome VARCHAR(200) NOT NULL, + trigger VARCHAR(50) NOT NULL, + condicao JSONB NOT NULL, + acao JSONB NOT NULL, + prioridade INTEGER DEFAULT 10, + ativo BOOLEAN DEFAULT true, + created_at TIMESTAMP DEFAULT NOW() +); + +CREATE TABLE soe_fiscal_eventos ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tipo VARCHAR(50) NOT NULL, -- 'emissao_nfe', 'cancelamento', etc. + empresa_id INTEGER NOT NULL, + documento_chave VARCHAR(100), + regras_aplicadas JSONB, -- quais regras foram aplicadas + payload_enviado JSONB, -- o que foi enviado ao Plus + payload_retorno JSONB, -- o que o Plus/SEFAZ respondeu + status VARCHAR(50) NOT NULL, + created_at TIMESTAMP DEFAULT NOW() +); + +CREATE TABLE soe_fiscal_configuracoes ( + empresa_id INTEGER PRIMARY KEY, + regime_tributario VARCHAR(50), -- simples, lucro_presumido, lucro_real + uf VARCHAR(2), + cnpj VARCHAR(18), + certificado_tipo VARCHAR(20), + aliquotas JSONB, -- alíquotas padrão por operação + cfops_padrao JSONB, -- CFOPs padrão por tipo de operação + created_at TIMESTAMP DEFAULT NOW() +); +``` + +--- + +## 5. CENTRAL ERP (ERPNext/Frappe) — Detalhamento + +### 5.1 O que ela resolve +O ERPNext tem **APIs complexas**. A Central ERP abstrai tudo isso em operações simples que o Arcádia entende. + +### 5.2 Adapter Layer ERPNext + +```typescript +// server/soe/erp/frappe-adapter.ts + +interface ERPAdapter { + // Produtos + criarProduto(data: ProdutoSOE): Promise + buscarProduto(codigo: string): Promise + atualizarEstoque(movimentacao: MovimentacaoEstoque): Promise + + // Pedidos + criarPedidoVenda(pedido: PedidoSOE): Promise + aprovarPedido(id: string): Promise + faturarPedido(id: string): Promise + + // Financeiro + criarLancamento(lancamento: LancamentoSOE): Promise + buscarPlanoContas(): Promise + + // Compras + criarPedidoCompra(data: PedidoCompraSOE): Promise + receberMercadoria(data: RecebimentoSOE): Promise +} + +// As regras ficam no SOE, o adapter só traduz +class FrappeAdapter implements ERPAdapter { + private baseUrl: string + private apiKey: string + + async criarPedidoVenda(pedido: PedidoSOE): Promise { + // Traduz do modelo SOE para o modelo Frappe + const frappePedido = this.traduzirParaFrappe(pedido) + + // Envia para ERPNext (invisível para o usuário) + const response = await fetch(`${this.baseUrl}/api/resource/Sales Order`, { + method: 'POST', + headers: { 'Authorization': `token ${this.apiKey}` }, + body: JSON.stringify(frappePedido) + }) + + // Traduz retorno de volta para modelo SOE + return this.traduzirDeVoltaSOE(await response.json()) + } +} +``` + +### 5.3 Regras de Negócio ERP no SOE + +```typescript +// server/soe/erp/rules.ts + +const REGRAS_ERP = [ + { + id: 'PEDIDO_APROVACAO_AUTOMATICA', + nome: 'Aprovação automática até R$ 5.000', + trigger: 'pre_aprovacao_pedido', + condicao: { valor_total: { menor_que: 5000 } }, + acao: { aprovar_automaticamente: true } + }, + { + id: 'ESTOQUE_RESERVA_VENDA', + nome: 'Reservar estoque ao confirmar venda', + trigger: 'pos_confirmacao_venda', + condicao: { status: 'confirmado' }, + acao: { reservar_estoque: true, gerar_separacao: true } + }, + { + id: 'NF_AUTOMATICA_FATURAMENTO', + nome: 'Emite NF-e automaticamente ao faturar', + trigger: 'pos_faturamento', + condicao: { tipo_cliente: ['pj', 'pf_contribuinte'] }, + acao: { emitir_nfe: true, via_soe_fiscal: true } + } +] +``` + +--- + +## 6. CENTRAL CONTÁBIL AVANÇADA + +### 6.1 Motor Atual (porta 8003) + Regras SOE + +O Motor Contábil Python já faz DRE e Balancete. O que falta é **alimentação automática**. + +### 6.2 Lançamentos Automáticos (grande salto) + +```typescript +// server/soe/contabil/auto-lancamentos.ts + +interface RegrasLancamentoAuto { + gatilho: string + debito: string // Conta contábil + credito: string // Conta contábil + historico: string + formula: string // Como calcular o valor +} + +const LANCAMENTOS_AUTOMATICOS: RegrasLancamentoAuto[] = [ + // Quando emite NF-e de venda + { + gatilho: 'emissao_nfe_venda', + debito: '1.1.3.01', // Clientes + credito: '3.1.1.01', // Receita Bruta de Vendas + historico: 'Venda conforme NF-e {numero}', + formula: 'valor_total_nota' + }, + { + gatilho: 'emissao_nfe_venda', + debito: '3.1.2.01', // Dedução de Receita (ICMS) + credito: '2.1.2.01', // ICMS a Recolher + historico: 'ICMS s/ Venda NF-e {numero}', + formula: 'valor_icms' + }, + // Quando paga conta + { + gatilho: 'pagamento_conta', + debito: '2.1.1.{categoria}', // Conta a Pagar específica + credito: '1.1.1.01', // Banco/Caixa + historico: 'Pagamento: {descricao}', + formula: 'valor_pago' + }, + // Quando recebe pagamento + { + gatilho: 'recebimento', + debito: '1.1.1.01', // Banco/Caixa + credito: '1.1.3.01', // Clientes + historico: 'Recebimento: {descricao}', + formula: 'valor_recebido' + }, + // Compra de mercadoria + { + gatilho: 'entrada_nfe_compra', + debito: '1.1.4.01', // Estoque + credito: '2.1.1.01', // Fornecedores + historico: 'Compra conforme NF-e {numero} / {fornecedor}', + formula: 'valor_mercadorias' + } +] +``` + +### 6.3 DRE Automático via SOE + +``` +Usuário pede DRE do mês + │ + ▼ +SOE Contábil consulta: + 1. Todos lançamentos do período (tabela soe_lancamentos) + 2. Agrupa por conta contábil + 3. Aplica estrutura DRE configurada + 4. Envia para Motor Python 8003 para cálculos + 5. Retorna DRE formatado + │ + ▼ +Usuário vê DRE no /contabil do Arcádia +(Nunca soube que teve lançamentos automáticos de NF-e, pagamentos, etc.) +``` + +--- + +## 7. CENTRAL FINANCEIRO AVANÇADO + +### 7.1 Regras Financeiras no SOE + +```typescript +// server/soe/financeiro/rules.ts + +const REGRAS_FINANCEIRO = [ + { + id: 'BOLETO_AUTO_VENCIMENTO', + nome: 'Gerar boleto automático para vendas a prazo', + trigger: 'pos_confirmacao_venda_prazo', + acao: { gerar_boleto: true, via: 'asaas', vencimento: '+{prazo}_dias' } + }, + { + id: 'ALERTA_VENCIMENTO_3DIAS', + nome: 'Alerta de vencimento 3 dias antes', + trigger: 'cron_diario', + condicao: { vencimento_em: 3 }, + acao: { notificar: ['whatsapp', 'email'], via_manus: true } + }, + { + id: 'PROVISAO_IMPOSTOS', + nome: 'Provisão mensal de impostos', + trigger: 'cron_mensal', + acao: { calcular_provisao: ['icms', 'pis', 'cofins', 'csll', 'irpj'], registrar_lancamento: true } + }, + { + id: 'CONCILIACAO_AUTO', + nome: 'Conciliação bancária automática via OFX', + trigger: 'importacao_ofx', + acao: { tentar_conciliar: true, confianca_minima: 0.85, pendentes_para_revisao: true } + } +] +``` + +--- + +## 8. MANUS AGENT + SOE CENTRAL + +### 8.1 O Manus consulta a Central + +``` +Pergunta: "Qual foi o resultado do mês passado?" + │ + ▼ +Manus → SOE Central + • GET /api/soe/contabil/dre?periodo=2026-02 + • GET /api/soe/financeiro/fluxo?periodo=2026-02 + • GET /api/soe/fiscal/resumo?periodo=2026-02 + │ + ▼ +SOE agrega dados dos motores (Python) + Plus + ERPNext + │ + ▼ +Manus recebe contexto completo e responde: + "Faturamento: R$ 120.000 + Deduções (impostos): R$ 18.000 + Receita Líquida: R$ 102.000 + Custo das mercadorias: R$ 65.000 + Lucro Bruto: R$ 37.000 + ..." +``` + +### 8.2 Tools do Manus para o SOE + +```typescript +// Novas tools do Manus que consultam o SOE Central + +{ + name: 'consultar_situacao_fiscal', + description: 'Consulta situação fiscal da empresa (NFs pendentes, impostos, SPED)', + endpoint: 'GET /api/soe/fiscal/situacao' +}, +{ + name: 'emitir_documento_fiscal', + description: 'Emite NF-e, NFC-e, CT-e ou MDF-e', + endpoint: 'POST /api/soe/fiscal/emitir' +}, +{ + name: 'consultar_dre', + description: 'Gera DRE de qualquer período', + endpoint: 'GET /api/soe/contabil/dre' +}, +{ + name: 'consultar_fluxo_caixa', + description: 'Consulta fluxo de caixa e previsões', + endpoint: 'GET /api/soe/financeiro/fluxo' +}, +{ + name: 'registrar_lancamento_contabil', + description: 'Registra lançamento contábil manualmente', + endpoint: 'POST /api/soe/contabil/lancamento' +} +``` + +--- + +## 9. ESTRUTURA DE PASTAS A CRIAR + +``` +server/ +└── soe/ ← Nova pasta (Central SOE) + ├── index.ts ← Router principal do SOE + ├── rule-engine.ts ← Motor de regras central + │ + ├── fiscal/ + │ ├── routes.ts ← GET/POST /api/soe/fiscal/* + │ ├── rules.ts ← Regras fiscais (CFOP, NCM, tributação) + │ ├── emissao.ts ← Orquestração de emissão (→ Plus) + │ ├── plus-adapter.ts ← Adaptador para o Plus (invisível) + │ └── sefaz-adapter.ts ← Comunicação direta SEFAZ (via Python 8002) + │ + ├── erp/ + │ ├── routes.ts ← GET/POST /api/soe/erp/* + │ ├── rules.ts ← Regras de negócio ERP + │ ├── frappe-adapter.ts ← Adaptador ERPNext (invisível) + │ └── plus-erp-adapter.ts ← Adaptador Plus-ERP (para dados de venda) + │ + ├── contabil/ + │ ├── routes.ts ← GET/POST /api/soe/contabil/* + │ ├── rules.ts ← Regras contábeis + │ ├── auto-lancamentos.ts ← Lançamentos automáticos + │ ├── plano-contas.ts ← Plano de contas SOE + │ └── python-adapter.ts ← Adaptador Motor Python 8003 + │ + ├── financeiro/ + │ ├── routes.ts ← GET/POST /api/soe/financeiro/* + │ ├── rules.ts ← Regras financeiras + │ ├── previsao.ts ← Previsão com IA + │ └── conciliacao.ts ← Conciliação bancária + │ + └── shared/ + ├── types.ts ← Tipos SOE compartilhados + ├── audit.ts ← Registro de todas as operações + └── event-bus.ts ← Eventos entre Centrais +``` + +--- + +## 10. TABELAS DO BANCO A CRIAR (Drizzle ORM) + +```typescript +// shared/schema.ts — Adicionar: + +// Configuração da empresa no SOE +export const soeEmpresaConfig = pgTable('soe_empresa_config', { + id: serial('id').primaryKey(), + empresaId: integer('empresa_id').notNull(), + regimeTributario: varchar('regime_tributario', { length: 50 }), // simples, presumido, real + uf: varchar('uf', { length: 2 }), + cnpj: varchar('cnpj', { length: 18 }), + planoContasId: integer('plano_contas_id'), + configFiscal: jsonb('config_fiscal'), // alíquotas, CFOPs padrão + configErp: jsonb('config_erp'), // qual ERP: plus, erpnext, ambos + createdAt: timestamp('created_at').defaultNow(), +}) + +// Regras configuráveis (editáveis pelo usuário) +export const soeRegras = pgTable('soe_regras', { + id: uuid('id').primaryKey().defaultRandom(), + empresaId: integer('empresa_id'), // null = regra global + dominio: varchar('dominio', { length: 50 }).notNull(), // 'fiscal', 'erp', 'contabil', 'financeiro' + nome: varchar('nome', { length: 200 }).notNull(), + trigger: varchar('trigger', { length: 100 }).notNull(), + condicao: jsonb('condicao').notNull(), + acao: jsonb('acao').notNull(), + prioridade: integer('prioridade').default(10), + ativo: boolean('ativo').default(true), + createdAt: timestamp('created_at').defaultNow(), +}) + +// Log de todas as operações SOE (audit trail) +export const soeEventos = pgTable('soe_eventos', { + id: uuid('id').primaryKey().defaultRandom(), + empresaId: integer('empresa_id').notNull(), + dominio: varchar('dominio', { length: 50 }).notNull(), + tipo: varchar('tipo', { length: 100 }).notNull(), + regraIds: jsonb('regra_ids'), // regras aplicadas + payloadEntrada: jsonb('payload_entrada'), + payloadSaida: jsonb('payload_saida'), + erp: varchar('erp', { length: 50 }), // 'plus', 'erpnext', 'python_8003', etc. + status: varchar('status', { length: 50 }).notNull(), + duracao: integer('duracao'), // ms + createdAt: timestamp('created_at').defaultNow(), +}) + +// Lançamentos contábeis centralizados +export const soeLancamentos = pgTable('soe_lancamentos', { + id: uuid('id').primaryKey().defaultRandom(), + empresaId: integer('empresa_id').notNull(), + data: date('data').notNull(), + contaDebito: varchar('conta_debito', { length: 30 }).notNull(), + contaCredito: varchar('conta_credito', { length: 30 }).notNull(), + valor: numeric('valor', { precision: 15, scale: 2 }).notNull(), + historico: text('historico').notNull(), + origem: varchar('origem', { length: 100 }), // 'emissao_nfe', 'pagamento', etc. + origemId: varchar('origem_id', { length: 100 }), + period: varchar('period', { length: 7 }), // '2026-03' + createdAt: timestamp('created_at').defaultNow(), +}) +``` + +--- + +## 11. ROADMAP DE IMPLEMENTAÇÃO + +### Fase 1 — Fundação (2–3 semanas) +``` +[ ] 1. Criar server/soe/ com estrutura básica +[ ] 2. Criar tabelas: soe_empresa_config, soe_regras, soe_eventos, soe_lancamentos +[ ] 3. Implementar Plus Adapter (encapsula chamadas ao Laravel) +[ ] 4. Implementar Frappe Adapter (encapsula chamadas ao ERPNext) +[ ] 5. Endpoint GET /api/soe/status (health check de todos os motores) +[ ] 6. Migrar /api/fisco/* para passar pelo SOE +``` + +### Fase 2 — Central Fiscal (2–3 semanas) +``` +[ ] 7. Implementar Rule Engine para fiscal +[ ] 8. Criar regras fiscais base (NCM, CFOP, tributação por regime) +[ ] 9. POST /api/soe/fiscal/emitir-nfe → Plus (invisível) +[ ] 10. POST /api/soe/fiscal/cancelar-nfe → Plus (invisível) +[ ] 11. GET /api/soe/fiscal/situacao → agrega Plus + Python 8002 +[ ] 12. Atualizar frontend /fisco para usar /api/soe/fiscal/* +``` + +### Fase 3 — Central Contábil (2 semanas) +``` +[ ] 13. Implementar auto-lancamentos para eventos fiscais +[ ] 14. Integrar Motor Python 8003 via SOE +[ ] 15. GET /api/soe/contabil/dre → resultado automático +[ ] 16. GET /api/soe/contabil/balancete → atualizado em tempo real +[ ] 17. Atualizar frontend /contabil para usar /api/soe/contabil/* +``` + +### Fase 4 — Central Financeiro (2 semanas) +``` +[ ] 18. Regras de boleto automático (via Asaas) +[ ] 19. Alertas de vencimento (via Manus/WhatsApp) +[ ] 20. Conciliação bancária semi-automática +[ ] 21. Previsão financeira com IA (Motor Python 8003 + Manus) +[ ] 22. Atualizar frontend /financeiro para usar /api/soe/financeiro/* +``` + +### Fase 5 — Manus + SOE (1 semana) +``` +[ ] 23. Registrar novas tools Manus apontando para SOE +[ ] 24. Manus usa SOE para responder perguntas de negócio +[ ] 25. Dashboard SOE: visão geral de todos os eventos +``` + +### Fase 6 — Central ERP (3 semanas) +``` +[ ] 26. Frappe Adapter completo (produtos, pedidos, estoque, compras) +[ ] 27. Regras de negócio ERP no SOE +[ ] 28. Sincronização bidirecional SOE ↔ ERPNext (via eventos) +[ ] 29. Atualizar /erp para usar /api/soe/erp/* +``` + +--- + +## 12. RESULTADO FINAL — O QUE O USUÁRIO EXPERIMENTA + +``` +Antes (fragmentado): + Usuário → /plus → vê Laravel diretamente + Usuário → /erp → vê ERPNext diretamente + Regras fiscais só no Plus + Contabilidade manual + Financeiro sem automação + +Depois (SOE Central): + Usuário → /fisco → emite NF-e, Plus executa invisível + Usuário → /contabil → vê DRE gerado automaticamente + Usuário → /financeiro → vê fluxo, previsões, alertas automáticos + Usuário → Manus → pergunta "qual meu resultado?" → resposta completa + + Plus e ERPNext: INVISÍVEIS, executando em background + Regras: CENTRALIZADAS no SOE, editáveis + Lançamentos: AUTOMÁTICOS baseados em eventos (NF-e, pagamentos, etc.) + Auditoria: TOTAL de todas as operações +``` + +--- + +## 13. PRINCÍPIO ORIENTADOR + +> **"O usuário não sabe o que está por trás. Ele só sabe que funciona."** +> +> O Arcádia Suite é o **Sistema Operacional** da empresa. +> O Plus e o ERPNext são **drivers de hardware** — poderosos, mas invisíveis. +> O SOE Central é o **kernel** que os orquestra com regras e inteligência. + +--- + +*PLANO_SOE_CENTRAL.md — Arcádia Suite v3.0* +*Gerado em: 2026-03-16* diff --git a/PLANO_SOE_CENTRAL_v2.md b/PLANO_SOE_CENTRAL_v2.md new file mode 100644 index 0000000..f5f9d40 --- /dev/null +++ b/PLANO_SOE_CENTRAL_v2.md @@ -0,0 +1,666 @@ +# PLANO SOE CENTRAL v2 — Análise Real + Evolução +## Baseado no MAPA_SOE_ARCADIA.md (Replit) + Auditoria do Código +### Versão 2.0 — Março 2026 + +--- + +## 1. DIAGNÓSTICO — O QUE JÁ EXISTE (e o plano v1 não sabia) + +O MAPA_SOE_ARCADIA.md do Replit revelou que **o SOE já é uma realidade arquitetural robusta**, não apenas um conceito. Antes de planejar qualquer coisa, é crítico entender o que já funciona. + +### 1.1 O que já está construído e funcionando + +| Componente | Status | Localização | +|---|---|---| +| `SOE.tsx` | ✅ 2.414 linhas — UI completa com 9 tabs | `client/src/pages/SOE.tsx` | +| `SoeMotorContext.tsx` | ✅ Seletor de motor (plus/erpnext) | `client/src/contexts/` | +| `ErpApiClient` (interface) | ✅ Interface unificada definida | `server/erp/index.ts` | +| `ArcadiaPlusClient` | ✅ Adaptador HTTP → Plus:8080 | `server/erp/index.ts` | +| `ArcadiaNextClient` | ✅ Adaptador HTTP → ERPNext API | `server/erp/index.ts` | +| `registerSoeRoutes()` | ✅ 60+ endpoints em /api/soe/* | `server/erp/routes.ts` | +| `server/plus/proxy.ts` | ✅ Proxy reverso para Plus | `server/plus/` | +| `server/plus/sso.ts` | ✅ SSO automático Plus ↔ Suite | `server/plus/` | +| `server/plus/launcher.ts` | ✅ Lança PHP artisan serve | `server/plus/` | +| Módulo de Pessoas unificado | ✅ `persons` + `person_roles` | Schema PostgreSQL | +| Módulo de Produtos | ✅ Com NCM, CST, CFOP, IMEI | Schema PostgreSQL | +| Módulo Financeiro | ✅ Contas a P/R + transações | Schema PostgreSQL | +| Motor Fisco (:8002) | ✅ NF-e/NFC-e via nfelib | `server/python/` | +| Motor Contábil (:8003) | ✅ DRE, Balanço, SPED | `server/python/` | +| Sistema de módulos por tenant | ✅ `tenants.features` (JSONB) | Schema PostgreSQL | +| Middleware de gating | ✅ `requireModule()` | `server/` | + +### 1.2 Bancos de Dados por Motor (detalhe crítico) + +``` +Arcádia Suite → PostgreSQL 16 (dados do SOE, pessoas, produtos, vendas...) +Arcádia Plus → MySQL 8.0 (dados do Laravel — vendas, estoque, NF-e...) +ERPNext → MariaDB (dados do Frappe — CRM, HR, projetos...) +Motor Fisco → sem banco (só processa, retorna resultado) +Motor Contábil → sem banco (só processa, retorna resultado) +``` + +**Implicação:** Não há sincronização automática entre esses bancos. Um pedido criado no SOE (PostgreSQL) não aparece no Plus (MySQL) automaticamente — e vice-versa. + +### 1.3 O padrão motor/adaptador atual + +``` +Request do usuário + │ + ▼ +/api/soe/sales-orders (POST) + │ + ▼ +Verifica motor ativo (localStorage: arcadia_soe_motor) + │ + ├── motor = "local" → INSERT direto no PostgreSQL + ├── motor = "plus" → POST → Plus:8080 → MySQL + └── motor = "erpnext" → POST → ERPNext API → MariaDB +``` + +--- + +## 2. O PROBLEMA REAL — Onde o SOE atual para + +O SOE atual é um **roteador inteligente**: recebe o request, decide para qual motor enviar, e despacha. Ele **não tem inteligência própria**. + +### 2.1 O que falta (lacuna real) + +``` +Situação atual: + +SOE.tsx → /api/soe/* ────────────────────────────► Plus/ERPNext + (sem regras, sem processamento) + Regras ficam DENTRO do Plus + Regras ficam DENTRO do ERPNext + +Situação desejada: + +SOE.tsx → /api/soe/* → [RULE ENGINE SOE] ──────► Plus/ERPNext + │ (só executa) + ├── Regras Fiscais + ├── Regras Contábeis + ├── Regras Financeiras + └── Regras de Negócio +``` + +### 2.2 Problemas concretos hoje + +| Problema | Impacto | +|---|---| +| Fiscal rules dentro do Plus | Se trocar de motor (Plus→ERPNext), perde todas as regras | +| Nenhum lançamento contábil automático | DRE fica vazio, contabilidade manual | +| Motor Contábil (:8003) existe mas nada alimenta ele | 0 lançamentos automáticos | +| Plus tem UI própria (/plus) | Usuário pode bypassar o SOE e ir direto ao Plus | +| Sem event bus entre motores | Uma NF-e emitida no Plus não dispara nada no SOE | +| 25 conectores ERP definidos, zero chamadas reais | Integração existe no papel, não funciona | + +### 2.3 O que o usuário vê hoje vs o que deveria ver + +``` +Hoje: + /soe → UI do SOE (tabs: dashboard, pessoas, produtos, vendas...) + /plus → UI do Plus (Laravel) — direto, sem passar pelo SOE + /erp → UI do ERP legado + (usuário VÊ o Plus se quiser) + +Desejado: + /soe → UI do SOE (mesma, mas com inteligência) + /plus → BLOQUEADO ou redirecionado para /soe + /erp → BLOQUEADO ou redirecionado para /soe + (Plus e ERPNext = invisíveis, executando em background) +``` + +--- + +## 3. ARQUITETURA EVOLUÍDA — SOE com Rule Engine + +### 3.1 O que muda (e o que fica igual) + +**NÃO MUDA:** +- `SOE.tsx` — a UI continua a mesma (só ganha funcionalidades) +- `SoeMotorContext.tsx` — seleção de motor continua existindo +- `ArcadiaPlusClient` / `ArcadiaNextClient` — adaptadores continuam +- Todas as rotas `/api/soe/*` — continuam funcionando +- Todos os bancos — PostgreSQL, MySQL, MariaDB — continuam separados + +**MUDA / ADICIONA:** +- Uma **camada de Rule Engine** entre as rotas e os adaptadores +- **Event Bus SOE** que dispara lançamentos contábeis automaticamente +- **Ocultação do Plus** — `/plus` passa a ser controlado pelo SOE +- **Regras fiscais** saem do Plus e entram no SOE + +### 3.2 Diagrama completo com Rule Engine + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ ARCÁDIA SUITE — CAMADA DE APRESENTAÇÃO │ +│ │ +│ SOE.tsx (2.414+ linhas) │ +│ Tabs: Dashboard | Pessoas | Produtos | Vendas | Compras │ +│ Financeiro | CRM | Sincronização | Config │ +│ │ +│ SoeMotorContext.tsx → motor = "plus" | "erpnext" | "local" │ +└───────────────────────────────┬─────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ /api/soe/* — CAMADA DE API (já existe) │ +│ registerSoeRoutes() em server/erp/routes.ts │ +│ requireAuth + requireModule middleware │ +└───────────────────────────────┬─────────────────────────────────────┘ + │ + ▼ ◄── INSERIR AQUI (novo) +┌─────────────────────────────────────────────────────────────────────┐ +│ SOE RULE ENGINE (NOVO) │ +│ server/soe/rule-engine/ │ +│ │ +│ Antes de despachar para o motor, o Rule Engine: │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 1. FISCAL RULES (server/soe/rule-engine/fiscal.ts) │ │ +│ │ • Resolve CFOP correto (intra/interestadual) │ │ +│ │ • Aplica tributação por regime (Simples/Presumido/Real) │ │ +│ │ • Valida NCM obrigatório │ │ +│ │ • Define CST/CSOSN automático │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 2. BUSINESS RULES (server/soe/rule-engine/business.ts) │ │ +│ │ • Aprovação automática de pedidos < R$ X │ │ +│ │ • Reserva de estoque ao confirmar venda │ │ +│ │ • Trigger de NF-e ao faturar pedido │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 3. ACCOUNTING RULES (server/soe/rule-engine/accounting.ts) │ │ +│ │ • Emitiu NF-e → lançamento automático D: Clientes │ │ +│ │ C: Receita │ │ +│ │ • Pagou conta → lançamento automático D: Fornecedor │ │ +│ │ C: Banco │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +└───────────────────────────────┬─────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ DESPACHADOR DE MOTOR (já existe, aprimorado) │ +│ createErpClient(connection) em server/erp/index.ts │ +│ │ +│ motor = "local" → INSERT PostgreSQL │ +│ motor = "plus" → ArcadiaPlusClient → Plus:8080 → MySQL │ +│ motor = "erpnext" → ArcadiaNextClient → ERPNext API → MariaDB │ +└───────────────────────────────┬─────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ SOE EVENT BUS (NOVO) │ +│ server/soe/event-bus.ts │ +│ │ +│ Depois que o motor executa, o Event Bus dispara: │ +│ │ +│ evento: "nfe_emitida" → Motor Contábil (lançamento auto) │ +│ evento: "venda_confirmada" → Reserva estoque + alerta WhatsApp │ +│ evento: "pagamento_feito" → Baixa C/P + lançamento contábil │ +│ evento: "recebimento" → Baixa C/R + lançamento contábil │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 4. O QUE CONSTRUIR — Detalhamento por Módulo + +### 4.1 SOE Rule Engine (PRIORIDADE MÁXIMA) + +**Localização:** `server/soe/rule-engine/` + +Este é o coração da evolução. É um middleware que intercepta as chamadas às rotas SOE **antes** de despachar para o motor. + +#### Como funciona na prática + +```typescript +// server/erp/routes.ts — modificação cirúrgica + +// ANTES (atual): +app.post("/api/soe/sales-orders", requireAuth, async (req, res) => { + const client = getActiveClient(req) // pega Plus ou ERPNext + const result = await client.createSalesOrder(req.body) // despacha direto + res.json(result) +}) + +// DEPOIS (com Rule Engine): +app.post("/api/soe/sales-orders", requireAuth, async (req, res) => { + // 1. Aplica regras ANTES de despachar + const enriched = await ruleEngine.apply('pre_sales_order', req.body, req.user) + + // 2. Despacha para o motor com dados enriquecidos + const client = getActiveClient(req) + const result = await client.createSalesOrder(enriched.payload) + + // 3. Dispara eventos DEPOIS da execução + await eventBus.emit('sales_order_created', { result, rules: enriched.appliedRules }) + + res.json(result) +}) +``` + +#### Estrutura do Rule Engine + +```typescript +// server/soe/rule-engine/index.ts + +interface SoeRule { + id: string + dominio: 'fiscal' | 'business' | 'accounting' | 'financial' + trigger: string // ex: 'pre_sales_order', 'post_nfe_emitida' + condicao: RuleCondition // quando esta regra se aplica + acao: RuleAction // o que ela faz ao payload + prioridade: number + ativo: boolean + empresaId?: number // null = regra global de todos os tenants +} + +class SoeRuleEngine { + async apply(trigger: string, payload: any, context: RuleContext): Promise { + // 1. Busca regras ativas para este trigger (do banco + defaults hardcoded) + const rules = await this.getActiveRules(trigger, context.tenantId) + + // 2. Filtra regras cuja condição se aplica ao payload + const applicable = rules.filter(r => this.avaliarCondicao(r.condicao, payload, context)) + + // 3. Aplica cada regra em ordem de prioridade + let enriched = { ...payload } + const applied: string[] = [] + for (const rule of applicable.sort((a, b) => a.prioridade - b.prioridade)) { + enriched = await this.aplicarAcao(rule.acao, enriched, context) + applied.push(rule.id) + } + + return { payload: enriched, appliedRules: applied } + } +} +``` + +### 4.2 Regras Fiscais no SOE + +Estas regras **hoje vivem dentro do Plus** (Laravel controllers). A ideia é trazê-las para o SOE. + +**Nota importante:** Não é mover o código PHP para TypeScript. É criar regras **declarativas** no SOE que enriquecem o payload **antes** de enviar ao Plus. O Plus ainda processa e emite — mas recebe o payload já correto. + +```typescript +// server/soe/rule-engine/fiscal-rules.ts + +export const FISCAL_RULES_PADRAO: SoeRule[] = [ + + // CFOP — resolve automaticamente por operação + { + id: 'CFOP_VENDA_DENTRO_ESTADO', + dominio: 'fiscal', + trigger: 'pre_sales_order', + condicao: { uf_emitente: '==', uf_destinatario: true, tipo_op: 'venda_produto' }, + acao: { set: { 'items[*].cfop': '5.102' } }, + prioridade: 10, ativo: true + }, + { + id: 'CFOP_VENDA_OUTRO_ESTADO', + dominio: 'fiscal', + trigger: 'pre_sales_order', + condicao: { uf_emitente: '!=', uf_destinatario: true, tipo_op: 'venda_produto' }, + acao: { set: { 'items[*].cfop': '6.102' } }, + prioridade: 10, ativo: true + }, + + // Tributação por Regime + { + id: 'CST_SIMPLES_NACIONAL', + dominio: 'fiscal', + trigger: 'pre_nfe_emissao', + condicao: { regime_tributario: 'simples_nacional' }, + acao: { + set: { 'items[*].cst_icms': '400', 'items[*].pis': null, 'items[*].cofins': null }, + // No Simples Nacional: CSOSN 400 = tributado, sem destaque PIS/COFINS + }, + prioridade: 5, ativo: true + }, + { + id: 'CST_LUCRO_PRESUMIDO', + dominio: 'fiscal', + trigger: 'pre_nfe_emissao', + condicao: { regime_tributario: 'lucro_presumido' }, + acao: { set: { 'items[*].cst_pis': '01', 'items[*].cst_cofins': '01' } }, + prioridade: 5, ativo: true + }, + + // Validações obrigatórias + { + id: 'VALIDAR_NCM_NFE', + dominio: 'fiscal', + trigger: 'pre_nfe_emissao', + condicao: { tipo_documento: ['nfe', 'nfce'] }, + acao: { validar: { campo: 'items[*].ncm', obrigatorio: true, formato: /^\d{8}$/ } }, + prioridade: 1, ativo: true + }, +] +``` + +### 4.3 SOE Event Bus — Lançamentos Contábeis Automáticos + +Este é o **maior salto de valor**. Hoje o Motor Contábil (:8003) existe mas nada o alimenta automaticamente. + +```typescript +// server/soe/event-bus.ts + +type SoeEvent = + | 'nfe_emitida' + | 'nfe_cancelada' + | 'venda_confirmada' + | 'compra_recebida' + | 'pagamento_realizado' + | 'recebimento_realizado' + | 'boleto_gerado' + +interface SoeEventPayload { + empresaId: number + tenantId: number + evento: SoeEvent + dados: Record + motorOrigem: 'plus' | 'erpnext' | 'local' +} + +class SoeEventBus { + async emit(evento: SoeEvent, payload: SoeEventPayload) { + // Registra no banco (audit trail) + await db.insert(soeEventos).values({ ...payload, createdAt: new Date() }) + + // Dispara handlers + await Promise.allSettled( + this.getHandlers(evento).map(h => h(payload)) + ) + } + + // Handlers por evento + private handlers: Record = { + 'nfe_emitida': [ + contabilHandler.lancamentoVenda, // D: Clientes / C: Receita Bruta + contabilHandler.lancamentoImpostos, // D: Impostos / C: ICMS/PIS/COFINS a Recolher + financialHandler.gerarRecebivel, // Cria C/R automaticamente + ], + 'pagamento_realizado': [ + contabilHandler.lancamentoPagamento, // D: Fornecedores / C: Banco + financialHandler.baixarContaPagar, // Baixa C/P + ], + 'recebimento_realizado': [ + contabilHandler.lancamentoRecebimento, // D: Banco / C: Clientes + financialHandler.baixarContaReceber, // Baixa C/R + ], + 'compra_recebida': [ + contabilHandler.lancamentoCompra, // D: Estoque / C: Fornecedores + ], + } +} +``` + +#### Lançamentos automáticos para cada evento + +``` +NF-e emitida (venda): + D: 1.1.3.01 — Clientes (valor total da nota) + C: 3.1.1.01 — Receita Bruta de Vendas + + D: 3.1.2.01 — Deduções (ICMS) + C: 2.1.2.01 — ICMS a Recolher + + D: 3.1.2.02 — Deduções (PIS) + C: 2.1.2.02 — PIS a Recolher + + D: 3.1.2.03 — Deduções (COFINS) + C: 2.1.2.03 — COFINS a Recolher + +Pagamento de fornecedor: + D: 2.1.1.{categoria} — Fornecedores + C: 1.1.1.01 — Banco (conta configurada) + +Recebimento de cliente: + D: 1.1.1.01 — Banco + C: 1.1.3.01 — Clientes + +Compra recebida (NF-e entrada): + D: 1.1.4.01 — Estoque / Mercadorias + C: 2.1.1.01 — Fornecedores +``` + +### 4.4 Ocultação do Plus e ERPNext + +O Plus tem página própria em `/plus` (client/src/pages/Plus.tsx). O usuário pode acessá-la diretamente. Precisamos de 3 mudanças: + +#### a) Redirecionar `/plus` para `/soe` + +```typescript +// client/src/App.tsx — modificação simples +// Trocar: +// Por: } /> +``` + +**Mas manter o proxy reverso Plus ativo** — o Plus continua funcionando em background, só não fica visível como página separada. + +#### b) Ocultar o seletor de motor do usuário final + +```typescript +// client/src/contexts/SoeMotorContext.tsx +// O seletor fica SOMENTE na tab Config do SOE, e somente para admins + +// A tab Config na SOE.tsx — adicionar role check: +{user?.role === 'admin' && Config} +``` + +#### c) Na tab Config (admin), o label muda + +``` +Antes: "Selecione o motor: Plus | ERPNext" +Depois: "Motor de execução: Plus | ERPNext | Local" +(invisível para usuário final, só admin de tenant vê) +``` + +--- + +## 5. TABELAS A CRIAR (complemento ao schema existente) + +As tabelas canônicas do SOE já existem. Precisamos adicionar apenas as tabelas do Rule Engine. + +```typescript +// shared/schema.ts — adicionar ao final + +// Regras do SOE — configuráveis por tenant +export const soeRegras = pgTable('soe_regras', { + id: uuid('id').primaryKey().defaultRandom(), + tenantId: integer('tenant_id'), // null = regra global (todas as empresas) + empresaId: integer('empresa_id'), // null = todas as empresas do tenant + dominio: varchar('dominio', { length: 50 }).notNull(), + trigger: varchar('trigger', { length: 100 }).notNull(), + nome: varchar('nome', { length: 200 }).notNull(), + condicao: jsonb('condicao').notNull(), + acao: jsonb('acao').notNull(), + prioridade: integer('prioridade').default(10), + ativo: boolean('ativo').default(true), + origemPadrao: boolean('origem_padrao').default(false), // true = regra default do sistema + createdAt: timestamp('created_at').defaultNow(), + updatedAt: timestamp('updated_at').defaultNow(), +}) + +// Log de todos os eventos SOE (audit trail completo) +export const soeEventos = pgTable('soe_eventos', { + id: uuid('id').primaryKey().defaultRandom(), + tenantId: integer('tenant_id').notNull(), + empresaId: integer('empresa_id'), + evento: varchar('evento', { length: 100 }).notNull(), + motorOrigem: varchar('motor_origem', { length: 50 }), // 'plus', 'erpnext', 'local' + regraIds: jsonb('regra_ids'), // regras aplicadas + payloadEntrada: jsonb('payload_entrada'), + payloadSaida: jsonb('payload_saida'), + status: varchar('status', { length: 50 }).notNull(), + duracaoMs: integer('duracao_ms'), + erro: text('erro'), + createdAt: timestamp('created_at').defaultNow(), +}) + +// Lançamentos contábeis automáticos do SOE +export const soeLancamentos = pgTable('soe_lancamentos', { + id: uuid('id').primaryKey().defaultRandom(), + tenantId: integer('tenant_id').notNull(), + empresaId: integer('empresa_id').notNull(), + data: date('data').notNull(), + contaDebito: varchar('conta_debito', { length: 30 }).notNull(), + contaCredito: varchar('conta_credito', { length: 30 }).notNull(), + valor: numeric('valor', { precision: 15, scale: 2 }).notNull(), + historico: text('historico').notNull(), + origemEvento: varchar('origem_evento', { length: 100 }), // 'nfe_emitida', etc. + origemEventoId: uuid('origem_evento_id'), // FK para soe_eventos + periodo: varchar('periodo', { length: 7 }), // '2026-03' + enviado8003: boolean('enviado_8003').default(false), // sincronizado com Motor Contábil + createdAt: timestamp('created_at').defaultNow(), +}) +``` + +--- + +## 6. ESTRUTURA DE PASTAS (Novo código a criar) + +``` +server/ +└── soe/ ← NOVA PASTA + ├── rule-engine/ + │ ├── index.ts ← SoeRuleEngine class + │ ├── fiscal-rules.ts ← Regras fiscais padrão + │ ├── business-rules.ts ← Regras de negócio + │ └── accounting-rules.ts ← Regras de lançamento contábil + │ + ├── event-bus.ts ← SoeEventBus class + │ + ├── handlers/ + │ ├── contabil-handler.ts ← Lançamentos automáticos + │ └── financial-handler.ts ← Automação financeira + │ + └── fiscal/ + └── cfop-resolver.ts ← Resolução de CFOP (lógica complexa) +``` + +**Modificações em arquivos existentes:** +``` +server/erp/routes.ts ← Inserir ruleEngine.apply() antes do dispatch +client/src/App.tsx ← Redirecionar /plus para /soe +client/src/pages/SOE.tsx ← Ocultar Config tab para não-admins +``` + +--- + +## 7. ROADMAP — Fases de Implementação + +### Fase 1 — Rule Engine Básico (1 semana) +``` +[ ] Criar server/soe/rule-engine/index.ts (SoeRuleEngine) +[ ] Criar tabelas soe_regras e soe_eventos (drizzle push) +[ ] Inserir ruleEngine.apply() em 3 rotas críticas: + - POST /api/soe/sales-orders + - POST /api/soe/sales-orders/:id/generate-nfe + - POST /api/soe/purchase-orders +[ ] Seed das regras fiscais padrão (CFOP, CST, validações NCM) +[ ] Testar: criar pedido → verificar que payload está sendo enriquecido +``` + +### Fase 2 — Event Bus + Contabilidade Automática (1 semana) +``` +[ ] Criar server/soe/event-bus.ts +[ ] Criar tabela soe_lancamentos (drizzle push) +[ ] Criar handlers: contabil-handler.ts + financial-handler.ts +[ ] Conectar: POST generate-nfe → emit('nfe_emitida') → lançamentos +[ ] Conectar: pagamento/recebimento → emit() → lançamentos +[ ] Criar endpoint: GET /api/soe/contabil/lancamentos?periodo=YYYY-MM +[ ] DRE: agora tem dados reais (via soe_lancamentos → Motor :8003) +``` + +### Fase 3 — Ocultar Plus/ERPNext (3 dias) +``` +[ ] client/src/App.tsx: /plus → redirect para /soe +[ ] client/src/pages/SOE.tsx: Config tab só para admins +[ ] Manter proxy Plus funcionando (invisível) +[ ] Testar: fluxo completo sem nenhum acesso direto ao Plus UI +``` + +### Fase 4 — Regras Configuráveis pelo Usuário (1 semana) +``` +[ ] UI na tab Config do SOE: "Regras de Negócio" +[ ] CRUD de regras via /api/soe/rules +[ ] Admin pode criar regras custom sem código +[ ] Exemplo: "Pedidos acima de R$10.000 requerem aprovação manual" +``` + +### Fase 5 — Financeiro Avançado (2 semanas) +``` +[ ] Auto-boleto ao confirmar venda (Asaas API) +[ ] Alertas de vencimento (Manus → WhatsApp) +[ ] Conciliação bancária OFX semi-automática +[ ] Previsão financeira (Motor BI :8004 + histórico soe_lancamentos) +``` + +### Fase 6 — Contábil Avançado (2 semanas) +``` +[ ] DRE automático mensal (100% alimentado pelo Event Bus) +[ ] Balanço Patrimonial automático +[ ] Fechamento contábil mensal +[ ] SPED ECD/ECF alimentado por soe_lancamentos +[ ] Exportação para escritório contábil (OFX, Excel, PDF) +``` + +--- + +## 8. COMPARAÇÃO: PLANO v1 vs PLANO v2 + +| Aspecto | Plano v1 (antes do Replit .md) | Plano v2 (com conhecimento real) | +|---|---|---| +| Adaptadores Plus/ERPNext | "Precisam ser criados" | Já existem — não tocar | +| SOE Routes | "Precisam ser criadas" | 60+ endpoints já existem | +| SOE.tsx | "Precisa ser construída" | 2.414 linhas — já funciona | +| Onde adicionar código | server/soe/ do zero | Middleware nas rotas existentes | +| Esforço estimado | Alto (refatoração total) | Médio (adição cirúrgica) | +| Risco de quebrar | Alto | Baixo (adição, não substituição) | +| Banco Plus | Ignorado | MySQL — separado, nunca tocar direto | + +--- + +## 9. PRINCÍPIO ORIENTADOR (REVISADO) + +> O SOE já é o roteador certo. Agora vamos torná-lo o **árbitro de regras**. +> +> O padrão motor/adaptador está perfeito. O que falta é a **inteligência entre a rota e o adaptador**. +> +> Plus e ERPNext continuam existindo e funcionando — só que o usuário final não sabe. +> Ele só vê a Central SOE. O restante é infraestrutura. + +--- + +## 10. RESUMO EXECUTIVO — O que fazer agora + +**1 ação que entrega valor imediato:** +``` +Criar o SoeRuleEngine e plugar nas rotas de venda/NF-e. +Resultado: Ao emitir uma NF-e, o CFOP correto é calculado +automaticamente pelo SOE — sem o usuário saber que o Plus está +sendo chamado por baixo. +``` + +**1 ação que entrega valor a médio prazo:** +``` +Criar o Event Bus com o handler de contabilidade. +Resultado: Cada NF-e emitida gera lançamentos contábeis +automaticamente. O DRE do mês é gerado sem entrada manual de dados. +``` + +**1 ação que fecha o conceito:** +``` +Redirecionar /plus → /soe. +Resultado: O usuário não tem mais acesso ao Plus diretamente. +Ele só vê o Arcádia. O Plus é infraestrutura invisível. +``` + +--- + +*PLANO_SOE_CENTRAL_v2.md — Arcádia Suite v3.0* +*Gerado em: 2026-03-16 — Baseado na análise real do MAPA_SOE_ARCADIA.md (Replit)* diff --git a/RELATORIO_TECNICO_RETAIL.md b/RELATORIO_TECNICO_RETAIL.md new file mode 100644 index 0000000..2efa44a --- /dev/null +++ b/RELATORIO_TECNICO_RETAIL.md @@ -0,0 +1,1261 @@ +# Relatório Técnico Completo - Módulo Retail (Arcádia Suite) +## Versão 1.0 - Fevereiro 2026 + +--- + +## SUMÁRIO + +1. [Visão Geral do Módulo](#1-visão-geral) +2. [Banco de Dados - Schema Completo](#2-banco-de-dados) +3. [Dashboard - Painel Principal](#3-dashboard) +4. [PDV - Ponto de Venda](#4-pdv) +5. [Trade-In - Gestão de Troca](#5-trade-in) +6. [Checklist de Avaliação](#6-checklist) +7. [Ordens de Serviço](#7-ordens-de-serviço) +8. [Devoluções e Trocas](#8-devoluções-e-trocas) +9. [Estoque e Depósitos](#9-estoque-e-depósitos) +10. [Comissões e Metas](#10-comissões-e-metas) +11. [Relatórios](#11-relatórios) +12. [Cadastros](#12-cadastros) +13. [Compras e Aquisições](#13-compras-e-aquisições) +14. [Créditos de Cliente](#14-créditos-de-cliente) +15. [Integração com Plus (Laravel)](#15-integração-plus) +16. [API - Endpoints Completos](#16-api-endpoints) +17. [Segurança e Multi-Tenant](#17-segurança) + +--- + +## 1. VISÃO GERAL + +### 1.1 Propósito +O módulo **Arcádia Retail** é o **front-office** da Suite, projetado especificamente para o segmento de **Loja de Celulares e Assistência Técnica**. Ele cobre todo o ciclo operacional: venda de dispositivos, avaliação de trade-in, ordens de serviço, gestão de estoque por IMEI, comissões de vendedores, e fechamento de caixa diário. + +### 1.2 Métricas do Módulo + +| Métrica | Valor | +|---------|-------| +| **Frontend** | 10.067 linhas (ArcadiaRetail.tsx) | +| **Backend** | 5.218 linhas (routes.ts) | +| **Sync Plus** | 542 linhas (plus-sync.ts) | +| **TradeIn Form** | 988 linhas (TradeInForm.tsx) | +| **Total** | ~16.815 linhas de código | +| **Tabelas no banco** | 40+ tabelas | +| **Endpoints de API** | ~130 endpoints REST | +| **Abas da interface** | 11 abas principais | + +### 1.3 Abas da Interface + +| # | Aba | Descrição | +|---|-----|-----------| +| 1 | **Dashboard** | Visão geral com KPIs, feed de atividades e alertas | +| 2 | **PDV** | Ponto de Venda com carrinho, pagamento múltiplo e trade-in | +| 3 | **Pessoas** | Cadastro unificado (clientes, fornecedores, técnicos) | +| 4 | **Estoque** | Depósitos, saldos, movimentações, inventários e séries | +| 5 | **Serviços** | Ordens de Serviço (externas e internas) | +| 6 | **Trade-In** | Avaliações de dispositivos usados | +| 7 | **Compras** | Pedidos de compra e recebimento de mercadoria | +| 8 | **Cadastros** | Formas de pagamento, vendedores, planos, promoções, tipos | +| 9 | **Relatórios** | 6 relatórios operacionais + detalhamento de vendas | +| 10 | **Comissões** | Dashboard de comissões, metas e fechamento | +| 11 | **Configuração** | Integração Plus, empresas, sincronização | + +--- + +## 2. BANCO DE DADOS - SCHEMA COMPLETO + +### 2.1 Tabelas do Módulo Retail (40 tabelas) + +#### Estrutura de Lojas e Depósitos + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `retail_stores` | id, tenantId, code, name, storeType (holding/distributor/store), parentStoreId, cnpj, posEnabled, serviceEnabled, leaseEnabled | Lojas e filiais na rede | +| `retail_warehouses` | id, tenantId, storeId, code, name, type (store/central/transit/virtual), isMainWarehouse, isDefault, allowNegativeStock, visibleToAllCompanies | Depósitos por loja ou central | +| `retail_warehouse_stock` | warehouseId, productId, quantity, reservedQuantity, availableQuantity, minStock, maxStock | Saldos por produto/depósito | +| `retail_stock_movements` | warehouseId, productId, movementType (entry/exit/transfer/adjustment/return), operationType, quantity, previousStock, newStock, unitCost | Movimentações detalhadas | +| `retail_stock_transfers` | sourceWarehouseId, destinationWarehouseId, status (pending/in_transit/completed/cancelled) | Transferências entre depósitos | +| `retail_stock_transfer_items` | transferId, productId, requestedQuantity, transferredQuantity, receivedQuantity | Itens da transferência | +| `retail_transfer_serials` | transferItemId, serialId | Séries/IMEIs vinculados | +| `retail_product_serials` | productId, warehouseId, serialNumber, imei, imei2, status (in_stock/reserved/sold/returned/defective/in_transit), acquisitionCost, salePrice | Números de série e IMEI | +| `retail_inventories` | warehouseId, inventoryNumber, type (full/partial/cyclic), status (open/counting/adjusting/completed) | Inventários | +| `retail_inventory_items` | inventoryId, productId, systemQuantity, countedQuantity, difference, adjustmentApplied | Itens do inventário | + +#### Dispositivos Móveis + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `mobile_devices` | imei, imei2, brand, model, color, storage, ram, condition (new/refurbished/used), purchasePrice, sellingPrice, acquisitionType (trade_in/purchase/consignment), relatedEvaluationId, relatedServiceOrderId, personId, suggestedPrice, profitMargin, status (in_stock/sold/in_service/returned/damaged/leased) | Celulares com IMEI | +| `device_history` | deviceId, imei, eventType (received/transferred/sold/returned/service_in/service_out/leased/purchased), fromLocation, toLocation, referenceType, referenceId | Histórico de movimentação por IMEI | + +#### PDV e Vendas + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `pos_sessions` | storeId, cashierId, cashierName, openingBalance, closingBalance, totalSales, totalRefunds, netSales, cashPayments, cardPayments, pixPayments, otherPayments, transactionCount, status (open/closed/reconciled) | Sessões de caixa | +| `pos_sales` | saleNumber, saleType (direct_sale/lease_to_own), customerId, customerName, subtotal, discountAmount, discountPercent, tradeInValue, tradeInEvaluationId, totalAmount, paymentMethod (cash/debit/credit/pix/combined), paymentDetails (JSONB), soldBy, plusVendaId, plusSyncStatus, empresaId | Vendas no PDV | +| `pos_sale_items` | saleId, itemType (product/device/accessory/service), itemName, imei, deviceId, quantity, unitPrice, discountAmount, totalPrice | Itens da venda | +| `pos_cash_movements` | sessionId, storeId, type (withdrawal/reinforcement), amount, reason, performedBy, authorizedBy | Sangria e reforço de caixa | + +#### Pagamentos e Parcelamento + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `payment_plans` | saleId, customerId, totalAmount, downPayment, remainingAmount, numberOfInstallments, installmentAmount, interestRate, firstInstallmentDate, paidInstallments, status (active/completed/defaulted/cancelled) | Planos de parcelamento | +| `payment_plan_installments` | planId, installmentNumber, dueDate, amount, paidAmount, paidDate, paymentMethod, status (pending/paid/overdue/cancelled) | Parcelas do plano | + +#### Locação com Opção de Compra + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `lease_agreements` | agreementNumber, deviceId, imei, leaseStartDate, leaseEndDate, monthlyPayment, totalLeaseCost, purchaseOptionAvailable, purchasePrice, rentCreditPercent | Contratos de locação | +| `lease_payments` | leaseId, paymentNumber, dueDate, amount, paidAmount, status (pending/paid/overdue) | Pagamentos da locação | + +#### Trade-In e Avaliações + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `device_evaluations` | imei, brand, model, personId, 19 campos de checklist booleano (cada com campo de notas), batteryHealth, estimatedValue, acquisitionValue, status (pending/analyzing/approved/rejected), linkedServiceOrderId, maintenanceOrderId, creditGenerated, creditId | Avaliações de Trade-In | +| `trade_in_checklist_templates` | name, deviceCategory (smartphone/tablet/laptop/smartwatch), isActive | Templates de checklist customizáveis | +| `trade_in_checklist_items` | templateId, category (visual/funcional/acessorios/documentacao), itemName, evaluationType (condition/boolean/percentage/text), options (JSON), impactOnValue (% impacto), isRequired, displayOrder | Itens do template | +| `trade_in_evaluation_results` | evaluationId, checklistItemId, result, percentValue, notes | Resultados por item | +| `trade_in_transfer_documents` | evaluationId, documentNumber, customerName/CPF/RG/address, deviceBrand/Model/IMEI/IMEI2, agreedValue, customerSignature (Base64), termsAccepted, status (draft/pending_signature/signed/completed) | Documento de transferência de posse | +| `retail_acquisitions` | type (trade_in/purchase/consignment), sourceEvaluationId, sourceServiceOrderId, deviceId, acquisitionCost, repairCost, totalCost, suggestedPrice, finalPrice, status (pending/ready_for_stock/in_stock/sold) | Aquisições processadas | + +#### Ordens de Serviço + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `service_orders` | orderNumber, deviceId, imei, customerName, serviceType (repair/maintenance/internal_review/diagnostic), origin (customer_request/device_acquisition/warranty), assignedTo, technicianName, partsCost, laborCost, totalCost, isInternal, internalType (revision/cleaning/maintenance/quality_check/trade_in_diagnosis/trade_in_maintenance), sourceEvaluationId, checklistData (JSONB), status (12 estados) | Ordens de Serviço | +| `service_order_items` | serviceOrderId, productId, itemType (part/labor/accessory), itemName, quantity, unitPrice, totalPrice | Peças e serviços da O.S. | +| `service_warranties` | serviceOrderId, deviceId, imei, serviceType, warrantyDays, startDate, endDate, status (active/expired/claimed/voided) | Garantias vinculadas | + +#### Devoluções + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `return_exchanges` | returnNumber, originalSaleId, returnType (return/exchange), reason, refundAmount, refundMethod, status (pending/approved/rejected/processed) | Devoluções e trocas | +| `return_exchange_items` | returnId, itemName, imei, deviceId, reason, refundAmount | Itens devolvidos | + +#### Cadastros e Configurações + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `retail_payment_methods` | name, type (cash/debit/credit/pix/boleto/financing), brand (visa/mastercard/elo/amex/hipercard), feePercent, fixedFee, installmentsMax, installmentFees (JSONB), daysToReceive | Formas de pagamento | +| `retail_sellers` | personId, code, name, storeId, commissionPlanId, hireDate, isActive | Vendedores | +| `retail_commission_plans` | name, type (fixed/percent/tiered/per_product), baseValue, basePercent, rules (JSONB) | Planos de comissão | +| `retail_seller_goals` | sellerId, month, year, goalAmount, goalType (sales/units/margin), achievedAmount, achievedPercent, bonus | Metas de vendedor | +| `retail_store_goals` | storeId, month, year, goalAmount, achievedAmount, achievedPercent | Metas da loja | +| `retail_commission_closures` | sellerId, periodType (daily/monthly/custom), periodStart, periodEnd, totalSales, totalReturns, netSales, commissionRate, commissionAmount, bonusAmount, status (open/closed/paid) | Fechamento de comissão | +| `retail_commission_closure_items` | closureId, saleId, returnId, itemType (sale/return), amount, commission | Vendas do fechamento | +| `retail_price_tables` | name, customerType (retail/wholesale/vip/employee), discountPercent, markupPercent, validFrom, validTo | Tabelas de preço | +| `retail_price_table_items` | priceTableId, productId, deviceId, customPrice, discountPercent | Preços por produto | +| `retail_promotions` | name, type (percent_off/fixed_off/buy_x_get_y/bundle), discountValue, discountPercent, applyTo (all/category/product/brand), validFrom, validTo | Promoções | +| `retail_product_types` | name, category (device/accessory/part/service), requiresImei, requiresSerial, ncm, cest, origem, cstIcms, csosn, cfops (4 tipos), alíquotas (ICMS/PIS/COFINS/IPI), aliqIbs, aliqCbs | Tipos com atributos fiscais | +| `retail_activity_feed` | activityType, entityType, entityId, title, description, metadata (JSONB), severity (info/success/warning/error) | Feed de atividades | +| `retail_reports` | name, type (sales/inventory/commissions/financial/custom), query, filters (JSONB), columns (JSONB) | Relatórios customizáveis | + +#### Créditos + +| Tabela | Campos-chave | Descrição | +|--------|-------------|-----------| +| `customer_credits` | personId, customerName, amount, remainingAmount, origin (trade_in/return/manual/promotion), status (active/used/expired/cancelled), expiresAt | Créditos de cliente | + +--- + +## 3. DASHBOARD - PAINEL PRINCIPAL + +### 3.1 KPIs em Tempo Real (5 Cards) + +| Card | Fonte de Dados | Cálculo | +|------|---------------|---------| +| **Dispositivos em Estoque** | `mobile_devices` WHERE status = 'in_stock' | COUNT total | +| **Vendas Hoje** | `pos_sales` WHERE DATE(created_at) = hoje AND status = 'completed' | SUM(total_amount) + COUNT | +| **OS Abertas** | `service_orders` WHERE status NOT IN ('completed','cancelled') | COUNT | +| **Trade-In Pendentes** | `device_evaluations` WHERE status = 'pending' | COUNT | +| **Ticket Médio** | Derivado | todaySalesTotal / todaySalesCount | + +### 3.2 Componentes do Dashboard + +| Componente | Descrição | +|------------|-----------| +| **Últimas Ordens de Serviço** | Lista das 5 O.S. mais recentes com número, dispositivo, cliente, status e valor | +| **Avaliações de Trade-In** | Lista das 5 avaliações mais recentes com IMEI, dispositivo, cliente, condição, valor e status | +| **Produtos com Estoque Baixo** | Alertas de produtos com `stockQty < minStock`, exibidos com badge vermelho | +| **Feed de Atividades** | Timeline em tempo real (atualiza a cada 30s) com ícones por tipo (venda/serviço/avaliação), severidade colorida (info/success/warning/error), indicador de não-lido | + +### 3.3 Endpoint do Dashboard Stats + +``` +GET /api/retail/dashboard-stats +``` + +**Queries executadas:** +1. COUNT de dispositivos em estoque +2. SUM e COUNT de vendas do dia +3. COUNT de O.S. abertas +4. COUNT de avaliações pendentes + +--- + +## 4. PDV - PONTO DE VENDA + +### 4.1 Pré-requisitos para Usar o PDV + +1. **Sessão de Caixa ativa** (abertura obrigatória com saldo inicial) +2. **Empresa selecionada** (seletor de empresa na barra superior) +3. **Vendedor selecionado** (obrigatório para registrar vendas) + +### 4.2 Layout do PDV (Grid 5 Colunas) + +``` +┌─────────────────────────────────────────┬───────────────────────┐ +│ CATÁLOGO DE ITENS (3 colunas) │ CARRINHO (2 colunas)│ +│ │ │ +│ [Dispositivos] [Produtos] [Faturar OS]│ Lista de itens │ +│ │ Subtotal │ +│ Busca + Filtro │ - Desconto │ +│ Lista de itens disponíveis │ - Trade-In │ +│ com preço e botão "Adicionar" │ - Crédito │ +│ │ = TOTAL │ +│ │ │ +│ │ [Trade-In] │ +│ │ [FINALIZAR VENDA] │ +└─────────────────────────────────────────┴───────────────────────┘ +``` + +### 4.3 Três Abas de Catálogo + +#### 4.3.1 Dispositivos (Celulares) +- **Busca:** IMEI, marca, modelo, cor, armazenamento, preço +- **Filtro:** Somente status "in_stock" +- **Exibição:** Marca + Modelo, Storage | Cor | IMEI, Badge de condição (new/refurbished/used), Badge do depósito, Preço de venda +- **Ação:** Botão "Adicionar" (desabilitado se IMEI já está no carrinho) +- **Tipo no carrinho:** `device` com IMEI vinculado + +#### 4.3.2 Produtos (Acessórios, Peças) +- **Busca:** Nome, código, descrição, código de barras, NCM +- **Filtro:** Somente status "active" +- **Exibição:** Nome, Código | Categoria, Badge de estoque (quantidade + unidade), Preço de venda +- **Ação:** Botão "Adicionar" com quantidade editável +- **Tipo no carrinho:** `product` + +#### 4.3.3 Faturar O.S. (Ordens de Serviço) +- **Busca:** Número da O.S. ou nome do cliente +- **Filtro:** O.S. com status "ready_pickup" (aguardando faturamento) +- **Exibição:** Número da O.S., Cliente, Marca + Modelo, Descrição, Valor total +- **Ação:** Botão "Faturar" (vincula a O.S. à venda) +- **Tipo no carrinho:** `service` com serviceOrderId vinculado + +### 4.4 Carrinho de Compras + +| Campo | Descrição | +|-------|-----------| +| **Itens** | Lista com nome, descrição, badge de tipo (Celular/Serviço), preço unitário, botão remover | +| **Subtotal** | Soma de todos os itens | +| **Desconto** | Desconto em R$ ou % (configurável) | +| **Trade-In** | Valor de abatimento de avaliação aprovada | +| **Crédito** | Crédito disponível do cliente (trade-in anterior, devolução) | +| **Total** | Subtotal - Desconto - TradeIn - Crédito | + +### 4.5 Ações do PDV + +| Botão | Função | +|-------|--------| +| **Sangria** | Retirada de dinheiro do caixa (exige motivo) | +| **Reforço** | Adição de dinheiro ao caixa (exige motivo) | +| **Devolução** | Abre fluxo de devolução/troca | +| **Selecionar Cliente** | Busca/cadastro de pessoa unificada | +| **Limpar** | Remove todos os itens do carrinho | +| **Trade-In** | Inicia avaliação de dispositivo do cliente | +| **Finalizar Venda** | Abre modal de pagamento | + +### 4.6 Fluxo de Finalização de Venda + +``` +1. Usuário clica "Finalizar Venda" +2. Modal de pagamento abre com: + - Forma de pagamento padrão: Dinheiro (valor total) + - Opções: Cash, Débito, Crédito, PIX, Combinado + - Para Crédito: campo de parcelas + - Para Combinado: múltiplas linhas de pagamento + - Desconto: campo de % e R$ +3. Ao confirmar: + a. Cria registro em pos_sales + b. Cria registros em pos_sale_items + c. Atualiza status dos dispositivos para "sold" + d. Atualiza estoque dos produtos + e. Registra no activity_feed + f. Gera impressão da venda (PDF A4) + g. Sincroniza com Plus (se configurado) + h. Limpa o carrinho +``` + +### 4.7 Impressão da Venda (PDF A4) + +A impressão é chamada **ANTES** de limpar o carrinho para preservar os dados: +- Formato: A4 (595 x 842pt) +- Conteúdo: Número da venda, data/hora, dados da empresa, cliente, vendedor, lista de itens (produto, quantidade, unitário, total), subtotal, desconto, trade-in, total, forma de pagamento +- Dispositivos: exibe IMEI +- Produtos: exibe NCM (quando disponível) +- Geração: via `jspdf` no navegador + +### 4.8 Formas de Pagamento Suportadas + +| Método | Campos | +|--------|--------| +| **Dinheiro (cash)** | Valor | +| **Débito (debit)** | Valor | +| **Crédito (credit)** | Valor + Parcelas | +| **PIX (pix)** | Valor | +| **Combinado (combined)** | Múltiplas linhas (ex: R$ 500 PIX + R$ 300 Crédito 3x) | + +--- + +## 5. TRADE-IN - GESTÃO DE TROCA + +### 5.1 Fluxo Completo do Trade-In (4 Etapas) + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ ETAPA 1 │ │ ETAPA 2 │ │ ETAPA 3 │ │ ETAPA 4 │ +│ Avaliação │───>│ Aprovação │───>│ Revisão │───>│ Estoque │ +│ │ │ │ │ (O.S. Int.) │ │ │ +│ Checklist │ │ Gera crédito │ │ Manutenção │ │ Cria device │ +│ IMEI/Cliente │ │ Cria O.S. │ │ Checklist │ │ Preço suger. │ +│ Valor estim. │ │ Registro │ │ Peças/custos │ │ Disponível │ +│ │ │ IMEI history │ │ │ │ para venda │ +│ Status: │ │ Status: │ │ Status: │ │ Status: │ +│ pending │ │ approved │ │ completed │ │ in_stock │ +└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ +``` + +### 5.2 Etapa 1 - Avaliação + +Dois modos de criação: + +#### Avaliação Rápida (Dialog simples) +- Campos: IMEI, Marca, Modelo, Cor, Cliente, Condição Geral, Valor Estimado +- Uso: avaliação expressa sem checklist detalhado + +#### Formulário Completo (TradeInForm - 988 linhas) +- **Dados do Cliente:** Busca por nome/CPF na base de pessoas, cadastro rápido +- **Dados do Dispositivo:** IMEI, Marca, Modelo, Cor, Armazenamento +- **Checklist Completo:** 19 itens de verificação (ver seção 6) +- **Peças Necessárias:** Lista de peças com valores +- **Valor de Avaliação:** Calculado ou manual +- **Assinatura Digital:** Canvas para assinatura do cliente (touchscreen/mouse) +- **Ações:** Salvar, Imprimir PDF, Limpar + +### 5.3 Etapa 2 - Aprovação + +**Endpoint:** `POST /api/retail/evaluations/:id/approve-and-process` + +O que acontece na aprovação: +1. Status da avaliação muda para `approved` +2. **Cria O.S. Interna** (`INT${YYMM}RANDOM`) com: + - `serviceType: "internal_review"` + - `isInternal: true` + - `internalType: "revision"` + - `sourceEvaluationId: evaluationId` +3. **Registra no IMEI History** (ação: `trade_in_approved`, status: `in_revision`) +4. **Gera Crédito para o Cliente:** + - Busca pessoa pelo `personId` + - Cria registro em `customer_credits` + - Origem: `trade_in` + - Status: `active` + - Valor = estimatedValue da avaliação + +### 5.4 Etapa 3 - Revisão (O.S. Interna) + +A O.S. Interna segue o mesmo fluxo de uma O.S. normal mas com marcação `isInternal = true`: +- Técnico pode preencher checklist de revisão +- Adicionar peças utilizadas (custo de reparo) +- Registrar mão de obra +- Preencher diagnóstico + +**Endpoint de finalização:** `POST /api/retail/service-orders/:id/finalize-internal` + +### 5.5 Etapa 4 - Entrada no Estoque + +Ao finalizar a O.S. Interna: +1. **Cria dispositivo** em `mobile_devices`: + - `condition: "refurbished"` (ou conforme avaliação) + - `acquisitionType: "trade_in"` + - `acquisitionCost: estimatedValue + repairCost` + - `relatedEvaluationId: evaluationId` + - `relatedServiceOrderId: serviceOrderId` + - `suggestedPrice: totalCost * (1 + profitMargin/100)` + - `profitMargin: margem configurada (padrão 30%)` + - `status: "in_stock"` +2. **Registra no IMEI History** (ação: `entered_stock`) +3. **Registra no Activity Feed** (tipo: `stock_in`) + +### 5.6 Consulta do Fluxo Completo + +**Endpoint:** `GET /api/retail/evaluations/:id/full-flow` + +Retorna: +```json +{ + "evaluation": { ... }, + "serviceOrder": { ... }, + "device": { ... }, + "history": [ ... ], + "flowStatus": "in_stock", + "flowStep": 4, + "steps": [ + { "step": 1, "name": "Avaliação", "status": "completed" }, + { "step": 2, "name": "Aprovação", "status": "completed" }, + { "step": 3, "name": "Revisão (O.S.)", "status": "completed" }, + { "step": 4, "name": "Estoque", "status": "completed" } + ] +} +``` + +### 5.7 Uso do Crédito Trade-In no PDV + +Quando o cliente com crédito ativo é selecionado no PDV: +- Um banner azul aparece: "Crédito disponível: R$ X.XXX,XX" +- O operador pode ativar "Usar crédito" como abatimento na compra +- O crédito é deduzido automaticamente do total +- Múltiplos créditos são somados (trade-in + devolução + manual) + +--- + +## 6. CHECKLIST DE AVALIAÇÃO + +### 6.1 Checklist Fixo (19 Itens Built-in) + +O `deviceEvaluations` possui 19 campos booleanos fixos (cada um com campo de notas/observações): + +| # | Campo | Pergunta | Tipo | Impacto | +|---|-------|----------|------|---------| +| 1 | `powerOn` | Aparelho liga corretamente? | Sim/Não | Crítico | +| 2 | `screenIssues` | Avarias, travamentos ou toque fantasma? | Sim/Não | Alto | +| 3 | `screenSpots` | Manchas na tela? | Sim/Não | Médio | +| 4 | `buttonsWorking` | Botões funcionando? | Sim/Não | Médio | +| 5 | `wearMarks` | Marcas de uso? | Sim/Não | Baixo | +| 6 | `wifiWorking` | Wi-Fi funcionando? | Sim/Não | Alto | +| 7 | `simWorking` | Chip funcionando? | Sim/Não | Alto | +| 8 | `mobileDataWorking` | 4G/5G funcionando? | Sim/Não | Alto | +| 9 | `sensorsNfcWorking` | Sensores funcionando / NFC? | Sim/Não | Médio | +| 10 | `biometricWorking` | Face ID / Touch ID funcionando? | Sim/Não | Alto | +| 11 | `microphonesWorking` | Microfones funcionando? | Sim/Não | Alto | +| 12 | `earSpeakerWorking` | Áudio auricular funcionando? | Sim/Não | Médio | +| 13 | `loudspeakerWorking` | Áudio alto-falante funcionando? | Sim/Não | Médio | +| 14 | `chargingPortWorking` | Entrada de carregamento funcionando? | Sim/Não | Alto | +| 15 | `camerasWorking` | Câmeras funcionando / Manchas? | Sim/Não | Alto | +| 16 | `flashWorking` | Flash funcionando? | Sim/Não | Baixo | +| 17 | `hasCharger` | Possui carregador? | Sim/Não | Baixo | +| 18 | `toolsAnalysisOk` | Análise pelo 3uTools OK? | Sim/Não | Alto | +| 19 | `batteryHealth` | Saúde da Bateria | 0-100% | Alto | + +Cada campo possui um campo paralelo `*Notes` (texto) para observações adicionais. + +### 6.2 Checklist do TradeInForm (Frontend - 19 Itens) + +O componente `TradeInForm.tsx` implementa o checklist como array com: +- **ID único** por item +- **Descrição** da verificação +- **Valor:** `"sim"` | `"nao"` | `""` (não avaliado) +- **Observação:** campo de texto livre + +``` +DEFAULT_CHECKLIST = [ + "Aparelho liga corretamente" + "Avarias, travamentos ou toque fantasma" + "Manchas na tela" + "Botões funcionando" + "Marcas de uso" + "Wi-Fi funcionando" + "Chip funcionando" + "4G/5G funcionando" + "Sensores funcionando / NFC" + "Face ID / Touch ID funcionando" + "Microfones funcionando" + "Áudio auricular funcionando" + "Áudio alto-falante funcionando" + "Entrada de carregamento funcionando" + "Câmeras funcionando / Manchas" + "Flash funcionando" + "Possui carregador" + "Análise pelo 3uTools OK" + "Saúde da Bateria (%)" +] +``` + +### 6.3 Sistema de Templates Customizáveis + +Para além do checklist fixo, existe um sistema de templates: + +| Tabela | Função | +|--------|--------| +| `trade_in_checklist_templates` | Templates por categoria (smartphone, tablet, laptop, smartwatch) | +| `trade_in_checklist_items` | Itens do template com: categoria (visual/funcional/acessorios/documentacao), tipo de avaliação (condition/boolean/percentage/text), opções JSON, % de impacto no valor, ordenação | +| `trade_in_evaluation_results` | Resultados vinculados à avaliação e item do checklist | + +**Tipos de avaliação:** +- `condition`: opções pré-definidas (ex: "perfeito", "bom", "regular", "ruim") +- `boolean`: sim/não +- `percentage`: valor de 0 a 100 +- `text`: texto livre + +### 6.4 Checklist na O.S. (Diagnóstico) + +As Ordens de Serviço possuem campo `checklistData` (JSONB) que armazena dados de checklist de forma flexível: +- Preenchido pelo técnico durante diagnóstico +- Endpoint: `PUT /api/retail/service-orders/:id/checklist` +- Timestamp de conclusão: `checklistCompletedAt` +- Autor: `checklistCompletedBy` + +--- + +## 7. ORDENS DE SERVIÇO + +### 7.1 Tipos de O.S. + +| Tipo | serviceType | Origem | Descrição | +|------|------------|--------|-----------| +| **Reparo (cliente)** | `repair` | `customer_request` | Cliente traz dispositivo para conserto | +| **Manutenção** | `maintenance` | `customer_request` | Manutenção preventiva | +| **Diagnóstico** | `diagnostic` | `customer_request` | Apenas diagnóstico/orçamento | +| **Revisão Interna** | `internal_review` | `device_acquisition` | Revisão de dispositivo Trade-In | +| **Garantia** | `repair` | `warranty` | Reparo coberto por garantia | + +### 7.2 Fluxo de Status da O.S. (12 Estados) + +``` +open → diagnosis → quote → pending_approval → approved → in_repair → waiting_parts → quality_check → ready_pickup → completed + ↓ ↓ + rejected cancelled +``` + +| Status | Descrição | +|--------|-----------| +| `open` | Recém-criada, aguardando atendimento | +| `diagnosis` | Em diagnóstico pelo técnico | +| `quote` | Orçamento elaborado, aguardando aprovação | +| `pending_approval` | Enviado para aprovação do cliente | +| `approved` | Cliente aprovou o orçamento | +| `rejected` | Cliente rejeitou o orçamento | +| `in_repair` | Em reparo ativo | +| `waiting_parts` | Aguardando peças/componentes | +| `quality_check` | Verificação de qualidade pós-reparo | +| `ready_pickup` | Pronto para retirada pelo cliente | +| `completed` | Concluída e entregue | +| `cancelled` | Cancelada | + +### 7.3 Campos da O.S. + +- **Identificação:** Número (auto-gerado), Loja, Prioridade (low/normal/high/urgent) +- **Dispositivo:** IMEI, Marca, Modelo, deviceId +- **Cliente:** Nome, Telefone, Email, personId (pessoa unificada) +- **Técnico:** Nome, personId do técnico +- **Custos:** Peças (partsCost), Mão de obra (laborCost), Total (totalCost) +- **Datas:** Data esperada, Data real de conclusão +- **Pagamento:** Status (pending/paid/partial) +- **O.S. Interna:** isInternal, internalType, sourceEvaluationId + +### 7.4 Itens da O.S. + +Cada O.S. pode ter múltiplos itens: +- **Peça (part):** Componente utilizado no reparo +- **Mão de obra (labor):** Serviço técnico +- **Acessório (accessory):** Acessório incluído + +### 7.5 Garantias de Serviço + +Ao concluir uma O.S., pode-se criar uma garantia vinculada: +- Vincula à O.S. e ao IMEI +- Define prazo em dias (ex: 90 dias) +- Status: active → expired (automático) ou claimed (cliente acionou) +- Consulta de garantia por IMEI: `GET /api/retail/warranties/check/:imei` + +### 7.6 Faturamento de O.S. no PDV + +Quando uma O.S. está com status `ready_pickup`: +1. Aparece na aba "Faturar O.S." do PDV +2. O operador adiciona ao carrinho como item de serviço +3. A venda é registrada normalmente +4. A O.S. é marcada como `completed` + +--- + +## 8. DEVOLUÇÕES E TROCAS + +### 8.1 Fluxo de Devolução + +``` +1. Operador clica "Devolução" no PDV +2. Busca venda original por número ou cliente +3. Seleciona itens para devolver +4. Define motivo e método de reembolso +5. Verificação de senha do gerente (MANAGER_PASSWORD) +6. Processamento: + a. Cria registro em return_exchanges + b. Cria itens em return_exchange_items + c. Para dispositivos: reverte status do mobile_device para "returned" + d. Para produtos: ajusta estoque + e. Gera crédito para o cliente (customer_credits) + f. Registra no IMEI history (para dispositivos) + g. Registra no activity feed +``` + +### 8.2 Tipos + +| Tipo | Descrição | +|------|-----------| +| `return` | Devolução pura (reembolso) | +| `exchange` | Troca por outro produto | + +### 8.3 Métodos de Reembolso + +- Crédito na loja (gera `customer_credits`) +- Dinheiro +- Estorno no cartão +- PIX + +### 8.4 Busca de Vendas para Devolução + +**Endpoint:** `GET /api/retail/sales-for-return?search=...` + +Busca por: +- Número da venda (saleNumber) +- Nome do cliente +- CPF do cliente + +Retorna vendas com status "completed" + itens detalhados. + +### 8.5 Segurança + +A devolução exige **senha do gerente** (`MANAGER_PASSWORD`) para ser processada. Endpoint de verificação: `POST /api/retail/verify-manager-password`. + +--- + +## 9. ESTOQUE E DEPÓSITOS + +### 9.1 Tipos de Depósito + +| Tipo | Descrição | +|------|-----------| +| `store` | Depósito vinculado a uma loja | +| `central` | Depósito central (distribuição) | +| `transit` | Em trânsito entre depósitos | +| `virtual` | Depósito virtual (ex: consignação) | + +### 9.2 Movimentações de Estoque + +| Tipo de Movimento | Operação | Descrição | +|-------------------|----------|-----------| +| `entry` | `purchase` | Entrada por compra | +| `entry` | `trade_in` | Entrada por trade-in | +| `entry` | `manual_entry` | Entrada manual | +| `entry` | `devolution` | Entrada por devolução | +| `exit` | `sale` | Saída por venda | +| `transfer_in` | - | Recebimento de transferência | +| `transfer_out` | - | Envio para transferência | +| `adjustment` | `inventory_adjustment` | Ajuste de inventário | +| `return` | - | Retorno (devolução) | + +### 9.3 Transferências entre Depósitos + +Fluxo: `pending → in_transit → completed` + +Cada transferência registra: +- Depósito de origem e destino +- Itens com quantidade solicitada, transferida e recebida +- Números de série/IMEI vinculados +- Responsáveis (solicitante, aprovador, recebedor) + +### 9.4 Inventário + +Tipos: `full` (completo), `partial` (parcial), `cyclic` (cíclico) + +Fluxo: `open → counting → adjusting → completed` + +Para cada item do inventário: +- Sistema mostra quantidade no sistema +- Operador informa quantidade contada +- Sistema calcula diferença +- Ao aplicar ajuste: cria movimentação automática + +--- + +## 10. COMISSÕES E METAS + +### 10.1 Dashboard de Comissões + +O dashboard exibe para cada vendedor: +- Total de vendas no período +- Número de vendas +- Ticket médio +- Comissão calculada +- Meta vs Realizado (progress bar) +- Comparativo entre vendedores + +### 10.2 Planos de Comissão + +| Tipo | Descrição | +|------|-----------| +| `fixed` | Valor fixo por venda | +| `percent` | Percentual sobre o valor da venda | +| `tiered` | Faixas progressivas (rules JSONB) | +| `per_product` | Comissão específica por produto/categoria | + +### 10.3 Metas + +- **Por Vendedor:** goalAmount, goalType (sales/units/margin), achievedAmount, achievedPercent, bonus +- **Por Loja:** goalAmount, achievedAmount, achievedPercent + +### 10.4 Fechamento de Comissão + +O fechamento consolida vendas e devoluções em um período: + +``` +POST /api/retail/commission-closures/calculate + +Input: sellerId, periodStart, periodEnd, commissionRate +Output: { + totalSales, + totalReturns (devoluções deduzidas), + netSales (vendas líquidas), + salesCount, + returnsCount, + commissionAmount, + items: [ { saleId, amount, commission } ] +} +``` + +Status do fechamento: `open → closed → paid` + +--- + +## 11. RELATÓRIOS + +### 11.1 Relatórios Disponíveis (6 + 1) + +| # | Relatório | Endpoint | Descrição | +|---|-----------|----------|-----------| +| 1 | **OS por Status** | `GET /reports/os-by-status` | Quantidade e valor total por status | +| 2 | **OS por Técnico** | `GET /reports/os-by-technician` | Total de O.S., concluídas, em andamento, receita por técnico | +| 3 | **Vendas por Vendedor** | `GET /reports/sales-by-seller` | Total vendas, receita, ticket médio, dias ativos | +| 4 | **Margem por IMEI** | `GET /reports/margin-by-imei` | Custo, venda, margem absoluta e %, status | +| 5 | **Caixa Diário** | `GET /reports/daily-cash` | Fechamento completo do dia | +| 6 | **Giro de Estoque** | `GET /reports/stock-turnover` | Estoque atual, vendas 30d, turnover ratio | +| 7 | **Detalhamento de Vendas** | `GET /sales?detailed=true` | Lista completa com filtros | + +### 11.2 Caixa Diário (Detalhamento) + +O relatório de caixa diário é o mais completo, executando **4 queries:** + +**Query 1 - Resumo:** +- Total de vendas (R$) +- Quantidade de vendas +- Total em dinheiro +- Total em cartão (débito + crédito) +- Total em PIX +- Total combinado + +**Query 2 - Movimentações:** +- Total de sangrias +- Total de reforços + +**Query 3 - Listagem de Vendas:** +- Cada venda com: número, hora, cliente, vendedor, subtotal, desconto, total, forma de pagamento + +**Query 4 - Vendas por Vendedor:** +Para cada vendedor, breakdown completo: + +| Coluna | Descrição | +|--------|-----------| +| Vendedor | Nome | +| Vendas | Quantidade | +| Dinheiro | Total em cash | +| Débito | Total em débito | +| Crédito | Total em crédito | +| PIX | Total em PIX | +| Combinado | Total combinado | +| Descontos | Total de descontos concedidos | +| **Total** | **Receita líquida** | + +Linha de rodapé com totalizadores gerais. + +**Cálculo do Saldo do Caixa:** +``` +Saldo = Dinheiro + Reforços - Sangrias +``` + +--- + +## 12. CADASTROS + +### 12.1 Formas de Pagamento + +CRUD completo com campos: +- Nome, Tipo (cash/debit/credit/pix/boleto/financing) +- Bandeira (visa/mastercard/elo/amex/hipercard) +- Taxa (%), Taxa fixa (R$) +- Máximo de parcelas +- Taxas por parcela (JSONB: [{installments, feePercent}]) +- Dias para recebimento + +### 12.2 Vendedores + +CRUD com vínculo a: +- Pessoa unificada (personId) +- Loja (storeId) +- Plano de comissão (commissionPlanId) +- Data de contratação + +### 12.3 Planos de Comissão + +Tipos: fixed, percent, tiered, per_product +Regras customizáveis via JSONB + +### 12.4 Tabelas de Preço + +- Tipos de cliente: retail, wholesale, vip, employee +- Desconto ou markup percentual +- Validade (de/até) +- Itens específicos com preço customizado + +### 12.5 Promoções + +- Tipos: percent_off, fixed_off, buy_x_get_y, bundle +- Aplicação: all, category, product, brand +- Quantidade mínima/máxima +- Período de validade + +### 12.6 Tipos de Produto + +Com atributos fiscais completos: +- Categoria: device, accessory, part, service +- Controle: requiresImei, requiresSerial +- Fiscal: NCM, CEST, Origem, CST ICMS, CSOSN, CFOPs (4 tipos), Alíquotas (ICMS, PIS, COFINS, IPI) +- Reforma Tributária: IBS e CBS (preparado) +- Unidade de medida + +--- + +## 13. COMPRAS E AQUISIÇÕES + +### 13.1 Pedidos de Compra + +Fluxo: `draft → submitted → approved → partially_received → received → cancelled` + +Campos: fornecedor, depósito destino, itens (produto, quantidade, preço), condições de pagamento, frete, desconto, totais. + +### 13.2 Recebimento de Mercadoria + +**Endpoint:** `POST /api/retail/purchase-orders/:id/receive` + +Ao receber: +1. Atualiza quantidades recebidas por item +2. Cria movimentações de estoque (entry/purchase) +3. Atualiza saldos no depósito destino +4. Registra números de série quando aplicável +5. Atualiza status do pedido + +--- + +## 14. CRÉDITOS DE CLIENTE + +### 14.1 Origens de Crédito + +| Origem | Quando é gerado | +|--------|----------------| +| `trade_in` | Aprovação de avaliação de Trade-In | +| `return` | Devolução com reembolso em crédito | +| `manual` | Criação manual pelo operador | +| `promotion` | Promoção que gera crédito | + +### 14.2 Ciclo de Vida + +``` +active → used (parcial ou total) → expired → cancelled +``` + +### 14.3 Uso no PDV + +Quando o cliente é selecionado: +1. Sistema busca `customer_credits` com status `active` e `remainingAmount > 0` +2. Soma total de créditos disponíveis +3. Exibe banner: "Crédito disponível: R$ X.XXX,XX" +4. Operador pode ativar abatimento +5. Na finalização, deduz do crédito mais antigo primeiro (FIFO) +6. Registra uso parcial (atualiza remainingAmount) ou total (status → used) + +### 14.4 Recibo de Crédito + +**Endpoint:** `GET /api/retail/customer-credits/:creditId/receipt` + +Gera dados para impressão do comprovante de crédito. + +--- + +## 15. INTEGRAÇÃO COM PLUS (LARAVEL) + +### 15.1 Componentes da Integração + +| Arquivo | Função | +|---------|--------| +| `server/plus/proxy.ts` | Proxy reverso `/plus/*` → Laravel :8080 | +| `server/plus/sso.ts` | SSO via token HMAC-SHA256 | +| `server/plus/launcher.ts` | Auto-start do Laravel (php artisan serve) | +| `server/plus/client.ts` | Cliente REST para API do Plus | +| `server/retail/plus-sync.ts` | Sincronização Retail → Plus | + +### 15.2 Sincronização Retail → Plus + +| Entidade Suite | Entidade Plus | Endpoint | +|---------------|--------------|----------| +| Persons (clientes) | Clientes | `POST /api/retail/plus/sync/customers` | +| POS Sales + Items | Vendas + Itens + Faturamento | `POST /api/retail/plus/sync/sales` | +| POS Sales | NF-e/NFC-e | `POST /api/retail/plus/sync/nfe` | + +### 15.3 Campos de Sync na pos_sales + +| Campo | Descrição | +|-------|-----------| +| `plusVendaId` | ID da venda criada no Plus | +| `plusNfeChave` | Chave de acesso da NF-e emitida | +| `plusSyncStatus` | pending → synced → error → not_applicable | +| `plusSyncError` | Mensagem de erro (se houver) | +| `plusSyncedAt` | Timestamp da sincronização | +| `empresaId` | ID da empresa (tenant_empresas) vinculada | + +--- + +## 16. API - ENDPOINTS COMPLETOS + +### 16.1 Listagem por Domínio + +Todos os endpoints estão sob `/api/retail/*` e requerem autenticação. + +#### Activity Feed (2) +``` +GET /activity-feed +POST /activity-feed/mark-read +``` + +#### Formas de Pagamento (4) +``` +GET /payment-methods +POST /payment-methods +PUT /payment-methods/:id +DELETE /payment-methods/:id +``` + +#### Vendedores (4) +``` +GET /sellers +POST /sellers +PUT /sellers/:id +DELETE /sellers/:id +``` + +#### Planos de Comissão (4) +``` +GET /commission-plans +POST /commission-plans +PUT /commission-plans/:id +DELETE /commission-plans/:id +``` + +#### Tabelas de Preço (4) +``` +GET /price-tables +POST /price-tables +PUT /price-tables/:id +DELETE /price-tables/:id +``` + +#### Promoções (4) +``` +GET /promotions +POST /promotions +PUT /promotions/:id +DELETE /promotions/:id +``` + +#### Tipos de Produto (5) +``` +GET /product-types +GET /product-types/:id +POST /product-types +PUT /product-types/:id +DELETE /product-types/:id +``` + +#### Lojas (3) +``` +GET /stores +POST /stores +PUT /stores/:id +``` + +#### Depósitos (4) +``` +GET /warehouses +POST /warehouses +PUT /warehouses/:id +DELETE /warehouses/:id +``` + +#### Saldos de Estoque (2) +``` +GET /warehouse-stock +GET /warehouse-stock/:warehouseId/summary +``` + +#### Movimentações de Estoque (2) +``` +GET /stock-movements +POST /stock-movements +``` + +#### Números de Série (3) +``` +GET /product-serials +POST /product-serials +PUT /product-serials/:id +``` + +#### Transferências (4) +``` +GET /stock-transfers +GET /stock-transfers/:id +POST /stock-transfers +PUT /stock-transfers/:id/status +``` + +#### Inventários (5) +``` +GET /inventories +POST /inventories +GET /inventories/:id +PUT /inventories/:id/count +PUT /inventories/:id/apply +``` + +#### Dispositivos (5) +``` +GET /devices +GET /devices/:id +GET /devices/imei/:imei +POST /devices +PUT /devices/:id +``` + +#### Avaliações / Trade-In (10) +``` +GET /evaluations +GET /evaluations/:id +POST /evaluations +PUT /evaluations/:id +PUT /evaluations/:id/approve +PUT /evaluations/:id/reject +PUT /evaluations/:id/start-analysis +POST /evaluations/:id/approve-and-process +GET /evaluations/:id/full-flow +GET /evaluations/:id/service-order +``` + +#### Ordens de Serviço (8) +``` +GET /service-orders +GET /service-orders/:id +POST /service-orders +PUT /service-orders/:id +PUT /service-orders/:id/complete-preparation +POST /service-orders/:id/items +GET /service-orders/:id/items +DELETE /service-orders/:id/items/:itemId +PUT /service-orders/:id/checklist +POST /service-orders/:id/finalize-internal +``` + +#### Sessões de Caixa (3) +``` +GET /pos-sessions +POST /pos-sessions/open +PUT /pos-sessions/:id/close +``` + +#### Movimentações de Caixa (2) +``` +GET /cash-movements +POST /cash-movements +``` + +#### Garantias (4) +``` +GET /warranties +POST /warranties +GET /warranties/check/:imei +PUT /warranties/:id/claim +``` + +#### Alertas de Estoque (1) +``` +GET /stock-alerts +``` + +#### Relatórios (7) +``` +GET /reports/os-by-status +GET /reports/os-by-technician +GET /reports/sales-by-seller +GET /reports/margin-by-imei +GET /reports/daily-cash +GET /reports/stock-turnover +GET /dashboard-stats +``` + +#### Vendas (1) +``` +GET /sales +``` + +#### Pessoas (7) +``` +GET /persons +GET /persons/:id +POST /persons +PUT /persons/:id +POST /persons/:id/roles +PUT /persons/:id/roles/:roleId +DELETE /persons/:id/roles/:roleType +``` + +#### Histórico por Pessoa (4) +``` +GET /persons/:id/sales +GET /persons/:id/services +GET /persons/:id/trade-ins +GET /persons/:id/credits +``` + +#### Histórico por IMEI (3) +``` +GET /devices/:imei/history +GET /devices/by-origin/:originType +GET /inventory/by-origin +``` + +#### Trade-In Workflow (2) +``` +GET /customer-trade-ins/:personId +``` + +#### Segurança (1) +``` +POST /verify-manager-password +``` + +#### Devoluções (5) +``` +GET /sales-for-return +GET /returns +POST /returns +GET /customer-credits/:personId +GET /customer-credits/:creditId/receipt +POST /customer-credits/:creditId/use +``` + +#### Metas de Vendedor (4) +``` +GET /seller-goals +POST /seller-goals +PUT /seller-goals/:id +DELETE /seller-goals/:id +``` + +#### Metas da Loja (3) +``` +GET /store-goals +POST /store-goals +PUT /store-goals/:id +``` + +#### Fechamento de Comissão (4) +``` +GET /commission-closures +POST /commission-closures +PUT /commission-closures/:id +POST /commission-closures/calculate +GET /commission-dashboard +``` + +#### Compras (5) +``` +GET /purchase-orders +GET /purchase-orders/:id +POST /purchase-orders +PATCH /purchase-orders/:id/status +POST /purchase-orders/:id/receive +DELETE /purchase-orders/:id +``` + +#### Plus Sync (8) +``` +GET /plus/status +POST /plus/sync/customers +POST /plus/sync/sales +POST /plus/sync/nfe +POST /plus/import/customers +POST /plus/import/products +GET /plus/empresas +POST /plus/empresas +POST /plus/empresas/:id/bind +``` + +#### ERPNext Sync (8) +``` +GET /sync/status +POST /sync/persons/:id +POST /sync/persons +POST /sync/devices/:id +POST /sync/service-orders/:id +POST /sync/import/customers +POST /sync/import/suppliers +POST /sync/full +POST /sync/stock-entry +POST /sync/sales-invoice +``` + +**Total: ~130 endpoints** + +--- + +## 17. SEGURANÇA E MULTI-TENANT + +### 17.1 Autenticação +- Todas as rotas exigem `requireAuth` (Passport.js session) +- Verificação: `req.isAuthenticated()` + +### 17.2 Tenant Scoping +- Todos os relatórios e consultas filtram por `tenantId` +- Se `tenantId` estiver ausente, retorna 403 +- Dados de um tenant nunca vazam para outro + +### 17.3 Module Gating +- Middleware `requireModule(key)` verifica se módulo está ativo no tenant +- Verifica campo JSONB `tenants.features[key]` +- Retorna 403 com ação sugerida se módulo inativo + +### 17.4 Operações Sensíveis +- Devoluções exigem senha do gerente (MANAGER_PASSWORD) +- Verificação via endpoint dedicado +- Sangrias de caixa registram responsável e autorizador + +### 17.5 Auditoria +- Todas as operações relevantes registram no `retail_activity_feed` +- IMEI history rastreia toda movimentação de dispositivos +- Device history registra eventos por IMEI + +--- + +## CONCLUSÃO + +O módulo Retail da Arcádia Suite é uma solução completa e verticalmente integrada para lojas de celulares e assistência técnica, com **~16.800 linhas de código**, **40+ tabelas**, e **~130 endpoints REST**. Ele cobre todo o ciclo operacional desde a aquisição de dispositivos (compra ou trade-in), passando pela gestão de estoque por IMEI, ordens de serviço com checklist detalhado, PDV com múltiplas formas de pagamento, até o fechamento de caixa com breakdown por vendedor e tipo de pagamento. A integração com o Plus (Laravel) permite emissão de NF-e/NFC-e e sincronização completa de dados fiscais. diff --git a/client/public/opengraph.jpg b/client/public/opengraph.jpg index b408d47..3b8b7dc 100644 Binary files a/client/public/opengraph.jpg and b/client/public/opengraph.jpg differ diff --git a/client/src/App.tsx b/client/src/App.tsx index aeff1f0..b1b4d76 100644 --- a/client/src/App.tsx +++ b/client/src/App.tsx @@ -9,6 +9,7 @@ import { SoeMotorProvider } from "@/contexts/SoeMotorContext"; import { ProtectedRoute } from "@/lib/protected-route"; import { CommandPalette } from "@/components/CommandPalette"; import { KnowledgeCollectorInit } from "@/components/KnowledgeCollectorInit"; +import { OpenClawWidget } from "@/components/openclaw/OpenClawWidget"; import NotFound from "@/pages/not-found"; import AuthPage from "@/pages/auth-page"; @@ -70,8 +71,6 @@ const XosPipeline = lazy(() => import("@/pages/XosPipeline")); const XosSupervisor = lazy(() => import("@/pages/XosSupervisor")); const XosReports = lazy(() => import("@/pages/XosReports")); const XosProtocols = lazy(() => import("@/pages/XosProtocols")); -const Skills = lazy(() => import("@/pages/Skills")); -const AutomationCenter = lazy(() => import("@/pages/AutomationCenter")); function LoadingFallback() { @@ -148,8 +147,6 @@ function Router() { - - @@ -168,6 +165,7 @@ function App() { + diff --git a/client/src/components/Browser/BrowserFrame.tsx b/client/src/components/Browser/BrowserFrame.tsx index de7c0cf..ad323af 100644 --- a/client/src/components/Browser/BrowserFrame.tsx +++ b/client/src/components/Browser/BrowserFrame.tsx @@ -1,7 +1,7 @@ import { useLocation } from "wouter"; import React, { useEffect } from "react"; -import { Bot, Settings, MessageCircle, Zap, LayoutDashboard, Compass, Users, Ticket, LogOut, User, Shield, Receipt, Package, Rocket, Beaker, TrendingUp, MapPin, Droplets, Star, Database, Layout, Code, Code2, Store, Layers, Building2 } from "lucide-react"; -const browserIcon = "/arcadia_suite_icon.png"; +import { Bot, Settings, MessageCircle, Zap, LayoutDashboard, Compass, Users, Ticket, LogOut, User, Shield, Receipt, Package, Rocket, Beaker, TrendingUp, MapPin, Droplets, Star, Database, Layout, Code, Code2, Store, Layers } from "lucide-react"; +import browserIcon from "@assets/arcadia_branding/arcadia_suite_icon.png"; import { useAuth } from "@/hooks/use-auth"; import { useNavigationTracking } from "@/hooks/use-navigation-tracking"; import { Button } from "@/components/ui/button"; @@ -31,7 +31,7 @@ function CompactNavigationBar() { return (
- {(user?.role === "admin" || user?.role === "master") && ( + {user?.role === "admin" && (
navigateTo("/admin", "Administração")} @@ -123,13 +123,13 @@ function CompactNavigationBar() {
navigateTo("/soe", "SOE")} - data-testid="bookmark-soe" + onClick={() => navigateTo("/erp", "ERP")} + data-testid="bookmark-erp" >
- +
- SOE + ERP
Retail
- {/* Plus hidden temporarily */} +
navigateTo("/plus", "Plus")} + data-testid="bookmark-plus" + > +
+ +
+ Plus +
navigateTo("/fisco", "Fisco")} @@ -179,10 +188,10 @@ function CompactNavigationBar() {

{user?.name || user?.username}

@{user?.username}

- {(user?.role === "admin" || user?.role === "master") && ( + {user?.role === "admin" && (

- {user?.role === "master" ? "Administrador Master" : "Administrador"} + Administrador

)}
@@ -192,7 +201,7 @@ function CompactNavigationBar() { Meu Perfil - {(user?.role === "admin" || user?.role === "master") && ( + {user?.role === "admin" && ( <> Plataforma diff --git a/client/src/components/Browser/Omnibox.tsx b/client/src/components/Browser/Omnibox.tsx index 6ea51df..5bc777d 100644 --- a/client/src/components/Browser/Omnibox.tsx +++ b/client/src/components/Browser/Omnibox.tsx @@ -80,10 +80,10 @@ export function Omnibox({ url, onNavigate, isLoading }: OmniboxProps) {

{user?.name || user?.username}

@{user?.username}

- {(user?.role === "admin" || user?.role === "master") && ( + {user?.role === "admin" && (

- {user?.role === "master" ? "Administrador Master" : "Administrador"} + Administrador

)}
diff --git a/client/src/components/CommandPalette.tsx b/client/src/components/CommandPalette.tsx index bff0d63..dbf1883 100644 --- a/client/src/components/CommandPalette.tsx +++ b/client/src/components/CommandPalette.tsx @@ -121,10 +121,10 @@ export function CommandPalette() { }, { id: "nav-crm", - name: "Abrir Manager Partners", + name: "Abrir Arcádia CRM", icon: , action: () => navigateTo("/crm"), - keywords: ["crm", "parceiros", "contratos", "manager", "partners"], + keywords: ["crm", "parceiros", "contratos", "vendas", "whatsapp"], group: "Navegação", }, { diff --git a/client/src/components/SupersetDashboard.tsx b/client/src/components/SupersetDashboard.tsx index 258b9f0..c465bce 100644 --- a/client/src/components/SupersetDashboard.tsx +++ b/client/src/components/SupersetDashboard.tsx @@ -27,8 +27,7 @@ export function SupersetDashboard({ const [status, setStatus] = useState<"loading" | "ready" | "error" | "unavailable">("loading"); const [errorMsg, setErrorMsg] = useState(""); - // Busca token e embeddedId (UUID) do backend - const fetchTokenData = useCallback(async (): Promise<{ token: string; embeddedId: string }> => { + const fetchGuestToken = useCallback(async (): Promise => { const resp = await fetch("/api/superset/guest-token", { method: "POST", headers: { "Content-Type": "application/json" }, @@ -39,7 +38,8 @@ export function SupersetDashboard({ const err = await resp.json().catch(() => ({ error: "Erro desconhecido" })); throw new Error(err.error || `HTTP ${resp.status}`); } - return resp.json(); + const { token } = await resp.json(); + return token; }, [dashboardId]); const loadDashboard = useCallback(async () => { @@ -56,9 +56,6 @@ export function SupersetDashboard({ return; } - // Resolve embeddedId (UUID) e obtém token inicial - const { embeddedId } = await fetchTokenData(); - // Importa SDK dinamicamente (só quando necessário) const { embedDashboard } = await import("@superset-ui/embedded-sdk"); @@ -68,13 +65,10 @@ export function SupersetDashboard({ } sdkRef.current = await embedDashboard({ - id: embeddedId, // UUID do embedded config (não o slug) - supersetDomain: "https://bi.onboardbi.com.br", + id: dashboardId, + supersetDomain: window.location.origin + "/superset", mountPoint: containerRef.current, - fetchGuestToken: async () => { - const { token } = await fetchTokenData(); - return token; - }, + fetchGuestToken, dashboardUiConfig: { hideTitle: true, hideChartControls: false, @@ -82,21 +76,18 @@ export function SupersetDashboard({ }, }); - // O SDK cria um