REF-202-04: Policy Engine

ADR: ADR-202 — Entitlement: Agregador CentralEscopo: 10 policies, hierarquia de override com 5 níveis, campos e defaults de cada policy, exemplos de override

---

1. Hierarquia de Override

global → entitlement class → organization → product → entitlement individual

O nível mais específico com valor definido prevalece. Níveis sem valor definido herdam do nível superior.

Nível	Onde configurado	Exemplo
Global	Settings do plugin (wp-admin)	"Créditos expiram em 12 meses"
Entitlement class	Settings por classe (PLG, ENV, SVC, etc.)	"PLG: sem suspensão antecipada"
Organization	Meta da organization	"Org X: créditos expiram em 24 meses"
Product	YAML do produto (policies block)	"SVC-HOST: cooldown de 30 dias"
Entitlement individual	Meta do entitlement	"SVC-001: cooldown de 90 dias"

---

2. CreditPolicy

Governa: expiração de créditos, carência, limites, consumo, regras para avulsos.

Campo	Tipo	Default	Descrição
expiration_months	int	12	Meses até expiração de créditos incluídos no plano
grace_before_days	int	0	Dias de carência antes da expiração
grace_after_days	int	30	Dias de carência após expiração
block_on_limit_exceeded	bool	false	Bloquear SRs quando saldo excede limite
limit_threshold	int	0	Créditos negativos permitidos antes de bloqueio
avulso_expiration_months	int	6	Expiração de créditos comprados avulso
consumption_order	enum	fifo	Ordem de consumo: fifo (mais antigos primeiro) ou lifo

---

3. PaymentRecoveryPolicy

Governa: suspensão por falha de pagamento, período suspended→cancelled.

Campo	Tipo	Default	Descrição
trigger	enum	retry_exhausted	Quando suspender: first_failure ou retry_exhausted
anticipate_suspension	bool	false	Suspender antecipadamente para clientes com histórico irregular
suspended_to_cancelled_days	int	30	Dias em suspended antes de cancelamento automático
auto_reactivate_on_payment	bool	true	Reativar automaticamente quando pagamento regularizado

---

4. TierChangePolicy

Governa: upgrade/downgrade — efeito, cooldown, aprovação.

Campo	Tipo	Default	Descrição
effect	enum	immediate	immediate ou next_cycle
downgrade_requires_approval	enum	none	none, admin, client, both
cooldown_days	int	0	Dias mínimos entre mudanças de tier
credit_behavior	enum	next_cycle	immediate, next_cycle, ou forfeit

---

5. CancellationPolicy

Governa: visibilidade pós-expiração, tempo expired→cancelled, retenção de dados.

Campo	Tipo	Default	Descrição
portal_visibility_days	int	90	Dias que entitlement expirado permanece visível no portal
expired_to_cancelled_days	int	30	Dias em expired antes de cancelamento automático
data_retention_days	int	365	Dias de retenção de dados operacionais pós-cancelamento
data_action	enum	export_and_delete	export_and_delete, archive, ou retain
offer_data_export	bool	true	Oferecer exportação de dados no processo de cancelamento

Nota: Dados fiscais seguem prazo legal (LGPD/fiscal) e NÃO são configuráveis via policy.

---

6. NotificationPolicy

Governa: canais de notificação, eventos, frequência, opt-out.

Campo	Tipo	Default	Descrição
channels	list	[email]	Canais ativos: email, sms, whatsapp, portal
events	list	(ver policy schema)	Eventos que disparam notificações
expiry_warning_days	list	[30, 7, 1]	Dias antes da expiração para enviar aviso
credit_low_threshold_pct	int	20	Percentual do saldo para alerta de créditos
allow_opt_out	bool	true	Permitir opt-out de notificações não-críticas

---

7. ProvisioningPolicy

Governa: auto vs manual provisioning, aprovação, webhook, deprovisionamento.

Campo	Tipo	Default	Descrição
auto	bool	true	true = self-serve (auto-provision). false = requer aprovação
require_approval	enum	none	none, admin, both — quem aprova provisioning manual
webhook_enabled	bool	false	Notificar sistema externo após provisioning
retry_on_failure	bool	true	Tentar novamente em caso de falha
max_retries	int	3	Tentativas máximas antes de falha definitiva
timeout_minutes	int	30	Timeout para provisioning antes de marcar como falha
notify_admin_on_manual	bool	true	Notificar admin quando provisioning manual necessário
deprovision_on_cancel	bool	false	Desprovisionamento automático quando entitlement cancelado

