Define uma integração de assinatura que separa objetos do provedor, períodos internos de serviço, movimentações financeiras e estado de direito para que tentativas, prorratações, cancelamentos e reconciliações permaneçam auditáveis.
Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não se afirma que uma implementação adotante os tenha aprovado.
Decisão
Manter uma projeção interna de assinatura a partir de eventos verificados do provedor, mas registrar movimentações financeiras e direito ao serviço como fatos imutáveis separados. O status do provedor é evidência de entrada, não o único livro contábil do negócio.
Escopo
- Mapeamento de cliente, versões de plano/preço, ciclo de vida da assinatura, faturas, pagamentos, créditos/reembolsos, períodos de serviço, direitos, cancelamentos, ordenação de eventos e reconciliação.
- Assinaturas recorrentes faturadas pelo provedor.
- Identidades orientadas à contabilidade e integração do ciclo de vida, não demonstrações financeiras formais.
Fora deste bloco
- Consultoria fiscal/contábil ou implementação de razão contábil geral.
- Assumir que o status da assinatura do provedor sozinho determina o acesso ao produto.
Contrato
- IDs de conta do provedor, cliente, assinatura, fatura, pagamento, reembolso e evento mapeiam para entidades internas distintas.
- Versões de plano e preço são imutáveis para períodos históricos; mudanças criam novas referências.
- Um período de serviço tem início/fim explícitos e resultado de direito independente do status atual mutável do objeto do provedor.
- Cancelamento distingue parada de renovação, fim de período e término imediato; datas visíveis ao usuário vêm do estado interno confirmado.
- Eventos são desduplicados e aplicados com regras de versão/tempo do objeto do provedor; eventos obsoletos não podem reverter uma transição aceita mais recente.
- Reconciliação compara faturas, valores capturados/reembolsados, períodos de assinatura e direitos, evidenciando em vez de apagar automaticamente diferenças.
Orientação de implementação
- Use uma caixa de entrada de eventos indexada por conta do provedor mais ID do evento e uma tabela de transição com estado/versão do objeto aceito.
- Grave valores monetários em unidades menores inteiras com moeda e tipo explícitos.
- Crie comandos de direito a partir de fatos aceitos do período de serviço por meio de uma caixa de saída.
- Mantenha ajustes manuais como novas entradas fundamentadas com ator e evidência, não edições do histórico do provedor.
Tratamento de falhas e salvaguardas
- Se eventos chegarem fora de ordem, retenha-os e aplique apenas transições válidas após o estado atual.
- Se o pagamento for bem-sucedido mas a projeção de direito falhar, reproduza a caixa de saída sem alterar registros financeiros.
- Se valores do provedor e internos divergirem, abra um caso de reconciliação; não sobrescreva silenciosamente nenhum dos lados.
Verificação e operações
- Meça atraso/duplicatas/ordem obsoleta de eventos, incompatibilidade fatura-pagamento, pagamento sem direito, direito sem período suportado, tempo de cancelamento, reembolsos e idade da reconciliação.
- Execute reconciliação diária de dinheiro e período de serviço mais sondagens direcionadas após mudanças de preço.
- Restrinja e audite a capacidade de ajuste manual.
Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Execute
python tools/validate.py a partir da raiz da coleção para verificar estrutura e metadados do pacote; então
implemente e execute os cenários no repositório alvo.
Suposições de adoção
- Nomes e valores numéricos em
example.yamlsão um perfil de adoção, não padrões universais. - A equipe adotante deve mapear atores, classes de dados, vocabulário de erros e propriedade para seu sistema.