Protocolo de Mutação de Schema (Anti-Gravity)

Este documento define o método soberano para alteração de schemas de aplicações no ecossistema FastApp. O não cumprimento deste protocolo pode comprometer a integridade da metadados e causar inconsistências entre o banco de dados e o manifesto estático.

🚫 O que NÃO fazer

• NUNCA faça buscas globais por strings no static-manifest.ts para substituição direta.
• NUNCA edite o banco de dados via SQL manual para alterações estruturais sem atualizar o manifesto.
• NUNCA ignore campos computados ou relações ao refatorar um objeto.

✅ O Método Soberano (Get -> Parse -> Modify -> Patch)

Toda mutação de schema deve seguir rigorosamente estes 5 passos:

1. AQUISIÇÃO (Fetch)

Sempre obtenha a versão mais recente do schema diretamente da API de Apps.

GET /api/app/:id

Isso garante que você está trabalhando com o estado atual do banco de dados (Sovereign State).

2. PRESERVAÇÃO (Versioning/Backup)

Guarde uma cópia do JSON original ou anote a versão antes de qualquer modificação. Isso permite rollback em caso de falha.

3. MODIFICAÇÃO ESTRUTURADA (Parse & Modify)

Faça o parse do JSON e manipule os objetos de forma estruturada. Use a lógica de "Merging Engine" inspirada no useFastappArchitect.ts:

• Objetos: Identifique por key ou name.
• Propriedades: Preserve propriedades existentes a menos que explicitamente solicitado para remover.
• Grupos: Mantenha a ordem de relevância através de property_groups.
• Orquestração de UI: Preserve campos como nested_crud, nested_view_mode, ui_visibility e group_render_mode, pois eles governam a experiência do usuário final.

4. APLICAÇÃO (Patch)

Envie apenas os campos modificados ou o objeto inteiro atualizado via PATCH.

PATCH /api/app/:id

O servidor se encarregará de validar a estrutura e atualizar o banco.

5. SINCRONIZAÇÃO (Snapshot)

Após o sucesso do PATCH, dispare sempre um snapshot para atualizar o static-manifest.ts.

POST /api/system/snapshot

Isso garante que o frontend e as ferramentas estáticas reflitam a mudança imediatamente.

🛠️ Ferramentas Recomendadas

Use o script scripts/agent-schema-tool.ts para automatizar este fluxo de forma segura.