docs(okf): entidades e relacionamentos OKF do DashDescomplicar

2026-10-28 16:01:20 +00:00
parent f063a2ec8c
commit 61ae4697f9
48 changed files with 2610 additions and 0 deletions
@@ -0,0 +1,65 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, integracao, csr, cache, fetch]
+title: "CSR-Integration"
+---
+
+# CSR-Integration
+
+Camada de integração Cliente-Servidor do DashDescomplicar. Gere fetch de dados da API, cache local, reconnection logic e tratamento de erros para todos os painéis.
+
+## Responsabilidades
+
+- **Fetch API**: Chamadas HTTP à Express-API com tipagem TypeScript
+- **Cache Local**: Estado React (`useState` + `useCallback`) para evitar refetchs desnecessários
+- **Reconnection**: Lógica de retry em falhas de rede (sem exponential backoff — simplicidade)
+- **Error Handling**: Erros capturados com `console.error`, estados de loading/error nos painéis
+- **Refresh Manual**: Botão "Actualizar" (RefreshCw) em cada painel com animação de spinner
+
+## Padrão de Fetch
+
+```typescript
+const [data, setData] = useState<T | null>(null)
+const [loading, setLoading] = useState(true)
+const [refreshing, setRefreshing] = useState(false)
+
+const fetchData = useCallback(async () => {
+  setRefreshing(true)
+  try {
+    const response = await fetch('/api/<endpoint>')
+    if (!response.ok) throw new Error('Failed')
+    setData(await response.json())
+  } catch {
+    console.error('Failed to fetch <endpoint>')
+  } finally {
+    setLoading(false)
+    setRefreshing(false)
+  }
+}, [])
+
+useEffect(() => { fetchData() }, [fetchData])
+```
+
+## Estados de UI
+
+- **Loading**: Spinner animado com ícone específico do painel
+- **Error**: Console.error (sem toast — minimalista)
+- **Empty**: `if (!data) return null` (protecção de render)
+- **Refreshing**: Ícone RefreshCw com animação `animate-spin`
+
+## Localizações
+
+- **Código**: Padrão replicado em cada `src/pages/*.tsx` (não extraído para hook — simplicidade)
+- **Sessions API**: `src/lib/api/sessions.ts` (único módulo de API extraído)
+
+## Dependências
+
+- **Express-API**: Todos os endpoints REST
+- **Dashboard-Engine**: Ciclo de vida React (mount/unmount)
+- **Metrics**: Eventos de fetch (latência, erros)
+
+## Fornece a
+
+- **Todos os 9 painéis**: Dados actualizados da API
+- **Metrics**: Telemetria de fetch (tempo de resposta, taxa de erro)