486 lines
15 KiB
Markdown
486 lines
15 KiB
Markdown
# Especificação Técnica - Navbar do Arcádia Suite
|
|
|
|
> **Versão:** 1.0
|
|
> **Data:** 2026-04-08
|
|
> **Arquivo Fonte:** `client/src/components/Browser/BrowserFrame.tsx`
|
|
> **Status:** Implementado e em produção
|
|
|
|
---
|
|
|
|
## 1. Visão Geral
|
|
|
|
A navbar do Arcádia Suite é uma barra de navegação compacta, horizontal e fixa no topo da tela. Ela implementa um padrão de "navegação por bookmarks" onde cada item representa um módulo principal do sistema.
|
|
|
|
### 1.1 Objetivos
|
|
- Acesso rápido aos módulos principais
|
|
- Navegação intuitiva estilo "browser"
|
|
- Rastreamento de uso para analytics
|
|
- Suporte a múltiplos perfis de usuário
|
|
|
|
### 1.2 Princípios de Design
|
|
- **Minimalista:** Apenas ícone + texto curto
|
|
- **Escalável:** Scroll horizontal permite muitos itens
|
|
- **Responsiva:** Adapta-se a diferentes telas
|
|
- **Consistente:** Cores e ícones padronizados
|
|
|
|
---
|
|
|
|
## 2. Estrutura do Componente
|
|
|
|
```
|
|
BrowserFrame (Container)
|
|
└── CompactNavigationBar (Navbar principal)
|
|
├── Área de Bookmarks (scroll horizontal)
|
|
│ └── BookmarkItem[] (itens de navegação)
|
|
└── Área do Usuário (fixa à direita)
|
|
└── UserDropdown (menu do usuário)
|
|
```
|
|
|
|
### 2.1 Hierarquia de Componentes
|
|
|
|
```tsx
|
|
// BrowserFrame.tsx
|
|
interface BrowserFrameProps {
|
|
children: React.ReactNode;
|
|
}
|
|
|
|
function CompactNavigationBar() {
|
|
// Hook de navegação
|
|
const [location, setLocation] = useLocation(); // wouter
|
|
const { user, logoutMutation } = useAuth();
|
|
const { trackPageView } = useNavigationTracking();
|
|
|
|
// Handler de navegação
|
|
const navigateTo = (path: string, pageName: string) => {
|
|
trackPageView(pageName, path);
|
|
setLocation(path);
|
|
};
|
|
|
|
return (
|
|
<div className="h-10 bg-background border-b...">
|
|
{/* Bookmarks */}
|
|
{/* User Menu */}
|
|
</div>
|
|
);
|
|
}
|
|
|
|
export function BrowserFrame({ children }: BrowserFrameProps) {
|
|
return (
|
|
<div className="flex flex-col h-screen w-screen...">
|
|
<CompactNavigationBar />
|
|
<div className="flex-1...">{children}</div>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Especificação Visual
|
|
|
|
### 3.1 Dimensões e Layout
|
|
|
|
| Propriedade | Valor | Tailwind |
|
|
|-------------|-------|----------|
|
|
| Altura | 40px | `h-10` |
|
|
| Padding horizontal | 12px | `px-3` |
|
|
| Gap entre itens | 8px | `gap-2` |
|
|
| Tamanho do ícone | 16x16px | `w-4 h-4` |
|
|
| Tamanho do ícone interno | 10x10px | `w-2.5 h-2.5` |
|
|
| Padding do bookmark | 6px 8px | `px-2 py-1.5` |
|
|
| Border radius | 4px | `rounded` |
|
|
|
|
### 3.2 Cores e Estilos
|
|
|
|
```
|
|
Fundo: bg-background (varia com tema claro/escuro)
|
|
Borda inferior: border-border
|
|
Texto: text-muted-foreground
|
|
Hover: hover:bg-muted
|
|
Sombra: shadow-xs
|
|
```
|
|
|
|
### 3.3 Estados dos Bookmarks
|
|
|
|
| Estado | Estilo |
|
|
|--------|--------|
|
|
| **Default** | `text-muted-foreground` |
|
|
| **Hover** | `hover:bg-muted` + cursor pointer |
|
|
| **Ativo** | Não há estado visual de "ativo" (intencional) |
|
|
|
|
---
|
|
|
|
## 4. Itens de Navegação (Bookmarks)
|
|
|
|
### 4.1 Lista Completa de Itens
|
|
|
|
| Ordem | Nome | Rota | Ícone | Cor do Gradient | Visibilidade |
|
|
|-------|------|------|-------|-----------------|--------------|
|
|
| 1 | Administração | `/admin` | Settings | slate-700 → slate-900 | Apenas admin |
|
|
| 2 | Início | `/` | Arcádia Icon | - (imagem) | Todos |
|
|
| 3 | Agent | `/agent` | Bot | primary → blue-600 | Todos |
|
|
| 4 | Inbox | `/xos/inbox` | MessageCircle | #00a884 → #25D366 | Todos |
|
|
| 5 | Automações | `/automations` | Zap | #c89b3c → #d4a94a | Todos |
|
|
| 6 | Insights | `/insights` | LayoutDashboard | #1f334d → #2d4a6f | Todos |
|
|
| 7 | Compass | `/compass` | Compass | #c89b3c → #1f334d | Todos |
|
|
| 8 | Produção | `/production` | Users | indigo-500 → indigo-700 | Todos |
|
|
| 9 | Suporte | `/support` | Ticket | rose-500 → rose-700 | Todos |
|
|
| 10 | ERP | `/erp` | Package | blue-600 → blue-800 | Todos |
|
|
| 11 | Retail | `/retail` | Store | cyan-500 → blue-600 | Todos |
|
|
| 12 | Plus | `/plus` | Layers | purple-500 → purple-700 | Todos |
|
|
| 13 | Fisco | `/fisco` | Receipt | emerald-600 → emerald-800 | Todos |
|
|
| 14 | Engenharia | `/engineering` | Compass | teal-500 → green-700 | Todos |
|
|
|
|
### 4.2 Estrutura de um Bookmark
|
|
|
|
```tsx
|
|
<div
|
|
className="flex items-center gap-1 hover:bg-muted px-2 py-1.5 rounded cursor-pointer transition-colors flex-shrink-0"
|
|
onClick={() => navigateTo("/rota", "Nome")}
|
|
data-testid="bookmark-nome"
|
|
>
|
|
{/* Container do ícone com gradiente */}
|
|
<div className="w-4 h-4 bg-gradient-to-br from-[COR1] to-[COR2] rounded-sm flex items-center justify-center">
|
|
<Icon className="w-2.5 h-2.5 text-white" />
|
|
</div>
|
|
{/* Texto (oculto em mobile) */}
|
|
<span className="hidden md:inline">Nome</span>
|
|
</div>
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Menu do Usuário (Dropdown)
|
|
|
|
### 5.1 Estrutura
|
|
|
|
```
|
|
[Avatar + Nome] ▼
|
|
│
|
|
├── Informações do Usuário
|
|
│ ├── Nome completo
|
|
│ ├── @username
|
|
│ └── Badge "Administrador" (se aplicável)
|
|
│
|
|
├── Meu Perfil
|
|
│
|
|
├── Plataforma (apenas admin)
|
|
│ └── Centro de Desenvolvimento
|
|
│
|
|
└── Sair (texto vermelho)
|
|
```
|
|
|
|
### 5.2 Componentes
|
|
|
|
- **Trigger:** Botão com avatar circular + nome
|
|
- **Avatar:** Inicial do nome em círculo colorido (5x5)
|
|
- **Dropdown:** `DropdownMenu` do shadcn/ui
|
|
- **Largura:** 224px (`w-56`)
|
|
|
|
---
|
|
|
|
## 6. Comportamento e Interações
|
|
|
|
### 6.1 Fluxo de Navegação
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Usuário clica │
|
|
│ em bookmark │
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ trackPageView │ ← Registra no backend via POST /api/learning/navigation
|
|
│ (pageName, path)│
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ setLocation │ ← wouter atualiza URL
|
|
│ (path) │
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ React.lazy() │ ← Code splitting carrega chunk
|
|
│ import() │
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ <Suspense> │ ← Mostra LoadingFallback
|
|
│ fallback │
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Página carrega │ ← Componente renderizado
|
|
│ e renderiza │
|
|
└─────────────────┘
|
|
```
|
|
|
|
### 6.2 Rastreamento (Analytics)
|
|
|
|
```typescript
|
|
// use-navigation-tracking.ts
|
|
const trackPageView = (pageName: string, route?: string) => {
|
|
track({
|
|
module: pageName, // Ex: "Agent", "Fisco"
|
|
action: "page_view",
|
|
metadata: {
|
|
route, // Ex: "/agent", "/fisco"
|
|
timestamp: "2026-04-08T15:30:00Z"
|
|
},
|
|
});
|
|
};
|
|
```
|
|
|
|
**Debounce:** 2000ms para evitar spam de eventos
|
|
|
|
### 6.3 Responsividade
|
|
|
|
| Breakpoint | Comportamento |
|
|
|------------|---------------|
|
|
| **Mobile** (< 768px) | Texto dos bookmarks oculto (`hidden md:inline`), apenas ícones |
|
|
| **Desktop** (≥ 768px) | Texto visível ao lado do ícone |
|
|
|
|
### 6.4 Scroll Horizontal
|
|
|
|
- A área de bookmarks tem `overflow-x-auto`
|
|
- Scrollbar oculta (`scrollbar-hide`)
|
|
- Itens não quebram linha (`flex-shrink-0`)
|
|
|
|
---
|
|
|
|
## 7. Dependências
|
|
|
|
### 7.1 Bibliotecas
|
|
|
|
```json
|
|
{
|
|
"wouter": "^3.3.5", // Router
|
|
"lucide-react": "^0.545.0", // Ícones
|
|
"@radix-ui/react-dropdown-menu": "^2.1.16" // Dropdown
|
|
}
|
|
```
|
|
|
|
### 7.2 Hooks Customizados
|
|
|
|
| Hook | Arquivo | Propósito |
|
|
|------|---------|-----------|
|
|
| `useLocation` | `wouter` | Navegação de rotas |
|
|
| `useAuth` | `@/hooks/use-auth` | Dados do usuário e logout |
|
|
| `useNavigationTracking` | `@/hooks/use-navigation-tracking` | Analytics |
|
|
|
|
### 7.3 Componentes UI
|
|
|
|
- `Button` (shadcn/ui)
|
|
- `DropdownMenu`, `DropdownMenuContent`, `DropdownMenuItem`, etc. (shadcn/ui)
|
|
|
|
---
|
|
|
|
## 8. Test IDs (data-testid)
|
|
|
|
Usados para testes automatizados:
|
|
|
|
```
|
|
bookmark-admin
|
|
bookmark-home
|
|
bookmark-agent
|
|
bookmark-xos-inbox
|
|
bookmark-automations
|
|
bookmark-insights
|
|
bookmark-compass
|
|
bookmark-production
|
|
bookmark-support
|
|
bookmark-erp
|
|
bookmark-retail
|
|
bookmark-plus
|
|
bookmark-fisco
|
|
bookmark-engineering
|
|
button-user-menu
|
|
button-logout
|
|
menu-development
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Como Modificar
|
|
|
|
### 9.1 Adicionar Novo Bookmark
|
|
|
|
```tsx
|
|
// Em CompactNavigationBar, adicionar antes do </div> da área de bookmarks:
|
|
|
|
<div
|
|
className="flex items-center gap-1 hover:bg-muted px-2 py-1.5 rounded cursor-pointer transition-colors flex-shrink-0"
|
|
onClick={() => navigateTo("/nova-rota", "Nome")}
|
|
data-testid="bookmark-novo"
|
|
>
|
|
<div className="w-4 h-4 bg-gradient-to-br from-[COR1] to-[COR2] rounded-sm flex items-center justify-center">
|
|
<NovoIcon className="w-2.5 h-2.5 text-white" />
|
|
</div>
|
|
<span className="hidden md:inline">Novo</span>
|
|
</div>
|
|
```
|
|
|
|
### 9.2 Alterar Ordem
|
|
|
|
Reorganizar os elementos `<div>` na ordem desejada dentro da área de bookmarks.
|
|
|
|
### 9.3 Condicional por Permissão
|
|
|
|
```tsx
|
|
{user?.role === "admin" && (
|
|
<div ...>...</div>
|
|
)}
|
|
|
|
// Ou por módulo permitido:
|
|
{(user as any)?.allowedModules?.includes("modulo") && (
|
|
<div ...>...</div>
|
|
)}
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Integração com Sistema
|
|
|
|
### 10.1 Uso nas Páginas
|
|
|
|
Todas as páginas que usam a navbar devem ser envolvidas por `BrowserFrame`:
|
|
|
|
```tsx
|
|
// Exemplo: client/src/pages/Agent.tsx
|
|
import { BrowserFrame } from "@/components/Browser/BrowserFrame";
|
|
|
|
export default function Agent() {
|
|
return (
|
|
<BrowserFrame>
|
|
<div className="h-full...">
|
|
{/* Conteúdo da página */}
|
|
</div>
|
|
</BrowserFrame>
|
|
);
|
|
}
|
|
```
|
|
|
|
### 10.2 Páginas que NÃO usam BrowserFrame
|
|
|
|
- `AuthPage` (tela de login)
|
|
- `NotFound` (página 404)
|
|
|
|
---
|
|
|
|
## 11. Considerações Técnicas
|
|
|
|
### 11.1 Performance
|
|
- Code splitting via `React.lazy()` em todas as páginas
|
|
- Suspense com fallback de loading
|
|
- Debounce no rastreamento (2s)
|
|
|
|
### 11.2 Acessibilidade
|
|
- `cursor-pointer` em todos os bookmarks
|
|
- Estrutura semântica do dropdown
|
|
- Contraste adequado nos ícones (branco sobre gradiente)
|
|
|
|
### 11.3 Limitações Conhecidas
|
|
- Não há indicador visual de "página ativa" (design intencional)
|
|
- Scroll horizontal pode esconder itens em telas muito pequenas
|
|
- Não suporta drag-and-drop para reordenar
|
|
|
|
### 11.4 Tratamento de Erros (Resolvido)
|
|
|
|
**Problema:** Se uma página carregada via `React.lazy()` tivesse erro (import quebrado, sintaxe inválida), o `Suspense` ficava preso no estado de loading infinito.
|
|
|
|
**Solução Implementada:**
|
|
|
|
1. **ErrorBoundary** (`client/src/components/ErrorBoundary.tsx`):
|
|
- Captura erros em componentes filhos, incluindo falhas no lazy loading
|
|
- Exibe UI de fallback com detalhes do erro
|
|
- Botão "Tentar Novamente" para recarregar
|
|
|
|
2. **LoadingFallback Aprimorado** (`client/src/App.tsx`):
|
|
- Após 3s: mostra mensagem "Isso está demorando mais que o esperado..."
|
|
- Após 10s: mostra alerta amarelo com botão de recarregar
|
|
|
|
3. **Integração no Router**:
|
|
```tsx
|
|
function Router() {
|
|
return (
|
|
<ErrorBoundary> {/* ← Captura erros */}
|
|
<Suspense fallback={<LoadingFallback />}>
|
|
<Switch>
|
|
<ProtectedRoute path="/" component={Cockpit} />
|
|
{/* ... outras rotas ... */}
|
|
</Switch>
|
|
</Suspense>
|
|
</ErrorBoundary>
|
|
);
|
|
}
|
|
```
|
|
|
|
**Fluxo de Erro:**
|
|
```
|
|
Usuário clica → lazy() falha → Suspense não resolve → ErrorBoundary captura
|
|
↓
|
|
LoadingFallback mostra
|
|
aviso após 3s/10s
|
|
↓
|
|
ErrorBoundary renderiza
|
|
UI de erro com retry
|
|
```
|
|
|
|
---
|
|
|
|
## 12. Diagrama de Sequência
|
|
|
|
```
|
|
┌────────┐ ┌─────────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐
|
|
│ Usuário│ │ Navbar │ │ wouter │ │ React │ │ Backend │
|
|
└───┬────┘ └──────┬──────┘ └────┬─────┘ └────┬────┘ └────┬─────┘
|
|
│ │ │ │ │
|
|
│──clica─────────▶│ │ │ │
|
|
│ │ │ │ │
|
|
│ │──trackPageView────────────────────│──────────────▶│
|
|
│ │ │ │ │
|
|
│ │──setLocation───▶│ │ │
|
|
│ │ │ │ │
|
|
│ │ │──atualiza URL──│ │
|
|
│ │ │ │ │
|
|
│ │ │◀─URL changed───│ │
|
|
│ │ │ │ │
|
|
│ │ │──lazy import──▶│ │
|
|
│ │ │ │ │
|
|
│ │◀────────────────│──chunk loaded──│ │
|
|
│ │ │ │ │
|
|
│ │──renderiza nova página────────────▶│ │
|
|
│ │ │ │ │
|
|
│◀────────────────│ │ │ │
|
|
│ │ │ │ │
|
|
```
|
|
|
|
---
|
|
|
|
## 13. Changelog
|
|
|
|
| Versão | Data | Alterações |
|
|
|--------|------|------------|
|
|
| 1.0 | 2026-04-08 | Especificação inicial criada |
|
|
| 1.1 | 2026-04-08 | Adicionado tratamento de erros (ErrorBoundary + LoadingFallback com timeout) |
|
|
|
|
---
|
|
|
|
## 14. Referências
|
|
|
|
- **Arquivo Fonte:** `client/src/components/Browser/BrowserFrame.tsx`
|
|
- **Hook de Tracking:** `client/src/hooks/use-navigation-tracking.ts`
|
|
- **Rotas:** `client/src/App.tsx`
|
|
- **Autenticação:** `client/src/hooks/use-auth.tsx`
|
|
- **UI Components:** `client/src/components/ui/`
|
|
|
|
---
|
|
|
|
**Nota para Agentes:**
|
|
> Ao modificar a navbar, mantenha a consistência visual com os bookmarks existentes. Sempre adicione `data-testid` para testes e atualize esta especificação se houver mudanças significativas na estrutura ou comportamento.
|