# Google Play Payments — Fase 2

## Objetivo

Esta fase cria o catálogo canónico que liga cada plano VIP do servidor aos
produtos reais da Google Play. Ainda não altera o checkout visível no Android;
essa troca acontece na Fase 3, depois de os IDs abaixo estarem configurados.

O Android nunca deve usar `preco`, `price` ou `price_with_ai` para cobrar. Esses
valores continuam a servir o site. No app, preço, moeda e oferta apresentada ao
artista virão sempre de `ProductDetails` da Google Play.

## Modelo adotado

Cada pacote pode ter:

- um produto de subscrição normal, por exemplo `vip_20`;
- um produto de subscrição com IA, por exemplo `vip_20_ai`, apenas se o pacote
  oferecer o add-on;
- um `basePlanId` para cada multiplicador disponível: `1`, `2`, `3`, `4` e
  `12`.

Não se usa um preço fornecido pelo app nem se concatena um ID no cliente. O
servidor devolve o mapeamento exato e, na fase de validação, voltará a procurar
esse mesmo mapeamento antes de conceder qualquer acesso.

## Configuração no painel 1MZ

1. Abrir **Pacotes VIP** e editar um pacote.
2. Na secção **Google Play Billing — Android**, preencher o Product ID normal.
3. Se o pacote oferece IA, preencher também o Product ID com IA.
4. Preencher o Base plan correspondente a cada duração realmente publicada na
   Play Console.
5. Guardar o pacote.

Uma duração incompleta fica deliberadamente indisponível no Android. O sistema
não inventa IDs nem recorre à carteira como fallback.

## Configuração na Play Console

Para cada Product ID configurado no painel:

1. Criar um produto de **Subscrição**.
2. Criar e ativar os base plans que serão vendidos.
3. Definir preço e países diretamente na Play Console.
4. Garantir que o período do base plan corresponde à duração comercial do
   plano. Na validação do servidor, a validade efetiva será derivada do
   `expiryTime` devolvido pela Google, e não de uma data enviada pelo app.
5. Repetir no produto com IA quando aplicável.

## Contrato da API

`GET /1mz/v1/subscription/plans` passa a incluir:

```json
{
  "billing_provider": "google_play",
  "play_account_id": "hash-opaco-de-64-caracteres",
  "plans": [{
    "durations": [{
      "months": 1,
      "google_play": {
        "standard": {
          "product_id": "vip_20",
          "product_type": "subs",
          "base_plan_id": "periodo-1"
        },
        "with_ai": {
          "product_id": "vip_20_ai",
          "product_type": "subs",
          "base_plan_id": "periodo-1-ai"
        }
      }
    }]
  }]
}
```

`play_account_id` é um HMAC estável e não contém telefone, e-mail ou outro dado
pessoal. Será enviado como `obfuscatedAccountId` no Billing Flow e validado no
servidor.

## Critérios de segurança concluídos

- IDs administrativos são normalizados e limitados a letras minúsculas,
  números, ponto, hífen e sublinhado.
- Plano normal e plano com IA não partilham preço implícito.
- Uma configuração incompleta produz `null`, nunca um ID presumido.
- O contrato Android aceita respostas antigas sem falhar, mas não autoriza
  compra sem mapeamento Play.
- A versão Android permanece `1.1.6` (`versionCode 19`).

## Próxima fase

Na Fase 3 o Android consulta `ProductDetails`, mostra o preço oficial, abre o
Google Play Billing e remove do checkout VIP os botões de saldo, PIN,
M-Pesa/E-Mola e depósito. A carteira continua disponível nas áreas permitidas,
como serviços físicos de videoclipe.