# DESIGN — 2meet Data Optimizer 架構決策

## 設計目標（pillars）

1. **Zero-side-effect**：未啟用任何 zone 的站台應感受不到此外掛存在
2. **Non-destructive**：所有操作可 rollback（snapshot + 7-state FSM）
3. **Schema-first**：所有欄位需明確 register，禁止隱式 mapping
4. **Hook-bus only**：所有寫入必經 Hook Bus；禁止繞過 interceptor 直 SQL
5. **Anti-EAV strict**：紅線禁止 `SELECT FROM wp_*meta`（除一次性 migration / cron）

---

## 七態 FSM 模組生命週期

```
  ┌──────────────────────────────────────────────┐
  │                                              │
  v                                              │
idle ──→ dual_write ──→ backfill ──→ verify ──→ cutover ──→ cleanup ──→ complete
                                       │            │
                                       └─ rollback ─┘
```

| 態 | 寫 | 讀 | 可逆 |
|---|---|---|---|
| idle | wp_*meta | wp_*meta | ✓ |
| dual_write | wp_*meta + zone | wp_*meta | ✓ |
| backfill | wp_*meta + zone | wp_*meta | ✓ |
| verify | wp_*meta + zone | wp_*meta | ✓ |
| cutover | wp_*meta + zone | zone | ✓ (rollback to verify) |
| cleanup | zone only | zone | ✗ (postmeta 已 DROP) |
| complete | zone only | zone | ✗ |

---

## 四象限分配原則

| Zone | 條件 | 範例 |
|---|---|---|
| Hot | 同欄位被 meta_query 過濾或 ORDER BY 排序 | `_price`, `hp_featured` |
| Warm | 高頻寫入 / 短 TTL / 弱一致性 | view counter, hourly flag |
| Cold | 長文本 / 不被搜尋 / 顯示用 | `_description`, social links JSON |
| Archive | 過期資料 / gzip 壓縮 | expired listings 歷史欄位 |

`TMDO_Zone_Classifier` 自動分析（transient 1h），但人工 register 永遠優先。

---

## Hook Bus 架構

Hook Bus 是寫入唯一真理之源。任何外掛要參與反 EAV 必須：

```php
// 註冊
add_action( 'tmdo_register_entity_fields', function ( $registry_class ) {
    $registry_class::register_group( 'user', 'my_group', [...] );
} );

// 訂閱事件
add_action( 'tmdo_after_write', function ( $type, $id, $key, $value, $result ) {
    // ... cross-domain logic
} );
```

禁止直接 hook `update_user_meta` / `add_post_meta`（會與 Hook Bus 衝突，CI gate 偵測）。

---

## Schema Registry 雙軌

- **`TMDO_Schema_Registry`**：post entity 的 zone 欄位（HP listing 模式）
- **`TMDO_Entity_Registry`**：4 entity 通用 group（user/post/term/comment）

兩者並存原因：post zone 模式較成熟，user/term/comment 較新；最終 v0.3.0 會收斂為單一 registry。

---

## Custom Table Registry

第三方外掛的自訂表可註冊到 `TMDO_Custom_Table_Registry` 享有：
- `wp tmdo doctor` 表結構檢查
- Schema drift 偵測（CREATE 與 DROP 對齊）
- Benchmark 整合（可選 `benchmark_callback`）
- 衝突偵測

僅限 schema 監控，不會被 Hook Bus 攔截寫入。

---

## 為什麼資料表沿用 `wp_wpdo_*` 不 rename 為 `wp_tmdo_*`

- 避免 v2.16.0 → v0.1.0 資料遷移的成本與風險
- 兩外掛同時存在時 schema 完全相容（互斥啟動）
- v0.2.0 後若決定 rename 再做（屆時提供 `wp tmdo migrate-from-wpdo`）

---

## 為什麼公開 API 同時暴露 `TMDO_API` + `WPDO_API` (alias)

- `class_alias( 'TMDO_API', 'WPDO_API' )` 確保 hub-core / spoke-sso / 其他 consumer 零修改可用
- `wpdo_*` hook 與 `tmdo_*` hook 並存 dual-fire
- 過渡期 ≥ 2 個 minor 版本後加 `_doing_it_wrong` deprecation notice

---

## CSS 設計系統

承襲父環境奶油莫蘭迪設計系統（見 `wp-local-dev/CLAUDE.md` § 設計系統）：
- 顏色：`var(--color-*)`，禁止 HEX 硬編碼
- 間距：`var(--space-*)` 8px 倍數
- 圓角：`var(--radius-*)`
- 按鈕最小高度 44px
- 過渡：`var(--ease-default) + var(--duration-normal)`

詳見 `admin/assets/wpdo-admin.css`（從 wp-data-optimizer v2.16.0 搬入）。

---

## 反 EAV 8 維評分（自評）

承襲 wp-data-optimizer 8 維 anti-EAV 評分標準，目標 v0.1.0 達 9.5+/10：

1. ✅ Schema-first registration
2. ✅ Hook Bus single source of truth
3. ✅ No direct `wp_*meta` SELECT in app code
4. ✅ Custom table registry 全覆蓋
5. ✅ Sync Bridge dual-write + cutover
6. ✅ Query Router pre_get_posts 改寫
7. ✅ Snapshot + rollback 機制
8. ✅ Conflict detection + CI gate