Prompts para apps da Takeat Store

Crie ou complete a especificação técnica deste projeto para que ele funcione
como um aplicativo instalável na Takeat Store usando OAuth 2.0 Authorization
Code com PKCE S256.

Contexto do produto:
- nome: [NOME DO PRODUTO]
- objetivo para o restaurante: [OBJETIVO]
- funcionalidades da Takeat necessárias: [FUNCIONALIDADES]
- ambientes e callbacks pretendidos: [AMBIENTES E CALLBACKS, SEM SEGREDOS]

Antes de editar, inspecione a estrutura, os documentos e as convenções do
projeto. Descubra se já existe uma especificação canônica; se existir,
atualize-a no lugar. Caso contrário, crie um documento Markdown em uma pasta de
documentação coerente com o repositório. Preserve alterações alheias.

Use somente as fontes oficiais:
https://docs.takeat.app/llms.txt
https://docs.takeat.app/md/v1/oauth.md
https://docs.takeat.app/md/v1/takeat-store.md
https://docs.takeat.app/openapi-v1.yaml
Leia também o contrato Markdown de cada rota /v1 necessária. Não invente
endpoints, campos, escopos ou garantias que não estejam publicados.

A especificação deve registrar:
1. Escopo funcional do app e fluxos visíveis ao restaurante.
2. Separação entre o navegador, o backend do app, o portal OAuth da Takeat e a
   External API. O navegador inicia o redirect, mas troca e armazena tokens
   somente através do backend do app.
3. Cliente público tk_app_..., sem client_secret. Redirect URIs devem coincidir
   exatamente com o cadastro e cada ambiente deve ter configuração própria.
4. state aleatório, opaco, de uso único e com expiração; code_verifier aleatório
   de 43 a 128 caracteres; challenge BASE64URL(SHA256(verifier)); método S256.
   Relacione state, verifier, redirect URI e contexto do usuário no backend.
5. Callback que trata code ou error, compara state antes da troca e consome a
   tentativa uma única vez. Não coloque code, verifier ou tokens em logs,
   analytics, URLs internas ou mensagens de erro.
6. POST /oauth/token com application/x-www-form-urlencoded e somente
   grant_type=authorization_code, client_id, code, redirect_uri e code_verifier.
7. Armazenamento criptografado por instalação. Use o access token como Bearer
   em /v1 e derive a validade do expires_in recebido.
8. Refresh rotativo com grant_type=refresh_token, client_id e o refresh token
   atual. Substitua o par atomicamente, coordene uma renovação por instalação e
   não repita cegamente um refresh depois de timeout.
9. Revogação e desconexão; trate reutilização de code ou refresh como sinal de
   comprometimento e exija nova autorização quando necessário.
10. Matriz de operações com método, path, escopo, campos consumidos, limites,
    cache, erros 400/401/403/409/429 e comportamento de retry.
11. Isolamento por restaurant installation em banco, cache, locks, jobs,
    observabilidade e filas. Nenhum restaurant_id vindo do navegador é uma
    autorização por si só.
12. Dados da proposta para a Takeat Store: identidade, suporte, site, política
    de privacidade, apresentação, preço, callbacks e justificativa de cada
    escopo. Inclua o compromisso do teste de sete dias sem presumir cobrança
    automática pela Takeat.
13. Plano de testes com mocks e valores fictícios: PKCE, state divergente,
    recusa, callback repetido, code expirado, refresh concorrente/reutilizado,
    revogação, escopo insuficiente e rate limit.
14. Critérios de aceite, rollout, métricas, alertas e rollback.

Não use grant_type=api_key nem client_credentials para instalar o app. As rotas
de dados usam Bearer nos dois modelos, mas isso não torna API Key e OAuth o
mesmo fluxo. Se o projeto também tiver uma automação própria com API Key,
documente-a como modo separado, com configuração, armazenamento e testes
independentes; não converta silenciosamente uma credencial na outra.

Não peça, leia, imprima ou altere segredos reais nem arquivos .env. Documente
apenas nomes de variáveis e placeholders em .env.example. Ao final, mostre o
arquivo criado ou atualizado, as decisões confirmadas pelas fontes, as lacunas
que exigem decisão humana e os testes que validarão a implementação. Não
implemente código de produção até a especificação ficar internamente
consistente.

Atualize a especificação existente deste projeto para adicionar ou migrar para
um aplicativo instalável da Takeat Store com OAuth 2.0 Authorization Code e
PKCE S256.

Comece com uma análise somente leitura. Localize a especificação canônica, os
diagramas, ADRs, variáveis de ambiente pelo nome, cliente HTTP, autenticação,
armazenamento de tokens, callbacks, jobs, filas, cache, observabilidade e
testes. Identifique separadamente chamadas à Nova API V1, API Key da Takeat,
client_credentials, login por e-mail/senha e API Legado. Não trate todos como
"OAuth" apenas porque alguma etapa retorna um Bearer token.

Leia antes de propor mudanças:
https://docs.takeat.app/llms.txt
https://docs.takeat.app/md/v1/oauth.md
https://docs.takeat.app/md/v1/takeat-store.md
https://docs.takeat.app/openapi-v1.yaml
Abra também o contrato .md de cada operação encontrada no projeto. Os
contratos publicados são a fonte da verdade; marque lacunas em vez de inventar.

Produza primeiro uma matriz "atual → alvo" com: fluxo, credencial inicial,
quem controla a credencial, tenant, armazenamento, expiração, renovação,
revogação, operação V1, escopo, mudança necessária e risco. Decida com base no
uso real:
- mantenha API Key apenas para automações controladas por um restaurante;
- use OAuth Authorization Code + PKCE para instalações de restaurantes
  diferentes;
- se ambos continuarem, preserve provedores separados e compartilhe somente o
  cliente de recursos que recebe um access token Bearer já emitido.

Atualize a especificação canônica no lugar, preservando histórico útil. Ela
deve cobrir: cliente público sem client_secret; callbacks exatos por ambiente;
state de uso único; verifier/challenge S256; callback e troca server-side;
tokens criptografados por instalação; expires_in; refresh rotativo com lock e
gravação atômica; timeout incerto; revogação; reconexão; isolamento por
restaurante; menor conjunto de escopos; 400/401/403/409/429; rate limits;
observabilidade sem segredos; e testes de replay, concorrência e falha.

Inclua uma seção Takeat Store com identidade, descrição, desenvolvedor,
suporte, site, política de privacidade, logo, screenshots, README, preço,
período, teste de sete dias, callbacks e justificativa por escopo. A Takeat não
processa automaticamente a cobrança. Enviar proposta não cria instalação;
aprovação cria o cliente público, e cada restaurante ainda precisa consentir.

Não faça substituição global de URLs ou de grant_type. Não envie API key em
/v1, não envie client_id no refresh de API Key e não omita client_id no refresh
de app para a Takeat Store. Não use client_credentials nem client_secret no fluxo público.

Segurança: não peça, leia, imprima ou altere e-mail, senha, API key, code,
code_verifier, access token, refresh token, cookie, Authorization ou arquivos
.env. Use nomes de variáveis e placeholders fictícios. Se encontrar possível
segredo, informe somente arquivo e localização com o valor mascarado e
recomende rotação.

Depois de editar a especificação, valide links, diagramas, exemplos, nomes de
campos e consistência entre requisitos, fluxos e testes. Entregue o diff
conceitual, decisões preservadas, mudanças explícitas, lacunas, riscos, plano
de implementação incremental, critérios de aceite e rollback. Não implemente a
migração de produção até eu aprovar a especificação atualizada.