# Quickstart

> Gere uma Central com o gerador oficial, rode localmente sem depender da plataforma e faça o primeiro cadastro.

## Pré-requisitos

- **Node.js 18 ou superior** compatível com os pacotes instalados.
- **MongoDB local** disponível para desenvolvimento (replica set é necessário apenas para invariantes transacionais).
- **npm** — o scaffold usa lockfiles npm separados para raiz, backend e frontend.

## Criar e rodar

1. **Gere a base oficial**

   ```bash
   npx @oondemand/create-central-oon minha-central
   cd minha-central
   ```

   Para fixar a versão do gerador e instalar manualmente:

   ```bash
   npx --yes --package @oondemand/create-central-oon@0.7.43 create-central-oon minha-central --no-install
   cd minha-central
   npm install
   npm install --prefix backend
   npm install --prefix frontend
   ```

2. **Configure o ambiente local**

   ```bash
   cp backend/.env.example backend/.env
   cp frontend/.env.example frontend/.env
   ```

   Ajuste `MONGO_URI` em `backend/.env` para um banco de desenvolvimento.

3. **Valide a documentação local e a conformidade**

   ```bash
   npm run check
   ```

   O `check` executa o `doctor`: versões, lockfiles, manifestos, cache `.ooncore/` e conformance.

4. **Inicie backend e frontend**

   ```bash
   npm run dev
   ```

   O orquestrador sobe o backend em `127.0.0.1:4000`, o frontend em `127.0.0.1:5173` e abre o navegador com uma sessão local já autenticada.

> [!TIP]
> No runtime local não é preciso cadastrar o App na Plataforma. O banner superior permite trocar entre os perfis declarados em `central.app.json` para testar permissões.

## O que foi gerado

```txt
minha-central/
├── central.app.json        # identidade, RBAC, capabilities, compatibilidade
├── oon.deploy.json         # contrato de publicação (runtime, health, recursos)
├── .ooncore/               # documentação canônica do Core (não edite à mão)
├── backend/
│   ├── central.config.js   # extensões de runtime
│   └── src/{models,validations,triggers,routes,services,...}
└── frontend/
    └── src/
        ├── main.tsx        # startOonApp(app)
        ├── app/            # app, routes, navigation, theme
        └── pages/          # suas páginas
```

Veja o detalhe de cada pasta em [Estrutura do projeto](/docs/introducao/estrutura-do-projeto).

## Seu primeiro cadastro

Adicione as permissões em `central.app.json`:

```json title="central.app.json"
{
  "rbac": {
    "permissions": ["pessoas.read", "pessoas.write"]
  }
}
```

Crie a model no backend:

```javascript title="backend/src/models/Pessoa.js"
const { defineModel, fields } = require("@oondemand/oon-core-back");

defineModel({
  name: "Pessoa", singular: "pessoa", basePath: "/pessoas", scope: "tenant",
  schema: { nome: fields.string({ required: true, label: "Nome" }) },
  crud: { enabled: true, permissions: { read: "pessoas.read", write: "pessoas.write" } },
});
```

E exiba a coleção no frontend:

```tsx title="frontend/src/pages/HomePage.tsx"
import { CoreCollection } from "@oondemand/oon-core-front";

export function HomePage() {
  return <CoreCollection model="Pessoa" label="Pessoas" endpoint="/pessoas" />;
}
```

Reinicie o `npm run dev`. Em **Início**, crie uma pessoa, consulte a lista e recarregue para confirmar a persistência. Sem nome, o backend recusa; com o perfil `viewer` (sem as permissões), leitura e escrita são negadas.

> [!NOTE]
> O formulário é derivado da metadata do backend — você não escreveu nenhum campo no frontend.

## Exemplo integrado opcional

Em uma base limpa, instale a jornada de demonstração completa (cadastro, ação privada, esteira, integração HTTPS, segredos e recursos nativos):

```bash
npx --no-install create-central-oon example
npm run dev
```

Abra **Primeira jornada** (`/jornada`) e **Recursos nativos** (`/recursos`).

## Próximos passos

```cards
[
  { "title": "Primeira jornada", "href": "/docs/introducao/primeira-jornada", "description": "Página + ação + endpoint privado + permissão." },
  { "title": "Models e CRUD", "href": "/docs/backend/models-e-crud", "description": "Tudo o que defineModel oferece." },
  { "title": "Runtime local", "href": "/docs/fundamentos/runtime-local", "description": "Sessão, perfis e limites do desenvolvimento desconectado." },
  { "title": "Publicação", "href": "/docs/operacao/publicacao", "description": "Do commit ao ambiente de Dev." }
]
```

Fonte: https://sdk.oonapps.com/docs/introducao/quickstart