Pular para o conteúdo principal

Feature - Onboarding Business com Integrações Sebrae

Introdução ao documento​

Este documento descreve o fluxo business, incluindo coleta de dados empresariais, validações de CNPJ e integrações condicionais com Sebrae. Evidência: src/flows/business.ts:132

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:16

Referencial teórico​

  • Máquina de telas de business.ts.
  • Feature flags de integração Sebrae.
  • Utilitário de validação de CNPJ. Evidência: src/flows/business.ts:156 Evidência: src/flows/business.ts:16 Evidência: src/utils/cnpj.ts:1

Visão geral​

O fluxo business coleta dados de empresa e endereço, valida parceiro ALI, captura aceite de termos, realiza matrícula e pode sincronizar dados/presença com Sebrae quando habilitado. Evidência: src/flows/business.ts:216 Evidência: src/flows/business.ts:307 Evidência: src/flows/business.ts:513 Evidência: src/flows/business.ts:575 Evidência: src/flows/business.ts:616

Atores​

  • Usuário final no WhatsApp Flow.
  • APIs WordPress e Sebrae.
  • ViaCEP para preenchimento de endereço. Evidência: src/flows/business.ts:2 Evidência: src/flows/business.ts:5 Evidência: src/flows/business.ts:4

Pré-condições​

  • flow_token válido com course_slug e user_id.
  • FEATURE_SEBRAE_INTEGRATION e FEATURE_SEBRAE_ADDRESS_INTEGRATION configuram caminhos de execução.
  • Acesso aos endpoints WordPress para perfil/matrícula. Evidência: src/utils/flowSession.ts:7 Evidência: src/flows/business.ts:16 Evidência: src/flows/business.ts:225

Fluxo principal​

  1. INIT apresenta introdução do curso.
  2. PRESENTATION valida elegibilidade e, se habilitado, lista empresas via Sebrae.
  3. Usuário informa/seleciona dados empresariais (BUSINESS, BUSINESS_LIST, BUSINESS_CNPJ, BUSINESS_NAME).
  4. Endereço é obtido por Sebrae (quando habilitado) ou ViaCEP/manual (BUSINESS_LOCATION, BUSINESS_LOCATION_CONFIRM).
  5. Captura PCD/ALI e valida código de parceiro quando aplicável.
  6. Registra termos, verifica turmas, matricula e sincroniza presença Sebrae (quando habilitado).
  7. Enfileira link de grupo e finaliza. Evidência: src/flows/business.ts:145 Evidência: src/flows/business.ts:181 Evidência: src/flows/business.ts:264 Evidência: src/flows/business.ts:366 Evidência: src/flows/business.ts:513 Evidência: src/flows/business.ts:579 Evidência: src/flows/business.ts:639

Fluxos alternativos​

  • flow_token inválido retorna ERROR.
  • CNPJ inválido bloqueia avanço em BUSINESS_CNPJ.
  • CEP não localizado permite preenchimento manual.
  • Código ALI inválido retorna erro e mantém tela.
  • Sem turma disponível retorna erro em TERMS_COMMITMENT. Evidência: src/flows/business.ts:158 Evidência: src/flows/business.ts:308 Evidência: src/flows/business.ts:413 Evidência: src/flows/business.ts:529 Evidência: src/flows/business.ts:580

Regras de negócio​

  • Integrações Sebrae só são usadas quando FEATURE_SEBRAE_INTEGRATION === "true".
  • Seleção de empresa pode cair para caminho manual quando opção NAO_ENCONTREI.
  • Validação de CNPJ é obrigatória no caminho BUSINESS_CNPJ.
  • Sync de presença com Sebrae ocorre após matrícula bem-sucedida e feature habilitada. Evidência: src/flows/business.ts:182 Evidência: src/flows/business.ts:299 Evidência: src/flows/business.ts:308 Evidência: src/flows/business.ts:616

Estados possíveis (quando houver)​

  • PRESENTATION, BUSINESS, BUSINESS_LIST, BUSINESS_CNPJ, BUSINESS_NAME, BUSINESS_LOCATION, BUSINESS_LOCATION_CONFIRM, PCD, ALI, TERMS, TERMS_COMMITMENT, SELECT_CLASS, FINAL, ERROR. Evidência: src/flows/business.ts:32 Evidência: src/flows/business.ts:67 Evidência: src/flows/business.ts:107 Evidência: src/flows/business.ts:562 Evidência: src/flows/business.ts:650

Endpoints envolvidos​

  • POST /
  • Endpoints WordPress e Sebrae consumidos internamente no fluxo. Evidência: src/server.ts:102 Evidência: src/features/api/wp/getUserData.ts:14 Evidência: src/features/api/wp/enrollToCourse.ts:18 Evidência: src/features/api/sebrae/getPersonCompanies.ts:12 Evidência: src/features/api/sebrae/updatePersonAttendance.ts:16

Dados impactados​

  • Dados de perfil/matrícula em WordPress (externo).
  • Dados de pessoa/presença em Sebrae (externo, quando habilitado).
  • Fila local GroupLinkDispatchQueue para envio de link de grupo.
  • Referência de dados locais: ../data/model.md. Evidência: src/flows/business.ts:342 Evidência: src/flows/business.ts:576 Evidência: src/flows/business.ts:635 Evidência: src/flows/business.ts:639

Pendências​

  • Confirmar matriz oficial de comportamento por combinação de feature flags (Sebrae on/off e address on/off).
  • Confirmar política de fallback quando APIs externas retornam payload parcial. Evidência: src/flows/business.ts:16 Evidência: src/flows/business.ts:367 Evidência: src/features/api/sebrae/getPersonCompanies.ts:13