wpdev
3d650eb848
- Add docs/PARTNER-REGISTRATION.md: TMDO_Anti_EAV_Aware bridge setup (plugins_loaded:3), table and entity-group registration with post_types scopes, frozen definitions, and the AddOn → self-registration migration checked with [COLLISION]/[ORPHAN] - TMDO_Deprecated_Addons_Notice warns administrators while any of the 8 in-house partner AddOns is active (site or network) - Trait register_entity_fields() forwards an optional $args (post_types) to the registry - Verify: DeprecatedAddonsNoticeTest (4); core unit 645 / integration 449, HP 148, WC 10 OK - PR: PR-021
116 lines
5.1 KiB
Markdown
116 lines
5.1 KiB
Markdown
# 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 類別，把它放在獨立檔案：
|
||
|
||
```php
|
||
// 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
|
||
);
|
||
```
|
||
|
||
```php
|
||
// 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 為例：
|
||
|
||
```php
|
||
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 表移到扁平表時才需要：
|
||
|
||
```php
|
||
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」決策紀錄；本指南回到這個做法。
|