REF-501-07: Affiliate Domain Spec

ADR: ADR-501 — Service DeliveryEscopo: Affiliate entity fields, status lifecycle, transitions, Entitlement AFL, hooks Relacionado: REF-901-07 — SolidAffiliate Integration (hooks consumidos, adapter, API endpoints)

1. Purpose

Rastrear Organizations que participam do programa de afiliados. O domínio Affiliate é a representação interna — SolidAffiliate (plugin externo) é a fonte de verdade para dados de afiliados (ADR-103). middag-account persiste apenas o Entitlement AFL e o estado do afiliado.

Dependência: Plugin SolidAffiliate instalado e ativo. Se ausente, domínio Affiliate desabilitado inteiramente (ADR-103).

2. Entity Fields

Campo	Tipo	Descrição
`organization_id`	int (FK)	Organization participante do programa
`solid_affiliate_id`	int (nullable)	ID no SolidAffiliate (preenchido após aprovação)
`referral_code`	string (unique)	Código de indicação único
`status`	enum	`PENDING` \| `ACTIVE` \| `SUSPENDED` \| `TERMINATED`
`commission_rate`	decimal(5,4)	Taxa de comissão (ex: `0.1000` = 10%)
`total_earned`	decimal(10,2)	Total acumulado de comissões
`activated_at`	datetime (nullable)	Data de ativação
`terminated_at`	datetime (nullable)	Data de encerramento definitivo

3. Status Lifecycle

PENDING ──────► ACTIVE ──────► SUSPENDED
   │              │                │
   │              │                │
   │              ▼                ▼
   │          TERMINATED ◄──── TERMINATED
   │              ▲
   │              │
   └──────────────┘ (admin rejeita = TERMINATED direto)

Transitions

De	Para	Gatilho
`PENDING`	`ACTIVE`	Admin aprova
`PENDING`	`TERMINATED`	Admin rejeita
`ACTIVE`	`SUSPENDED`	Admin suspende OU SolidAffiliate webhook
`SUSPENDED`	`ACTIVE`	Admin reativa
`ACTIVE`	`TERMINATED`	Encerramento permanente (admin)
`SUSPENDED`	`TERMINATED`	Encerramento permanente (admin)

TERMINATED é estado final — nenhuma transição permitida a partir dele.

4. Entitlement AFL

Quando Affiliate status = ACTIVE, um Entitlement classe AFL é criado/ativado automaticamente:

Código: AFL-{YYYY}{MM}{SEQ:4d} (ex: AFL-202604-0001)
Vinculado à Organization do afiliado
Status do Entitlement segue status do Affiliate:
- Affiliate ACTIVE → Entitlement ACTIVE
- Affiliate SUSPENDED → Entitlement SUSPENDED
- Affiliate TERMINATED → Entitlement CANCELLED

Detalhes do modelo Entitlement em ADR-202 e REF-202-01.

5. Hooks Disparados

Hook	Quando	Payload
`middag_affiliate_activated`	PENDING → ACTIVE	`$organization_id`, `$affiliate`
`middag_affiliate_suspended`	ACTIVE → SUSPENDED	`$organization_id`, `$reason`
`middag_affiliate_reactivated`	SUSPENDED → ACTIVE	`$organization_id`
`middag_affiliate_terminated`	* → TERMINATED	`$organization_id`, `$reason`

6. Open Questions

Créditos de afiliado têm validade (expiram)? Comissões acumuladas em total_earned — verificar se há prazo de resgate.
Self-registration? Hoje admin aprova manualmente. Avaliar fluxo de auto-registro no portal.

REF-501-07: Affiliate Domain Spec ​

1. Purpose ​

2. Entity Fields ​

3. Status Lifecycle ​

Transitions ​

4. Entitlement AFL ​

5. Hooks Disparados ​

6. Open Questions ​