{"id":"repo/protocol-schema-mutation","source":"repo","sourceLabel":"repository root","sourcePath":"PROTOCOL_SCHEMA_MUTATION.md","routePath":"/fastapp/public-docs/page/repo/protocol-schema-mutation","rawPath":"/fastapp/public-docs/raw/repo/protocol-schema-mutation","slug":["repo","protocol-schema-mutation"],"slugPath":"repo/protocol-schema-mutation","title":"Protocolo de Mutação de Schema (Anti Gravity)","description":"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 man...","headings":["Protocolo de Mutação de Schema (Anti Gravity)","🚫 O que NÃO fazer","✅ O Método Soberano (Get Parse Modify Patch)","1. AQUISIÇÃO (Fetch)","2. PRESERVAÇÃO (Versioning/Backup)","3. MODIFICAÇÃO ESTRUTURADA (Parse & Modify)","4. APLICAÇÃO (Patch)","5. SINCRONIZAÇÃO (Snapshot)","🛠️ Ferramentas Recomendadas"],"wordCount":303,"markdown":"# Protocolo de Mutação de Schema (Anti-Gravity)\r\n\r\nEste 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.\r\n\r\n## 🚫 O que NÃO fazer\r\n- **NUNCA** faça buscas globais por strings no `static-manifest.ts` para substituição direta.\r\n- **NUNCA** edite o banco de dados via SQL manual para alterações estruturais sem atualizar o manifesto.\r\n- **NUNCA** ignore campos computados ou relações ao refatorar um objeto.\r\n\r\n## ✅ O Método Soberano (Get -> Parse -> Modify -> Patch)\r\n\r\nToda mutação de schema deve seguir rigorosamente estes 5 passos:\r\n\r\n### 1. AQUISIÇÃO (Fetch)\r\nSempre obtenha a versão mais recente do schema diretamente da API de Apps.\r\n```http\r\nGET /api/app/:id\r\n```\r\nIsso garante que você está trabalhando com o estado atual do banco de dados (Sovereign State).\r\n\r\n### 2. PRESERVAÇÃO (Versioning/Backup)\r\nGuarde uma cópia do JSON original ou anote a versão antes de qualquer modificação. Isso permite rollback em caso de falha.\r\n\r\n### 3. MODIFICAÇÃO ESTRUTURADA (Parse & Modify)\r\nFaça o parse do JSON e manipule os objetos de forma estruturada. Use a lógica de \"Merging Engine\" inspirada no `useFastappArchitect.ts`:\r\n- **Objetos**: Identifique por `key` ou `name`.\r\n- **Propriedades**: Preserve propriedades existentes a menos que explicitamente solicitado para remover.\r\n- **Grupos**: Mantenha a ordem de relevância através de `property_groups`.\r\n- **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.\r\n\r\n### 4. APLICAÇÃO (Patch)\r\nEnvie apenas os campos modificados ou o objeto inteiro atualizado via PATCH.\r\n```http\r\nPATCH /api/app/:id\r\n```\r\nO servidor se encarregará de validar a estrutura e atualizar o banco.\r\n\r\n### 5. SINCRONIZAÇÃO (Snapshot)\r\nApós o sucesso do PATCH, dispare sempre um snapshot para atualizar o `static-manifest.ts`.\r\n```http\r\nPOST /api/system/snapshot\r\n```\r\nIsso garante que o frontend e as ferramentas estáticas reflitam a mudança imediatamente.\r\n\r\n## 🛠️ Ferramentas Recomendadas\r\nUse o script `scripts/agent-schema-tool.ts` para automatizar este fluxo de forma segura.\r\n"}