@oondemand/create-ooncore-back

Scaffold oficial do backend da fábrica de software oondemand: uma API Node.js + Express + MongoDB (Mongoose), com autenticação JWT, integração Omie, documentação Swagger, audit log (ImmutableLog) e infra de deploy (Docker/Kubernetes) já incluída.

Este pacote é um gerador de projeto (estilo create-*): ele cria, na sua máquina, um novo backend já renomeado e pronto para configurar.

Índice

• Pré-requisitos
• Início rápido
• Uso passo a passo
• Regras do slug
• O que o gerador faz
• Estrutura do projeto gerado
• Configuração (.env)
• Banco de dados (MongoDB)
• Executando o projeto
• Ativação inicial (POST /ativacao)
• Documentação da API (Swagger)
• Customização para o cliente
• Deploy
• Solução de problemas

Pré-requisitos

| Ferramenta | Versão | Observação | |---|---|---| | Node.js | ≥ 16.7 | necessário para o gerador (fs.cpSync). O projeto roda bem em Node 18/20/22. | | npm | ≥ 7 | já vem com o Node. | | MongoDB | 5+ | local, Docker ou Atlas. Há um docker-compose.yml pronto no projeto. |

Início rápido

# 1. Gerar o projeto (pergunta o slug, ex: unimed)
npm create @oondemand/ooncore-back@latest

# 2. Entrar e instalar
cd projeto-unimed-backend
npm install

# 3. Configurar ambiente
cp .env.exemple .env      # edite os valores

# 4. Subir um MongoDB (se não tiver um)
docker compose -f infra/docker/docker-compose.yml up -d

# 5. Rodar em desenvolvimento
npm run dev               # API em http://localhost:4000

Uso passo a passo

1. Executar o gerador

De dentro da pasta onde você quer criar o projeto, rode:

npm create @oondemand/ooncore-back@latest

O comando pergunta:

Slug do projeto: unimed

Você também pode passar o slug direto, pulando a pergunta:

npm create @oondemand/ooncore-back@latest unimed

O resultado é uma pasta projeto-unimed-backend/ no diretório atual.

O gerador aborta se já existir uma pasta com esse nome — ele nunca sobrescreve algo existente.

2. Instalar dependências

cd projeto-unimed-backend
npm install

3. Criar o .env

cp .env.exemple .env

Edite o .env (veja a tabela de variáveis). No mínimo, ajuste a conexão do banco (DB_*) e o JWT_SECRET.

4. Subir o banco e a API

# Mongo local via Docker (opcional, se você ainda não tem um)
docker compose -f infra/docker/docker-compose.yml up -d

npm run dev

A API sobe em http://localhost:4000 (porta configurável via PORT).

5. Ativar o sistema

Na primeira execução, rode a ativação inicial para criar os dados base.

Regras do slug

• Informe apenas o slug (ex: unimed) — sem projeto- e sem -backend. O gerador monta o nome completo (projeto-unimed-backend).
• Formato aceito: kebab-case — letras minúsculas, números e hífens. Regex: ^[a-z0-9]+(-[a-z0-9]+)*$.
• Exemplos válidos: unimed, acme, acme-cotacoes.
• Inválidos: Unimed (maiúscula), acme_cotacoes (underscore), acme cotacoes (espaço).

O que o gerador faz

1. Valida o slug e checa se a pasta de destino já existe (aborta se existir).
2. Copia o template do backend para projeto-<slug>-backend/.
3. Restaura o .gitignore (publicado como gitignore por uma limitação do npm).
4. Ajusta o package.json → campo name para projeto-<slug>-backend.
5. Ajusta o .env.exemple → SERVICE_NAME=projeto-<slug>-backend.
6. Mostra os próximos passos.

O gerador não roda npm install nem cria o .env automaticamente — esses passos são seus, após revisar a configuração.

Estrutura do projeto gerado

projeto-<slug>-backend/
├── .env.exemple            # modelo de variáveis de ambiente
├── .gitignore
├── .github/workflows/      # pipelines de deploy (homolog/prod)
├── infra/
│   ├── docker/             # Dockerfile.dev, Dockerfile.prod, docker-compose.yml (Mongo)
│   └── kubernetes/         # manifests de deployment/ingress/service
├── src/
│   ├── server.js           # bootstrap (porta, conexão DB)
│   ├── app.js              # Express, middlewares e rotas
│   ├── config/             # db, logger, multer, apiOmie
│   ├── controllers/        # handlers HTTP por domínio
│   ├── routers/            # rotas Express por domínio
│   ├── services/           # regra de negócio
│   ├── models/             # schemas Mongoose
│   ├── middlewares/        # auth, audit log, log, erro
│   ├── seeds/              # JSONs de dados base (ativação)
│   ├── constants/          # enums (ex.: LISTAS)
│   ├── utils/              # helpers, paginação, excel
│   └── docs/swagger/       # documentação OpenAPI
└── package.json

Configuração (.env)

