Quickstart
Do zero ao sistema rodando em menos de 5 minutos.
Pré-requisitos
- Node.js ≥ 18
- MongoDB rodando localmente (
mongod) ou uma URI do MongoDB Atlas
1. Gerar a Central
npx @oondemand/create-central-oon minha-central
Isso cria a pasta minha-central/ com backend e frontend mínimos e já executa npm install nos dois:
minha-central/
├── backend/
│ ├── central.config.js # identidade + módulos ativos
│ ├── src/
│ │ └── models/Pessoa.js # seu primeiro modelo
│ └── package.json
└── frontend/
├── central.ui.json # declaração de views (JSON)
├── src/main.tsx
└── package.json
2. Configurar o backend
cd minha-central/backend
cp .env.example .env
Edite o .env:
MONGO_URI=mongodb://localhost:27017/minha-central
PORT=4000
SERVICE_NAME=minha-central
MEUS_APPS_BACKEND_URL=https://meus-apps.oondemand.com.br
APP_KEY=sua-app-key
# Token de desenvolvimento local (sem Meus Apps)
DEV_TOKEN=dev-local
O Core não tem login próprio. Em produção, toda autenticação é delegada ao Meus Apps via bearer token. Para desenvolvimento local, use DEV_TOKEN — veja o passo 6.
3. Subir o backend
npm run dev
O Core sobe o Express, conecta no MongoDB e expõe automaticamente:
| Endpoint | Descrição |
|---|---|
GET / | Status do serviço e banco |
GET /core/metadata | Metadados de todas as models |
GET /pessoas | Listagem paginada (requer auth) |
POST /pessoas | Criação (requer auth) |
PUT /pessoas/:id | Atualização (requer auth) |
DELETE /pessoas/:id | Remoção (requer auth) |
GET /auth/validar-token | Valida o bearer token |
4. Ativar a Central
A ativação cria o singleton Sistema no banco e deve ser executada uma vez na primeira inicialização (ou após resetar o banco):
npm run activate
Saída esperada:
Conectado ao MongoDB (...)
Sistema (singleton) criado.
Ativação concluída.
5. Configurar o frontend
cd ../frontend
cp .env.example .env
Edite o .env:
VITE_API_URL=http://localhost:4000
VITE_MEUS_APPS_URL=https://meus-apps.oondemand.com.br
6. Subir o frontend
npm run dev
Acesse http://localhost:5173.
6.1 Autenticar em desenvolvimento local
O frontend redireciona para o Meus Apps quando não há sessão. Para entrar sem o Meus Apps, acesse a URL com o DEV_TOKEN no parâmetro ?code=:
http://localhost:5173/?code=dev-local
O frontend captura o token, valida em GET /auth/validar-token e abre a Central autenticado como admin. A sessão fica ativa no localStorage do browser até você fazer logout.
O central.config.js gerado pelo scaffold já inclui o bloco devAuth que, com NODE_ENV=development e DEV_TOKEN definido, aceita o token local sem chamar o Meus Apps. Em produção (sem DEV_TOKEN), o Core usa o Meus Apps normalmente.
O que acabou de acontecer?
O frontend chamou GET /core/metadata, recebeu a descrição dos campos de Pessoa e renderizou automaticamente a tabela, o formulário e os botões de ação.
Você só declarou o modelo — o Core fez o resto.
Próximo passo
Edite backend/src/models/Pessoa.js para adicionar campos, ou explore os templates disponíveis para casos de uso mais ricos.