軽量で制御可能な構造化データ管理プラグインへの再設計を調査する

[Olein-jp]

目的

OD Structured Dataを「AI対策プラグイン」ではなく、WordPressの情報から正確で重複のないJSON-LDを生成し、出力内容・情報源・競合状態を投稿ごとに確認、制御できる軽量な構造化データ管理プラグインとして再設計する。

今回は実装せず、既存データと公開APIの互換性を維持できる実装方針と、後続イシューへの分割案を整理する。

背景

Googleは、検索のAI機能向けに特別なSchema.orgマークアップは不要としている。一方、通常の構造化データについては、ページの可視コンテンツとの一致、正確性、適切な型の利用を引き続き求めている。

• AI 機能とウェブサイト
• Article 構造化データ
• 構造化データに関する一般的なガイドライン

現在のMVPには、以下の改善余地がある。

• Schema.orgとしての妥当性、Google向け推奨、可視コンテンツとの整合性が一つの検証結果に混在している
• 一部の項目不足をエラーとして扱い、JSON-LD全体の出力を停止している
• 自由入力の上書き値が、ページ上の可視コンテンツと不一致になる可能性がある
• SEOプラグインとの競合は存在検出と警告に留まり、Schemaごとの出力担当を制御できない
• 投稿設定が二値のため、投稿タイプ既定値の継承や安全な一括運用が難しい
• プレビューが保存済み投稿データと編集中データで一致しない可能性があり、設定変更ごとにREST APIを呼び出している
• サイト主体を常に最小のOrganizationとして扱っており、個人サイトや明示設定を表現できない

調査対象

最初に以下を確認する。

• docs/plugin-design-spec.md
• includes/class-schema-validator.php
• includes/class-graph-builder.php
• includes/class-post-settings.php
• includes/class-plugin-settings.php
• includes/class-conflict-detector.php
• includes/class-preview-rest-controller.php
• assets/editor.js
• tests/class-graph-builder-test.php
• tests/class-plugin-settings-test.php

上記から直接参照されるコードは、調査に必要な場合のみ追加で確認する。リポジトリ全体の網羅的調査は行わない。

調査で確認したいこと

1. バリデーションの責務分離

以下の3層を分離する設計を検討する。

• JSON-LD／Schema.orgの構文・型エラー
• Google Article向けの推奨・品質警告
• ページ上の可視コンテンツとの整合性警告

どの条件だけが出力を停止すべきかを明文化する。Googleの現行ドキュメントと、設計書にある「Google向け評価とSchema.orgとしての妥当性を分ける」という方針も照合する。

2. 出力ポリシーと既存データ移行

投稿単位の二値設定 enabled: true/false を、次の三状態へ移行する案を検討する。

• 投稿タイプ設定を継承
• この投稿だけ有効
• この投稿だけ無効

投稿タイプ側には「無効」「投稿ごとに有効化」「原則有効・投稿ごとに除外」などの出力ポリシーを持たせる。

既存の _od_structured_data、od_structured_data_default_enabled、一括有効化済みデータを壊さない移行方針を示す。一括有効化処理の廃止、またはバッチ化の要否も判断する。

3. Schemaの出力担当と競合制御

Article、WebPage、WebSite、Organizationなど、Schema単位で出力担当を選べる設計を検討する。

既知SEOプラグインが存在する場合も、他プラグインの出力を無断で削除・変更しない。公式APIや公開フィルターを使用できる連携だけをIntegrationとして扱い、安全な初期値と競合時の表示方法を決める。

4. 編集画面とプレビューの信頼性

次を実現するUI・データフローを検討する。

• 出力する／しない理由の表示
• Schemaの出力担当と競合状態
• 各プロパティの取得元、自動取得値、上書き値、最終出力値
• 上書き値と可視コンテンツが異なる場合の警告
• 未保存のタイトル、抜粋、画像を含む正確なプレビュー
• RESTプレビューのdebounce、キャンセル、必要時のみの取得
• JSON-LD全文は詳細表示にする

自由入力の上書きを通常設定として維持するか、エキスパート設定または取得元選択へ変更するかも判断する。

5. サイト主体とリリース品質

サイト主体としてOrganization、Person、出力なしを選択できる設定と、名称、URL、ロゴ、sameAs、publisher参照の扱いを検討する。

併せて、後続実装で必要になる以下の品質項目を整理する。

• 設定・投稿メタのマイグレーション
• REST API、レンダリング、競合制御、JavaScript、E2Eのテスト
• WordPress／PHP互換性マトリクス
• アンインストール時のデータ保持・削除方針
• フロントエンドと編集画面の性能予算

受け入れ条件

• 現状の責務と問題点が、対象ファイルに紐づけて整理されている
• 推奨データモデル、出力停止条件、競合制御、UIデータフローが示されている
• 既存オプション、投稿メタ、公開フィルターを考慮した後方互換性・移行方針が示されている
• 必要なテスト、性能上の注意、セキュリティ上の注意が整理されている
• 実装計画が5項目以内で示され、後続実装イシューの分割案と推奨順序が含まれている

制約

• 今回はコード、設定、ドキュメントを変更しない
• 既存の od_structured_data_* フィルターを安易に破壊しない
• 他プラグインのフックやJSON-LDを無断で削除・改変しない
• 検索順位、リッチリザルト、AI機能への掲載を保証する表現を採用しない
• 新しいSchemaタイプの追加を今回の主目的にしない
• 新しい依存パッケージを追加しない
• 関係のないリファクタリングや網羅的なリポジトリ調査を行わない

成果物

以下を簡潔に報告する。

1. 現状理解と主要な設計上の問題
2. 推奨するデータモデル・責務分割
3. 変更予定ファイルと公開APIへの影響
4. 必要なテスト・検証、移行リスク
5. 5項目以内の実装計画と後続イシュー分割案

作業方法

• サブエージェントは使用しない
• 最初に指定したファイルと直接参照される依存だけを確認する
• 実装可能な方針が確定した時点で調査を終了する
• 追加機能のアイデアは実装計画へ混ぜず、必要なら将来候補として分離する