Configurando Policies

Esta página explica onde e como configurar policies em cada nível da hierarquia. Algumas telas de configuração já estão implementadas; outras estão planejadas. Cada seção indica o status atual.

Para entender o que cada policy faz, consulte Policies Disponíveis. Para entender como a hierarquia resolve valores, consulte Hierarquia de Policies.

Visão geral: onde as policies ficam

Nível	Local de configuração	Status
Global	WP Admin > MIDDAG Account > Settings > Policies	Implementado
Entitlement Class	Arquivos YAML em docs/commerce/policies/	Implementado
Organização	WP Admin > Organização > Editar > Aba Policies	Planejado
Produto	Bloco policies: no YAML do produto	Implementado
Entitlement Individual	WP Admin > Entitlement > Editar > Aba Policies	Planejado

---

Nível 1: Policies globais

Local: WP Admin > MIDDAG Account > Settings > Policies

As policies globais são a linha de base. Todo campo possui um valor padrão definido no schema da policy, e as configurações globais sobrescrevem esses padrões para toda a instalação.

Fonte de verdade: O arquivo docs/commerce/policies/global.yaml define todos os valores de policy global. Alterações neste arquivo são sincronizadas com o banco de dados do WordPress via composer policies:sync (a ferramenta de sincronização está em desenvolvimento).

O que configurar aqui:

• Comportamento de renovação para todos os entitlements (renovação automática, período de carência, precificação)
• Padrões de recuperação de pagamento (quando suspender, quanto tempo antes do cancelamento)
• Canais e timing de notificações
• Tier de SLA base e metas
• Janela de reembolso e regras de aprovação
• Expiração de créditos e ordem de consumo

Como funciona:

1. Navegue até WP Admin > MIDDAG Account > Settings.
2. Selecione a aba Policies.
3. Cada policy é exibida como uma seção retrátil com todos os seus campos.
4. Edite os valores que deseja alterar.
5. Salve. Todos os entitlements sem uma sobrescrita mais específica usarão esses valores.

Dica: O nível global deve refletir o caso de negócio mais comum. Sobrescreva em níveis inferiores apenas onde necessário.

---

Nível 2: Policies por Entitlement Class

Local: Arquivos YAML em docs/commerce/policies/

As policies de nível de classe definem regras que se aplicam a todos os entitlements de um determinado tipo. O sistema vem com as classes: PLG (Plugin), ENV (Environment), SVC (Service), ORD (Order), AFL (Affiliate) e EDU (Education).

Arquivos:

Arquivo	Aplica-se a
class-plg.yaml	Entitlements de plugin
class-env.yaml	Entitlements de ambiente
class-svc.yaml	Entitlements de serviço
class-ord.yaml	Entitlements baseados em pedido
class-afl.yaml	Entitlements de afiliado
class-edu.yaml	Entitlements de educação

Como funciona:

Os arquivos YAML de classe incluem apenas os campos que diferem dos padrões globais. Qualquer campo não presente no arquivo de classe é herdado do nível global.

Por exemplo, class-plg.yaml sobrescreve a janela de suspensão da recuperação de pagamento para 14 dias, mas não define uma Renewal Policy — portanto, entitlements PLG herdam os padrões globais de renovação.

O que configurar aqui:

• Tier de SLA e horário de suporte por classe (ex.: SVC recebe Priority, PLG recebe Standard)
• Modo de provisionamento (automático para PLG, manual para SVC)
• Disponibilidade de trial (habilitado para ENV, desabilitado para outros)
• Termos de reembolso por classe (generoso para PLG, zero para SVC)
• Cronogramas de cancelamento por classe

Editando policies de classe:

1. Abra o arquivo class-*.yaml apropriado em docs/commerce/policies/.
2. Adicione ou modifique apenas os campos que deseja sobrescrever.
3. Execute o comando de sincronização para aplicar as alterações: composer policies:sync (em desenvolvimento).

Importante: Os arquivos de classe devem incluir _class: PLG (ou o código de classe apropriado) no cabeçalho YAML para válidação.

---

Nível 3: Policies de organização

Status: [Planejado]

Local planejado: WP Admin > Organizations > [Nome da Organização] > Editar > Aba Policies

As policies de nível de organização permitem definir regras específicas por cliente. É aqui que você configura termos negociados para clientes enterprise, regras mais rígidas para clientes com problemas de pagamento ou períodos de crédito estendidos para contas estratégicas.

Como funcionará:

