{"id":"repo/data-taxonomy","source":"repo","sourceLabel":"repository root","sourcePath":"DATA_TAXONOMY.md","routePath":"/fastapp/public-docs/page/repo/data-taxonomy","rawPath":"/fastapp/public-docs/raw/repo/data-taxonomy","slug":["repo","data-taxonomy"],"slugPath":"repo/data-taxonomy","title":"🧬 DATA TAXONOMY — A Semântica do Dado","description":"Este documento define os eixos de classificação semântica que permitem ao motor Fastapp reagir de forma inteligente à natureza dos dados. No motor Anti Gravity, a semântica governa a infraestrutura. Atualizado para a Ontologia v3 .","headings":["🧬 DATA TAXONOMY — A Semântica do Dado","🏗️ Os 3 Eixos da Taxonomia Semântica","1. Categoria Semântica (object.category)","2. Natureza Arquitetural (object.nature)","3. Orquestração Logística e Roteirização (object.routing type) [NEW]","4. Origem da API (app. e object. )","🛰️ Tipologia de Recursos e Espaço","Tipos de Recurso (object.resource type)","Tipos Espaciais (property.spatial type)","🎨 Os 2 Novos Eixos da Ontologia v3","4. Semântica de Campo (property.semantic)","5. Topologia de Apresentação (module.topology)","⛓️ Restrições de Governança (object.geo constraint)","⛓️ Relacionamentos e Persistência (object.relations)","🏗️ Reação do Motor (Behaviors)","📈 6. Extensões Analíticas (Ontologia v3) [NEW]","Propriedades Analíticas (property)","Eixos de Análise (object)","🔗 Contribuição Dimensional (relation)"],"wordCount":883,"markdown":"# 🧬 DATA TAXONOMY — A Semântica do Dado\r\n\r\nEste documento define os eixos de classificação semântica que permitem ao motor Fastapp reagir de forma inteligente à natureza dos dados. No motor Anti-Gravity, a semântica governa a infraestrutura. Atualizado para a **Ontologia v3**.\r\n\r\n---\r\n\r\n## 🏗️ Os 3 Eixos da Taxonomia Semântica\r\n\r\n### 1. Categoria Semântica (`object.category`)\r\nDefine o \"comportamento de vida\" do dado no ecossistema and impacta diretamente como o gerador de código e o motor de cache operam.\r\n\r\n| Categoria | Descrição | Comportamento Automático (Behavior) |\r\n| :--- | :--- | :--- |\r\n| **master** | Dados mestres e estáveis (ex: Corretoras, Usuários). | O motor prioriza caches agressivos, dropdowns globais e otimiza buscas por nome/label. |\r\n| **transactional** | Eventos e registros de fluxo com alta volatilidade (ex: Leads, Transações). | Ativa automaticamente índices por data, logs de auditoria e filtros de período/time-scales. |\r\n| **configuration** | Parâmetros de ajuste do sistema ou do usuário (ex: Settings). | O motor gera interfaces simplificadas de \"Settings\", ocultando listagens densas e focando em editores diretos. |\r\n\r\n### 2. Natureza Arquitetural (`object.nature`)\r\nDefine a \"física\" do dado, ou seja, onde ele reside fisicamente no backend.\r\n\r\n- **physical**: Possui uma tabela própria no DB com ID único global, sendo plenamente referenciável por qualquer outro objeto.\r\n- **embedded**: Vive dentro do JSON de um objeto pai (Document-based). Não possui tabela própria.\r\n- **virtual**: Calculado em runtime (ex: saldo total, status derivado).\r\n\r\n### 3. Orquestração Logística e Roteirização (`object.routing_type`) [NEW]\r\nDefine como o motor interpreta o dado em um contexto geográfico e de transporte.\r\n\r\n- **waypoint**: O dado representa um ponto de parada ou serviço (ex: Local de Entrega, Checkpoint). Ativa o calculo de ETAs e janelas de serviço.\r\n- **route**: O dado representa um trajeto completo ligando múltiplos waypoints. Ativa a visualização de linhas de desejo e trajetos otimizados.\r\n\r\n### 4. Origem da API (`app.*` e `object.*`)\r\nDefine como o objeto resolve a fonte de dados em runtime.\r\n\r\n- **Default**: `provider = local` (usa `/api/v1/data/:object` com storage interno Fastapp).\r\n- **App-level override**: `app.api_base_url` + `app.provider = external-api` (ou `app.is_api_data_source = true`).\r\n- **Object-level override**: `object.api_url` (tem precedência sobre qualquer config do app).\r\n- **Compatibilidade legado**: `isApiDataSource` e `_legacy.source_isApiDataSource` continuam aceitos.\r\n\r\n---\r\n\r\n## 🛰️ Tipologia de Recursos e Espaço\r\n\r\n### Tipos de Recurso (`object.resource_type`)\r\nClassifica entidades para algoritmos de alocação de recursos finitos.\r\n- **human**: Técnicos, motoristas, profissionais (possuem agenda e especialidade).\r\n- **mobile_asset**: Veículos, equipamentos móveis (possuem posição GPS e capacidade).\r\n- **fixed_asset**: Salas, ferramentas fixas (possuem disponibilidade local).\r\n\r\n### Tipos Espaciais (`property.spatial_type`)\r\nDefine a geometria do dado para o motor GIS.\r\n- **point**: Coordenadas geográficas simples (Lat/Long). Ativa o `CoreMapRenderer`.\r\n- **polygon**: Áreas de cobertura ou cercas eletrônicas (Geofencing). Ativa buscas por contenção.\r\n\r\n---\r\n\r\n## 🎨 Os 2 Novos Eixos da Ontologia v3\r\n\r\n### 4. Semântica de Campo (`property.semantic`)\r\nDefine a **natureza semântica** de um campo individual, ativando renderização especializada.\r\n\r\n| Semantic | Renderização Automática | Exemplo |\r\n| :--- | :--- | :--- |\r\n| `asset` | Upload de arquivo com preview | Foto do produto, documento PDF |\r\n| `money` | Máscara monetária (R$ 1.234,56) | Preço, salário |\r\n| `percentage` | Slider ou input com sufixo % | Margem, desconto |\r\n| `phone` | Máscara de telefone + link `tel:` | WhatsApp, comercial |\r\n| `email` | Validação + link `mailto:` | Email principal |\r\n| `url` | Link clicável externo | Website, LinkedIn |\r\n| `color` | Color picker nativo | Cor do tema, cor de status |\r\n| `cpf` / `cnpj` | Máscara de documento | CPF, CNPJ |\r\n\r\n### 5. Topologia de Apresentação (`module.topology`)\r\nDefine a **dinâmica de navegação** de um módulo ou objeto no app.\r\n\r\n| Topology | Comportamento | Exemplo |\r\n| :--- | :--- | :--- |\r\n| `focal` | Dashboard central com métricas e visão consolidada | Módulo de Logistica com mapa |\r\n| `connected` | Lista que se conecta a detalhes (master-detail) | Pedidos → Itens |\r\n| `hierarchical` | Árvore navegável (tree view) | Categorias → Subcategorias |\r\n\r\n## ⛓️ Restrições de Governança (`object.geo_constraint`)\r\nDefine regras de negócio espaciais automatizadas.\r\n- **geofencing**: Garante que uma ação só ocorra dentro de um polígono definido.\r\n- **area_of_action**: Vincula recursos a territórios específicos, impedindo alocação fora da zona permitida.\r\n\r\n---\r\n\r\n## ⛓️ Relacionamentos e Persistência (`object.relations`)\r\n... (Inalterado) ...\r\n\r\n---\r\n\r\n## 🏗️ Reação do Motor (Behaviors)\r\n\r\nA taxonomia permite a **Escada de Abstração**:\r\n\r\n1.  **L1 (Atômico)**: Tipos `location` ou `area` ativam automaticamente o seletor de mapa.\r\n2.  **L2 (Padrões)**: Objetos com `routing_type: 'waypoint'` ativam o `ui_mode: 'dispatch_map'`.\r\n3.  **L3 (Orquestração)**: O motor implementa a **Exclusão Geotemporal** — impede que um recurso seja alocado em dois locais se o tempo de deslocamento calculado (via Routes API) for insuficiente.\r\n\r\n## 📈 6. Extensões Analíticas (Ontologia v3) [NEW]\r\n\r\nDefine como o motor interpreta o dado para geração de insights, métricas e visualizações de BI.\r\n\r\n### Propriedades Analíticas (`property`)\r\n| Atributo | Tipo | Descrição | Comportamento Reativo |\r\n| :--- | :--- | :--- | :--- |\r\n| `aggregation` | `enum` | [sum, avg, min, max, count, distinct, none] | Define a estatística primária. `money` assume `sum`, `percentage` assume `avg`. |\r\n| `target` | `number` | Valor de meta ou baseline. | Ativa o indicador de progresso e barra de performance no `BiWidget`. |\r\n\r\n### Eixos de Análise (`object`)\r\n| Atributo | Tipo | Descrição | Exemplo |\r\n| :--- | :--- | :--- | :--- |\r\n| `temporal_axis` | `string` | Campo de data usado como referência de tempo principal. | `closed_at` em vendas, `created_at` default. |\r\n| `temporal_resolution` | `enum` | [day, week, month, year, auto] | Define a granularidade padrão dos gráficos de série temporal. |\r\n| `target_property` | `string` | Campo que define o valor de meta para este objeto. | `meta_mensal` em `broker`. |\r\n\r\n### 🔗 Contribuição Dimensional (`relation`)\r\n| Atributo | Tipo | Descrição | Comportamento Reativo |\r\n| :--- | :--- | :--- | :--- |\r\n| `contribution_property` | `string` | Campo do objeto filho que deve ser somado no agrupamento. | `valor` em `sale` agrupado por `broker`. |\r\n\r\n---\r\n\r\n---\r\n\r\n> [!IMPORTANT]\r\n> A taxonomia é o que transforma JSON morto em uma aplicação viva. Toda alteração nestes atributos deve seguir o **Protocolo FADAP**.\r\n\r\n---\r\n\r\n> \"Na arquitetura Anti-Gravity, os dados descrevem não apenas o que são, mas como devem se comportar. A Ontologia v3 estende isso para *como devem parecer*, *como devem navegar* e *como devem ser medidos*.\"\r\n"}