204 lines
7.7 KiB
Markdown
204 lines
7.7 KiB
Markdown
# 🤖 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
|
|
|
|
### Navegação (Navbar)
|
|
- **Especificação Completa:** [`docs/SPEC_NAVBAR.md`](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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```tsx
|
|
<button
|
|
data-testid="button-submit"
|
|
onClick={handleSubmit}
|
|
>
|
|
Enviar
|
|
</button>
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Documentação Adicional
|
|
|
|
- **Documentação Técnica Completa:** [`DOCUMENTATION.md`](DOCUMENTATION.md)
|
|
- **Mapa do Sistema:** [`MAPA_SISTEMA_ARCADIA.md`](MAPA_SISTEMA_ARCADIA.md)
|
|
- **Contexto para Claude:** [`CLAUDE.md`](CLAUDE.md)
|
|
- **README:** [`README.md`](README.md)
|
|
|
|
---
|
|
|
|
## 🆘 Precisa de Ajuda?
|
|
|
|
1. Consulte a especificação técnica específica em `docs/`
|
|
2. Verifique exemplos similares no código existente
|
|
3. 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:**
|
|
|
|
1. **ErrorBoundary** (`client/src/components/ErrorBoundary.tsx`):
|
|
- Captura erros de renderização, incluindo lazy load
|
|
- Mostra UI de fallback com botão de retry
|
|
|
|
2. **LoadingFallback com Timeout** (`client/src/App.tsx`):
|
|
- 3s: mensagem "Isso está demorando..."
|
|
- 10s: alerta amarelo com botão recarregar
|
|
|
|
3. **Integração:**
|
|
```tsx
|
|
<ErrorBoundary>
|
|
<Suspense fallback={<LoadingFallback />}>
|
|
<Switch>{/* rotas */}</Switch>
|
|
</Suspense>
|
|
</ErrorBoundary>
|
|
```
|