ADR-103: Plugin Ecosystem
Status: Accepted
Contexto
middag-account opera dentro de um ecossistema de plugins: 2 satélites da MIDDAG (woocommerce-quotes, woocommerce-banco-inter), 1 dependência obrigatória (WooCommerce) e 3 dependências opcionais (WC Subscriptions, WC Software License, SolidAffiliate). Precisa-se de regras claras sobre: o que vive dentro do core vs fora, como plugins se comunicam, como domínios são ativados/desativados, e que contratos de estabilidade são garantidos.
Decisão
Core Plugin vs Satélites
Tudo que define gestão de ciclo de vida B2B vive dentro do middag-account:
- 16 domínios (Organization, Collaborator, Entitlement, License, Order, Invoice, TaxInvoice, Quote, Contract, Document, Environment, Service, ServiceRequest, CreditBalance, Download, Affiliate)
- REST API v1 completa
- Admin UI (Inertia.js + React)
- Todas as integrações (HubSpot, Stripe, ISSNet (NFSe Brasília/DF), Banco Inter, Cloudflare, SolidAffiliate, Jira, Chatwoot)
- WordPress Abstraction Layer + DI Container
Justificativa: Integrações vivem DENTRO do core porque: (1) reagem a eventos de domínio, (2) compartilham o DI container, (3) estão travadas na mesma versão do modelo de domínio, (4) plugins separados criariam dependências circulares.
Satélites são plugins independentes que middag-account aprimora mas não requer:
| Satélite | Funciona sozinho? | Se ausente |
|---|---|---|
| woocommerce-quotes | Sim | Quote limitado à criação manual, sem templates PDF |
| woocommerce-banco-inter | Sim | Pix/Boleto indisponíveis, Stripe cobre cartão/ACH |
Comunicação por Hooks Only
middag-account NUNCA chama código de satélite diretamente.
Satélites NUNCA chamam código do middag-account diretamente.
Comunicação é via hooks WordPress e REST API apenas.middag-account dispara hooks como middag_entitlement_created, middag_quote_paid, middag_domain_enabled — satélites e extensões escutam. middag-account escuta hooks como woocommerce_order_status_completed, woocommerce_quotes_quote_accepted, solid_affiliate_referral_created.
Interfaces PHP (EntitlementProviderInterface, QuoteHandlerInterface, SettingsSectionInterface) são fornecidas por conveniência — nunca obrigatórias. Hooks são sempre o contrato primário.
Domain Activation/Deactivation
Domínios divididos em CORE (sempre ativo) e OPTIONAL (togglável via Settings):
| Tipo | Domínios |
|---|---|
| CORE | Organization, Collaborator, Entitlement, License, Order, Invoice, Quote |
| OPTIONAL | TaxInvoice, Contract, Document, Environment, Service, ServiceRequest, CreditBalance, Download, Affiliate |
Ativação registra: CPT, item de menu, endpoints de API, hooks, serviços DI. Desativação oculta tudo mas NUNCA apaga dados — reativação restaura acesso completo.
Dependências entre domínios são enforçadas:
- ServiceRequest requer Service OU Environment
- TaxInvoice requer Invoice + config ISSNet
- Affiliate requer plugin SolidAffiliate
- CreditBalance auto-ativa com Service
- Download requer License (sempre ativo, sem restrição efetiva)
Dependências de Terceiros
| Plugin | Obrigatório? | Comportamento se ausente |
|---|---|---|
| WooCommerce | Obrigatório | Admin notice + degradação graciosa |
| WC Subscriptions | Opcional | Funcionalidades de assinatura desabilitadas |
| WC Software License | Opcional | Domínio License usa gestão built-in (mais simples) |
| SolidAffiliate | Opcional | Domínio Affiliate desabilitado inteiramente |
Versionamento SemVer
MAJOR.MINOR.PATCH
5.0.0 — Release inicial (migração do tema)
5.0.1 — Patch: bug fix, sem mudanças na API
5.1.0 — Minor: novas features, retrocompatível
6.0.0 — Major: breaking changes (improvável a curto prazo)Contrato de Estabilidade
| Camada | Garantia |
|---|---|
| REST API v1 | Estável. Novos endpoints aditivos. Campos existentes nunca removidos. Depreciação com 6 meses de aviso. |
| WordPress Hooks | Estável. Hooks existentes nunca removidos. Novos parâmetros adicionados ao final, nunca reordenados. |
| Interfaces PHP | Estável dentro da MAJOR. Métodos nunca removidos na v5. Novos métodos requerem bump MAJOR. |
| Admin UI | Fluida. UI não é contrato — adotantes não devem depender de classes CSS ou estrutura DOM. |
| Schema do banco | Estável. Migrações apenas aditivas. Colunas nunca renomeadas/removidas dentro da v5. |
Futuro: Extração middag-core
Após v5 estabilizar (mínimo 3 meses em produção), avaliar extração de infraestrutura compartilhada (DI Container, WP Abstraction Layer, classes base de entity/repository/service, adapter Inertia.js) em pacote middag-core. Critérios: pelo menos 2 plugins compartilham código, padrões comprovados em produção, extração retrocompatível. Até lá, middag-account é autocontido.
Consequências
Positivas:
- Comunicação por hooks garante que satélites e core evoluem independentemente
- Domain activation permite que adotantes configurem o plugin para seu negócio sem código
- Contrato de estabilidade dá confiança para desenvolvedores construírem sobre a API
- SemVer + política de depreciação previnem breaking changes silenciosos
Negativas:
- Core plugin grande (16 domínios + integrações) — tamanho do ZIP e consumo de memória
- Hooks como contrato primário são menos tipados que chamadas diretas — erros descobertos em runtime
- Satélites com release independente requerem teste de compatibilidade em cada versão
- Extração futura do middag-core introduzirá migração para plugins existentes