# @oondemand/create-central-oon

Gerador de **Centrais Oon declarativas**. Cria backend e frontend prontos para consumir `@oondemand/oon-core-back` e `@oondemand/oon-core-front`, sem copiar shell, autenticação, páginas genéricas ou infraestrutura para a Central.

## Uso

```bash
npx create-central-oon central-transtour
npx create-central-oon central-transtour --template=servicos-tomados
npx create-central-oon --list
```

Aliases: o binário também responde por `scaffold-central-oon`.

## Contrato `central.app.json`

Toda Central gerada possui um manifesto raiz com identidade e capabilities:

```json
{
  "$schema": "./node_modules/@oondemand/create-central-oon/schemas/central.app.schema.json",
  "schemaVersion": 1,
  "id": "central-exemplo",
  "name": "Central Exemplo",
  "slug": "central-exemplo",
  "appKind": "member-central",
  "modules": {
    "collections": true,
    "documents": false,
    "pipelines": false,
    "integrations": false,
    "omie": false,
    "assistants": false,
    "currencies": false
  },
  "capabilities": ["core.collections"],
  "compatibility": {
    "core": {
      "minVersion": "0.3.45",
      "maxVersionExclusive": "0.4.0"
    }
  }
}
```

O schema versionado é publicado no pacote em:

```txt
@oondemand/create-central-oon/schemas/central.app.schema.json
```

Responsabilidades do manifesto:

- identidade estável (`id`, `name`, `slug`);
- perfil arquitetural (`appKind`);
- módulos e capabilities habilitados;
- faixa compatível do OonCore;
- metadados declarativos de ativação.

`backend/central.config.js` fica reservado a extensões excepcionais de runtime. Em Centrais `member-central` e `portal-cockpit`, identidade, módulos e autenticação não podem ser reintroduzidos nesse arquivo. O token local de desenvolvimento é validado pelo próprio OonCore por `DEV_TOKEN`.

## Verificação de conformidade

Na raiz da Central:

```bash
npm run ooncore:conformance
```

ou:

```bash
npx create-central-oon conformance
npx create-central-oon conformance --json
```

O comando falha quando encontra, entre outros desvios:

- ausência ou incompatibilidade de `central.app.json`;
- transformações ou registries no bootstrap do frontend;
- páginas genéricas e extensões executáveis locais;
- identidade ou autenticação reintroduzida em `central.config.js`;
- models técnicos de integração;
- workers, runtimes, locks, clients Omie ou registries locais;
- patches de métodos do Mongoose;
- arquivos com extensões fora da allowlist.

A CI de uma Central deve executar o comando antes do build e da publicação.

## Documentação interna para Codex

O pacote inclui documentação canônica em `docs/`. Ao criar uma Central, o CLI gera `.ooncore/` como cache local da documentação da versão instalada.

```bash
npm run ooncore:docs
npm run ooncore:docs:check
```

A pasta `.ooncore/` não é fonte de verdade; ela pode ser regenerada a partir do pacote npm.

## Templates funcionais

| Template | O que gera |
| --- | --- |
| `basic` | Uma coleção dinâmica (`Pessoa`). |
| `omie-sidecar` | Estrutura declarativa inicial para mapping Omie. |
| `servicos-tomados` | Prestadores e esteira por status. |
| `servicos-prestados` | Clientes e esteira por etapa. |
| `pedidos-marketplace` | Catálogo e esteira de pedidos. |
| `documentos-fiscais` | Documento fiscal com aprovação. |
| `multi-moedas` | Moedas e cotações. |

## Estrutura gerada

```txt
<central>/
├── central.app.json            # identidade, appKind, módulos e capabilities
├── package.json                # docs, conformance e comandos locais
├── .ooncore/                   # cache regenerável da documentação
├── backend/
│   ├── central.config.js       # somente extensão excepcional de runtime
│   ├── central.domain.json     # domínio declarativo
│   └── src/{validations,triggers,hooks,mappings,rules}/
└── frontend/
    ├── central.ui.json         # telas, formulários, grids e esteiras
    └── src/main.tsx            # bootstrap mínimo gerado
```

O bootstrap gerado importa `central.app.json` e `central.ui.json` e chama `startCentralFromManifest`. Não deve transformar manifestos, registrar componentes padrão nem conhecer regras de um cliente.

## Próximos passos

```bash
cd <central>
npm run check

cd backend && cp .env.example .env && npm run dev
cd ../frontend && cp .env.example .env && npm run dev
```

Evoluir a Central significa declarar domínio, UI, mappings e regras específicas. O OonCore implementa como a aplicação funciona.