# 🛰️ ANTIGRAVITY GUIDELINES — As Leis da Abstração Soberana (v3.1) > "Se algo é repetitivo, deve ser abstraído; se é específico, deve ser generalizado. Se é generalizável, o motor deve fazê-lo sozinho." Este 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**. --- ## 1. O Princípio da Generalização Soberana 1. **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'))". 2. **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. 3. **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. 4. **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. --- ## 2. Camadas de Core (A Escada de Abstração) As camadas do Core definem os níveis de inteligência e responsabilidade do motor: * 🟣 **Core L1 — Atômico**: Renderização pura de tipos e semânticas (money, phone, email, asset). * 🔵 **Core L2 — Padrões**: Kanban, Sidebars de edição, Layouts adaptativos baseados em `crud_mode` e comportamentos padronizados de CRUD. * 🟢 **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. --- ## 3. Orquestração de Dados (DataSources) O sistema utiliza a abstração de **Conectividade** para gerenciar dados internos e externos: - **DataSource Object**: Define `type` (REST, Internal, GraphQL), `base_url`, `auth_strategy` (Bearer, API Key, Laravel Proxy) e headers globais. - **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. - **Vantagem**: Desacoplamento total entre a definição da taxonomia e a infraestrutura física de rede. --- ## 4. Protocolo FADAP 3.0 (Sovereign Sync & DDL) A evolução estrutural segue um fluxo de estado atômico, soberano e OBRIGATORIAMENTE via API. Não há atalhos. 1. **Mutação (Sovereign Patch)**: Alterações estruturais (campos, objetos, workflows, crud_mode) ocorrem EXCLUSIVAMENTE via `PATCH /api/app/[id]` no Nuxt. 2. **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.** 3. **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. 4. **Estado & Cache**: O sistema invalida caches imediatamente após o snapshot. > [!CAUTION] > **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. > [!CAUTION] > **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). --- ## 11. Defensive Dynamic Rendering (L1/L2) A renderização dinâmica deve ser resiliente a metadados incompletos ou malformados: 1. **Label Fallback**: Nunca assuma que `prop.label` existe. Use `prop.label || prop.name || ''` para evitar `TypeError: can't access property toUpperCase`. 2. **Multiplicity Logic Core**: - Toda propriedade do tipo `array` ou `inner_collection` deve ser considerada `isAttachedMany` por padrão. - A ausência de `foreign_object` não deve impedir a detecção de multiplicidade para tipos de coleção. 3. **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. --- ## 12. Metadata Integrity & Recovery 1. **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: - Extrair o objeto íntegro do `static-manifest.ts`. - Realizar um `PATCH` manual/via script ignorando campos de auditoria (created_at/updated_at). - Disparar `/api/system/snapshot`. 2. **Validation before Writing**: Futuras evoluções do Core devem validar a integridade estrutural (Schema-of-Schemas) no motor Nuxt antes de persistir no DB. --- ## 5. Alinhamento Laravel (Identity & RBAC) O Laravel provê a inteligência de governança que o Nuxt interpreta: - **Identity Authority**: O Laravel define quem acessa o quê (`User` & `UserApp`). - **Dynamic RBAC**: Permissões (`fastapp_permission`) são exportadas para o Nuxt no payload do `me()` ou JWT. - **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. --- ## 6. Atributos de Comportamento (Ontologia v3) | Atributo | Valores | Impacto no Motor (Behavior) | | :--- | :--- | :--- | | **crud_mode** | `modal`, `sidebar`, `page` | Define onde o `CoreDynamicForm` será renderizado. | | **layout_grid** | `col-span-12`, `6`, `4`, `3` | Define a largura responsiva do campo no formulário (Grid de 12 colunas). | | **semantic** | `money`, `asset`, `point` | Ativa máscaras, uploads ou mapas (`CoreMapRenderer`). | | **routing_type**| `waypoint`, `route` | Ativa inteligência logística e cálculo de ETAs. | | **provider** | `local`, `external-api`| Define se o dado vem do Prisma local ou do Laravel/Externo. | --- ## 7. AI Mutation Guard & Fetch Rule > [!CAUTION] > **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. > [!IMPORTANT] > **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. > [!IMPORTANT] > O motor aprende com cada app. O sucesso do Arquiteto IA é medido pela quantidade de código deletado em favor de metadados interpretados. --- ## 8. Arquitetura de Performance (Architect Sync) Para garantir que o Arquiteto IA seja fluido, seguimos estas regras de sincronização: 1. **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. 2. **Debounced Mutations**: Alterações em metadados granulares (como labels ou grid) devem ser disparadas com debounce (mínimo 300ms) para evitar layout thrashing. 3. **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. --- ## 9. UX Singleton Pattern (The Designer Hub) Para garantir uma experiência de desenvolvimento sem fricção: 1. **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. 2. **Stateless Bridging**: O componente designer não possui estado próprio; ele é um espelho profundo do `activeObjectSchema` do sistema. 3. **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. --- ## 10. Taxonomy-Driven GUI (Semantic Layer) A interface deve se adaptar automaticamente com base na taxonomia dos dados: 1. **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. 2. **Semantic Rendering**: O `CoreDynamicForm` deve priorizar atributos de semântica (ex: `semantic: asset` gera dropzone, `semantic: identity` gera destaque de cabeçalho). 3. **Visual Hierarchy**: Áreas de configuração no Sidebar devem seguir a hierarquia: Identidade (Quem) → Atributos (O quê) → Motor (Como) → Agente (Para quem).