# 🧬 DATA TAXONOMY — A Semântica do Dado 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**. --- ## 🏗️ Os 3 Eixos da Taxonomia Semântica ### 1. Categoria Semântica (`object.category`) Define o "comportamento de vida" do dado no ecossistema and impacta diretamente como o gerador de código e o motor de cache operam. | Categoria | Descrição | Comportamento Automático (Behavior) | | :--- | :--- | :--- | | **master** | Dados mestres e estáveis (ex: Corretoras, Usuários). | O motor prioriza caches agressivos, dropdowns globais e otimiza buscas por nome/label. | | **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. | | **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. | ### 2. Natureza Arquitetural (`object.nature`) Define a "física" do dado, ou seja, onde ele reside fisicamente no backend. - **physical**: Possui uma tabela própria no DB com ID único global, sendo plenamente referenciável por qualquer outro objeto. - **embedded**: Vive dentro do JSON de um objeto pai (Document-based). Não possui tabela própria. - **virtual**: Calculado em runtime (ex: saldo total, status derivado). ### 3. Orquestração Logística e Roteirização (`object.routing_type`) [NEW] Define como o motor interpreta o dado em um contexto geográfico e de transporte. - **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. - **route**: O dado representa um trajeto completo ligando múltiplos waypoints. Ativa a visualização de linhas de desejo e trajetos otimizados. ### 4. Origem da API (`app.*` e `object.*`) Define como o objeto resolve a fonte de dados em runtime. - **Default**: `provider = local` (usa `/api/v1/data/:object` com storage interno Fastapp). - **App-level override**: `app.api_base_url` + `app.provider = external-api` (ou `app.is_api_data_source = true`). - **Object-level override**: `object.api_url` (tem precedência sobre qualquer config do app). - **Compatibilidade legado**: `isApiDataSource` e `_legacy.source_isApiDataSource` continuam aceitos. --- ## 🛰️ Tipologia de Recursos e Espaço ### Tipos de Recurso (`object.resource_type`) Classifica entidades para algoritmos de alocação de recursos finitos. - **human**: Técnicos, motoristas, profissionais (possuem agenda e especialidade). - **mobile_asset**: Veículos, equipamentos móveis (possuem posição GPS e capacidade). - **fixed_asset**: Salas, ferramentas fixas (possuem disponibilidade local). ### Tipos Espaciais (`property.spatial_type`) Define a geometria do dado para o motor GIS. - **point**: Coordenadas geográficas simples (Lat/Long). Ativa o `CoreMapRenderer`. - **polygon**: Áreas de cobertura ou cercas eletrônicas (Geofencing). Ativa buscas por contenção. --- ## 🎨 Os 2 Novos Eixos da Ontologia v3 ### 4. Semântica de Campo (`property.semantic`) Define a **natureza semântica** de um campo individual, ativando renderização especializada. | Semantic | Renderização Automática | Exemplo | | :--- | :--- | :--- | | `asset` | Upload de arquivo com preview | Foto do produto, documento PDF | | `money` | Máscara monetária (R$ 1.234,56) | Preço, salário | | `percentage` | Slider ou input com sufixo % | Margem, desconto | | `phone` | Máscara de telefone + link `tel:` | WhatsApp, comercial | | `email` | Validação + link `mailto:` | Email principal | | `url` | Link clicável externo | Website, LinkedIn | | `color` | Color picker nativo | Cor do tema, cor de status | | `cpf` / `cnpj` | Máscara de documento | CPF, CNPJ | ### 5. Topologia de Apresentação (`module.topology`) Define a **dinâmica de navegação** de um módulo ou objeto no app. | Topology | Comportamento | Exemplo | | :--- | :--- | :--- | | `focal` | Dashboard central com métricas e visão consolidada | Módulo de Logistica com mapa | | `connected` | Lista que se conecta a detalhes (master-detail) | Pedidos → Itens | | `hierarchical` | Árvore navegável (tree view) | Categorias → Subcategorias | ## ⛓️ Restrições de Governança (`object.geo_constraint`) Define regras de negócio espaciais automatizadas. - **geofencing**: Garante que uma ação só ocorra dentro de um polígono definido. - **area_of_action**: Vincula recursos a territórios específicos, impedindo alocação fora da zona permitida. --- ## ⛓️ Relacionamentos e Persistência (`object.relations`) ... (Inalterado) ... --- ## 🏗️ Reação do Motor (Behaviors) A taxonomia permite a **Escada de Abstração**: 1. **L1 (Atômico)**: Tipos `location` ou `area` ativam automaticamente o seletor de mapa. 2. **L2 (Padrões)**: Objetos com `routing_type: 'waypoint'` ativam o `ui_mode: 'dispatch_map'`. 3. **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. ## 📈 6. Extensões Analíticas (Ontologia v3) [NEW] Define como o motor interpreta o dado para geração de insights, métricas e visualizações de BI. ### Propriedades Analíticas (`property`) | Atributo | Tipo | Descrição | Comportamento Reativo | | :--- | :--- | :--- | :--- | | `aggregation` | `enum` | [sum, avg, min, max, count, distinct, none] | Define a estatística primária. `money` assume `sum`, `percentage` assume `avg`. | | `target` | `number` | Valor de meta ou baseline. | Ativa o indicador de progresso e barra de performance no `BiWidget`. | ### Eixos de Análise (`object`) | Atributo | Tipo | Descrição | Exemplo | | :--- | :--- | :--- | :--- | | `temporal_axis` | `string` | Campo de data usado como referência de tempo principal. | `closed_at` em vendas, `created_at` default. | | `temporal_resolution` | `enum` | [day, week, month, year, auto] | Define a granularidade padrão dos gráficos de série temporal. | | `target_property` | `string` | Campo que define o valor de meta para este objeto. | `meta_mensal` em `broker`. | ### 🔗 Contribuição Dimensional (`relation`) | Atributo | Tipo | Descrição | Comportamento Reativo | | :--- | :--- | :--- | :--- | | `contribution_property` | `string` | Campo do objeto filho que deve ser somado no agrupamento. | `valor` em `sale` agrupado por `broker`. | --- --- > [!IMPORTANT] > A taxonomia é o que transforma JSON morto em uma aplicação viva. Toda alteração nestes atributos deve seguir o **Protocolo FADAP**. --- > "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*."