2meet-data-optimizer/docs/PARTNER-REGISTRATION.md

Partner 外掛自行註冊指南

適用：2meet 自家外掛（bookings、collab、hub、infocards、mobile-bridge、playlist、quotation、spoke）。 這 8 個外掛原本各有一個 2meet-data-optimizer-<slug>-addon，替它們向核心註冊資料表和欄位。 這些 AddOn 已淘汰：資料結構的定義應該和資料的擁有者放在一起，所以改由 partner 外掛自己註冊。 啟用中的 AddOn 會在後台顯示淘汰通知（TMDO_Deprecated_Addons_Notice）。

HivePress、WooCommerce、LatePoint 是第三方外掛，仍然保留各自的 AddOn。

1. 掛上 trait

核心提供 TMDO_Anti_EAV_Aware trait（includes/trait-tmdo-anti-eav-aware.php）。trait 由核心載入，所以只有在核心存在時才宣告 bridge 類別，把它放在獨立檔案：

// 2meet-bookings.php（partner 主檔）
add_action(
	'plugins_loaded',
	static function () {
		if ( ! trait_exists( 'TMDO_Anti_EAV_Aware' ) ) {
			return; // 核心未啟用：什麼都不做。
		}
		require_once __DIR__ . '/includes/class-tmb-tmdo-bridge.php';
		( new TMB_TMDO_Bridge() )->boot();
	},
	3
);

// includes/class-tmb-tmdo-bridge.php
final class TMB_TMDO_Bridge {
	use TMDO_Anti_EAV_Aware;

	protected function plugin_slug(): string {
		return '2meet-bookings';
	}

	public function boot(): void {
		$this->bind_anti_eav_hooks();
	}

	// 覆寫需要的 on_register_*()，見下面兩節。
}

時機：核心在 plugins_loaded:4 觸發 wpdo_register_*，並在 init:1 再觸發一次。 建議掛在 plugins_loaded:3，這樣第一次觸發就能收到你的註冊，init 之前的讀寫也會被正確路由。 掛在 :5 之後也能運作（會在 init:1 補上），只是 init 之前的請求看不到你的欄位。

名稱：請用 TMDO_Anti_EAV_Aware。WPDO_Anti_EAV_Aware 是舊的 wp-data-optimizer 3.x 的 trait，由 mu-plugin wpdo-policy-enforcer.php 從已退役的路徑載入，沒有後面提到的 post_types 參數。

2. 註冊自有資料表

讓 wp wpdo doctor / benchmark 認得你的資料表，並做 schema 漂移檢查。以 bookings 為例：

public function on_register_custom_tables( TMDO_Custom_Table_Registry $r ): void {
	$this->register_custom_table(
		$r,
		array(
			'table_name'       => '2mb_services',   // 不含 $wpdb->prefix
			'primary_key'      => 'id',
			'post_type_link'   => null,            // 若每列對應一個 post，填 post_type（playlist 用 'hp_vendor'）
			'expected_columns' => array(
				'id'        => 'BIGINT',
				'vendor_id' => 'BIGINT',
				'title'     => 'VARCHAR',
				// …照 CREATE TABLE 逐欄列出
			),
			'indexes'          => array(
				'vendor_id' => array( 'vendor_id' ),
			),
		)
	);
}

collab、playlist、quotation、mobile-bridge 的 AddOn 只做這件事：把各自 includes/class-tmdo-<slug>.php 裡 register_custom_tables() 的 $tables 陣列原樣搬進 partner 的 bridge 即可。

3. 註冊 entity 欄位群組（選用）

只有要把 meta 從 wp_postmeta / wp_usermeta 等 EAV 表移到扁平表時才需要：

public function on_register_entity_fields(): void {
	$this->register_entity_fields(
		'post',
		'tmb_service_core',
		array(
			array( 'key' => 'tmb_price', 'type' => 'decimal', 'searchable' => true ),
			array( 'key' => 'tmb_status', 'type' => 'enum', 'options' => array( 'open', 'closed' ) ),
		),
		array( 'post_types' => array( 'tmb_service' ) )
	);
}

• post_types（post 群組建議必填）：群組只套用在這些 post type。多個群組共用同一個 meta key 時，會依 post 本身的類型決定寫到哪張表；不屬於這些 post type 的 post，這個 key 不受管理（照舊寫原生 meta）。沒有宣告時，共用 key 會被「最後註冊的群組」整個接走。
• 定義一旦上線就不要改：欄位定義的 hash 存在 wpdo_registry_meta，改了會對已有資料的扁平表執行 ALTER。要新增欄位時，開新群組。
• 群組名稱不可和別人重複：同名但定義不同時，後註冊的會被忽略，並在 Site Health、後台 Doctor 分頁和 wp wpdo doctor 顯示 [COLLISION]。

4. 從 AddOn 遷移

1. 在 partner 的 bridge 裡註冊和 AddOn 完全相同的資料表與群組（直接複製 AddOn 的定義）。
2. 部署 partner 新版，AddOn 先保持啟用。wp wpdo doctor 不應出現 [COLLISION]；兩邊定義相同時，重複註冊會被靜默忽略。
3. 停用 AddOn。
4. 再跑一次 wp wpdo doctor：資料表仍在清單中，而且不應出現 [ORPHAN]。如果出現，表示有群組沒有被 partner 接手；該實體是 aeav_only 時，核心會依 wpdo_registry_meta 暫時還原它，讓資料可以讀取，但仍應補上註冊。
5. 確認沒有問題後，刪除 AddOn 外掛。

hub、infocards、spoke 的 partner 外掛本身已經會自己註冊，AddOn 只是重複註冊；停用前照第 2 步確認沒有 [COLLISION] 即可。

相關文件

• ENTITY_ADAPTER_COOKBOOK.md：整合深度 Tier 1–3（TMDO_API facade、Schema Registry、自訂 adapter）。
• INTEGRATION_PATTERN_DECISION.md：2026-04 的「partner 自帶 bridge」決策紀錄；本指南回到這個做法。