<?php
/**
 * TMDO_Module_Rules — Declarative trigger conditions per module (v2.5.0 M16).
 *
 * Separates "what makes this module worth enabling" from the detection
 * machinery (Module_Detector consumes these rules). Each rule declares：
 *   - compat_required：list of plugins that must be active (any of)
 *   - post_type_required：post_type must exist + have rows
 *   - min_post_count：threshold for post_type row count
 *   - min_trash_count：(archive only) trashed post count threshold
 *   - consult_classifier + min_classifier_confidence：(zone modules only)
 *   - description：human reason shown in UI
 *
 * Extensible via filter `wpdo/module_rules` — third-party plugins can register
 * their own modules and rules without forking this file.
 *
 * @package WP_Data_Optimizer
 */

declare(strict_types=1);

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Static rules registry.
 */
class TMDO_Module_Rules {

	/**
	 * Default rules for the 15 known modules. Use `get()` to apply filter.
	 */
	private const DEFAULT_RULES = array(
		// ─── HPCT modules（HivePress + HPCT）────────────────────────────
		'reviews'         => array(
			'compat_required'    => array( 'hivepress' ),
			'post_type_required' => 'hp_review',
			'min_post_count'     => 100,
			'description'        => '若使用 HivePress reviews 且累積評論 ≥ 100 條，啟用後可顯著降低 listing 查詢的 JOIN 成本。',
		),
		'messages'        => array(
			'compat_required'    => array( 'hivepress' ),
			'post_type_required' => 'hp_message_thread',
			'min_post_count'     => 50,
			'description'        => 'HivePress messages 累積對話數 ≥ 50 時，啟用 module 可加速 inbox / unread count 查詢。',
		),
		'favorites'       => array(
			'compat_required'    => array( 'hivepress' ),
			'post_type_required' => 'hp_favorite',
			'min_post_count'     => 200,
			'description'        => '使用者 favorite 累積 ≥ 200 條時，啟用 module 把 favorite meta 從 wp_postmeta 搬出。',
		),
		'memberships'     => array(
			'compat_required'    => array( 'hivepress' ),
			'post_type_required' => 'hp_membership',
			'min_post_count'     => 50,
			'description'        => 'HivePress memberships 啟用且 ≥ 50 條訂閱時，membership 過期檢查會更快。',
		),
		'statistics'      => array(
			'compat_required'    => array( 'hivepress' ),
			'post_type_required' => 'hp_listing',
			'min_post_count'     => 500,
			'description'        => 'Listing ≥ 500 條時，view_count / favorite_count 等高頻統計搬到 stats module 可大幅減少 wp_postmeta 寫入。',
		),
		'requests'        => array(
			'compat_required'    => array( 'hivepress' ),
			'post_type_required' => 'hp_request',
			'min_post_count'     => 50,
			'description'        => 'HivePress requests / quotes 累積 ≥ 50 條時建議啟用。',
		),
		'listing_meta'    => array(
			'compat_required'    => array( 'hivepress' ),
			'post_type_required' => 'hp_listing',
			'min_post_count'     => 100,
			'description'        => '所有 listing meta 集中管理；listing ≥ 100 時可省下大量 postmeta JOIN。',
		),
		'wc_orders'       => array(
			'compat_required'    => array( 'woocommerce' ),
			'post_type_required' => 'shop_order',
			'min_post_count'     => 100,
			'description'        => 'WooCommerce 訂單 ≥ 100 筆且未啟用 HPOS 時，建議啟用 module 把 vendor commission 搬到 wp_wpdo_wc_commissions。',
		),
		'latepoint'       => array(
			'compat_required'    => array( 'latepoint' ),
			'post_type_required' => null,
			'description'        => 'LatePoint 預約系統啟用時建議開啟，把 booking meta 從 wp_postmeta 搬出。',
		),

		// ─── Zone modules（任何站皆可，但仍依環境推薦）────────────────────
		'warm'            => array(
			'compat_required'    => array(),
			'post_type_required' => null,
			'min_post_count'     => 0,
			'priority'           => 'recommended_first',
			'description'        => 'Warm zone 處理 view counts / TTL 暫存；任何站都可啟用，幾乎零風險。',
		),
		'archive'         => array(
			'compat_required'    => array(),
			'post_type_required' => null,
			'min_trash_count'    => 50,
			'description'        => '已 trashed posts ≥ 50 個時，啟用 archive module 可釋放 wp_postmeta 空間（自動 gzip 壓縮）。',
		),
		'hot_hp_listing'  => array(
			'compat_required'           => array( 'hivepress' ),
			'post_type_required'        => 'hp_listing',
			'min_post_count'            => 100,
			'consult_classifier'        => true,
			'min_classifier_confidence' => 0.6,
			'description'               => '使用 HivePress + listing ≥ 100 條 + Classifier confidence ≥ 0.6 時，把高頻欄位搬到 wp_wpdo_hot_hp_listing 可大幅加速 WP_Query。',
		),
		'cold_hp_listing' => array(
			'compat_required'           => array( 'hivepress' ),
			'post_type_required'        => 'hp_listing',
			'min_post_count'            => 100,
			'consult_classifier'        => true,
			'min_classifier_confidence' => 0.5,
			'description'               => '低頻 listing meta（如 settings / preferences）搬到 cold zone，減少 hot path 的 postmeta JOIN。',
		),
		'hot_hp_vendor'   => array(
			'compat_required'           => array( 'hivepress' ),
			'post_type_required'        => 'hp_vendor',
			'min_post_count'            => 50,
			'consult_classifier'        => true,
			'min_classifier_confidence' => 0.6,
			'description'               => 'HivePress 商家 ≥ 50 個時，把高頻 vendor meta 搬到 hot zone 可加速 vendor 列表頁。',
		),
		'cold_hp_vendor'  => array(
			'compat_required'           => array( 'hivepress' ),
			'post_type_required'        => 'hp_vendor',
			'min_post_count'            => 50,
			'consult_classifier'        => true,
			'min_classifier_confidence' => 0.5,
			'description'               => '低頻 vendor meta 搬到 cold zone。',
		),
	);

	/**
	 * Return all rules with filter applied.
	 *
	 * @return array<string,array>
	 */
	public static function all(): array {
		$rules = self::DEFAULT_RULES;
		if ( function_exists( 'apply_filters' ) ) {
			$filtered = apply_filters( 'wpdo/module_rules', $rules );
			if ( is_array( $filtered ) ) {
				return $filtered;
			}
		}
		return $rules;
	}

	/**
	 * Return rule for one module.
	 *
	 * @param string $module Module slug.
	 * @return array|null Rule or null when no rule registered.
	 */
	public static function for_module( string $module ): ?array {
		$rules = self::all();
		return $rules[ $module ] ?? null;
	}

	/**
	 * List all module slugs that have rules registered.
	 *
	 * @return array<int,string>
	 */
	public static function known_modules(): array {
		return array_keys( self::all() );
	}
}