{"id":"repo/antigravity-guidelines","source":"repo","sourceLabel":"repository root","sourcePath":"ANTIGRAVITY_GUIDELINES.md","routePath":"/fastapp/public-docs/page/repo/antigravity-guidelines","rawPath":"/fastapp/public-docs/raw/repo/antigravity-guidelines","slug":["repo","antigravity-guidelines"],"slugPath":"repo/antigravity-guidelines","title":"🛰️ ANTIGRAVITY GUIDELINES — As Leis da Abstração Soberana (v3.1)","description":"\"Se algo é repetitivo, deve ser abstraído; se é específico, deve ser generalizado. Se é generalizável, o motor deve fazê lo sozinho.\"","headings":["🛰️ ANTIGRAVITY GUIDELINES — As Leis da Abstração Soberana (v3.1)","1. O Princípio da Generalização Soberana","2. Camadas de Core (A Escada de Abstração)","3. Orquestração de Dados (DataSources)","4. Protocolo FADAP 3.0 (Sovereign Sync & DDL)","11. Defensive Dynamic Rendering (L1/L2)","12. Metadata Integrity & Recovery","5. Alinhamento Laravel (Identity & RBAC)","6. Atributos de Comportamento (Ontologia v3)","7. AI Mutation Guard & Fetch Rule","8. Arquitetura de Performance (Architect Sync)","9. UX Singleton Pattern (The Designer Hub)","10. Taxonomy Driven GUI (Semantic Layer)"],"wordCount":1176,"markdown":"# 🛰️ ANTIGRAVITY GUIDELINES — As Leis da Abstração Soberana (v3.1)\r\n\r\n> \"Se algo é repetitivo, deve ser abstraído; se é específico, deve ser generalizado. Se é generalizável, o motor deve fazê-lo sozinho.\"\r\n\r\nEste documento consolida a filosofia de desenvolvimento do Fastapp Engine. Ele orienta como o Arquiteto IA e os desenvolvedores colaboradores devem atuar para reduzir o boilerplate através da **Escada de Abstração** e da **Auto-Evolução**.\r\n\r\n---\r\n\r\n## 1. O Princípio da Generalização Soberana\r\n\r\n1.  **Abstração > Customização**: Soluções genéricas no Core atendem múltiplos domínios via esquema. Evite \"if (app === 'crm')\". Em vez disso, use \"if (object.has_feature('kanban'))\".\r\n2.  **Esquema Governa a UI**: Nenhuma funcionalidade é \"solta\". Para cada comportamento em tela (ex: `is_sortable`, `is_filterable`), deve existir um metadado correspondente que o habilite.\r\n3.  **Fastapp como Modelo 0**: O Schema Manager é construído sobre as mesmas abstrações que oferece. Evoluir o Schema Manager é evoluir o motor para todos os inquilinos.\r\n4.  **Persistent DevShell**: Ferramentas de arquitetura (Sidebars de Design) devem ser Singleton Globais localizadas no Layout principal, garantindo estabilidade durante navegações e snapshots sem perda de estado.\r\n\r\n---\r\n\r\n## 2. Camadas de Core (A Escada de Abstração)\r\n\r\nAs camadas do Core definem os níveis de inteligência e responsabilidade do motor:\r\n\r\n*   🟣 **Core L1 — Atômico**: Renderização pura de tipos e semânticas (money, phone, email, asset).\r\n*   🔵 **Core L2 — Padrões**: Kanban, Sidebars de edição, Layouts adaptativos baseados em `crud_mode` e comportamentos padronizados de CRUD.\r\n*   🟢 **Core L3 — Orquestração**: Lógica complexa de recursos e logística (routing_type, geo_constraints, alocação geotemporal). Automatização de UX baseada em Taxonomia Semântica.\r\n\r\n---\r\n\r\n## 3. Orquestração de Dados (DataSources)\r\n\r\nO sistema utiliza a abstração de **Conectividade** para gerenciar dados internos e externos:\r\n\r\n-   **DataSource Object**: Define `type` (REST, Internal, GraphQL), `base_url`, `auth_strategy` (Bearer, API Key, Laravel Proxy) e headers globais.\r\n-   **Vinculação**: Um App ou Object aponta para um `datasource_id`. Alterar a infraestrutura (ex: mudar o host do Laravel) exige apenas uma mudança no DataSource, refletindo em todos os objetos vinculados.\r\n-   **Vantagem**: Desacoplamento total entre a definição da taxonomia e a infraestrutura física de rede.\r\n\r\n---\r\n\r\n## 4. Protocolo FADAP 3.0 (Sovereign Sync & DDL)\r\n\r\nA evolução estrutural segue um fluxo de estado atômico, soberano e OBRIGATORIAMENTE via API. Não há atalhos.\r\n\r\n1.  **Mutação (Sovereign Patch)**: Alterações estruturais (campos, objetos, workflows, crud_mode) ocorrem EXCLUSIVAMENTE via `PATCH /api/app/[id]` no Nuxt.\r\n2.  **Snapshot (Consolidação)**: Geração do `static-manifest.ts` disparada via `POST /api/system/snapshot`. **É a única forma de garantir que o runtime veja a nova estrutura.**\r\n3.  **DDL Automation**: Para objetos `nature: physical`, a criação ou alteração de tabelas é disparada pelo motor Nuxt APÓS o Patch de metadados, garantindo consistência.\r\n4.  **Estado & Cache**: O sistema invalida caches imediatamente após o snapshot.\r\n\r\n> [!CAUTION]\r\n> **Integrity Pitfall**: Nunca manipule o banco de dados diretamente ou edite o `static-manifest.ts`. Se você ignorar a API, criará um \"drift\" entre o Desejo (Metadados) e a Realidade (DB), quebrando o motor.\r\n\r\n> [!CAUTION]\r\n> **Integrity Pitfall**: Falhas no salvamento de metadados complexos (ex: arrays aninhados) podem corromper o esquema no banco. O `static-manifest.ts` é a sua \"Fonte da Verdade\" para recuperação (Disaster Recovery).\r\n\r\n---\r\n\r\n## 11. Defensive Dynamic Rendering (L1/L2)\r\n\r\nA renderização dinâmica deve ser resiliente a metadados incompletos ou malformados:\r\n\r\n1.  **Label Fallback**: Nunca assuma que `prop.label` existe. Use `prop.label || prop.name || ''` para evitar `TypeError: can't access property toUpperCase`.\r\n2.  **Multiplicity Logic Core**:\r\n    - Toda propriedade do tipo `array` ou `inner_collection` deve ser considerada `isAttachedMany` por padrão.\r\n    - A ausência de `foreign_object` não deve impedir a detecção de multiplicidade para tipos de coleção.\r\n3.  **Data Hydration Guards**: No `DynamicForm`, garanta que o pulso de dados inicial (`initialValues`) seja sanitizado antes de ser injetado no rastro de reatividade do Vee-Validate/Zod.\r\n\r\n---\r\n\r\n## 12. Metadata Integrity & Recovery\r\n\r\n1.  **Sovereign Restore**: Se o banco de dados for corrompido ou o salvamento via Arquiteto IA falhar de forma catastrófica, o procedimento de restauração deve ser:\r\n    - Extrair o objeto íntegro do `static-manifest.ts`.\r\n    - Realizar um `PATCH` manual/via script ignorando campos de auditoria (created_at/updated_at).\r\n    - Disparar `/api/system/snapshot`.\r\n2.  **Validation before Writing**: Futuras evoluções do Core devem validar a integridade estrutural (Schema-of-Schemas) no motor Nuxt antes de persistir no DB.\r\n\r\n---\r\n\r\n## 5. Alinhamento Laravel (Identity & RBAC)\r\n\r\nO Laravel provê a inteligência de governança que o Nuxt interpreta:\r\n\r\n-   **Identity Authority**: O Laravel define quem acessa o quê (`User` & `UserApp`).\r\n-   **Dynamic RBAC**: Permissões (`fastapp_permission`) são exportadas para o Nuxt no payload do `me()` ou JWT.\r\n-   **Data Sovereignty**: O Laravel governa o Domínio Externo (APIs de referência como Central Filtros) enquanto o Nuxt governa os Metadados e a execução de DDL.\r\n\r\n---\r\n\r\n## 6. Atributos de Comportamento (Ontologia v3)\r\n\r\n| Atributo | Valores | Impacto no Motor (Behavior) |\r\n| :--- | :--- | :--- |\r\n| **crud_mode** | `modal`, `sidebar`, `page` | Define onde o `CoreDynamicForm` será renderizado. |\r\n| **layout_grid** | `col-span-12`, `6`, `4`, `3` | Define a largura responsiva do campo no formulário (Grid de 12 colunas). |\r\n| **semantic** | `money`, `asset`, `point` | Ativa máscaras, uploads ou mapas (`CoreMapRenderer`). |\r\n| **routing_type**| `waypoint`, `route` | Ativa inteligência logística e cálculo de ETAs. |\r\n| **provider** | `local`, `external-api`| Define se o dado vem do Prisma local ou do Laravel/Externo. |\r\n\r\n---\r\n\r\n## 7. AI Mutation Guard & Fetch Rule\r\n\r\n> [!CAUTION]\r\n> **Fetch before Modify**: Sempre execute `GET /api/app/[id]` antes de propor mudanças para garantir o estado real da taxonomia e evitar sobrescrever metadados de outros agentes/usuários.\r\n\r\n> [!IMPORTANT]\r\n> **O Princípio da Mutação Soberana**: Para alterar a estrutura do próprio FastApp (Builder, Editores, Workflows), você deve realizar o `PATCH` no **App ID 16**. O motor aprende e evolui alterando seu próprio esquema.\r\n\r\n> [!IMPORTANT]\r\n> O motor aprende com cada app. O sucesso do Arquiteto IA é medido pela quantidade de código deletado em favor de metadados interpretados.\r\n\r\n---\r\n\r\n## 8. Arquitetura de Performance (Architect Sync)\r\n\r\nPara garantir que o Arquiteto IA seja fluido, seguimos estas regras de sincronização:\r\n\r\n1.  **Memory Memoization**: Evite `JSON.parse(JSON.stringify())` em cada pulso de reatividade. Utilize clones profundos apenas no início da sessão ou em trocas de contexto.\r\n2.  **Debounced Mutations**: Alterações em metadados granulares (como labels ou grid) devem ser disparadas com debounce (mínimo 300ms) para evitar layout thrashing.\r\n3.  **Reactive Bridges**: Páginas e componentes devem apenas \"publicar\" o esquema ativo no `systemStore.activeObjectSchema`, delegando a renderização da ferramenta de edição ao motor global.\r\n\r\n---\r\n\r\n## 9. UX Singleton Pattern (The Designer Hub)\r\n\r\nPara garantir uma experiência de desenvolvimento sem fricção:\r\n\r\n1.  **Fixed Shell Principle**: O Sidebar de Arquitetura deve ser persistente. Ele nunca deve ser destruído durante a navegação entre Table e Form de um mesmo objeto.\r\n2.  **Stateless Bridging**: O componente designer não possui estado próprio; ele é um espelho profundo do `activeObjectSchema` do sistema.\r\n3.  **No-Modal Architecting**: Evite modais para edição de metadados. Use sidebars fixos que permitam ao designer observar o impacto visual das mudanças no formulário dinâmico em tempo real.\r\n\r\n---\r\n\r\n## 10. Taxonomy-Driven GUI (Semantic Layer)\r\n\r\nA interface deve se adaptar automaticamente com base na taxonomia dos dados:\r\n\r\n1.  **Topology Awareness**: Componentes de lista devem detectar se o objeto é `root` (vários registros) ou `attached-one` (exibição de detalhes aninhados) e ajustar o layout automaticamente.\r\n2.  **Semantic Rendering**: O `CoreDynamicForm` deve priorizar atributos de semântica (ex: `semantic: asset` gera dropzone, `semantic: identity` gera destaque de cabeçalho).\r\n3.  **Visual Hierarchy**: Áreas de configuração no Sidebar devem seguir a hierarquia: Identidade (Quem) → Atributos (O quê) → Motor (Como) → Agente (Para quem).\r\n"}