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,80 @@
+---
+type: Entity
+layer: wiki
+tags: [stack, dashdescomplicar, backend, observabilidade, sessoes, sqlite, systemd]
+title: "Observabilidade-Sessions"
+---
+
+# Observabilidade-Sessions
+
+Sistema de observabilidade de sessões Claude Code (Espelho). Indexa, armazena e expõe dados de sessões de múltiplos motores IA (Claude Code, Hermes, OpenCode) via SQLite local.
+
+## Responsabilidades
+
+- **Indexação**: Watcher incremental de ficheiros JSONL (Claude Code) + import de BD (Hermes SQLite, OpenCode SQLite)
+- **Armazenamento**: SQLite local (`~/.claude-work/sessions.db`) com schema optimizado
+- **Worklog Import**: Import de worklogs Desk CRM (discussions #31/#32/#33)
+- **Pattern Detection**: Detecção semanal de padrões de uso (tools, skills, erros)
+- **API**: Rota `/api/sessions` (lista + detalhe com eventos)
+- **Sincronização**: Volume bind EasyPanel (`/root/data/dashboard-descomplicar/sessions.db` → `/data/sessions.db`)
+
+## Stack
+
+- **DB**: `better-sqlite3` 12.9 (síncrono, zero-deps)
+- **Watcher**: `chokidar` 5.0 (file system events)
+- **Parser**: `node-html-parser` 7.1 (extração HTML de worklogs)
+- **Runtime**: Node.js 22 via `tsx` (systemd services)
+
+## Componentes do Sistema
+
+| Componente | Ficheiro | Função |
+|---|---|---|
+| Indexer | `api/scripts/sessions-indexer.ts` | Watcher incremental de JSONL |
+| Patterns | `api/scripts/sessions-patterns.ts` | Detector semanal de padrões |
+| Worklog Import | `api/scripts/sessions-worklog-import.ts` | Import de worklogs Desk |
+| DB Layer | `api/services/sessions/db.ts` | Schema, queries, CRUD |
+| Parser | `api/services/sessions/parser.ts` | Parse de ficheiros JSONL |
+| Claude Indexer | `api/services/sessions/indexer.ts` | Indexação específica Claude |
+| Hermes Indexer | `api/services/sessions/hermes-indexer.ts` | Indexação Hermes (`~/.hermes/state.db`) |
+| OpenCode Indexer | `api/services/sessions/opencode-indexer.ts` | Indexação OpenCode (`~/.local/share/opencode/opencode.db`) |
+| MCP Client | `api/services/sessions/mcp-client.ts` | Cliente MCP para Desk CRM |
+| Watcher | `api/services/sessions/watcher.ts` | File watcher eventos |
+| Patterns Engine | `api/services/sessions/patterns.ts` | Análise de padrões (19KB) |
+
+## Fontes de Dados
+
+- **Claude Code**: `~/.claude/projects/*/sessions/*.jsonl` (JSONL)
+- **Hermes**: `~/.hermes/state.db` (SQLite)
+- **OpenCode**: `~/.local/share/opencode/opencode.db` (SQLite)
+- **Gemini**: `~/.claude-work/tool-invocations.jsonl` (via Gemini-Telemetry)
+- **Desk CRM**: Discussions #31, #32, #33 (worklogs)
+
+## Systemd Timers
+
+| Timer | Schedule | Função |
+|---|---|---|
+| `observabilidade-indexer.service` | Sempre ligado (simple) | Watcher incremental |
+| `observabilidade-worklog-import.timer` | Diário 03:00 | Import worklogs Desk |
+| `observabilidade-patterns.timer` | Dom 23:00 | Detecção de padrões |
+
+## Localizações
+
+- **SQLite DB**: `~/.claude-work/sessions.db` (local) / `/data/sessions.db` (container)
+- **Código**: `api/services/sessions/` (10 ficheiros, ~56KB)
+- **Scripts**: `api/scripts/sessions-*.ts` (3 scripts)
+- **Systemd**: `systemd/observabilidade-*.{service,timer}` (5 ficheiros)
+- **Volume**: `/root/data/dashboard-descomplicar/sessions.db` → container
+
+## Dependências
+
+- **Systemd-Timers**: Execução agendada dos scripts
+- **Gemini-Telemetry**: Dados de telemetria Gemini
+- **MySQL-Pool**: Worklogs Desk CRM (discussions)
+- **Express-API**: Rota `/api/sessions` expõe dados
+- **Sistema de Ficheiros**: `~/.claude/`, `~/.hermes/`, `~/.local/share/opencode/`
+
+## Fornece a
+
+- **Painel-Sessoes**: Dados para listagem e detalhe
+- **Express-API**: Rota `/api/sessions`
+- **Sistema IA**: Métricas de uso, padrões, anomalias