🧬 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."