1. プラグイン概要・2段リッチサジェストの仕組み
ECサイトの売上（CVR）を高める上で、検索機能の使いやすさは最重要指標のひとつです。多くのユーザーは「探している商品の名前」を正確に覚えていないか、あるいはスマホでのタイピングを面倒に感じています。
- 文字だけの単語リスト： 候補単語をクリックしても、結局また「検索結果一覧ページ」に飛ばされ、そこから商品を再スクロールして探さなければならず、離脱が発生する。
- 入力ミスの壁： 「よーぐると」とひらがなで入れたり、「yogurt」と英語で入れた場合に、カタカナ商品名の「ヨーグルト」がヒットせず「検索結果0件」となってしまう。
- スマホでの操作性不良： スマホの小さな画面でドロップダウンが崩れたり、キーボードに隠れて選択できない。
本プラグイン（RichSearchSuggest）は、これらの課題を一掃するEC-CUBE公式ストア水準の2段構造サジェストを提供します。
2. 動作要件・システム環境
本プラグインは外部の形態素解析サーバーや重いJavaプロセス（Sudachi等）を一切必要とせず、標準のPHP/MySQL/PostgreSQL環境のみで超軽量に動作します。
| 項目 | 要件・対応仕様 |
|---|---|
| 対応EC-CUBE | EC-CUBE 4.2.0 〜 4.3.x（4.2系 / 4.3系 両対応） |
| PHPバージョン | PHP 8.1 〜 PHP 8.3（PHP 8.2+ 準拠） |
| 対応データベース | MySQL 5.7 / 8.0、PostgreSQL 10 〜 16 |
| CSSフレームワーク | Bootstrap 5（4.3系標準）および Bootstrap 4（4.2系標準）完全対応 |
| フロントエンド依存 | Vanilla JavaScript（jQuery等の外部重厚ライブラリ依存ゼロ） |
3. インストール・初期セットアップ
3-1. インストールと有効化
- EC-CUBE管理画面の [オーナーズストア] ＞ [プラグイン] ＞ [プラグイン一覧] を開きます。
- 購入済みの「RichSearchSuggest」の [インストール] をクリックします。
- 完了後、プラグインの [有効化] スイッチをONにします。
input[name="name"]）を自動認識してリッチサジェストが即座に起動します。テンプレートファイルを手動で書き換える必要は一切ありません。
有効化後、管理画面のメニュー [設定] ＞ [店舗設定] ＞ [リッチ検索サジェスト設定] から詳細な動作設定を行えます。
4. 管理画面の設定項目一覧
管理画面の [設定] ＞ [店舗設定] ＞ [リッチ検索サジェスト設定] で設定可能な項目です。
4-1. 基本設定
| 設定項目 | 初期値 | 説明 |
|---|---|---|
| プラグイン機能の有効化 | 有効（ON） | フロント画面でのリッチサジェスト機能全体のON/OFFを切り替えます。 |
| 商品表示件数 | 3件 | 2段目の商品プレビューカードに表示する最大件数（1〜10件）を設定します。 |
| キーワード表示件数 | 5件 | 1段目の関連キーワードサジェストに表示する最大件数（1〜10件）を設定します。 |
4-2. 表示項目のカスタマイズ
| 設定項目 | 初期値 | 説明 |
|---|---|---|
| 商品サムネイル画像の表示 | 表示する（ON） | 商品プレビューに正方形のサムネイル画像を表示するかどうかを設定します。 |
| 税込販売価格の表示 | 表示する（ON） | 商品プレビューに税込価格（¥1,480など）を表示するかどうかを設定します。 |
| スマホ全画面モーダル | 有効（ON） | 画面幅768px以下のモバイル環境で、アプリ風の全画面検索オーバーレイを使用するか設定します。 |
4-3. デザイン・ハイライトカラー設定
検索窓に入力した文字と商品名が一致した部分をハイライト表示するカラー（背景色または文字色）をカラーピッカーで直感的に変更できます。
| 設定項目 | 初期値 | 説明 |
|---|---|---|
| キーワード強調色 | #fef08a（ソフトイエロー） |
商品名中の一致テキストを強調する <mark> タグの背景カラーを設定します。 |
5. 表記揺れ自動吸収（インテリジェント変換）
日本語ECサイトにおける検索離脱の最大の原因である「ひらがな・カタカナ・英字入力の不一致」をシステムが自動で吸収します。
| 入力されたキーワード例 | 自動変換・吸収パターン | ヒットする商品名の例 |
|---|---|---|
よーぐると（ひらがな） |
カタカナ変換 ➔ ヨーグルト |
生乳100% プレーンヨーグルト |
yogurt（英単語） |
カタカナ辞書照合 ➔ ヨーグルト |
飲むヨーグルト 500ml |
giri（ローマ字） |
カタカナ音節変換 ➔ ギリ |
濃厚ギリシャヨーグルト |
全角英数 Ｔシャツ |
半角正規化 ➔ Tシャツ |
オーガニックコットン Tシャツ |
mb_convert_kana）と軽量な和英・ローマ字対照変換を組み合わせて処理するため、サーバーのメモリを消費せず数ミリ秒で即座に判定されます。
6. スマートフォン全画面検索オーバーレイ
スマートフォン（画面幅768px以下）では、検索窓をタップした瞬間に「フルスクリーン検索レイヤー」が起動します。
- 広い入力視野： モバイルキーボードが表示されても画面が狭くならず、候補リストが広々と見やすく表示されます。
- 1タップクリアボタン（✕）： 入力欄の右側にクリアボタンが表示され、文字の打ち直しが片手親指で瞬時に行えます。
- 背景スクロール抑止： モーダル展開中は背面ページの不要なスクロールが自動的にロックされ、操作の誤タップを防ぎます。
- 閉じるボタン・戻る対応： 画面右上の [閉じる] ボタンまたは画面外タップでスムーズに元の画面へ戻れます。
7. 高速レスポンス（DQL最適化＆非同期API）
7-1. デバウンス制御（Debounce: 250ms）
キーボードを1文字叩くごとに無駄なAPIリクエストを連打しないよう、入力停止から250ミリ秒経過後に初めてリクエストを発行するデバウンス処理を実装しています。
7-2. 先行リクエストの自動中断（AbortController）
「yo」➔「yog」と素早く打ち込んだ場合、前の「yo」のリクエスト処理がサーバーから返ってくるのを待たずに即時キャンセル（abort()）します。
古い検索結果が後から上書き表示されるレースコンディション（表示のチッカチッカや逆転現象）を完全に排除しています。
7-3. 最適化されたDoctrine DQL
商品テーブル（dtb_product）と規格テーブル（dtb_product_class）を結合し、公開中（ステータス: 公開）かつ削除フラグが立っていないレコードのみをインデックスを活用してピンポイント抽出。商品数1,000件〜10,000件規模の店舗でも20ms台の超高速レスポンスを維持します。
8. よくある質問・トラブルシューティング
Q. 独自にカスタマイズしたデザインテンプレートでも動きますか？
はい、問題なく動作します。本プラグインは input[name="name"] を持つ標準検索入力要素を動的に検知して動作するため、Bootstrap 5や独自CSSでデザインを変更されたテーマでもそのままリッチサジェストが機能します。
Q. 非公開のテスト商品や在庫切れ商品は表示されますか？
非公開ステータスの商品はサジェスト対象から自動的に除外されます。在庫切れ商品については、商品詳細への導線として表示しつつ「品切れ」バッジを表示する仕様となっており、機会損失を防ぎます。
Q. 検索キーワードの入力履歴をユーザーごとに保存できますか？
本バージョンではプライバシー保護および軽量高速化のため、クッキーやDBへの個別履歴蓄積は行わず、ショップ全商品のタイトルおよび検索ワード（search_word）に基づいた予測サジェストに特化しています。
Q. インストール後にサジェストが表示されない場合のチェック項目は？
以下の項目をご確認ください：
- プラグインの有効化： [オーナーズストア] ＞ [プラグイン一覧] でプラグインが「有効」になっているか。
- キャッシュクリア： 管理画面の [コンテンツ管理] ＞ [キャッシュ管理] からキャッシュを削除してブラウザをリロード（Ctrl+F5）してください。
- 設定の有効化： [設定] ＞ [店舗設定] ＞ [リッチ検索サジェスト設定] で「プラグイン機能の有効化」がONになっているか。