Pular para o conteúdo principal

Feature - Onboarding Personal

Introdução ao documento​

Este documento descreve o fluxo de onboarding personal implementado em src/flows/personal.ts. Evidência: src/flows/personal.ts:52

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 do flow em personal.ts.
  • Integrações WP, ViaCEP e fila de link de grupo. Evidência: src/flows/personal.ts:72 Evidência: src/flows/personal.ts:105 Evidência: src/flows/personal.ts:207

Visão geral​

O fluxo personal valida elegibilidade de matrícula, coleta endereço por CEP, registra aceite de termos, permite seleção de turma e finaliza inscrição. Evidência: src/flows/personal.ts:85 Evidência: src/flows/personal.ts:103 Evidência: src/flows/personal.ts:169 Evidência: src/flows/personal.ts:190

Atores​

  • Usuário final no WhatsApp Flow.
  • API de WordPress (dados de curso, perfil e matrícula).
  • ViaCEP para preenchimento de endereço. Evidência: src/flows/personal.ts:61 Evidência: src/flows/personal.ts:85 Evidência: src/flows/personal.ts:105

Pré-condições​

  • flow_token válido com course_slug e user_id.
  • Dados de curso disponíveis (getCourseDetails).
  • Endpoints WordPress acessíveis para status e matrícula. Evidência: src/utils/flowSession.ts:7 Evidência: src/server.ts:326 Evidência: src/flows/personal.ts:85 Evidência: src/flows/personal.ts:192

Fluxo principal​

  1. INIT retorna tela de apresentação.
  2. Em PRESENTATION, valida se já está inscrito.
  3. LOCATION consulta CEP no ViaCEP.
  4. LOCATION_CONFIRM persiste endereço em WP.
  5. TERMS e TERMS_COMMITMENT registram aceite e consultam disponibilidade.
  6. SELECT_CLASS realiza matrícula e enfileira link de grupo.
  7. Retorna FINAL. Evidência: src/flows/personal.ts:61 Evidência: src/flows/personal.ts:85 Evidência: src/flows/personal.ts:105 Evidência: src/flows/personal.ts:134 Evidência: src/flows/personal.ts:169 Evidência: src/flows/personal.ts:192 Evidência: src/flows/personal.ts:220

Fluxos alternativos​

  • flow_token inválido retorna tela ERROR.
  • CEP inválido retorna erro e mantém usuário no fluxo de localização.
  • Sem turma disponível retorna erro em TERMS_COMMITMENT.
  • Falha de matrícula retorna erro em SELECT_CLASS. Evidência: src/server.ts:314 Evidência: src/flows/personal.ts:106 Evidência: src/flows/personal.ts:170 Evidência: src/flows/personal.ts:194

Regras de negócio​

  • Usuário já inscrito não prossegue no fluxo.
  • Endereço só avança quando cidade/UF/logradouro/CEP estão preenchidos.
  • Termo (term=true) é persistido antes da seleção de turma.
  • O enfileiramento de link de grupo é best-effort (erro não bloqueia finalização). Evidência: src/flows/personal.ts:87 Evidência: src/flows/personal.ts:133 Evidência: src/flows/personal.ts:165 Evidência: src/flows/personal.ts:214

Estados possíveis (quando houver)​

  • PRESENTATION, LOCATION, LOCATION_CONFIRM, TERMS, TERMS_COMMITMENT, SELECT_CLASS, FINAL, ERROR. Evidência: src/flows/personal.ts:18 Evidência: src/flows/personal.ts:25 Evidência: src/flows/personal.ts:35 Evidência: src/flows/personal.ts:190 Evidência: src/flows/personal.ts:220

Endpoints envolvidos​

  • POST /
  • Endpoints WordPress consumidos internamente (/course/enrolled, /enroll/{slug}, /registration/people/{id}). Evidência: src/server.ts:102 Evidência: src/features/api/wp/getCourseEnrollStatus.ts:14 Evidência: src/features/api/wp/enrollToCourse.ts:18 Evidência: src/features/api/wp/wpPatchProfile.ts:36

Dados impactados​

  • Dados de perfil e matrícula no WordPress (sistema externo).
  • Fila local GroupLinkDispatchQueue quando há matrícula bem-sucedida.
  • Referência de dados locais: ../data/model.md. Evidência: src/flows/personal.ts:134 Evidência: src/flows/personal.ts:192 Evidência: src/flows/personal.ts:207

Pendências​

  • Confirmar tratamento de timeout/erro de integração WP para mensagens funcionais mais granulares em todas as telas. Evidência: src/flows/personal.ts:194 Evidência: src/features/api/wp/enrollToCourse.ts:20