Public Markdown Document

🏛️ APP HIERARCHY — A Pirâmide de Metadados

Este guia detalha a anatomia rigorosa de uma "Aplicação" no Fastapp Engine. A estrutura de metadados é o DNA que permite ao motor renderizar interfaces dinâmicas com inteligência.

449 palavras8 headingsrepository root

🏛️ APP HIERARCHY — A Pirâmide de Metadados

Este guia detalha a anatomia rigorosa de uma "Aplicação" no Fastapp Engine. A estrutura de metadados é o DNA que permite ao motor renderizar interfaces dinâmicas com inteligência.

🏛️ A Pirâmide de Abstração

O sistema segue uma hierarquia de quatro níveis:

App: A unidade de negócio (ex: "CRM Flux", "Gestão de Ativos").
Module: Agrupamento lógico de navegação (ex: "Comercial", "Configurações").
Object: A entidade mestre de dados (ex: "Lead", "Broker", "Tarefa").
Property: Os campos individuais que compõem o objeto (ex: "Nome", "Status").

📦 1. App (`App`)

O container principal da experiência do usuário.

slug: Identificador único usado na URL (ex: /app/crm-flux).
objects: Lista de definições de objetos disponíveis.
modules: Estrutura de navegação (sidebar) que organiza o acesso aos objetos.
pages: Lista de páginas customizadas ou dinâmicas integradas.
provider: Estratégia de dados padrão do app (local | external-api).
is_api_data_source: Flag de compatibilidade para forçar fonte externa.
api_base_url: URL base opcional para rotear /api/v1/data/:object para API externa.

🧱 2. Objeto (`SystemObject`)

Define o comportamento da entidade na UI e no Storage.

name: Nome técnico em snake_case (ex: crm_lead).
category: [Master | Transactional | Configuration] (Ver DATA_TAXONOMY.md).
nature: [Physical | Embedded | Virtual] (Ver DATA_TAXONOMY.md).
crud_mode: [Modal | Page | Inline] (Define como o formulário de edição abre).
provider: Override de fonte de dados no nível do objeto.
is_api_data_source: Flag de compatibilidade para ativar API externa no objeto.
api_url: URL externa completa para este objeto (prioridade sobre api_base_url do app).
api_path: Path de recurso opcional quando o app já define api_base_url.

🏷️ 3. Propriedades (`Property`)

Os átomos que definem o dado e sua validação.

type: [String | Number | Boolean | Enum | Date | Array | Json].
semantic: [asset | money | percentage | phone | email | url | color | cpf | cnpj]. (Ver DATA_TAXONOMY.md, Ontologia v3)
layout_grid: Classes PrimeFlex/Tailwind para posicionamento (ex: col-span-12 md:col-span-6).
show_in_list: Visibilidade na tabela/lista principal.
required: Validação obrigatória em tempo de execução.

📄 4. Páginas (`Page`)

Definem rotas integradas ao menu dinâmico.

type: 'custom': Aponta para arquivo físico em pages/ (ex: /crm/leads).
type: 'dynamic_crud': Gera rota automática para o objeto alvo.
Atributos: name, label, icon, path, component_key.

🔗 Relacionamentos (`Relation`)

Como os objetos se conectam entre si:

has_many: Relação 1:N (Ex: Um Lead tem muitas Tarefas).
belongs_to: Relação N:1 (Ex: Uma Tarefa pertence a um Lead).
associates_with: Relação N:N (Ex: Leads e Tags).

Estratégias de Persistência

reference_id: Salva o ID do objeto relacionado (Chave Estrangeira).
document_embed: Salva o filho inteiro dentro do JSON do pai (usado com nature: embedded).

"Estruturar bem o metadado é garantir que o motor trabalhe para você, não contra você. Com a Ontologia v3, o metadado governa não só a persistência, mas também a renderização, a navegação e a inteligência artificial."