@wibi-global/sdk 0.1.0 → 0.1.2

package/dist/sdk/src/data/serialization/dashboard-serialization.types.ts

@@ -0,0 +1,430 @@
+export interface SerializedMetadata {
+  name: string
+  description: string
+  schema_version: string
+  generated_at: string
+  category: string
+  is_public: boolean
+  /** Cor de fundo global do dashboard (hex, rgb, ou CSS gradient) */
+  background_color?: string
+  /** Cor do texto padrão do dashboard */
+  text_color?: string
+  /** Fonte customizada para o dashboard */
+  font_family?: string
+  /** Espaçamento entre seções em px */
+  section_gap?: number
+  /** Padding geral do dashboard em px */
+  padding?: number
+}
+
+export type DatePeriodType = 'D' | 'S' | 'M' | 'T' | 'SE' | 'A' | 'W' | 'Q' | 'Y' | 'SP' | 'CUSTOM'
+
+export interface SerializedDateFilter {
+  id: string
+  type: 'date'
+  label: string
+  default_period_type: DatePeriodType
+  fallback_days?: number
+  binds_to: string[]
+}
+
+export interface SerializedEmpresaFilter {
+  id: string
+  type: 'empresa'
+  label: string
+  placeholder: string
+  default_value: number
+  sql_template: string
+}
+
+export type SerializedFilter = SerializedDateFilter | SerializedEmpresaFilter
+
+export interface SerializedSection {
+  id: string
+  title: string
+  columns: number
+  responsive?: {
+    sm?: number
+    md?: number
+    xl?: number
+  }
+  items: string[]
+  /** Cor de fundo da seção */
+  background_color?: string
+  /** Cor do texto da seção */
+  text_color?: string
+  /** Raio de borda da seção em px */
+  border_radius?: number
+  /** Padding interno da seção em px */
+  padding?: number
+  /** Mostrar ou ocultar o título da seção */
+  show_title?: boolean
+}
+
+export interface SerializedLayout {
+  mode: 'sections'
+  sections: SerializedSection[]
+}
+
+export type SerializedWidgetType =
+  | 'kpi'
+  | 'chart'
+  | 'grid'
+  | 'progress-list'
+  | 'gauge'
+  | 'funnel'
+  | 'waterfall'
+  | 'heatmap'
+  | 'scatter'
+  | 'treemap'
+  | 'sankey'
+  | 'graph'
+  | 'sunburst'
+  | 'tree'
+  | 'radar'
+  | 'candlestick'
+  | 'boxplot'
+  | 'parallel'
+  | 'themeriver'
+  | 'sparkline'
+  | 'multi-card'
+  | 'panel'
+  | 'date'
+  | 'companies'
+  | 'heading'
+  | 'text'
+  | 'image'
+  | 'divider'
+  | 'spacer'
+
+export interface SerializedKpiProperties {
+  widget_variant: 'kpi-card' | 'card-component'
+  label: string
+  value_field: string
+  value_format: 'currency' | 'percent' | 'days' | 'days-absolute' | 'number'
+  currency?: string
+  decimals?: number
+  caption: string
+  icon: string
+  tone: string
+  thresholds?: Record<string, number | boolean>
+  card_properties?: {
+    prefix?: string
+    aggregation?: string
+    subtitle?: string
+    color?: string
+    compact?: boolean
+  }
+}
+
+export interface SerializedChartProperties {
+  /** Tipo visual do gráfico */
+  chart_type: 'bar' | 'line' | 'area' | 'pie' | 'donut' | 'horizontal_bar' | 'stacked_bar' | 'scatter'
+  /** Campo do eixo X (categorias) */
+  x_field: string
+  /** Campo de valor do eixo Y (série única) */
+  y_field?: string
+  /** Campos de valor do eixo Y (múltiplas séries) */
+  y_fields?: string[]
+  /** Campo para agrupar dados em séries automáticas */
+  group_by_field?: string
+  /** Tipo de agregação: sum, avg, count, min, max, first, last */
+  aggregation?: string
+  /** Limitar aos top N registros */
+  top_n?: number
+  /** Ordenação dos dados: asc | desc */
+  sort_order?: string
+  /** Título exibido no widget */
+  title?: string
+  /** Descrição curta abaixo do título */
+  description?: string
+  /** Exibir legenda */
+  show_legend?: boolean
+  /** Exibir rótulos com valores em cada barra/ponto/fatia */
+  show_data_labels?: boolean
+  /** Texto quando não há dados */
+  empty_state?: string
+
+  // — Barras —
+  /** Cada barra/fatia recebe cor diferente da paleta do tema. Use para rankings e top N. */
+  alternate_colors?: boolean
+  /** Orientação: 'vertical' (padrão) ou 'horizontal' */
+  orientation?: 'vertical' | 'horizontal'
+  /** Largura máxima das barras em % (1-100) */
+  bar_width?: number
+  /** Rotacionar labels do eixo X em 45° */
+  rotate_labels?: boolean
+  /** Habilitar zoom interativo */
+  enable_zoom?: boolean
+
+  // — Linhas —
+  /** Suavizar curvas (line/area) */
+  smooth?: boolean
+  /** Mostrar pontos nos vértices */
+  show_symbol?: boolean
+  /** Tamanho dos pontos */
+  symbol_size?: number
+  /** Estilo da linha: solid, dashed, dotted */
+  line_style?: string
+
+  // — Área —
+  /** Opacidade do preenchimento (0 a 1) */
+  area_opacity?: number
+  /** Usar gradiente no preenchimento */
+  gradient?: boolean
+
+  // — Pizza/Donut —
+  /** Raio externo da pizza em % */
+  radius?: number
+  /** Raio interno (furo) para donut em % */
+  inner_radius?: number
+  /** Tipo rose: 'radius', 'area', false */
+  rose_type?: string | boolean
+  /** Ângulo inicial em graus */
+  start_angle?: number
+  /** Ângulo mínimo de cada fatia */
+  min_angle?: number
+  /** Exibir porcentagem nos labels */
+  show_percentage?: boolean
+  /** Posição dos labels: outside, inside, center */
+  label_position?: string
+  /** Máximo de categorias na pizza */
+  max_categories?: number
+  /** Critério de ordenação para pizza: value | name */
+  sort_by?: string
+}
+
+export interface SerializedGridColumnFormat {
+  /** Tipo de formatação: text, number, currency, percentage, date, datetime, boolean */
+  type?: 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'datetime' | 'boolean'
+  /** Número de casas decimais */
+  decimals?: number
+  /** Moeda (padrão BRL): BRL, USD, MXN, COP, CLP */
+  currency?: string
+  /** Locale (padrão pt-BR) */
+  locale?: string
+  /** Notação: standard, compact, scientific */
+  notation?: 'standard' | 'compact' | 'scientific' | 'engineering'
+}
+
+export interface SerializedGridColumnDef {
+  /** ID do campo (deve existir nos dados da query) */
+  id: string
+  /** Label exibido no cabeçalho */
+  header: string
+  /** Largura fixa em px ou string CSS (ex: '200px', '25%') */
+  width?: number | string
+  /** Largura mínima em px */
+  min_width?: number
+  /** Se a coluna é ordenável (padrão: true) */
+  sortable?: boolean
+  /** Classe CSS adicional para o cabeçalho */
+  header_class?: string
+  /** Classe CSS adicional para as células */
+  cell_class?: string
+  /** Formatação automática do valor */
+  format?: SerializedGridColumnFormat
+}
+
+export interface SerializedGridProperties {
+  title: string
+  page_size: number
+  columns: string[]
+  column_labels: Record<string, string>
+  enable_filters: boolean
+  enable_export: boolean
+  enable_pagination: boolean
+  enable_column_settings: boolean
+  enable_fullscreen: boolean
+  enable_aggregation: boolean
+  /** Definições avançadas por coluna (DataGridV2). Se presente, tem prioridade sobre columns + column_labels. */
+  column_defs?: SerializedGridColumnDef[]
+  /** Ordenação inicial: campo e direção */
+  default_sort?: { column_id: string; direction: 'asc' | 'desc' }
+  /** Usar DataGridV2 em vez do DataGrid legado (padrão: false para compatibilidade) */
+  use_grid_v2?: boolean
+  /** Mensagem quando não há dados */
+  empty_message?: string
+  /** Mensagem durante carregamento */
+  loading_message?: string
+}
+
+export interface SerializedPanelAction {
+  path: string
+  title: string
+  description: string
+}
+
+export interface SerializedProgressListProperties {
+  /** Campo de label (categoria/nome exibido na linha) */
+  labelField: string
+  /** Campo de valor numérico para as barras */
+  valueField: string
+  /** Agregação: sum | avg | count | min | max */
+  aggregation?: 'sum' | 'avg' | 'count' | 'min' | 'max'
+  /** Número máximo de itens exibidos */
+  maxItems?: number
+  /** Exibir valor numérico ao lado da barra */
+  showValues?: boolean
+  /** Exibir percentual ao lado da barra */
+  showPercentage?: boolean
+  /** Formato do valor: number | currency | compact | percentage */
+  valueFormat?: 'number' | 'currency' | 'compact' | 'percentage'
+  /** Altura em px das barras de progresso */
+  barHeight?: number
+  /** Esquema de cores: gradient | single | custom */
+  colorScheme?: 'gradient' | 'single' | 'custom'
+  /** Cor primária (usada em colorScheme='single') */
+  primaryColor?: string
+  /** Ordenação: value | label | none */
+  sortBy?: 'value' | 'label' | 'none'
+  /** Direção da ordenação: asc | desc */
+  sortOrder?: 'asc' | 'desc'
+}
+
+export interface SerializedPanelProperties {
+  panel_type: 'risk-summary' | 'info' | 'actions'
+  title: string
+  score_field?: string
+  score_format?: string
+  score_thresholds?: Record<string, number>
+  diagnostic_fields?: string[]
+  actions?: SerializedPanelAction[]
+  sources?: string[]
+}
+
+export interface SerializedDateWidgetProperties {
+  label?: string
+  default_period_type?: DatePeriodType
+  fallback_days?: number
+}
+
+export interface SerializedCompaniesWidgetProperties {
+  placeholder?: string
+  show_icon?: boolean
+  auto_select_first?: boolean
+  default_value?: number
+}
+
+// ─── Decorative Elements ─────────────────────────────────────────────
+
+export interface SerializedHeadingProperties {
+  /** Nível do heading: h1, h2, h3, h4 */
+  level: 'h1' | 'h2' | 'h3' | 'h4'
+  /** Texto do heading */
+  content: string
+  /** Alinhamento: left, center, right */
+  align?: 'left' | 'center' | 'right'
+  /** Cor do texto (hex, rgb, nome CSS) */
+  color?: string
+  /** Subtítulo opcional abaixo do heading */
+  subtitle?: string
+  /** Cor do subtítulo */
+  subtitle_color?: string
+  /** Ícone opcional (nome Lucide) */
+  icon?: string
+}
+
+export interface SerializedTextProperties {
+  /** Conteúdo do texto (suporta markdown básico: **bold**, *italic*, [links]) */
+  content: string
+  /** Alinhamento: left, center, right, justify */
+  align?: 'left' | 'center' | 'right' | 'justify'
+  /** Tamanho da fonte: xs, sm, base, lg, xl */
+  font_size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl'
+  /** Cor do texto */
+  color?: string
+  /** Cor de fundo */
+  background_color?: string
+  /** Padding interno em px */
+  padding?: number
+  /** Raio de borda em px */
+  border_radius?: number
+  /** Cor da borda (se definido, aplica borda de 1px) */
+  border_color?: string
+}
+
+export interface SerializedImageProperties {
+  /** URL da imagem */
+  src: string
+  /** Texto alternativo */
+  alt: string
+  /** Ajuste da imagem: cover, contain, fill, none */
+  object_fit?: 'cover' | 'contain' | 'fill' | 'none'
+  /** Altura fixa em px (se não definido, usa aspect ratio natural) */
+  height?: number
+  /** Raio de borda em px */
+  border_radius?: number
+  /** Link ao clicar na imagem */
+  href?: string
+  /** Legenda abaixo da imagem */
+  caption?: string
+}
+
+export interface SerializedDividerProperties {
+  /** Estilo da linha: solid, dashed, dotted */
+  style?: 'solid' | 'dashed' | 'dotted'
+  /** Cor da linha */
+  color?: string
+  /** Espessura em px */
+  thickness?: number
+  /** Margem vertical em px */
+  margin?: number
+  /** Texto opcional no centro do divider */
+  label?: string
+}
+
+export interface SerializedSpacerProperties {
+  /** Altura do espaçamento em px */
+  height: number
+}
+
+export type SerializedWidgetProperties =
+  | SerializedKpiProperties
+  | SerializedChartProperties
+  | SerializedGridProperties
+  | SerializedProgressListProperties
+  | SerializedPanelProperties
+  | SerializedDateWidgetProperties
+  | SerializedCompaniesWidgetProperties
+  | SerializedHeadingProperties
+  | SerializedTextProperties
+  | SerializedImageProperties
+  | SerializedDividerProperties
+  | SerializedSpacerProperties
+
+export interface SerializedWidget {
+  id: string
+  title: string
+  widget_type: SerializedWidgetType
+  section_id: string
+  order: number
+  col_span: number
+  height?: number
+  properties: SerializedWidgetProperties
+  query_id: string | null
+  /** Cor de fundo do widget */
+  background_color?: string
+  /** Cor do texto do widget */
+  text_color?: string
+  /** Raio de borda em px */
+  border_radius?: number
+  /** Ocultar borda do widget */
+  borderless?: boolean
+}
+
+export interface SerializedQuery {
+  id: string
+  description: string
+  sql_template: string
+  sources: string[]
+  output_fields: string[]
+}
+
+export interface SerializedDashboard {
+  metadata: SerializedMetadata
+  filters: SerializedFilter[]
+  layout: SerializedLayout
+  widgets: SerializedWidget[]
+  queries: SerializedQuery[]
+}

