feat(onboarding): cadeia de pré-requisito Welcome => Squads (#351)

[cristopherpds]

Contexto

O onboarding Squads (APTO) não pode ser iniciado por quem ainda não concluiu o onboarding Welcome — essa é a cadeia de pré-requisito inter-tipo prevista no PRD (#341). Até então, SquadsOnboardingFlow::prerequisites() retornava [] (com um TO-DO: #351) e o StartOnboarding não validava nada, permitindo iniciar o Squads sem o Welcome concluído.

Este PR implementa a cadeia: o flow do Squads declara [Welcome] como pré-requisito e o StartOnboarding valida cada pré-requisito através do gate público OnboardingCompletionGate::isCompleted() (#349) antes de qualquer escrita. Quando o pré-requisito não está completed, o início é bloqueado com uma PrerequisiteNotMetException que carrega o tipo bloqueado e o pré-requisito faltante como motivo — nenhum onboarding órfão é persistido.

Alterações

• src/Flows/SquadsOnboardingFlow.php — prerequisites() passa a retornar [OnboardingType::Welcome].
• src/Actions/StartOnboarding.php — recebe o OnboardingCompletionGate por injeção e valida os pré-requisitos do flow antes da transação; classe agora é final readonly.
• src/Exceptions/PrerequisiteNotMetException.php — nova exception com type e prerequisite públicos (o motivo do bloqueio), no mesmo estilo da GateBlockedException.
• database/factories/OnboardingFactory.php — novo state completed() para os testes.
• tests/Feature/OnboardingPrerequisiteChainTest.php — novo teste cobrindo os cenários BDD da issue: Squads sem Welcome é bloqueado com o motivo (inclusive com Welcome apenas in_progress), Welcome concluído destrava o Squads, e Welcome segue sem pré-requisitos.
• tests/Feature/SquadsOnboardingFlowTest.php — atualizado: prerequisites() agora esperado como [Welcome] e os testes que iniciam Squads concluem o Welcome antes.

Critérios de aceite

• prerequisites() do Squads = [Welcome]
• Iniciar Squads sem Welcome concluído é bloqueado com motivo
• Iniciar Squads com Welcome concluído funciona
• Teste da cadeia

---

Plano de Testes

• Executar make check (Rector, Pint e PHPStan passando)
• Executar make test — módulo onboarding: 35/35 testes passando
• Suíte completa: 949/951 — as 2 falhas são em MergeDuplicateDiscordProfilesTest (módulo integration-discord) e pré-existentes: reproduzem de forma idêntica na base feat/squads (8ab4cce0) sem este commit. Este PR toca apenas app-modules/onboarding, sem código compartilhado com esse teste
• Revisor: conferir que os cenários BDD da issue feat(onboarding): cadeia de pré-requisito (Welcome ⇒ Squads) #351 correspondem aos testes de OnboardingPrerequisiteChainTest"

---

Issues Relacionadas

Closes #351
Related to #341

[BrunaDomingues]

LGTM!

[sirelves]

Implementação está correta e no tamanho certo do problema: os pré-requisitos são
validados antes da transação (nenhum onboarding órfão), a exception carrega o
type e o prerequisite como motivo, e o throw_unless com named args segue o
mesmo padrão que já existe no createNextStep do Squads. Nada de camada nova pra
resolver isso, que era o risco aqui.

Deixei um comentário num teste, é uma linha e não trava o merge.

Sobre os outros testes que usam ->completed()->create() sem dizer o tipo: não me
preocupa. Se o default do factory mudar, eles falham em vez de passar errado, que
é o comportamento que a gente quer. Fica como preferência: um
['type' => OnboardingType::Welcome] explícito faria o cenário se ler no próprio
teste, sem precisar abrir o factory.

Aproveitando: cheguei a levantar se a validação no handle poderia bloquear um
Squads que já existe, já que o firstOrCreate fazia o método ser idempotente. Fui
olhar e o OnboardingStatus::Completed é terminal (allowedTransitions() retorna
[]), então um Welcome concluído nunca volta a ficar incompleto e o cenário não é
alcançável. Deixo registrado só pra não ficar a dúvida.

[buzinei-bibi]

lgtm