1. Navegue até WP Admin > Organizations.
2. Clique na organização que deseja configurar.
3. Abra a aba Policies.
4. Você verá uma lista de todas as 10 policies, cada uma mostrando o valor efetivo atual (herdado ou sobrescrito).
5. Para sobrescrever um campo, ative o botão de sobrescrita e insira o novo valor.
6. Valores sobrescritos são destacados para diferenciá-los dos valores herdados.
7. Salve. Todos os entitlements desta organização usarão esses valores (a menos que uma sobrescrita de produto ou entitlement seja mais específica).

Objetivos de design para a tela de admin:

• Mostrar o valor efetivo de cada campo (de onde vem na hierarquia).
• Mostrar o valor herdado ao lado de qualquer sobrescrita, para que o admin saiba o que está alterando.
• Fornecer um botão Redefinir por campo para remover a sobrescrita e retornar ao valor herdado.
• Registrar todas as alterações de policy na trilha de auditoria da organização.

O que configurar aqui:

• Expiração de créditos estendida para acordos enterprise
• Períodos de recuperação de pagamento mais longos para clientes com compras internas lentas
• Tier de SLA personalizado para clientes com contrato
• Timing de notificações ajustado

---

Nível 4: Policies de produto

Local: Arquivo YAML do produto, bloco policies:

As policies de nível de produto permitem definir regras para um produto WooCommerce específico. Todos os entitlements criados a partir de compras daquele produto herdam esses valores.

Como funciona:

Cada arquivo YAML de produto no catálogo de comércio pode incluir um bloco policies: que sobrescreve campos específicos. Inclua apenas os campos que deseja sobrescrever.

# Exemplo: YAML do produto para um plano premium de hospedagem
name: "Campus EAD Business"
sku: "ENV-CAMPUS-BIZ"
policies:
  sla:
    sla_level: priority
    uptime_target: "99.95%"
  trial:
    duration_days: 30

Neste exemplo, o produto sobrescreve o nível de SLA para Priority e estende o trial para 30 dias. Todos os outros campos herdam dos níveis de classe (ENV) ou global.

O que configurar aqui:

• Metas de SLA específicas do produto (uptime mais alto para planos premium)
• Durações de trial diferentes por produto
• Cooldowns de mudança de tier para produtos específicos
• Janelas de reembolso personalizadas para produtos específicos

---

Nível 5: Policies de Entitlement Individual

Status: [Planejado]

Local planejado: WP Admin > Entitlements > [Código do Entitlement] > Editar > Aba Policies

Sobrescritas de entitlement individual são para exceções pontuais. Este é o nível mais específico e deve ser usado com moderação.

Como funcionará:

1. Navegue até WP Admin > Entitlements (ou encontre o entitlement pela visualização da organização).
2. Clique no código do entitlement (ex.: SVC-2026050012).
3. Abra a aba Policies.
4. Você verá todos os campos de policy com seus valores efetivos e o nível de onde são herdados.
5. Sobrescreva campos específicos conforme necessário.
6. Salve.

Objetivos de design para a tela de admin:

• Indicação clara do nível de origem de cada valor efetivo (global, classe, organização, produto ou entitlement).
• Entrada na trilha de auditoria para cada sobrescrita, incluindo quem fez a alteração e quando.
• Aviso ao sobrescrever valores que diferem do nível da organização ou do produto, para evitar conflitos acidentais.

O que configurar aqui:

• Exceções contratuais negociadas para um acordo específico
• Acomodações de migração para entitlements importados de sistemas externos
• Extensões ou ajustes pontuais oriundos de escalações de clientes

---

Verificando policies efetivas

Para verificar quais valores de policy estão em vigor para um entitlement específico:

1. Navegue até o entitlement no WP Admin.
2. Abra a aba Policies. (Planejado)
3. Cada campo mostrará:
   • O valor efetivo atualmente em uso.
   • O nível de origem (Global, Classe, Organização, Produto ou Entitlement).
   • Se o valor é herdado ou sobrescrito neste nível.

Esta visualização facilita diagnosticar por que um entitlement está se comportando de determinada forma e onde a policy que o controla está definida.

---

Auditoria de alterações de policies

Todas as alterações de policies são registradas no log de auditoria do sistema:

• Quem fez a alteração (usuário WordPress)
• Quando a alteração foi feita (timestamp)
• O que mudou (nome do campo, valor anterior, novo valor)
• Em qual nível (global, classe, organização, produto ou entitlement)

Esta trilha de auditoria é essencial para conformidade e para depurar comportamentos inesperados.

Próximos passos

• Receitas de Policies — guias práticos de configuração
• Policies Disponíveis — referência de campos para todas as 10 policies
• Hierarquia de Policies — entendendo a resolução de sobrescritas