2meet-data-optimizer/README.md

2meet Data Optimizer

通用 WordPress 反 EAV 引擎 — 零依賴，零 HivePress / WooCommerce / 2meet-* 綁定

把 wp_postmeta / wp_usermeta / wp_termmeta / wp_commentmeta 的高頻欄位自動分流到四象限扁平表（Hot / Warm / Cold / Archive），帶來 3-30× 的查詢加速。

從 wp-data-optimizer v2.16.0 提煉的純核心，整合層全部移到獨立 AddOn。

---

為什麼

WordPress 預設用 EAV (Entity-Attribute-Value) 模式儲存所有 meta：每筆 meta 都是 wp_*meta 表的一列。對少量欄位無傷，但站台一長大就出現：

• 單一 listing 可能對應數十條 postmeta → 列表頁查詢爆炸
• meta_query 複雜過濾必須 N 次 JOIN
• autoload=yes 的 wp_options 拖慢每頁載入
• _transient_* 滲入 wp_options 造成持續性脹

2meet-data-optimizer 為這些 meta 建立扁平欄位表（每 post_type 一張），由 Sync Bridge 雙寫，由 Query Router 改寫 meta_query 為直接 JOIN，達到接近原生欄位的效能。

---

四象限

Zone	表名	用途	加速場景
A Hot	wp_wpdo_hot_{type}	搜尋 / 篩選欄位	meta_query 過濾、ORDER BY 排序
B Warm	wp_wpdo_warm	TTL 計數 / 短期快取	瀏覽計數、暫時旗標
C Cold	wp_wpdo_cold_{type}	展示 / 描述欄位	詳情頁讀取
D Archive	wp_wpdo_archive	過期 gzip 歸檔	歷史資料保留

---

系統需求

• WordPress ≥ 6.0
• PHP ≥ 8.1
• MySQL ≥ 5.7 / MariaDB ≥ 10.3 (SQLite 亦支援)

---

安裝

1. 從 GitHub Release 下載 2meet-data-optimizer-v0.1.0.zip
2. 在 WordPress 後台 → 外掛 → 安裝外掛 → 上傳外掛
3. 啟用後執行 wp tmdo doctor 驗證

---

整合 AddOn（選用）

主外掛只覆蓋 WordPress 原生 4 entity meta。若使用 HivePress / WooCommerce / LatePoint / 2meet-* 系列等外掛並希望也享有反 EAV 加速，請額外安裝對應 AddOn：

AddOn	對應外掛
2meet-data-optimizer-hub-addon	2meet-hub-core
2meet-data-optimizer-spoke-addon	2meet-spoke-sso
2meet-data-optimizer-hivepress-addon	hivepress + 12 HP 擴充
2meet-data-optimizer-woocommerce-addon	woocommerce
2meet-data-optimizer-latepoint-addon	latepoint
2meet-data-optimizer-infocards-addon	2meet-infocards
2meet-data-optimizer-bookings-addon	2meet-bookings
2meet-data-optimizer-quotation-addon	2meet-quotation
2meet-data-optimizer-mobile-bridge-addon	2meet-mobile-bridge
2meet-data-optimizer-collab-addon	2meet-collab
2meet-data-optimizer-playlist-addon	2meet-playlist

---

WP-CLI 速查

wp tmdo status                  # 整體狀態
wp tmdo doctor                  # 健診（schema drift / 表對齊 / index）
wp tmdo benchmark hot_post --samples=200
wp tmdo migrate hot_post        # 執行 backfill
wp tmdo verify hot_post         # 比對 postmeta 與 zone 表
wp tmdo cutover hot_post        # 讀寫切到 zone 表
wp tmdo rollback hot_post       # 退回 postmeta
wp tmdo cleanup --archive-expired

---

公開 API（給其他外掛）

// 通用 4-entity 讀寫
TMDO_API::set_entity( 'user', $user_id, 'membership_level', 'gold' );
$level = TMDO_API::get_entity( 'user', $user_id, 'membership_level' );

// Schema 註冊
add_action( 'tmdo_register_entity_fields', function ( $registry_class ) {
    $registry_class::register_group( 'user', 'my_group', [
        [ 'key' => 'my_field', 'type' => 'text', 'searchable' => true ],
    ] );
} );

// 自訂表註冊（給其他外掛的表加入 doctor 監控）
add_action( 'tmdo_register_custom_tables', function ( $registry ) {
    $registry->register( 'my-plugin', [
        'table_name' => 'my_table',
        'primary_key' => 'id',
        'expected_columns' => [ ... ],
    ] );
} );

向後相容：WPDO_API / WPDO_Schema_Registry 等舊類別名透過 class_alias() 仍可使用（v0.2.0 起加 deprecation notice）。

---

授權

GPL-2.0-or-later

---

文件

• readme.txt — WordPress 外掛目錄格式說明（隨 ZIP 發佈）
• CONTEXT.md — 領域詞彙表（Zone / Registry / Mode / FSM 的正式定義）
• PLAN.md — 開發任務追蹤
• CHANGELOG.md — 版本歷史
• DEPLOY.md — 部署流程
• SECURITY.md — 安全聯絡
• DESIGN.md — 架構決策
• CLAUDE.md — AI 協作指引

給夥伴外掛作者（docs/，不進 ZIP）：

• ENTITY_ADAPTER_COOKBOOK.md — 五層整合階梯與決策樹
• adr-001-post-entity-source-of-truth.md — post entity 的權威來源契約
• adr-002-dual-write-naming-collision.md — dual_write 在兩套 FSM 的同名衝突
• INTEGRATION_PATTERN_DECISION.md — 整合模式取捨紀錄（含 v1.0.0 後記）
• anti-eav-lint.yml.template — 夥伴外掛 CI gate 樣板