# 🔌 META API SPEC — A Meta-Interface

Este documento é a referência oficial das rotas de gestão do Fastapp Engine. Estas rotas permitem gerir a estrutura das aplicações e acompanhar a evolução do ecossistema.

---

## 🛠️ Gerenciamento de Aplicações (`/api/app`)

### 🚩 Listar/Criar Apps
- **GET `/api/app`**: Lista todos os apps cadastrados.
- **POST `/api/app`**: Cria uma nova aplicação baseada no `AppSchema`.

### ✏️ Atualizar App (Metadata Patch)
- **PATCH `/api/app/:id`**: Atualiza a definição do app (objetos, módulos).
- **Parâmetro `autoSnapshot`**: Se `true`, dispara o snapshot automático após o patch.

---

## 📸 Sistema de Snapshot (`/api/system`)

### 🧊 Gerar Snapshot
- **POST `/api/system/snapshot`**: Lê o banco de dados e gera o arquivo físico `app/fastapp/static-manifest.ts`.
- **Importante**: Garante performance e versionamento via Git.

---

## 🗃️ Sincronização de Storage (`/api/data`)

### ⚙️ Adaptar Storage (DDL Adapt)
- **POST `/api/data/:object/storage`**: Alinha o banco de dados físico com os metadados.
- **Segurança**: Operação deliberadamente manual para revisão de alterações SQL.

---

## 📊 Endpoints de Dados (v1) (`/api/v1/data`)

O motor provê acesso universal aos dados através de uma interface de consulta soberana.

### 🔍 Filtragem (Formatos Aceitos)

O sistema suporta dois formatos de filtros. O formato **Flat** é o padrão soberano para novas implementações.

| Operador | Flat (Recomendado) | Legacy | Exemplo Flat |
| :--- | :--- | :--- | :--- |
| **Eq** | `field=val` | `filters[field][=]=val` | `?status=NOVO` |
| **Ne** | `field[ne]=val` | `filters[field][$ne]=val` | `?status[ne]=FIXED` |
| **Gt/Gte** | `field[gt/gte]=v`| `filters[field][$gt/gte]=v`| `?val[gt]=100` |
| **Lt/Lte** | `field[lt/lte]=v`| `filters[field][$lt/lte]=v`| `?val[lt]=50` |
| **Like** | `field[like]=str`| `filters[field][$like]=str`| `?name[like]=mario` |
| **Between**| `field[between]=a,b`| `filters[field][between]=a,b`| `?date[between]=2023-01-01,2023-12-31` |
| **In** | `field[in]=a,b,c`| `filters[field][in]=a,b,c`| `?id[in]=1,2,3` |

### 📑 Paginação e Ordenação

Parâmetros reservados para controle de fluxo:

| Parâmetro | Tipo | Descrição | Exemplo |
| :--- | :--- | :--- | :--- |
| **$limit** | `number` | Limite de registros por página (default: 50). | `?$limit=10` |
| **$skip** | `number` | Quantidade de registros a ignorar. | `?$skip=20` |
| **$sort** | `object` | Dicionário `{campo: 1/-1}`. | `?$sort[created_at]=-1` |
| **granularity**| `string`| Define a resolução temporal para métricas BI. | `?granularity=month` |

### 🚀 Exemplo de Requisição Completa
`GET /api/v1/data/lead?status=NOVO&$limit=10&$sort[nome]=1`

---

---

> "A Meta-API é a ponte entre a inteligência do motor e a operação do sistema."