🛰️ 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).