mataba/shop/docs/DATABASE-MODEL.md

XShop – Database Model

1. Philosophy

Reuse WP/WC primitives. No custom tables in v1.0 – revisit via ADR if query scale warrants. Document every key.

2. WordPress-Owned

• Users (wp_users, wp_usermeta): native. XShop adds: xshop_wishlist (array of product IDs), xshop_compare (array), xshop_recently_viewed (capped list).
• Posts/Pages (wp_posts, wp_postmeta): native.
• Media (wp_posts attachment): native.
• Menus (wp_terms nav_menu): native.
• Comments/Reviews: WC reviews = WP comments on product post type. XShop Q&A moderation hooks onto comment moderation flow where applicable – but primary store is custom (below).

3. WooCommerce-Owned

• Products (wp_posts post_type product + wp_postmeta + wp_wc_* where HPOS enabled). Variations are product_variation children.
• Orders/Customers/Coupons/Shipping/Payment/Taxes/Cart/Checkout: WC owned (HPOS tables if enabled). XShop never writes directly to WC order tables except via WC APIs.

4. XShop-Core Custom Data

4.1 Banners – CPT xshop_banner

• post_type = xshop_banner (non-public, show_ui true under XShop menu).
• Meta:
  • _xshop_banner_image (attachment ID, int)
  • _xshop_banner_mobile_image (attachment ID, int, nullable)
  • _xshop_banner_link (url, esc_url_raw)
  • _xshop_banner_cta (string)
  • _xshop_banner_position (enum: home_hero, home_strip, shop_top, product_sidebar, etc.)
  • _xshop_banner_active (1|0)
  • _xshop_banner_start / _xshop_banner_end (datetime Y-m-d H:i:s, UTC)
  • _xshop_banner_order (int)
• Scheduling checked on render (skip if outside window or inactive).

4.2 Questions & Answers – CPT xshop_qa

Decision: CPT (not comments) for cleaner moderation + threading without polluting reviews.

• post_type = xshop_qa, post_parent = product ID (or meta _xshop_qa_product_id for query flexibility – both stored, parent is canonical).
• Post fields: post_title empty, post_content = question body, post_status = pending|publish|trash, post_author = asker.
• Meta:
  • _xshop_qa_product_id (int, indexed via meta query)
  • _xshop_qa_answer (string, nullable – single answer for v1; extension to multiple answers uses child xshop_qa rows with post_parent = question ID in v1.1)
  • _xshop_qa_answered_by (int user ID)
  • _xshop_qa_answered_at (datetime)
• Alternative for multiple answers (future): child posts post_type=xshop_qa, post_parent=question ID.
• Spam: honeypot + nonce + rate limit (transient per IP/user, 60s).

4.3 Wishlist & Compare

• Logged-in: wp_usermeta keys xshop_wishlist, xshop_compare (serialized array of ints, capped: wishlist 200, compare 4).
• Guest: cookie xshop_wishlist / xshop_compare (JSON, HttpOnly false for JS count, SameSite Lax, 30 days) + optional transient xshop_guest_<token>.
• On login: merge cookie → user meta (union, cap), clear cookie.
• Counts exposed via REST and localized script data.

4.4 Recently Viewed

• Cookie xshop_recently_viewed (JSON array of product IDs, capped 20, 30 days). No DB write for guests. Logged-in also stored in xshop_recently_viewed user meta for cross-device.

5. Options

• Single option xshop_settings (array) – all Theme Options. Autoload yes. Individual mods also mirrored via theme_mod for Customizer preview where needed, but source of truth is xshop_settings.
• Option xshop_settings_backup (for import/export).
• Transient xshop_search_cache_<hash> (5 min) for AJAX search results.
• Transient xshop_filter_counts_<hash> (5 min) for filter counts.

Do NOT scatter random options.

6. Indexes & Query Patterns

• Banners: query by post_type + meta position+active+date range → meta query; small cardinality.
• Q&A: WP_Query by post_type=xshop_qa + post_parent=product_id + post_status=publish (index on post_parent + post_type already exists).
• Wishlist/Compare: user meta single-row lookup – O(1).
• Search: WP_Query with s + post_type=product + tax_query for category, meta_query for SKU (_sku), limited to 8 suggestions, no_found_rows true, fields=ids then prime caches.

7. Migrations & Compatibility

• HPOS: use wc_get_products() / CRUD, not direct wp_postmeta writes for product data.
• On plugin deactivate: data retained (no destructive cleanup). Uninstall hook offered to purge (uninstall.php with confirmation).