| Variável | Obrigatória | Padrão / exemplo | Descrição | |---|---|---|---| | NODE_ENV | não | development | development habilita logs (morgan) e nodemon. | | SERVICE_NAME | sim | projeto-<slug>-backend | Nome do serviço (logs, audit log). Já ajustado pelo gerador. | | PORT | não | 4000 | Porta da API. | | DB_SERVER | sim | mongodb://localhost:27017 | Host do MongoDB. | | DB_USER | sim | admin | Usuário do banco. | | DB_PASSWORD | sim | senha123 | Senha do banco. | | DB_NAME | sim | core-oon | Nome do banco. | | DB_AUTH_SOURCE | não | admin | Banco de autenticação do Mongo. | | DB_REPLICA_SET | não | — | Nome do replica set (Atlas/cluster). | | DB_TSL | não | — | Flag de TLS, quando aplicável. | | API_OMIE | sim* | https://app.omie.com.br/api/v1/ | Base da API Omie (se usar integração Omie). | | JWT_SECRET | sim | jwt_secret | Segredo de assinatura dos tokens JWT. Troque em produção. | | MEUS_APPS_BACKEND_URL | não | https://api.meus-apps.oondemand.online | Integração com o ecossistema oondemand. | | API_IMTBL_KEY | não | — | Habilita o audit log ImmutableLog. Sem ela, o middleware é no-op. | | API_IMTBL_URL | não | (default no código) | Base URL do ImmutableLog. | | IMTBL_SERVICE_NAME | não | — | Sobrescreve o service nos eventos de auditoria. | | IMTBL_ENV | não | NODE_ENV | Sobrescreve o env nos eventos. |

* "Obrigatória" depende do escopo: se o projeto não usar Omie, API_OMIE é dispensável.

Banco de dados (MongoDB)

O projeto já traz um docker-compose.yml com um MongoDB pronto:

docker compose -f infra/docker/docker-compose.yml up -d

Isso sobe um Mongo em localhost:27017 com usuário admin / senha senha123 (combina com o .env.exemple). Para parar:

docker compose -f infra/docker/docker-compose.yml down

Prefere Atlas ou um Mongo gerenciado? Basta apontar DB_SERVER/DB_USER/DB_PASSWORD/DB_REPLICA_SET no .env.

Executando o projeto

| Comando | O que faz | |---|---| | npm run dev | Desenvolvimento com nodemon + NODE_ENV=development (reinício automático). | | npm start | Produção (node src/server.js). | | npm run format | Formata o código com Prettier. | | npm run release | Bump de versão + changelog (release-it). |

Após npm run dev, verifique a saúde da API acessando http://localhost:4000/ (rota de status).

Ativação inicial (POST /ativacao)

Em um banco recém-criado, é preciso rodar a ativação uma única vez. Ela cria os dados base: configuração Omie, sistemas, etapas, assistentes, listas Omie, moedas, integrações e as listas vazias (correção já incluída neste template, que evita erros 404 nas telas logo após a ativação).

Chame o endpoint (uma vez só — se já houver dados, retorna 400 "Ativação já realizada"):

curl -X POST http://localhost:4000/ativacao \
  -H "Content-Type: application/json" \
  -d '{
    "baseOmie": { "appKey": "SUA_APP_KEY", "appSecret": "SEU_APP_SECRET" },
    "appKey": "SUA_APP_KEY",
    "openIaKey": "SUA_OPENAI_KEY"
  }'

Confirme o contrato exato em /docs (Swagger) do seu projeto — os campos esperados pelo endpoint podem evoluir conforme o escopo do cliente.

Documentação da API (Swagger)

Com a API no ar, a documentação interativa fica em:

http://localhost:4000/docs

Customização para o cliente

O gerador faz apenas o scaffold mínimo (renomear pacote e serviço). O rebrand e a configuração de escopo do cliente (identidade, menus, módulos habilitados, logo) são feitos depois, dentro do projeto gerado, seguindo o documento config_default.md da fábrica oondemand.

Deploy

O projeto inclui:

• infra/docker/Dockerfile.dev e Dockerfile.prod — imagens de dev e produção.
• infra/kubernetes/ — manifests de deployment, ingress e service (homolog e prod).
• .github/workflows/deploy.yml e deploy-homolog.yml — pipelines de CI/CD.

Esses arquivos vêm do boilerplate e devem ser ajustados (nomes de imagem, hosts, secrets) para a infraestrutura do cliente.

Solução de problemas

| Sintoma | Causa provável | Solução | |---|---|---| | The directory ... já existe. Abortando. | Já existe projeto-<slug>-backend | Use outro slug ou remova/renomeie a pasta. | | Erro de conexão com o Mongo | Banco não está no ar / DB_* errado | Suba o docker-compose ou ajuste o .env. | | Telas retornam 404 em /listas/:codigo | Ativação não foi rodada | Rode POST /ativacao. | | npm create baixa versão antiga | Cache do npm | Use @latest ou npm create @oondemand/[email protected]. | | Node reclama de fs.cpSync/sintaxe | Node < 16.7 | Atualize o Node. |

Versão e manutenção

Pacote escopado público na org oondemand. Para publicar novas versões deste gerador, consulte o runbook em project-scopes/npm_core.md (inclui o passo de OTP/2FA do npm).

Licença

Veja template/LICENSE-ODR-NC-v1.0.md.