refactor(zones): 回填 Zone_Router + Routing_Predicate（PR-C）

A v3.0.1/v3.4.0 的架構深化，B 完全缺席：新增 - includes/zones/class-tmdo-zone-router.php：module_name / read / write / delete_field / delete_post 五個 static 分派點 - includes/class-tmdo-routing-predicate.php：entity_bridge_owns（含 request-level cache，B 原本沒有）+ should_{write,read,query}_from_zone + flush_cache 改寫 - Sync_Bridge 改用兩者，移除 5 個 private wrapper（get_zone_module / read_from_zone / write_to_zone / delete_from_zone / is_owned_by_entity_bridge）與 44 行 inline cleanup_post → Zone_Router::delete_post 一行（400→269 行） - Query_Router 抽出 extract_hot_clauses() public static，pre_get_posts 變薄殼 - 收斂 5 處重複的 'hot_'/'cold_' . sanitize_key()（rest-api ×3、 hot/cold-migration ×2） - back-compat 補 WPDO_Zone_Router / WPDO_Routing_Predicate alias 測試 - 移植 ZoneRouterTest（250 行）+ RoutingPredicateTest（85 行） - SyncBridgeEntityGuardTest 的 setUp/tearDownAfterClass 補 flush_cache()，否則 entity_bridge_cache 會跨測試污染（A v3.4.6 踩過同一個坑） unit 409 / integration 398 GREEN Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TbG1keQQ7XBa7qMQY16KCY
2026-07-31 05:47:08 +08:00
parent 98774c5035
commit f187ac5401
14 changed files with 685 additions and 211 deletions
@@ -0,0 +1,110 @@
+<?php
+/**
+ * Routing predicate — centralises Zone ownership and activation checks.
+ *
+ * Two recurring predicates previously scattered across callers:
+ *
+ * 1. entity_bridge_owns(): was TMDO_Sync_Bridge::is_owned_by_entity_bridge() —
+ *    answers "does the Hook Bus own this meta_key (Zone Bridge must skip it)?".
+ *
+ * 2. should_write_to_zone() / should_read_from_zone() / should_query_from_zone():
+ *    were inline TMDO_Zone_Router::module_name() + TMDO_Feature_Flags::is_*()
+ *    pairs repeated in Sync_Bridge, Query_Router, and REST API.
+ *
+ * @package TMDO
+ * @since 0.2.0
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Centralised routing predicate for Zone write/read/query activation checks.
+ */
+class TMDO_Routing_Predicate {
+
+	/**
+	 * Request-level cache for entity_bridge_owns().
+	 *
+	 * @var array<string, bool>
+	 */
+	private static array $entity_bridge_cache = array();
+
+	/**
+	 * Returns true when the Entity Bridge (Hook Bus) owns writes for $meta_key on
+	 * the 'post' entity type — Zone Sync_Bridge must not also write to a Zone table.
+	 *
+	 * Replaces the former TMDO_Sync_Bridge::is_owned_by_entity_bridge().
+	 *
+	 * @param string $meta_key Meta key being written.
+	 * @return bool
+	 */
+	public static function entity_bridge_owns( string $meta_key ): bool {
+		if ( isset( self::$entity_bridge_cache[ $meta_key ] ) ) {
+			return self::$entity_bridge_cache[ $meta_key ];
+		}
+
+		$result = false;
+		if ( class_exists( 'TMDO_Mode_Manager' )
+			&& class_exists( 'TMDO_Entity_Registry' )
+			&& TMDO_Mode_Manager::writes_to_flat( 'post' )
+			&& null !== TMDO_Entity_Registry::get_field( 'post', $meta_key ) ) {
+			$result = true;
+		}
+
+		self::$entity_bridge_cache[ $meta_key ] = $result;
+		return $result;
+	}
+
+	/**
+	 * Returns true when Zone dual-write is active for the given post_type + zone.
+	 *
+	 * Replaces the repeated inline pattern:
+	 *   $module = TMDO_Zone_Router::module_name( $zone, $post_type );
+	 *   TMDO_Feature_Flags::is_write_active( $module );
+	 *
+	 * @param string $post_type Post type slug.
+	 * @param string $zone      Zone identifier: 'hot', 'cold', 'warm', 'archive'.
+	 * @return bool
+	 */
+	public static function should_write_to_zone( string $post_type, string $zone ): bool {
+		return TMDO_Feature_Flags::is_write_active(
+			TMDO_Zone_Router::module_name( $zone, $post_type )
+		);
+	}
+
+	/**
+	 * Returns true when Zone read-from-custom is active for the given post_type + zone.
+	 *
+	 * @param string $post_type Post type slug.
+	 * @param string $zone      Zone identifier.
+	 * @return bool
+	 */
+	public static function should_read_from_zone( string $post_type, string $zone ): bool {
+		return TMDO_Feature_Flags::is_read_custom(
+			TMDO_Zone_Router::module_name( $zone, $post_type )
+		);
+	}
+
+	/**
+	 * Returns true when Zone query-rewrite is active for the given post_type + zone.
+	 *
+	 * @param string $post_type Post type slug.
+	 * @param string $zone      Zone identifier.
+	 * @return bool
+	 */
+	public static function should_query_from_zone( string $post_type, string $zone ): bool {
+		return TMDO_Feature_Flags::is_query_active(
+			TMDO_Zone_Router::module_name( $zone, $post_type )
+		);
+	}
+
+	/**
+	 * Flush the request-level entity bridge cache.
+	 * Call this in test setUp to isolate test cases.
+	 */
+	public static function flush_cache(): void {
+		self::$entity_bridge_cache = array();
+	}
+}