---

8. RenewalPolicy

Governa: renovação automática, grace period, preço de renovação, notificações.

Campo	Tipo	Default	Descrição
auto_renew	bool	true	Renovar automaticamente antes da expiração
grace_days_pre_expiry	int	7	Dias antes da expiração para tentar renovação
renewal_pricing	enum	same	same (mesmo preço), current (preço atual do catálogo)
early_renewal_days	int	30	Janela para renovação antecipada (dias antes da expiração)
renewal_reminder_days	list	[30, 7, 1]	Dias antes da expiração para enviar lembrete de renovação
failed_renewal_retries	int	3	Tentativas de renovação antes de desistir
block_downgrade_at_renewal	bool	false	Impedir downgrade durante o período de renovação

---

9. TrialPolicy

Governa: trial gratuito — duração, limites, conversão, abuso.

Campo	Tipo	Default	Descrição
enabled	bool	false	Trial disponível para este nível
duration_days	int	14	Duração do trial em dias
auto_convert	bool	true	Converter automaticamente em assinatura paga ao fim do trial
require_payment_method	bool	false	Exigir método de pagamento para iniciar trial
max_trials_per_org	int	1	Máximo de trials por organização (previne abuso)
extend_allowed	bool	false	Permitir extensão do trial por admin
notification_days_before_end	list	[3, 1]	Dias antes do fim do trial para notificar

---

10. RefundPolicy

Governa: reembolso — prazo, percentual, condições, impacto no entitlement.

Campo	Tipo	Default	Descrição
refund_window_days	int	30	Dias após compra para solicitar reembolso
auto_refund	bool	false	Reembolso automático dentro da janela (até auto_refund_max)
auto_refund_max	decimal	100.00	Valor máximo para reembolso automático (acima = manual)
partial_allowed	bool	true	Permitir reembolso parcial (proporcional ao uso)
approval_required	enum	admin	none, admin — quem aprova reembolso
cancel_entitlement	bool	true	Cancelar entitlement automaticamente após reembolso total
credits_on_refund	enum	forfeit	forfeit (perder), retain (manter), proportional (ajustar)

---

11. SLAPolicy

Governa: níveis de serviço — tempos de resposta/resolução, disponibilidade, escalação.

Campo	Tipo	Default	Descrição
response_time	string	24h	Tempo máximo para primeira resposta
resolution_time	string	72h	Tempo máximo para resolução
uptime_target	string	99.5%	Meta de disponibilidade (ENVs gerenciados)
support_hours	enum	business_hours	business_hours, extended, 24x7
escalation_enabled	bool	true	Habilitar escalação automática por SLA breach
escalation_after_pct	int	80	Percentual do tempo SLA para escalar (80% = 80% do prazo)
priority_levels	list	[low, normal, high, urgent]	Prioridades disponíveis para SRs deste nível

---

12. Resolução de Conflitos

1. Buscar valor no nível mais específico (entitlement individual)
2. Se não definido → subir para product
3. Se não definido → subir para organization
4. Se não definido → subir para entitlement class
5. Se não definido → usar global
6. Se global não definido → usar default hardcoded (tabelas acima)

Nunca mesclar valores de níveis diferentes para o mesmo campo. O nível mais específico com valor definido é o valor final.

---

13. Exemplos de Override

Exemplo 1: CreditPolicy

Global:              expiration_months = 12
Classe SVC:          (não definido — herda global = 12)
Organization X:      expiration_months = 24
Produto SVC-HOST:    (não definido — herda org = 24)
Entitlement SVC-001: (não definido — herda org = 24)

Resultado para SVC-001: créditos expiram em 24 meses.

Exemplo 2: PaymentRecoveryPolicy

Global:              trigger = retry_exhausted
Classe PLG:          trigger = retry_exhausted (explícito, mesmo valor)
Organization Y:      trigger = first_failure (cliente com histórico ruim)
Produto PLG-MOODLE:  (não definido — herda org = first_failure)
Entitlement PLG-042: (não definido — herda org = first_failure)

Resultado para PLG-042: suspensão imediata na primeira falha.

Exemplo 3: TierChangePolicy

Global:              cooldown_days = 0
Classe SVC:          cooldown_days = 30
Organization Z:      (não definido — herda classe = 30)
Produto SVC-HOST:    cooldown_days = 60 (produto com commitment)
Entitlement SVC-005: cooldown_days = 90 (contrato enterprise)

Resultado para SVC-005: mínimo 90 dias entre mudanças de tier.