package/dist/sdk/src/data/serialization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/data/serialization/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,qBAAqB,EACrB,8BAA8B,EAC9B,mCAAmC,EACnC,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,eAAe,EACf,cAAc,GACf,MAAM,oCAAoC,CAAA"}

package/dist/sdk/src/data/serialization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/data/serialization/index.ts"],"names":[],"mappings":""}

package/dist/sdk/src/data/syntax.wbx

@@ -0,0 +1,155 @@
+{
+  "__CONTEXT_BLOCK__": {
+    "block_name": "DB_SCHEMA_SYNTAX",
+    "block_role": "SOURCE_OF_TRUTH_FOR_SQL_SYNTAX",
+    "llm_instruction": "Este bloco define a sintaxe SQL permitida. Quando houver SQL no TSX, siga este bloco e não misture dialetos."
+  },
+  "sql_syntax": {
+    "clickhouse": [
+      "",
+      "=== SINTAXE CLICKHOUSE ===",
+      "Você está conectado a um banco CLICKHOUSE. Use a sintaxe correta do ClickHouse:",
+      "",
+      "⚠️ As views já retornam automaticamente a versão mais recente dos dados.",
+      "NÃO é necessário usar a palavra-chave FINAL nas queries.",
+      "Exemplo: SELECT colunas FROM vw_clientes WHERE condicao;",
+      "",
+      "FUNÇÕES DE DATA:",
+      "- now() - data/hora atual",
+      "- today() - data atual",
+      "- yesterday() - ontem",
+      "- toDate(coluna) - converter para date",
+      "- subtractDays(now(), 7) - 7 dias atrás",
+      "- subtractMonths(now(), 1) - 1 mês atrás",
+      "- dateDiff('day', data1, data2) - diferença em dias",
+      "- toYear(coluna) - extrair ano",
+      "- toMonth(coluna) - extrair mês (número)",
+      "- monthName(coluna) - nome do mês (use monthName, NÃO toMonthName)",
+      "- toDayOfMonth(coluna) - dia do mês",
+      "- toDayOfWeek(coluna) - dia da semana",
+      "- toHour(coluna) - hora",
+      "",
+      "TRUNCAR DATAS (usar início de período):",
+      "⚠️ CRÍTICO: NO CLICKHOUSE NÃO EXISTE FUNÇÃO trunc() PARA DATAS!",
+      "- toStartOfDay(coluna) - início do dia (00:00:00)",
+      "- toStartOfWeek(coluna) - início da semana (segunda-feira)",
+      "- toStartOfMonth(coluna) - primeiro dia do mês",
+      "- toStartOfQuarter(coluna) - primeiro dia do trimestre",
+      "- toStartOfYear(coluna) - primeiro dia do ano (01/01)",
+      "- toStartOfHour(coluna) - início da hora (:00:00)",
+      "- toStartOfMinute(coluna) - início do minuto (:00)",
+      "",
+      "FUNÇÕES DE FORMATAÇÃO:",
+      "- formatDateTime(coluna, 'formato') - formatar data/hora",
+      "- formatDateTime(coluna, 'formato', 'timezone') - formatar com timezone específico",
+      "- toString(coluna) - converter para string",
+      "",
+      "FORMATAÇÃO DE DATA/HORA COM TIMEZONE:",
+      "⚠️ IMPORTANTE: Use timezone 'UTC' ou 'America/Sao_Paulo' quando necessário",
+      "- formatDateTime(coluna, '%Y-%m-%d', 'UTC') - formata em UTC",
+      "- formatDateTime(coluna, '%d/%m/%Y %H:%M:%S', 'America/Sao_Paulo') - horário de Brasília",
+      "- Formatos comuns:",
+      "  * '%Y-%m-%d' - 2024-11-20",
+      "  * '%d/%m/%Y' - 20/11/2024",
+      "  * '%Y-%m-%d %H:%M:%S' - 2024-11-20 14:30:00",
+      "  * '%d/%m/%Y %H:%M' - 20/11/2024 14:30",
+      "",
+      "EXEMPLOS CORRETOS:",
+      "✅ WHERE data_venda >= subtractDays(today(), 7)",
+      "✅ WHERE toYear(data_venda) = toYear(now())",
+      "✅ WHERE data_venda >= today() - INTERVAL 7 DAY",
+      "✅ WHERE data_venda >= toStartOfMonth(today())  -- Primeiro dia do mês atual",
+      "✅ WHERE data_venda >= toStartOfYear(today())   -- Primeiro dia do ano atual",
+      "✅ WHERE data_venda >= toStartOfWeek(today())   -- Início da semana (segunda)",
+      "✅ SELECT monthName(data_venda) AS mes",
+      "✅ SELECT toMonth(data_venda) AS mes_numero  -- Retorna 1-12",
+      "✅ SELECT formatDateTime(data_venda, '%Y-%m-%d') AS data",
+      "✅ SELECT formatDateTime(data_venda, '%d/%m/%Y', 'America/Sao_Paulo') AS data_br",
+      "✅ SELECT formatDateTime(now(), '%Y-%m-%d %H:%M:%S', 'UTC') AS data_hora_utc",
+      "",
+      "EXEMPLOS ERRADOS (NÃO USE NO CLICKHOUSE):",
+      "❌ WHERE data_venda >= trunc(today(), 'month')  -- trunc() NÃO EXISTE! Use toStartOfMonth()",
+      "❌ WHERE data_venda >= TRUNC(SYSDATE, 'MM')  -- Sintaxe Oracle, não ClickHouse",
+      "❌ WHERE data_venda >= DATE_TRUNC('month', NOW())  -- Sintaxe PostgreSQL, não ClickHouse",
+      "❌ SELECT toMonthName(data_venda)  -- Função não existe, use monthName()",
+      "",
+      "EXEMPLOS PRÁTICOS DE PERÍODOS:",
+      "-- Mês atual (do dia 1 até hoje)",
+      "✅ WHERE data_venda >= toStartOfMonth(today()) AND data_venda <= today()",
+      "",
+      "-- Ano atual (do dia 1/1 até hoje)",
+      "✅ WHERE data_venda >= toStartOfYear(today()) AND data_venda <= today()",
+      "",
+      "-- Semana atual (de segunda até hoje)",
+      "✅ WHERE data_venda >= toStartOfWeek(today()) AND data_venda <= today()",
+      "",
+      "-- Mês anterior completo",
+      "✅ WHERE data_venda >= toStartOfMonth(subtractMonths(today(), 1))",
+      "   AND data_venda < toStartOfMonth(today())",
+      "",
+      "PLACEHOLDERS DE FILTRO DINÂMICO (usar em sql_template):",
+      "⚠️ CRÍTICO: Use SEMPRE os placeholders abaixo para filtros de período e empresa.",
+      "O runtime substitui os placeholders antes de enviar a query ao ClickHouse.",
+      "NÃO envie templates literais como '{{startDate}}' sem que o runtime resolva — isso causará erro de parse.",
+      "",
+      "PLACEHOLDERS CANÔNICOS (formatos aceitos pelo runtime):",
+      "  {{startDate}}  — data inicial do período selecionado (string 'YYYY-MM-DD')",
+      "  {{endDate}}    — data final do período selecionado (string 'YYYY-MM-DD')",
+      "",
+      "ALIASES TAMBÉM ACEITOS (evite usar, prefira os canônicos acima):",
+      "  ${startDate}   — equivalente a {{startDate}}",
+      "  ${endDate}     — equivalente a {{endDate}}",
+      "  {{start_date}} — equivalente a {{startDate}}",
+      "  {{end_date}}   — equivalente a {{endDate}}",
+      "",
+      "EXEMPLOS CORRETOS DE sql_template COM PLACEHOLDERS:",
+      "✅ WHERE data_movimento >= '{{startDate}}' AND data_movimento <= '{{endDate}}'",
+      "✅ WHERE data_venda >= '{{startDate}}' AND data_venda <= '{{endDate}}'",
+      "✅ WHERE data_emissao BETWEEN '{{startDate}}' AND '{{endDate}}'",
+      "",
+      "EXEMPLOS ERRADOS:",
+      "❌ WHERE data_movimento >= subtractDays(today(), 30)  -- ignora filtro do usuário",
+      "❌ WHERE data_movimento >= '2024-01-01'              -- data hardcoded",
+      "",
+      "RESPOSTA DA API — camelCase:",
+      "⚠️ A API retorna os dados em camelCase (camel_case: true).",
+      "Use nomes de alias em camelCase nas queries para que o runtime os receba corretamente.",
+      "Exemplos:",
+      "✅ SELECT sum(valor_total) AS totalFaturamento",
+      "✅ SELECT count() AS totalPedidos",
+      "✅ SELECT fornecedor AS nomeFornecedor",
+      "❌ SELECT sum(valor_total) AS total_faturamento  -- snake_case será convertido para totalFaturamento mesmo assim",
+      "",
+      "AGREGAÇÕES:",
+      "- LIMIT 10 (não TOP 10)",
+      "- GROUP BY pode usar alias ou índice da coluna",
+      "",
+      "REGRAS PARA CTEs (Common Table Expressions):",
+      "⚠️ CRÍTICO: Estruture CTEs de forma progressiva e linear",
+      "1. NUNCA faça JOIN duplicado: se tabela X já foi unida na CTE anterior, use os dados dela diretamente",
+      "2. GROUP BY: toda coluna no SELECT deve estar no GROUP BY (exceto agregações)",
+      "3. Fluxo correto: Filtros → Agregar granular → JOIN dimensões → Agregar final",
+      "4. Valide sempre: 'a coluna X existe no SELECT da CTE anterior?'",
+      "5. JOINs com dimensões (produtos, clientes, rotas) só na CTE onde serão agregados",
+      "",
+      "✅ EXEMPLO CORRETO DE CTE:",
+      "WITH vendas_filtradas AS (",
+      "    SELECT id_cliente, id_produto, SUM(valor_total) AS total",
+      "    FROM vw_vendas",
+      "    WHERE data_venda >= toStartOfMonth(today())",
+      "    GROUP BY id_cliente, id_produto",
+      "),",
+      "vendas_com_cliente AS (",
+      "    SELECT vf.*, c.nome_completo",
+      "    FROM vendas_filtradas vf",
+      "    INNER JOIN vw_clientes c ON vf.id_cliente = c.id_cliente  -- JOIN apenas aqui",
+      ")",
+      "SELECT * FROM vendas_com_cliente",
+      "",
+      "❌ EXEMPLO ERRADO:",
+      "-- Não faça JOIN duplicado em múltiplas CTEs com a mesma tabela",
+      "",
+      ""
+    ]
+  }
+}

