REF-202-02: Auto-Provisioning

ADR: ADR-202 — Entitlement: Agregador CentralEscopo: Fluxo Order→Entitlement por classe, análise de line items, entidades downstream criadas, hook de provisioning

---

1. Fluxo Geral

Quote aceito pelo cliente
    │
    ▼
Order WooCommerce criada (via woocommerce-quotes ou direta)
    │
    ▼
Pagamento confirmado (webhook Stripe / webhook Banco Inter)
    │
    ▼
Hook: woocommerce_order_status_completed
    │
    ▼
EntitlementProvisioningService.provision($order)
    │
    ├── Para cada line item do order:
    │   ├── Determinar classe via product meta `_middag_entitlement_class`
    │   ├── Verificar se entitlement já existe (idempotência)
    │   ├── Gerar código: {CLASS}-{YEAR}{MONTH}{SEQ:4d}
    │   ├── Criar Entitlement (status: active)
    │   └── Provisionar entidades downstream (ver seção 2)
    │
    └── Hook: middag_entitlement_provisioned($entitlement, $order)

---

2. Provisioning por Classe

PLG (Plugin/Software)

Entitlement PLG criado
    │
    ├── License criada
    │   ├── Chave gerada (ou via WOO_SL adapter se ativo)
    │   ├── max_activations = valor do produto
    │   └── Status: active
    │
    └── Download habilitado (se produto tem arquivo downloadable)

ENV (Environment)

Entitlement ENV criado
    │
    └── Environment criado
        ├── Status: provisioning
        ├── platform: valor do produto (moodle/wordpress/custom)
        ├── url: null (preenchido manualmente ou via webhook)
        └── Hook: middag_environment_provisioning($environment)

SVC (Service)

Entitlement SVC criado
    │
    ├── Service criado
    │   ├── lifecycle: ongoing/project (via product meta)
    │   ├── type: a definir (via product meta, opcional)
    │   └── Status: active
    │
    ├── Contract criado (se lifecycle = ongoing, ou conforme POLICY)
    │   ├── Termos de SLA vinculados
    │   ├── start_date: data do pagamento
    │   └── end_date: start_date + duração do produto
    │
    └── CreditBalance criado
        ├── Saldo inicial: conforme plano do produto
        ├── Expiração: conforme CreditPolicy
        └── Status: active

ORD (Order-based)

Entitlement ORD criado
    │
    ├── Vinculado ao Order de origem
    ├── Invoice referenciada
    └── Download habilitado (se produto tem arquivo downloadable)

AFL (Affiliate)

Entitlement AFL criado
    │
    └── Vinculado ao Affiliate (SolidAffiliate)
        └── Tier e comissão conforme regras do SolidAffiliate

EDU (Education)

Entitlement EDU criado
    │
    ├── Vinculado ao Order de origem
    ├── Download habilitado (se material educacional disponível)
    └── Notificações: send_welcome_email + send_onboarding_email

---

3. Análise de Line Items

O EntitlementProvisioningService determina a classe a partir de product meta:

Product Meta	Valor	Classe	Notas
_middag_entitlement_class	PLG	PLG	Obrigatório para auto-provisioning
_middag_entitlement_class	ENV	ENV
_middag_entitlement_class	SVC	SVC
_middag_entitlement_class	ORD	ORD	Default se nenhuma classe definida
_middag_entitlement_class	AFL	AFL
_middag_entitlement_class	EDU	EDU
_middag_svc_lifecycle	ongoing	—	Usado com SVC para determinar tipo
_middag_svc_lifecycle	project	—
_middag_parent_entitlement	código	—	Auto-vincula como filho se definido

---

4. Idempotência

• Webhook duplicado NÃO cria entitlement duplicado
• Verificação: order_id + line_item_id + entitlement_class já existe?
• Se existe → skip (log informativo)
• Se não existe → criar

---

5. Hooks

Hook	Parâmetros	Quando
middag_entitlement_provisioned	$entitlement, $order	Após auto-criação de entitlement
middag_entitlement_created	$entitlement, $source	Qualquer criação (auto ou manual)
middag_environment_provisioning	$environment	ENV criado, aguardando setup

---

6. Parent-Child Auto-Vinculação

Quando um order contém múltiplos line items com um SVC + outros itens:

1. SVC é criado primeiro (é o "pai")
2. Demais entitlements do mesmo order são auto-vinculados como filhos
3. Flag use_parent_credits = true por default nos filhos
4. Product meta _middag_parent_entitlement pode override manual