REF-102-02: Plugin Entry Point Spec

ADR: ADR-102 — Architecture FoundationEscopo: middag-account.php (main plugin file), header, constantes, boot sequence, activation/deactivation/uninstall triad

---

1. Arquivo Principal: middag-account.php

Localizado na raiz do plugin. É o único arquivo carregado diretamente pelo WordPress.

Header WordPress (obrigatório — todos os campos)

Plugin Name: MIDDAG Account
Plugin URI: https://account.middag.com.br
Description: B2B client lifecycle management for WordPress — organizations, entitlements, billing, contracts and service delivery.
Version: 5.0.0
Requires at least: 6.5
Requires PHP: 8.4
Author: MIDDAG
Author URI: https://middag.com.br
Text Domain: middag-account
Domain Path: /languages
WC requires at least: 9.0
WC tested up to: 9.x

Nota: WC requires at least e WC tested up to são metadata do WooCommerce — necessários para compatibilidade na página de plugins.

---

2. Constantes

Definidas no início do arquivo principal, antes de qualquer lógica:

Constante	Valor	Uso
MIDDAG_ACCOUNT_VERSION	'5.0.0'	Comparação de versão, cache busting
MIDDAG_ACCOUNT_FILE	__FILE__	Referência ao arquivo principal
MIDDAG_ACCOUNT_PATH	plugin_dir_path(__FILE__)	Caminho absoluto do plugin (fs)
MIDDAG_ACCOUNT_URL	plugin_dir_url(__FILE__)	URL pública do plugin (http)

---

3. Boot Sequence

register_activation_hook(__FILE__, [Activator::class, 'activate']);
register_deactivation_hook(__FILE__, [Deactivator::class, 'deactivate']);
add_action('plugins_loaded', fn() => (new Kernel(__FILE__))->boot(), 10);

Regra: Boot SEMPRE no hook plugins_loaded — nunca imediatamente. Prioridade 10 (default) garante que WooCommerce e outros plugins já foram carregados.

Kernel::boot()

1. Carrega Composer autoloader (vendor/autoload.php)
2. Compila Symfony DI Container (ou carrega cache compilado)
3. Registra hooks via auto-discovery de classes HookInterface
4. Registra CPTs, REST routes, cron jobs
5. Inicializa InertiaAdapter (shared props) se is_admin()

---

4. Activator::activate()

Chamado UMA vez quando o plugin é ativado (via register_activation_hook).

Passo	Ação
1	Verificar PHP >= 8.4 — se não, wp_die() com mensagem
2	Verificar WooCommerce >= 9.0 instalado e ativo — se não, admin notice
3	Registrar CPTs (middag_{domain}) para que rewrite rules existam
4	flush_rewrite_rules() — registrar URLs dos CPTs
5	Criar wp_options defaults (prefixo middag_) se não existirem
6	Criar tabelas customizadas se houver (CCT migration)
7	Disparar hook middag_activated

Nota: Activator NÃO deve executar lógica pesada. Se houver migração de dados, agendar via WP-Cron para execução assíncrona.

---

5. Deactivator::deactivate()

Chamado quando o plugin é desativado (via register_deactivation_hook).

Passo	Ação
1	flush_rewrite_rules() — limpar URLs dos CPTs
2	Limpar todos os WP-Cron jobs agendados (prefixo middag_)
3	Disparar hook middag_deactivated

NUNCA apagar dados na desativação. Reativação deve restaurar acesso completo a todos os registros.

---

6. uninstall.php

Arquivo separado na raiz do plugin. Executado APENAS quando o plugin é deletado pelo admin via painel WordPress.

Passo	Ação
1	Verificar defined('WP_UNINSTALL_PLUGIN') — segurança
2	Deletar wp_options com prefixo middag_
3	Deletar wp_usermeta com prefixo middag_
4	Disparar hook middag_uninstall (para plugins satélites)
5	Limpar transients com prefixo middag_

NÃO apagar CPTs nem posts — dados preservados por padrão. Se o operador quiser limpeza total, hook middag_uninstall permite que código externo execute a remoção.

Justificativa: Dados de organizações, entitlements e faturas são ativos de negócio. Deleção acidental é irreversível. Preservar por padrão é a escolha segura.

---

7. Dependency Check Pattern

plugins_loaded
    │
    ├── WooCommerce ativo?
    │   ├── SIM → boot normal (Kernel::boot())
    │   └── NÃO → registrar admin notice + retornar
    │           (plugin carregado mas funcionalidade desabilitada)
    │
    ├── PHP >= 8.4?
    │   └── NÃO → wp_die() na ativação (nunca chega aqui em boot)
    │
    └── Optional deps (WC Subscriptions, SolidAffiliate, etc.)
        └── Detectados via `class_exists()` — funcionalidades toggladas