O estado da assinatura comercial é a autoridade para concessões de direitos, a projeção de acesso é derivada e revogável em superfícies separadas, e cache mais trabalhos em segundo plano devem convergir dentro de uma latência limitada quando o pagamento ou plano mudam e revogam o acesso a recursos.
Status do pacote: Pacote de referência assistido por IA. A validação estática do pacote foi aprovada; cenários de implementação ainda não foram executados e revisão humana do domínio é necessária antes da adoção estável.
Decisão
O livro razão de faturamento/assinatura permanece como a única autoridade para determinar se um locatário ou usuário possui um direito comercial. Os controles de recursos da aplicação leem de uma projeção de acesso derivada de eventos de direitos que carregam source_event_id e idempotency_key, nunca diretamente de webhooks do provedor de pagamento. Concessões podem ser armazenadas em cache até cache_grant_ttl_seconds, mas uma revogação atualiza a verdade da projeção e sua versão de direito em uma única transação. Os controles aceitam uma concessão em cache somente quando sua versão corresponde à versão legível atual; uma verificação de versão indisponível falha fechada.
Escopo
- Eventos de concessão e revogação de direitos, armazenamento da projeção de acesso, verificações de middleware da API, chaves de cache e guardas de capacidade de trabalhos em segundo plano.
- Atualizações de plano, rebaixamentos, expiração de teste, suspensão por estorno e ajustes manuais do operador que afetam o acesso a recursos.
Fora deste bloco
- Captura de pagamento, faturamento e cálculo de impostos.
- Flags de recursos de marketing não relacionados a direitos pagos.
- Entradas detalhadas do diário contábil de assinaturas e regras de reconhecimento de receita.
Contrato
- Todo evento de direito inclui source_event_id, idempotency_key, subject_id e occurred_at conforme entitlement-events.yaml.
- Nenhum controle de recurso lê objetos do provedor de pagamento diretamente; ele lê linhas da projeção indexadas por subject_id e entitlement_code com source_event_id.
- Após a persistência do evento de revogação, a negação da API ocorre dentro de max_projection_lag_seconds sob carga normal.
- A atualização imediata de versão cache_revoke_invalidation atualiza a projeção e a versão atomica na revogação, invalidando concessões em cache mesmo quando cache_ttl_seconds é maior que max_projection_lag_seconds.
- Verificações de negação usam a projeção quando deny_checks_projection_not_cache é true; acertos de cache requerem leitura de versão e correspondência exata de versão. Ausência, desatualização ou indisponibilidade da evidência de versão nega o acesso.
- Eventos duplicados com a mesma idempotency_key e source_event_id não estendem o prazo de validade nem duplicam linhas da projeção.
- Trabalhos em segundo plano rechecagem direitos em tempo de execução quando background_job_recheck é true.
Orientação de implementação
- Implemente atualizações de projeção como consumidores idempotentes do vocabulário entitlement-events.yaml.
- Aumente a versão do direito na mesma transação de cada revogação da projeção e inclua a versão nas chaves de cache.
- Exponha diagnósticos internos mostrando o último source_event_id aplicado por sujeito para suporte sem expor credenciais do livro razão de faturamento para camadas da aplicação.
- Documente quais rotas HTTP, workers e ferramentas administrativas consultam a projeção versus APIs de leitura de faturamento para auditorias de acesso.
Tratamento de falhas e salvaguardas
- Atraso da projeção além do limite falha fechada para verificações de concessão: negar acesso premium em vez de permitir concessões desatualizadas.
- Falha ao ler a versão atual do direito falha fechada; concessões em cache não são tratadas como prova por si só.
- Suspensão por estorno revoga todos os direitos pagos em uma única atualização atômica da projeção por regras de perfil.
- Trabalho em segundo plano verifica direito em pontos de verificação para trabalhos de longa duração.
Verificação e operações
- Testes simulam rebaixamento e medem latência de negação através dos caminhos da API e cache após revogação com cache_grant_ttl_seconds ainda ativo.
- Métricas acompanham atraso da projeção, acertos de cache desatualizados prevenidos, aumentos de versão do cache na revogação e pulos de trabalho devido à revogação.
- Alerta quando SLA de convergência é violado após mudanças no estado da assinatura.
Suposições de adoção
- Nomes e valores numéricos em example.yaml e entitlement-events.yaml são um perfil de adoção, não padrões universais.
- A equipe adotante mapeia SKUs para códigos de direitos e possui a integração da autoridade de faturamento.