# Continuidade do primeiro pagamento

Destino: núcleo. Sem mudança de schema, trigger financeiro, provedor ou configuração de autenticação.

## Autoridade e caminho

SignupForm envia `continuar_pagamento` somente para escolha explícita de plano sem trial, fora de convite. `signUp` revalida o plano oferecido antes de criar a conta. Só uma identidade nova efetivamente criada pelo GoTrue pode gerar a intenção, vinculada a usuário, UUID planejado da empresa, plano, nonce, versão e sete dias de validade. `INTERNAL_SECRET` assina o recibo HMAC SHA-256; não há segredo público de reserva. A auditoria aceita INSERT autenticado de tenants: sua mera presença **não** autoriza cobrança. Só a assinatura verificada prova a origem. Ausência, expiração, adulteração ou segredo indisponível mantêm continuação manual.

`ensureTenantForUser` verifica o recibo antes do INSERT e usa o UUID da empresa escolhido pelo servidor. Não toma esse UUID da metadata editável. Sem recibo válido, conserva a geração nativa de UUID. Membership existente continua retornando antes de qualquer provisionamento; colisão do UUID reservado não gera uma segunda empresa com outro UUID. Leitura de intenção que falha fecha o provisionamento e conserva o caminho de erro/recuperação nativo. A continuação exige igualdade exata entre esse UUID assinado e a empresa da sessão: outra empresa da mesma pessoa/plano não herda o aceite.

A confirmação anti-scanner, convite, Google, recuperação e MFA conservam seus handlers. Após Auth, o gate financeiro continua barrando acesso ao produto. O hub reconhece `pagamento_inicial_pendente=true`, sem período pago nem assinatura ativa, e leva administradores fora do modo suporte a `/cobranca/contratar`. Pedido LGPD e ajuda continuam no hub. Dívida posterior e suspensão administrativa conservam seu fluxo. Usuários sem papel financeiro recebem orientação, sem checkout automático.

A porta financeira compartilha uma régua entre hub e continuação: admin da organização ou poder pleno de plataforma, sempre fora do modo suporte. Plataforma somente leitura sem papel admin permanece no hub; não há redirect em laço nem nova autoridade financeira. O guard de sessão/MFA e `requireRole` continuam sendo nativos. Estado `cancelada` retira a continuação automática mesmo com recibo não expirado; a tela informa o estado e uma retomada exige clique atual.

O GET da continuação só lê estado da organização da sessão e preço/período do plano no banco. O componente inicia POST nativo apenas quando recebeu intenção válida, os dados obrigatórios já existem e a empresa ainda não tem fatura nem cliente no provedor (`checkout_url` e `provedor_cliente_id` nulos). Leitura que falha não derruba a tela: sem estado ela mostra tentar de novo e o suporte; sem intenção legível, só a continuação manual. CPF/CNPJ faltante pede preenchimento e um único Continuar para pagamento; digitar não envia. Não guarda documento na intenção nem na auditoria. Convite, trial e login sem intenção não criam pagamento automático.

## Dinheiro, concorrência e retorno

`POST /api/v1/cobranca/assinatura/checkout` conserva requireRole, suporte, MFA e módulo nativos. A continuação automática relê o recibo, que só prova a intenção: a chave idempotente é a do clique (`Idempotency-Key`), nunca o nonce, e o mesmo plano é exigido antes do CAS da reserva. Reserva também filtra esse plano. Link ainda válido ou assinatura já existente são reutilizados pelo mecanismo nativo. Falhas não provocam loop de retry automático. O caminho manual exige clique atual autenticado como antes.

O retorno passa pela ponte nativa de cookie Strict e destino fixo permitido. Antes de sair ao gateway, histórico local ganha `retomar=1`, evitando redirecionamento automático ao voltar. `voltou=1` e Já paguei apenas chamam a sincronização nativa. Só `estado=ativa` **e** `org_operante=true` levam ao onboarding. Query de sucesso ou declaração humana não liberam uso. Valor anual mostra o total pago de uma vez; preço não vem da URL.

## Régua e retorno do provedor

CONFIRMADO pelo código: `aplicarRegua` usa `primeiroPagamentoPendente`, que exige a marca inicial, ausência de período pago e assinatura ainda não ativa. Nesse estado, e enquanto a empresa está suspensa por cobrança, a régua não agenda aviso de inadimplência; reativada pelo "Dar prazo" sem ter pago, volta a avisar e suspender quando o prazo vence. Uma marca inicial antiga numa assinatura ativa ou com período pago não silencia o atraso legítimo. Cancelamento e sincronização financeira conservam seus caminhos nativos, e retry de aviso real continua deduplicado.

CONFIRMADO pelo código: o adaptador Asaas configura `callback.successUrl` com `voltou=1` e `autoRedirect=true` na assinatura e na primeira fatura; a atualização idempotente da fatura também cobre assinatura recuperada após retry. O callback é **melhor esforço**: o Asaas exige que o `successUrl` seja do domínio cadastrado na conta do vendedor, e a conta sem domínio recusa a criação inteira. Por isso URL de volta que não é HTTPS (fora do loopback injetado para teste), ou que tem credencial ou fragmento, segue **sem** callback; recusa 4xx do POST com callback é refeita uma vez sem ele (4xx não processou; 5xx/rede nunca são refeitos); e falha do PUT na fatura só vai ao log (`cobranca.asaas.callback_nao_aplicado`), sem derrubar o link. Sem callback a cobrança sai igual, e a volta é o Já paguei, que relê. Nenhum callback marca pagamento ou aceita valor/plano vindo da URL. NÃO MEDIDO: o status e o `code` exatos que o Asaas devolve para callback de domínio não cadastrado.

## Living System Checklist

1. Entrada: formulário validado, identidade nova do GoTrue, auditoria assinada e estado atual da org da sessão.
2. Saída: hub → `/cobranca/contratar` → checkout nativo → ponte de retorno → sincronização → onboarding.
3. Registro: `auth.signup_requested` recebe intenção assinada; `cobranca.checkout_iniciado` continua no helper financeiro nativo.
4. Tela: continuação mostra plano/período, estado e erro recuperável; hub mantém LGPD e recuperação.
5. Porta: redirect do hub financeiro, link Continuar para pagamento em ajuda, retorno nativo do provedor. Fora de `app/app/**`, não é item do menu do produto bloqueado.
6. Anti-morte: documento faltante, ausência de provedor, erro e retorno pendente sempre mostram próximo passo. Sem reenvio externo automático.
7. Configuração: planos e provedor nas superfícies administrativas nativas; módulo desligado conserva seus gates; falha de provedor aparece na continuação.
8. Continuidade IA/humano: não há agente, conversa ou handoff nesta contratação autenticada; não altera os mecanismos existentes.
9. Laço: erro permite retry explícito; checkout pendente é reutilizado; confirmação nativa reavalia estado e acesso. Não cria aprendizado nem aprovação financeira pela tela.
10. Mapa: `continuidade-primeiro-pagamento.architecture.json`, com entradas e saídas concretas.

## Prova e limites

Testes dirigidos verificam assinatura adulterada/expirada, vínculo de pessoa e plano, negativa sem intenção, primeiro pagamento versus dívida, LGPD, suporte/papéis, POST único/StrictMode, documento, reserva, erro, link inseguro e retorno pendente/confirmado. Os handlers de confirmação e recuperação são reutilizados em regressão. Banco, Auth e gateway são dublês; não prova entrega de e-mail nem liquidação real. Build, UI servida e promoção têm recibos próprios; não se inferem destes testes.