# 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`](https://github.com/2meet/wp-data-optimizer) 提煉的純核心，整合層全部移到獨立 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 速查

```bash
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（給其他外掛）

```php
// 通用 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](readme.txt) — WordPress 外掛目錄格式說明（隨 ZIP 發佈）
- [CONTEXT.md](CONTEXT.md) — 領域詞彙表（Zone / Registry / Mode / FSM 的正式定義）
- [PLAN.md](PLAN.md) — 開發任務追蹤
- [CHANGELOG.md](CHANGELOG.md) — 版本歷史
- [DEPLOY.md](DEPLOY.md) — 部署流程
- [SECURITY.md](SECURITY.md) — 安全聯絡
- [DESIGN.md](DESIGN.md) — 架構決策
- [CLAUDE.md](CLAUDE.md) — AI 協作指引

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

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