Pular para o conteúdo principal

dhedalos-api-onboarding-express

Introdução ao documento​

Este README descreve o serviço Node.js/Express responsável pelo endpoint de WhatsApp Flows, rotas de OTP, webhook Meta e envio de templates integrados com APIs externas. Evidência: package.json:2 Evidência: src/server.ts:102 Evidência: src/server.ts:162

Versionamento​

  • Versão da aplicação: 1.0.0.
  • Versão deste documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: package.json:3

Referencial teórico​

  • Express para API HTTP.
  • Sequelize + SQLite para persistência local.
  • OpenAPI 3.0 para contrato HTTP em docs/api/openapi.yaml.
  • Padrão interno de documentação com seções obrigatórias. Evidência: package.json:17 Evidência: package.json:18 Evidência: package.json:19 Evidência: codex-promts.md:11 Evidência: codex-promts.md:16

Visão geral do repositório​

  • Entrypoint HTTP em src/server.ts com inicialização de DB (db.authenticate, db.sync) e start do worker de fila de link de grupo.
  • Rotas expostas: POST /, GET /, GET /api/liveness, GET /api/readiness, GET /api/status, /otp, /sendtemplate, /sendreminder, /webhook.
  • O serviço integra WhatsApp Cloud API, backend WordPress (WP_BASE_URL), API Sebrae (SEBRAE_BASE_URL) e ViaCEP. Evidência: src/server.ts:76 Evidência: src/server.ts:79 Evidência: src/server.ts:82 Evidência: src/server.ts:162 Evidência: src/server.ts:168 Evidência: src/server.ts:176 Evidência: src/routes/webhook.ts:29 Evidência: src/features/api/wp/config.ts:4 Evidência: src/features/api/sebrae/config.ts:3 Evidência: src/features/api/viacep/getAdressByCep.ts:11

Como rodar (dev/test/build)​

Node local​

npm install
npm run dev
npm run build
npm run start

Evidência: package.json:8 Evidência: package.json:9 Evidência: package.json:10

Docker local​

docker compose up --build -d

Evidência: compose.sh:4 Evidência: docker-compose.yml:3

Testes​

Não existe script test em package.json; há somente dev, build e start. Evidência: package.json:7

Variáveis de ambiente​

VariávelUso principal no código
PASSPHRASEDescriptografia da requisição de flow.
PRIVATE_KEYChave privada para decrypt de payload do flow.
APP_SECRETValidação opcional de assinatura x-hub-signature-256.
PORTPorta do app.listen (default 4000).
SERVICE_TOKENAutorização de /otp, /sendtemplate, /sendreminder.
WHATSAPP_API_TOKENAutorização na Graph API da Meta.
WHATSAPP_PHONE_IDIdentificador de telefone da API WhatsApp.
WEBHOOK_VERIFY_TOKENVerificação GET /webhook.
WP_BASE_URL e WP_API_TOKENIntegração com backend WordPress.
SEBRAE_BASE_URLIntegração com API Sebrae.
FEATURE_SEBRAE_INTEGRATIONHabilita chamadas Sebrae no fluxo business.
FEATURE_SEBRAE_ADDRESS_INTEGRATIONHabilita uso de endereço Sebrae no fluxo business.
GROUP_LINK_SEND_DELAY_MS, GROUP_LINK_MAX_ATTEMPTSConfiguração de enfileiramento do link de grupo.
GROUP_LINK_WORKER_POLL_INTERVAL_MS, GROUP_LINK_WORKER_BATCH_SIZE, GROUP_LINK_WORKER_RETRY_BASE_DELAY_MSConfiguração do worker de consumo da fila.
DATABASE_PATHCaminho do SQLite local.
DEBUGControle de logs e retorno de erro detalhado.
Evidência: .env.example:1
Evidência: .env.example:7
Evidência: .env.example:23
Evidência: src/server.ts:100
Evidência: src/server.ts:341
Evidência: src/auth/serviceToken.ts:7
Evidência: src/routes/webhook.ts:89
Evidência: src/features/api/wp/config.ts:3
Evidência: src/features/api/sebrae/config.ts:3
Evidência: src/services/groupLinkDispatchQueue.ts:21
Evidência: src/workers/groupLinkDispatchWorker.ts:13
Evidência: src/config/database.ts:5

Contexto C4 L1 (atores, integrações, dependências)​

Atores:

  • Usuário final interage via WhatsApp e aciona webhook/flows.
  • Serviços internos consomem endpoints protegidos por SERVICE_TOKEN. Dependências:
  • Persistência local SQLite para OTP e fila de link de grupo.
  • APIs externas Meta, WordPress, Sebrae e ViaCEP. Evidência: src/routes/webhook.ts:16 Evidência: src/auth/serviceToken.ts:3 Evidência: src/config/database.ts:8 Evidência: src/features/api/whatsapp/sendFlowTemplate.ts:10 Evidência: src/features/api/wp/getCourseDetails.ts:13 Evidência: src/features/api/sebrae/getPersonCompanies.ts:12 Evidência: src/features/api/viacep/getAdressByCep.ts:11

Estrutura principal​

  • src/server.ts: bootstrap HTTP, middlewares, healthchecks e montagem de rotas.
  • src/routes: handlers HTTP (otp, sendTemplate, sendGroupLink, webhook).
  • src/flows: orquestração de telas de onboarding (personal e business).
  • src/features/api: clientes HTTP para Meta, WordPress, Sebrae e ViaCEP.
  • src/models, src/services, src/workers: modelo e fila de envio de link de grupo.
  • helm e kubernetes: empacotamento/deploy em cluster.
  • .github/workflows: pipeline CI/CD e governança de documentação. Evidência: src/server.ts:7 Evidência: src/server.ts:14 Evidência: src/server.ts:12 Evidência: src/features/api/wp/index.ts:1 Evidência: src/models/groupLinkDispatchQueue.ts:60 Evidência: src/workers/groupLinkDispatchWorker.ts:171 Evidência: helm/templates/deployment.yaml:1 Evidência: .github/workflows/ci-cd-pipeline.yml:1
  • Documentação micro deste serviço: docs/overview.md.
  • Índice de features: docs/features/README.md.
  • Estrutura de documentação espelhada em subárvore local: micro-repo/README.md.
  • Não há URL Git explícita, no código versionado, para o repositório WordPress consumido por WP_BASE_URL. Evidência: micro-repo/README.md:1 Evidência: src/features/api/wp/config.ts:4

Práticas complementares (Storybook, JSDoc, Docstrings, PHPDoc, Mindmap)​

  • Storybook: não identificado neste repositório Node API (sem dependências/scripts relacionados).
  • JSDoc/Docstrings: uso parcial de comentários técnicos no código, sem padrão JSDoc abrangente.
  • PHPDoc: não aplicável neste repositório TypeScript.
  • Mindmap: disponível em docs/architecture/mindmap.md. Evidência: package.json:7 Evidência: package.json:14 Evidência: src/routes/webhook.ts:5 Evidência: docs/architecture/mindmap.md:1 Evidência: codex-promts.md:62

A documentação técnica detalhada fica na pasta docs/. Evidência: codex-promts.md:58

Pendências​

  • Confirmar se APP_SECRET, PORT e WEBHOOK_VERIFY_TOKEN devem ser adicionados ao .env.example (são usados no código, mas não estão declarados no arquivo de exemplo).
  • Confirmar URL Git dos repositórios externos relacionados (WordPress e demais sistemas), pois o código só evidencia URL base via variável de ambiente. Evidência: .env.example:1 Evidência: src/server.ts:100 Evidência: src/server.ts:341 Evidência: src/features/api/wp/config.ts:4