# 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.
```http
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.
```http
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`.
```http
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.