# 🏛️ 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:

1.  **App**: A unidade de negócio (ex: "CRM Flux", "Gestão de Ativos").
2.  **Module**: Agrupamento lógico de navegação (ex: "Comercial", "Configurações").
3.  **Object**: A entidade mestre de dados (ex: "Lead", "Broker", "Tarefa").
4.  **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."