7.7 KiB

Raw Blame History

🤖 Referência Rápida para Agentes - Arcádia Suite

Guia de referência para desenvolvimento autônomo no projeto Arcádia Suite

📁 Documentação Técnica por Componente

Especificação Completa: docs/SPEC_NAVBAR.md
Arquivo Fonte: client/src/components/Browser/BrowserFrame.tsx
Hook de Tracking: client/src/hooks/use-navigation-tracking.ts
Error Boundary: client/src/components/ErrorBoundary.tsx (tratamento de erros lazy loading)

Banco de Dados (Schema)

Arquivo Principal: shared/schema.ts (7.000+ linhas)
Tabelas Principais:
- users, profiles, roles - Autenticação e RBAC
- tenants, tenantUsers - Multi-tenancy
- workspacePages, pageBlocks - Produtividade (estilo Notion)
- conversations, messages - Chat/Agente
- whatsappSessions, whatsappMessages - WhatsApp
- crmPartners, crmContracts - CRM
- fiscalNcms, fiscalGruposTributacao - Fiscal
- retailStores, posSales, mobileDevices - Retail
- manusRuns, manusSteps - Agente Manus
- biDatasets, biCharts, biDashboards - BI

Backend (API Routes)

Registro de Rotas: server/routes.ts
Autenticação: server/auth.ts
Agente Manus: server/manus/service.ts + server/manus/tools.ts
WhatsApp: server/whatsapp/routes.ts + server/whatsapp/service.ts
CRM: server/crm/routes.ts
Fiscal: server/fisco/routes.ts
Retail: server/retail/routes.ts
Blackboard (Agentes): server/blackboard/routes.ts

Frontend (Páginas)

Router: client/src/App.tsx (inclui ErrorBoundary + Suspense)
Cockpit (Home): client/src/pages/Cockpit.tsx
Agent: client/src/pages/Agent.tsx
DevCenter: client/src/pages/DevCenter.tsx
Crm: client/src/pages/Crm.tsx
Fisco: client/src/pages/Fisco.tsx
Retail: client/src/pages/ArcadiaRetail.tsx
WhatsApp: client/src/pages/WhatsApp.tsx
ErrorBoundary: client/src/components/ErrorBoundary.tsx

🏗️ Arquitetura do Sistema

┌─────────────────────────────────────────────────────────────────┐
│                    CAMADA DE APRESENTAÇÃO                        │
│   React 18 + TypeScript + Tailwind CSS + shadcn/ui              │
│   66 páginas / Interface tipo browser com abas                  │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   CAMADA DE ORQUESTRAÇÃO                         │
│   Express.js + Socket.IO + Manus Agent                          │
│   API REST + WebSocket em tempo real                            │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   CAMADA DE INTELIGÊNCIA                         │
│   FastAPI (Contábil 8003, BI 8004, Automação 8005)              │
│   OpenAI GPT-4o + LiteLLM Gateway + Ollama                      │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      CAMADA DE DADOS                             │
│   PostgreSQL 16 + Drizzle ORM + pgvector                        │
│   Session Store + Multi-tenant                                  │
└─────────────────────────────────────────────────────────────────┘

🛠️ Stack Tecnológico

Camada	Tecnologia
Frontend	React 18, TypeScript, Tailwind CSS, shadcn/ui
Backend	Express.js, Socket.IO, Passport.js
Banco	PostgreSQL 16, Drizzle ORM, pgvector
Python	FastAPI (microserviços nas portas 8001-8005)
IA	OpenAI GPT-4o, LiteLLM, Ollama
Deploy	Docker Compose, Coolify, PM2

🔧 Comandos Úteis

# Desenvolvimento
npm run dev                    # Inicia servidor de desenvolvimento
npm run dev:client            # Apenas frontend (porta 5000)

# Banco de dados
npm run db:push               # Aplica migrations Drizzle
npm run db:apply-rls          # Aplica políticas RLS

# Build
npm run build                 # Build para produção
npm run start                 # Inicia em produção

# Docker
docker compose up -d          # Sobe todos os serviços
docker compose --profile ai up  # Sobe com IA (Ollama + LiteLLM)

📋 Convenções de Código

Nomenclatura

Componentes: PascalCase (ex: BrowserFrame.tsx)
Hooks: camelCase com prefixo use (ex: useAuth.tsx)
Utilitários: camelCase (ex: navigation-tracking.ts)
Rotas API: kebab-case (ex: /api/whatsapp/connect)

Estrutura de Pastas

client/src/
  components/     # Componentes reutilizáveis
  pages/          # Páginas da aplicação
  hooks/          # Custom hooks
  lib/            # Utilitários e configurações
  
server/
  [modulo]/       # Um diretório por módulo
    routes.ts     # Rotas da API
    service.ts    # Lógica de negócio
    storage.ts    # Acesso a dados

🧪 Test IDs

Sempre adicione data-testid em elementos interativos:

<button 
  data-testid="button-submit"
  onClick={handleSubmit}
>
  Enviar
</button>

📚 Documentação Adicional

Documentação Técnica Completa: DOCUMENTATION.md
Mapa do Sistema: MAPA_SISTEMA_ARCADIA.md
Contexto para Claude: CLAUDE.md
README: README.md

🆘 Precisa de Ajuda?

Consulte a especificação técnica específica em docs/
Verifique exemplos similares no código existente
Siga os padrões já estabelecidos no projeto

Última atualização: 2026-04-08

🐛 Tratamento de Erros - Lazy Loading

Problema Resolvido: Loading Infinito na Navegação

Sintoma: Ao clicar em itens da navbar, se a página tivesse erro (import quebrado, sintaxe inválida), o loading ficava infinito.

Causa: React.lazy() falha silenciosamente e Suspense não tem como capturar o erro.

Solução:

ErrorBoundary (client/src/components/ErrorBoundary.tsx):
- Captura erros de renderização, incluindo lazy load
- Mostra UI de fallback com botão de retry
LoadingFallback com Timeout (client/src/App.tsx):
- 3s: mensagem "Isso está demorando..."
- 10s: alerta amarelo com botão recarregar
Integração:

<ErrorBoundary>
  <Suspense fallback={<LoadingFallback />}>
    <Switch>{/* rotas */}</Switch>
  </Suspense>
</ErrorBoundary>

7.7 KiB Raw Blame History