{"id":"repo/app-hierarchy","source":"repo","sourceLabel":"repository root","sourcePath":"APP_HIERARCHY.md","routePath":"/fastapp/public-docs/page/repo/app-hierarchy","rawPath":"/fastapp/public-docs/raw/repo/app-hierarchy","slug":["repo","app-hierarchy"],"slugPath":"repo/app-hierarchy","title":"🏛️ APP HIERARCHY — A Pirâmide de Metadados","description":"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.","headings":["🏛️ APP HIERARCHY — A Pirâmide de Metadados","🏛️ A Pirâmide de Abstração","📦 1. App (App)","🧱 2. Objeto (SystemObject)","🏷️ 3. Propriedades (Property)","📄 4. Páginas (Page)","🔗 Relacionamentos (Relation)","Estratégias de Persistência"],"wordCount":449,"markdown":"# 🏛️ APP HIERARCHY — A Pirâmide de Metadados\r\n\r\nEste 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.\r\n\r\n---\r\n\r\n## 🏛️ A Pirâmide de Abstração\r\n\r\nO sistema segue uma hierarquia de quatro níveis:\r\n\r\n1.  **App**: A unidade de negócio (ex: \"CRM Flux\", \"Gestão de Ativos\").\r\n2.  **Module**: Agrupamento lógico de navegação (ex: \"Comercial\", \"Configurações\").\r\n3.  **Object**: A entidade mestre de dados (ex: \"Lead\", \"Broker\", \"Tarefa\").\r\n4.  **Property**: Os campos individuais que compõem o objeto (ex: \"Nome\", \"Status\").\r\n\r\n---\r\n\r\n## 📦 1. App (`App`)\r\nO container principal da experiência do usuário.\r\n- `slug`: Identificador único usado na URL (ex: `/app/crm-flux`).\r\n- `objects`: Lista de definições de objetos disponíveis.\r\n- `modules`: Estrutura de navegação (sidebar) que organiza o acesso aos objetos.\r\n- `pages`: Lista de páginas customizadas ou dinâmicas integradas.\r\n- `provider`: Estratégia de dados padrão do app (`local` | `external-api`).\r\n- `is_api_data_source`: Flag de compatibilidade para forçar fonte externa.\r\n- `api_base_url`: URL base opcional para rotear `/api/v1/data/:object` para API externa.\r\n\r\n## 🧱 2. Objeto (`SystemObject`)\r\nDefine o comportamento da entidade na UI e no Storage.\r\n- `name`: Nome técnico em snake_case (ex: `crm_lead`).\r\n- `category`: [Master | Transactional | Configuration] (Ver `DATA_TAXONOMY.md`).\r\n- `nature`: [Physical | Embedded | Virtual] (Ver `DATA_TAXONOMY.md`).\r\n- `crud_mode`: [Modal | Page | Inline] (Define como o formulário de edição abre).\r\n- `provider`: Override de fonte de dados no nível do objeto.\r\n- `is_api_data_source`: Flag de compatibilidade para ativar API externa no objeto.\r\n- `api_url`: URL externa completa para este objeto (prioridade sobre `api_base_url` do app).\r\n- `api_path`: Path de recurso opcional quando o app já define `api_base_url`.\r\n\r\n## 🏷️ 3. Propriedades (`Property`)\r\nOs átomos que definem o dado e sua validação.\r\n- `type`: [String | Number | Boolean | Enum | Date | Array | Json].\r\n- `semantic`: [asset | money | percentage | phone | email | url | color | cpf | cnpj]. (Ver `DATA_TAXONOMY.md`, Ontologia v3)\r\n- `layout_grid`: Classes PrimeFlex/Tailwind para posicionamento (ex: `col-span-12 md:col-span-6`).\r\n- `show_in_list`: Visibilidade na tabela/lista principal.\r\n- `required`: Validação obrigatória em tempo de execução.\r\n\r\n## 📄 4. Páginas (`Page`)\r\nDefinem rotas integradas ao menu dinâmico.\r\n- `type: 'custom'`: Aponta para arquivo físico em `pages/` (ex: `/crm/leads`).\r\n- `type: 'dynamic_crud'`: Gera rota automática para o objeto alvo.\r\n- Atributos: `name`, `label`, `icon`, `path`, `component_key`.\r\n\r\n---\r\n\r\n## 🔗 Relacionamentos (`Relation`)\r\n\r\nComo os objetos se conectam entre si:\r\n- **has_many**: Relação 1:N (Ex: Um Lead tem muitas Tarefas).\r\n- **belongs_to**: Relação N:1 (Ex: Uma Tarefa pertence a um Lead).\r\n- **associates_with**: Relação N:N (Ex: Leads e Tags).\r\n\r\n### Estratégias de Persistência\r\n- `reference_id`: Salva o ID do objeto relacionado (Chave Estrangeira).\r\n- `document_embed`: Salva o filho inteiro dentro do JSON do pai (usado com `nature: embedded`).\r\n\r\n---\r\n\r\n> \"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.\"\r\n"}