docs: 移植 readme.txt / CONTEXT.md / docs（backport A v3.4.6）

- readme.txt（WP 外掛目錄格式，隨 ZIP 發佈）：Stable tag 對齊 1.0.0， changelog 補 1.0.0 條目 - CONTEXT.md（領域詞彙表）：Status 區塊改寫為 v1.0.0 實況； HPCT_INTERCEPTORS 與 HivePress Adapter 兩節標註「已搬到 AddOn，核心無此常數」 - docs/：ENTITY_ADAPTER_COOKBOOK、2 篇 ADR、INTEGRATION_PATTERN_DECISION、 anti-eav-lint.yml.template - cookbook 修掉兩個死連結（ANTI_EAV_PLAYBOOK 在來源外掛就不存在） - INTEGRATION_PATTERN_DECISION 加 v1.0.0 後記：結論已被 AddOn 拆分取代 - template 改 wpdev/2meet-data-optimizer + ref v1.0.0 + wp tmdo lint - README.md 文件索引補上以上 7 個檔案前綴改寫刻意只動類別/函式/slug（WPDO_→TMDO_、wp-data-optimizer→2meet-...）， wpdo_ option/cron/hook/表名與 wpdo/v1 REST namespace 一律保留 —— 這是資料層零遷移的前提。
2026-07-31 10:06:03 +08:00
parent 2203bc471c
commit b63ab46f54
8 changed files with 1564 additions and 0 deletions
@@ -0,0 +1,560 @@
+# Entity Adapter Cookbook
+
+How partner plugins integrate with `2meet-data-optimizer v1.0.0+` to gain anti-EAV
+benefits without modifying their existing data model.
+
+This is the practical guide. For the canonical vocabulary see `CONTEXT.md`; for the
+two standing architectural decisions see `docs/adr-001-post-entity-source-of-truth.md`
+and `docs/adr-002-dual-write-naming-collision.md`.
+
+---
+
+## ⚡ TL;DR Decision Tree (read this first — v2.1.2 reordered)
+
+The most common mistake is picking Tier 1-3 when Tier 5 was the right answer.
+Ask these questions in order:
+
+```
+Q1. Does the partner plugin have its OWN custom tables / lookup tables
+    that already provide anti-EAV? (HPOS, wc_product_meta_lookup,
+    BuddyPress activity tables, EDD payments, etc.)
+
+    ├── YES → 🟢 TIER 5 (integrate, don't duplicate). STOP HERE.
+    │         Register awareness only. Do not migrate.
+    │         See: TMDO_WooCommerce reference.
+    │
+    └── NO → continue to Q2.
+
+Q2. Is this a brand-new plugin you control end-to-end?
+
+    ├── YES → 🟢 TIER 4 (greenfield, anti-EAV from day 1).
+    │         Use `wp tmdo register-stub <slug>` for boilerplate.
+    │         See: 2meet-inquiries reference.
+    │
+    └── NO (existing plugin with postmeta) → continue to Q3.
+
+Q3. Is the relevant postmeta key heavily queried (filter / sort / search)?
+    Benchmark: > 10k rows OR > 3-condition meta_query OR sort by meta_value.
+
+    ├── YES → 🟢 TIER 1-3 (migrate to a Zone).
+    │         Tier 1 (5 min) for read-only optimization.
+    │         Tier 2 (30 min) for full dual-write.
+    │         Tier 3 (1-2 days) for new entity type.
+    │
+    └── NO → 🟢 LEAVE AS POSTMETA. Premature optimization.
+              Re-evaluate when scale crosses Q3 thresholds.
+```
+
+**Why Tier 5 is FIRST**: at v2.1.2 audit time, every mature plugin we surveyed
+(WC / BuddyPress potential / EDD potential / GravityForms) has its own anti-EAV.
+Defaulting to Tier 1-3 risks the catastrophic "two sources of truth" failure
+mode. See `docs/INTEGRATION_PATTERN_DECISION.md` for the principle.
+
+### How to tell if a partner plugin already has anti-EAV (Tier 5 candidate)
+
+Check these signals in order — any ONE is sufficient for Tier 5:
+
+| Signal | Where to look | Examples |
+|--------|---------------|----------|
+| **Lookup tables** with name pattern `*_lookup` / `*_meta_lookup` / `*_index` | `SHOW TABLES LIKE 'wp_{prefix}_%lookup%'` | `wp_wc_product_meta_lookup`, `wp_wc_customer_lookup` |
+| **HPOS-style migration toggle** (custom table replaces postmeta) | Plugin's settings → "High Performance" or "Custom Tables" feature | WooCommerce HPOS, EDD 3.0 payments |
+| **Dedicated columns instead of meta** in main entity table | `DESC wp_{plugin}_entities` shows `price`, `status` etc. as columns | BuddyPress activity table, MemberPress subscriptions |
+| **Plugin's own search/filter API** that bypasses `meta_query` | `wc_get_products()`, `bp_activity_get()`, `edd_get_payments()` | WC, BuddyPress, EDD all have native APIs |
+| **`*_stats` / `*_aggregate` tables** for analytics queries | `wp_wc_order_stats`, `wp_*_lookup` | WC analytics, MonsterInsights |
+| **db_version option** that hits `dbDelta` migration on plugin update | `wp option get {plugin}_db_version` returns a non-trivial version | Indicates the plugin has its own schema migration story |
+
+If you see **2+ signals** → definitely Tier 5.
+If you see **0 signals** but the plugin has heavy postmeta usage → Tier 1-3.
+If you see **0 signals** and postmeta is light → leave it (Q3 = NO).
+
+**Quick command-line audit**:
+```bash
+# List custom tables for a plugin
+wp db query "SHOW TABLES LIKE 'wp_{prefix}_%'"
+
+# Count postmeta keys the plugin owns (low = likely Tier 5; high = candidate Tier 1-3)
+wp db query "SELECT COUNT(DISTINCT meta_key) FROM wp_postmeta WHERE meta_key LIKE '\\_{prefix}_%'"
+
+# If both numbers are non-trivial → Tier 5 is correct (plugin uses both, but
+# its tables are the truth and postmeta is legacy/secondary).
+```
+
+---
+
+## Three integration tiers
+
+Pick the one that matches your plugin's data model:
+
+### Tier 1 — `TMDO_API` facade（最少改動，5 分鐘）
+
+If your plugin reads/writes `*_meta()` directly today, swap to the facade. This
+gives you future-proofing for free — the day the field migrates to a zone or
+entity adapter, your plugin needs zero changes.
+
+**Before:**
+```php
+$token = get_post_meta( $vendor_id, 'tmeetic_ical_token', true );
+update_post_meta( $vendor_id, 'tmeetic_ical_token', $new_token );
+```
+
+**After:**
+```php
+$token = class_exists( 'TMDO_API' )
+    ? TMDO_API::get_field( $vendor_id, 'tmeetic_ical_token' )
+    : get_post_meta( $vendor_id, 'tmeetic_ical_token', true );
+
+if ( class_exists( 'TMDO_API' ) ) {
+    TMDO_API::set_field( $vendor_id, 'tmeetic_ical_token', $new_token );
+} else {
+    update_post_meta( $vendor_id, 'tmeetic_ical_token', $new_token );
+}
+```
+
+**Real example:** `2meet-courses/includes/class-2meetic-ical.php` (Wave 2 改造).
+
+**Cross-entity:**
+```php
+TMDO_API::get_entity( 'user',    $user_id, 'points' );
+TMDO_API::get_entity( 'term',    $term_id, 'usage_count' );
+TMDO_API::get_entity( 'comment', $comment_id, 'helpful_count' );
+TMDO_API::set_entity( 'user', $uid, 'points', 50 );
+```
+
+**Helper:**
+```php
+TMDO_API::is_field_registered( 'post', 'hp_price' );  // bool
+TMDO_API::trace_storage( 'post', 'hp_price', 'hp_listing' );  // 'zone_hot' | 'postmeta' | ...
+```
+
+### Tier 2 — Schema Registry 註冊（中等改動，30 分鐘）
+
+If your plugin owns specific meta_keys that benefit from Hot zone (search/filter),
+Cold zone (display/JSON), or Warm zone (TTL counter) treatment.
+
+**Implementation:** create one integration class.
+
+```php
+// my-plugin/includes/class-tmdo-myplugin.php
+final class TMDO_MyPlugin {
+    public static function register(): void {
+        // Detect partner plugin (2meet-data-optimizer) — no-op when absent.
+        if ( ! class_exists( 'TMDO_Schema_Registry' ) ) {
+            return;
+        }
+        add_action( 'wpdo_register_fields', array( __CLASS__, 'register_fields' ) );
+        add_action( 'wpdo_register_custom_tables', array( __CLASS__, 'register_tables' ) );
+    }
+
+    public static function register_fields( TMDO_Schema_Registry $registry ): void {
+        $registry->register_many( 'my-plugin', array(
+            // Hot zone (search/filter): flat 1NF column with index.
+            array(
+                'post_type' => 'my_post_type',
+                'meta_key'  => 'my_price',
+                'zone'      => 'hot',
+                'data_type' => 'decimal(10,2) NOT NULL DEFAULT 0',
+                'column'    => 'my_price',
+                'indexed'   => true,
+            ),
+            // Cold zone (description / JSON / display).
+            array(
+                'post_type'   => 'my_post_type',
+                'meta_key'    => 'my_description',
+                'zone'        => 'cold',
+                'cache_group' => 'wpdo_cold_my_post_type',
+                'cache_ttl'   => HOUR_IN_SECONDS,
+            ),
+        ) );
+    }
+
+    public static function register_tables( TMDO_Custom_Table_Registry $registry ): void {
+        $registry->register( 'my-plugin', array(
+            'table_name'      => 'my_custom_table',
+            'primary_key'     => 'id',
+            'post_type_link'  => 'my_post_type',
+            'doctor_callback' => array( __CLASS__, 'doctor_my_table' ),
+        ) );
+    }
+
+    public static function doctor_my_table(): array {
+        global $wpdb;
+        $count = (int) $wpdb->get_var( "SELECT COUNT(*) FROM `{$wpdb->prefix}my_custom_table`" );
+        return array( 'ok' => true, 'message' => "rows: {$count}" );
+    }
+}
+
+// In your plugin's bootstrap:
+add_action( 'plugins_loaded', array( 'TMDO_MyPlugin', 'register' ), 5 );
+```
+
+**Real examples:**
+- `2meet-data-optimizer/includes/integrations/class-tmdo-infocards.php` — 9 fields + 3 tables
+- `2meet-data-optimizer/includes/integrations/class-tmdo-bookings.php` — 7 tables only
+
+### Tier 3 — Custom Entity Adapter（大改動，1-2 天）
+
+If you need cross-entity behaviour (e.g. counter that works on user / term /
+comment uniformly), use the demo entity counter pattern.
+
+**Real example:** `2meet-data-optimizer/includes/integrations/class-tmdo-demo-entity-counter.php`.
+
+**Pattern:**
+```php
+final class My_Counter {
+    public const MODULE = 'entity_my_counter';
+    public const TABLE  = 'wpdo_my_counters';
+
+    public static function install_table(): void {
+        global $wpdb;
+        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+        dbDelta( "CREATE TABLE {$wpdb->prefix}" . self::TABLE . " (
+          id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
+          entity_type varchar(20) NOT NULL,
+          entity_id   bigint(20) unsigned NOT NULL,
+          counter_key varchar(100) NOT NULL,
+          counter_value bigint(20) NOT NULL DEFAULT 0,
+          updated_at datetime NOT NULL,
+          PRIMARY KEY (id),
+          UNIQUE KEY ui_entity_counter (entity_type, entity_id, counter_key),
+          KEY idx_lookup (entity_type, counter_key, counter_value)
+        ) {$wpdb->get_charset_collate()};" );
+    }
+
+    public static function set( string $entity_type, int $entity_id, string $key, int $value ): void {
+        // Always write native (durability anchor).
+        TMDO_API::set_entity( $entity_type, $entity_id, $key, $value );
+
+        // Conditional dual-write to zone table.
+        if ( TMDO_Feature_Flags::is_write_active( self::MODULE ) ) {
+            TMDO_DB::upsert(
+                $GLOBALS['wpdb']->prefix . self::TABLE,
+                array(
+                    'entity_type'   => $entity_type,
+                    'entity_id'     => $entity_id,
+                    'counter_key'   => $key,
+                    'counter_value' => $value,
+                    'updated_at'    => current_time( 'mysql' ),
+                ),
+                array( 'counter_value', 'updated_at' ),
+                array( 'entity_type', 'entity_id', 'counter_key' ),
+                array( '%s', '%d', '%s', '%d', '%s' )
+            );
+        }
+    }
+
+    public static function get( string $entity_type, int $entity_id, string $key ): int {
+        if ( TMDO_Feature_Flags::is_read_custom( self::MODULE ) ) {
+            // Read from zone table; fallback to native if row missing.
+            $val = $GLOBALS['wpdb']->get_var( $GLOBALS['wpdb']->prepare(
+                "SELECT counter_value FROM `{$GLOBALS['wpdb']->prefix}" . self::TABLE . "`
+                 WHERE entity_type = %s AND entity_id = %d AND counter_key = %s",
+                $entity_type, $entity_id, $key
+            ) );
+            if ( null !== $val ) {
+                return (int) $val;
+            }
+        }
+        return (int) TMDO_API::get_entity( $entity_type, $entity_id, $key );
+    }
+
+    public static function top_n( string $entity_type, string $key, int $n = 10 ): array {
+        // Killer query that postmeta cannot do efficiently.
+        return $GLOBALS['wpdb']->get_results( $GLOBALS['wpdb']->prepare(
+            "SELECT entity_id, counter_value FROM `{$GLOBALS['wpdb']->prefix}" . self::TABLE . "`
+             WHERE entity_type = %s AND counter_key = %s
+             ORDER BY counter_value DESC LIMIT %d",
+            $entity_type, $key, $n
+        ), ARRAY_A );
+    }
+}
+```
+
+---
+
+## FSM lifecycle reference
+
+For Tier 3 entity adapters, drive the 7+1 state machine via CLI:
+
+```bash
+# 1. Install schema (one-time)
+wp tmdo doctor   # verify base tables
+
+# 2. Initial state: idle (do not register feature flag)
+wp tmdo mode-audit | grep entity_my_counter   # should show 'idle'
+
+# 3. Begin dual_write — both native + zone get writes
+wp tmdo mode-set entity_my_counter dual_write
+
+# 4. Run backfill (if you have existing data)
+# (custom script or wp tmdo migrate)
+
+# 5. Verify with shadow_read for 7 days
+wp tmdo mode-set entity_my_counter verify
+wp tmdo shadow-enable entity_my_counter
+
+# Check for diffs
+wp eval 'echo (int) $GLOBALS["wpdb"]->get_var("SELECT COUNT(*) FROM {$GLOBALS[\"wpdb\"]->prefix}wpdo_shadow_diffs WHERE entity_type=\"user\"");'
+
+# 6. Cutover — reads switch to zone
+wp tmdo shadow-disable entity_my_counter
+wp tmdo mode-set entity_my_counter cutover
+
+# 7. After 7 more days, cleanup native rows
+wp tmdo mode-set entity_my_counter cleanup
+
+# 8. Final state — no fallback, zone is source of truth
+wp tmdo mode-set entity_my_counter complete
+
+# Rollback at any time
+wp tmdo mode-set entity_my_counter idle
+```
+
+---
+
+## Anti-EAV lint exemptions
+
+Some patterns require direct SQL by design (one-off migration scans, cron token
+expiry checks). Mark them with `phpcs:ignore` so `wp tmdo lint --strict` accepts them:
+
+```php
+// phpcs:ignore WPDO.AntiEAV.PostmetaScan -- Cron sweeps postmeta to find expiring IG tokens.
+$ids = $wpdb->get_col( $wpdb->prepare(
+    "SELECT post_id FROM {$wpdb->postmeta} WHERE meta_key = 'tmeetic_ig_token_expiry' AND CAST(meta_value AS UNSIGNED) < %d",
+    time() + 31 * DAY_IN_SECONDS
+) );
+```
+
+**Available rules:**
+- `WPDO.AntiEAV.PostmetaScan` — cross-postmeta scan in migration / cron
+- `WPDO.AntiEAV.UsermetaScan` — same, usermeta
+- `WPDO.AntiEAV.PostmetaFallback` — fallback path during graceful degradation
+
+The exemption stays line-local. The lint cannot be silenced for an entire file.
+
+---
+
+## Verification checklist (before merge)
+
+```bash
+# 1. Lint passes strict
+wp tmdo lint --plugin=$(pwd) --strict
+
+# 2. Conflict scan clean
+wp tmdo conflict-scan
+
+# 3. Doctor check (your custom tables registered + healthy)
+wp tmdo doctor
+
+# 4. Tests pass (if your plugin has them)
+./vendor/bin/phpunit
+```
+
+---
+
+## Real-world results (dev10, 2026-04-25)
+
+Production benchmarks measured with 50 hp_listing posts:
+
+| Path | Latency (n=100) | Speedup |
+|---|---|---|
+| Native `get_post_meta()` | 205ms | 1.0x baseline |
+| `TMDO_Listing_Stats::get_view_count()` (Zone B Warm + fallback) | 81ms | **2.51x** |
+| `TMDO_Demo_Entity_Counter::top_n()` (Zone via 1 LEFT JOIN) | 0.19ms / call | **postmeta cannot do efficiently** |
+
+The `top_n` example is the killer use case — sorting 1000s of users by point
+count via postmeta requires a full meta_value scan + filesort. The zone table
+serves it from a covering index in sub-millisecond.
+
+---
+
+## Tier 4: Greenfield plugin — `2meet-inquiries` (v0.5.0)
+
+The cleanest case: a plugin written **from scratch** to be anti-EAV from day 1.
+Use this as a template for all new 2meet-* plugins.
+
+### Why this is the gold standard
+
+| Pattern | What `2meet-inquiries` does | What `bookings`/`courses`/`infocards` had to retrofit |
+|---|---|---|
+| Large structured config | `wp_2mqi_forms.config_json LONGTEXT` (custom table) | Originally postmeta `_eh_inquiry_config` (anti-EAV violation) |
+| Hot-zone meta on hp_vendor | `wpdo_register_fields` — `_tmqi_default_form_id` (bigint, indexed) | Some retrofitted via Schema_Registry Hot Wave 1; others still WP_Query-driven |
+| Sensitive PII | `customer_email_enc BLOB` + `customer_email_hash CHAR(64)` for indexed lookup | Originally separate plugins each rolled own AES wrapper |
+| Audit-trail rows | Dedicated `wp_2mqi_responses` table (1 row per submission) | Older plugins used `wp_postmeta` rows-per-field → EAV blow-up |
+| Analytics events | Dedicated `wp_2mqi_analytics` (event_type, stage_index, session_id) | N/A — most plugins didn't have analytics, would've gone to postmeta if they did |
+| Webhook config | `wp_options` per vendor (autoload=no, low cardinality) | Same |
+
+### Anatomy: 4 custom tables, 0 plugin-owned postmeta keys
+
+```
+wp_2mqi_forms       — form definitions (config_json + counters + slug)
+wp_2mqi_responses   — submitted inquiries (encrypted PII + payload_json)
+wp_2mqi_drafts      — in-progress submissions (token + 14-day expire)
+wp_2mqi_analytics   — funnel events (view, stage_*, submit)
+```
+
+Plus 2 `hp_vendor` fields registered to Schema_Registry Hot zone:
+
+```php
+$registry->register_many( '2meet-inquiries', array(
+    array(
+        'post_type' => 'hp_vendor',
+        'meta_key'  => '_tmqi_default_form_id',
+        'zone'      => 'hot',
+        'data_type' => 'bigint(20) NOT NULL DEFAULT 0',
+        'column'    => '_tmqi_default_form_id',
+        'indexed'   => true,
+    ),
+    array(
+        'post_type' => 'hp_vendor',
+        'meta_key'  => '_tmqi_inquiries_enabled',
+        'zone'      => 'hot',
+        'data_type' => 'tinyint(1) NOT NULL DEFAULT 0',
+        'column'    => '_tmqi_inquiries_enabled',
+        'indexed'   => true,
+    ),
+) );
+```
+
+### Bootstrap pattern (recommended)
+
+```php
+final class TMQI_Plugin {
+    use TMDO_Anti_EAV_Aware;  // ← strict contract; fails to load without it
+
+    public function run(): void {
+        // Register tables on the canonical action.
+        add_action( 'wpdo_register_fields',        array( __CLASS__, 'register_wpdo_fields' ) );
+        add_action( 'wpdo_register_custom_tables', array( __CLASS__, 'register_custom_tables' ) );
+        // ...
+    }
+
+    public static function register_wpdo_fields(): void { /* hot-zone fields */ }
+    public static function register_custom_tables( $registry = null ): void {
+        TMQI_WPDO_Integration::register_tables( $registry );
+    }
+}
+```
+
+### Ground rules followed
+
+✅ **No `update_post_meta()` calls anywhere** — even for hp_vendor metas, we call `TMDO_API::set_field()`
+✅ **No direct `SELECT FROM wp_postmeta`** — `wpdo lint --strict` exits 0
+✅ **All large JSON in custom tables** — `config_json` and `payload_json` columns, never postmeta
+✅ **Sensitive data encrypted** — reuse `TMEETIC_Crypto::encrypt()` (don't roll your own)
+✅ **Indexed search on encrypted columns** — store SHA-256 hash alongside ciphertext
+✅ **Single `do_action( 'tmqi/submitted' )`** — downstream notifiers, analytics, webhook all hook here
+
+### Verification (run on dev10 right now)
+
+```bash
+# Custom tables registered
+wp eval 'echo count(TMDO_Custom_Table_Registry::instance()->for_provider("2meet-inquiries"));'
+# → 4
+
+# Strict lint passes
+wp tmdo lint --plugin=$(wp plugin path 2meet-inquiries) --strict
+# → Success: Anti-EAV lint passed
+
+# Conflict scan
+wp tmdo conflict-scan
+# → 0 conflicts detected
+```
+
+### Takeaway for Wave 2/3 retrofits
+
+When refactoring an existing plugin to be anti-EAV, the question is not "how do
+we shoehorn this into postmeta less?" — it's "**what does the data look like if
+we redesign it like 2meet-inquiries from day 1?**" Then plot a migration path.
+
+For most plugins the answer is: **replace one big postmeta key with one custom
+table row, and register a small number of hot-zone hp_vendor fields for search.**
+
+---
+
+## Tier 5: Integrating with a plugin that has its OWN anti-EAV — `TMDO_WooCommerce` (v2.1.0)
+
+The hardest case: WC core already has anti-EAV (HPOS for orders, `wp_wc_product_meta_lookup`
+for products). WPDO's job is to **integrate, not duplicate**.
+
+### Why this is different from Tiers 1-4
+
+| Aspect | Tier 1-4 (we own the data) | Tier 5 (WC owns it) |
+|--------|---------------------------|----------------------|
+| Custom tables | We define + create | WC defines + creates |
+| Hot-zone fields | Migrated from postmeta to our Hot zone | Already in WC's lookup tables; we just **register awareness** |
+| Doctor probes | We control existence + schema | We probe but don't fix |
+| Schema drift | Our migration tooling | WC's update_db_*() handles |
+| Conflict | None (single owner) | **Risk: shadow lookup tables** |
+
+### Anti-pattern: ❌ DON'T duplicate WC's lookup tables
+
+```php
+// WRONG — creates a parallel system that drifts from WC's truth
+$schema->register( 'woocommerce', array(
+    'post_type' => 'product',
+    'meta_key'  => '_price',
+    'zone'      => 'hot',
+    // ... migrate _price into our wpdo_hot_product table
+) );
+// Now `_price` lives in BOTH wp_wc_product_meta_lookup AND our hot zone.
+// Updates touch one but not the other. Catastrophe.
+```
+
+### Right pattern: ✅ Register awareness, defer to WC's anti-EAV
+
+```php
+// In TMDO_WooCommerce::register_custom_tables():
+foreach ( WC_CORE_TABLES as $name => $meta ) {
+    $registry->register( 'woocommerce', array(
+        'table_name'     => $name,        // wp_wc_product_meta_lookup
+        'description'    => $meta['description'],
+        'doctor_callback' => array( __CLASS__, 'doctor_check' ),
+    ) );
+}
+
+// In TMDO_WooCommerce::register_schema_fields():
+// Register postmeta keys WC STILL uses (the ones not yet migrated to lookups).
+// When `_price` is also in wc_product_meta_lookup, registering doesn't migrate
+// to OUR hot zone — it's just a hint to TMDO_API consumers about "this is hot".
+$schema->register_many( 'woocommerce', array(
+    array( 'post_type' => 'product', 'meta_key' => '_price', 'zone' => 'hot', ... ),
+    // ...
+) );
+```
+
+### Decision tree for new partner integrations
+
+```
+Does the partner plugin store data in postmeta?
+├── NO → already on custom tables → Tier 4 (register tables + done)
+└── YES → does the partner have its own lookup/cache table?
+    ├── NO → Tier 1-3 (we manage migration)
+    └── YES → Tier 5: register awareness only, never duplicate
+```
+
+### Tier 5 checklist for `TMDO_WooCommerce`
+
+- [x] Register all 20 `wp_wc_*` tables to Custom_Table_Registry
+- [x] Add `doctor_callback` that probes existence + row count (not schema diff)
+- [x] Register hot-zone postmeta fields (legacy path only) — WC's lookup is the truth
+- [x] Detect HPOS state via `OrderUtil::custom_orders_table_usage_is_enabled()`
+- [x] When HPOS off → register order postmeta hot fields (`_order_total`, etc.)
+- [x] When HPOS on → DON'T register order postmeta (would be stale)
+- [x] Customer usermeta hot fields registered unconditionally (WC always uses usermeta for these)
+- [x] Subscription product fields conditional on `WC_Subscriptions` OR `wc-linepay-subscription`
+- [x] Own custom table (`wpdo_wc_commissions`) for vendor marketplace tracking
+- [x] Admin notice recommends HPOS when legacy order count > threshold
+- [x] Admin dashboard surfaces commission stats + table health
+
+### What this DOESN'T do (and shouldn't)
+
+- ❌ Migrate `_price` into our hot zone (WC already has wc_product_meta_lookup)
+- ❌ Mirror `wc_orders` into our archive zone (WC handles its own archive)
+- ❌ Intercept `update_post_meta` for product meta (interferes with WC's lookup sync)
+- ❌ Create products / orders / customers (WC's domain)
+
+### When to revisit
+
+- WC drops a lookup table (unlikely but possible) → migrate that field path to Tier 3
+- HPOS becomes default-on → audit our order postmeta registrations and remove
+- New WC subextension introduces meta keys we should register → add to `register_subscription_fields()`