package/dist/sdk/src/data/view-categories.wbx

@@ -0,0 +1,88 @@
+{
+    "__CONTEXT_BLOCK__": {
+        "block_name": "VIEW_CATEGORIES",
+        "block_role": "SOURCE_OF_TRUTH_FOR_VIEW_CATEGORY_RESTRICTIONS",
+        "llm_instruction": "Este arquivo define quais views SQL sao permitidas para cada categoria de dashboard. Ao gerar queries, leia project.category de dashboard.context.json e use SOMENTE as views listadas na categoria correspondente. Se a view nao estiver na lista da categoria, ela NAO pode ser usada. O campo __doc__ de cada categoria explica o contexto de negocio."
+    },
+    "agro": {
+        "__doc__": "Agronegocio. Movimentacoes de produtos agricolas, faturamento, fornecedores, logistica agro. Dados importados de sistema agrologico.",
+        "views": ["vw_base_agrolog"],
+        "strict": true
+    },
+    "comercial": {
+        "__doc__": "Comercial / Vendas. Analises de faturamento, clientes, vendedores, metas, rotas, produtos, precos, positivacao e cobertura.",
+        "views": [
+            "vw_vendas_validas",
+            "vw_clientes",
+            "vw_clientes_estatisticas",
+            "vw_clientes_rotas",
+            "vw_vendedores",
+            "vw_rotas",
+            "vw_rotas_vendedores",
+            "vw_produtos",
+            "vw_produtos_precos_detalhes",
+            "vw_metas",
+            "vw_metas_produtos",
+            "vw_empresas",
+            "vw_calendario",
+            "vw_calendario_rotas",
+            "vw_positivacao_semanal_cliente",
+            "vw_positivacao_semanal_fornecedor",
+            "vw_positivacao_semanal_grupo",
+            "vw_positivacao_semanal_produto",
+            "vw_positivacao_semanal_secao",
+            "vw_positivacao_semanal_subgrupo"
+        ],
+        "strict": true
+    },
+    "financeiro": {
+        "__doc__": "Financeiro. Contas a pagar, contas a receber, movimentacao de contas, plano de contas, fornecedores e empresas.",
+        "views": [
+            "vw_financ_cp_parcelas",
+            "vw_financ_cr_parcelas",
+            "vw_financ_mov_contas",
+            "vw_plano_contas",
+            "vw_fornecedores",
+            "vw_clientes",
+            "vw_empresas",
+            "vw_calendario"
+        ],
+        "strict": true
+    },
+    "producao": {
+        "__doc__": "Producao / Industria. Ordens de producao, fichas tecnicas, componentes, etapas produtivas, equipamentos e custos.",
+        "views": [
+            "vw_ordem_producao",
+            "vw_ordem_producao_etapas",
+            "vw_ordem_producao_etapas_equip",
+            "vw_ordem_producao_itens",
+            "vw_ordem_producao_itens_comp",
+            "vw_ficha_tecnica",
+            "vw_ficha_tecnica_detalhes",
+            "vw_ficha_tecnica_acabados",
+            "vw_ficha_tecnica_acabados_emb",
+            "vw_produtos",
+            "vw_empresas",
+            "vw_calendario"
+        ],
+        "strict": true
+    },
+    "logistica": {
+        "__doc__": "Logistica / Frota. Abastecimentos, custos logisticos, estoque e operacoes de movimentacao.",
+        "views": [
+            "vw_abastecimentos",
+            "vw_custos",
+            "vw_estoque_operacoes",
+            "vw_produtos",
+            "vw_fornecedores",
+            "vw_empresas",
+            "vw_calendario"
+        ],
+        "strict": true
+    },
+    "geral": {
+        "__doc__": "Categoria generica. Sem restricao de views — todas as views listadas em views.wbx sao permitidas.",
+        "views": "__ALL__",
+        "strict": false
+    }
+}