enonic-guillotine-query-builder

Enonic Guillotine クエリビルダー

手順

ステップ 1：ワークスペース内で既存の Guillotine の使用箇所をスキャンする

1. node scripts/find-guillotine-targets.mjs . を実行して、Guillotine のマーカー（クエリ文字列、ライブラリーのインポート、エンドポイント参照）が含まれるファイルを一覧表示します。
2. Node ランタイムを利用できない場合は、.ts、.js、.graphql、.gql ファイル内の guillotine、queryDsl、queryDslConnection、/lib/guillotine を手動で検索します。
3. 使用中の Guillotine のバージョンを確認します。query(query: "...") 形式の文字列ベースのフィールドが見つかった場合、プロジェクトでは非推奨の 5.x スタイルの API が使用されています。queryDsl / queryDslConnection が見つかった場合は、6.x 以降の DSL が使用されています。Guillotine 7 Extensions API の使用を検出するには、guillotine/guillotine.js 内の exports.extensions を確認します。
4. 両方のスタイルが混在している場合は、非推奨の使用箇所を移行対象として示します。

ステップ 2：Guillotine API リファレンスを読み込む

1. クエリを作成する前に、references/guillotine-reference.md を読みます。
2. ワークスペースが Guillotine のバージョンを対象とする場合、またはバージョン間の移行を行う場合は、references/compatibility.md を読みます。

ステップ 3：クエリの形式を決定する

1. ユーザーが必要としている操作を特定します。
   • 単一コンテンツの取得：get(key) を使用します。
   • 直接の子コンテンツ：getChildren(key) を使用します。ページネーションには getChildrenConnection(key) を使用します。
   • フィルター付き検索：フラットなリストには queryDsl(query) を、ページネーション、集計、またはハイライトには queryDslConnection(query) を使用します。
   • コンテンツタイプのメタデータ：getType(name) または getTypes を使用します。
2. ページネーションが必要な場合は、Connection 版（queryDslConnection、getChildrenConnection）を優先し、呼び出し元に after / first を渡すよう案内します。
3. 集計またはハイライトが必要な場合は、queryDslConnection を必須とします。これらの機能は queryDsl では利用できません。

ステップ 4：コンテンツタイプのフラグメントを作成する

1. コンテンツタイプ記述子から GraphQL タイプ名を導き出します。ドット（.）とコロン（:）をアンダースコア（_）に置き換え、ハイフン（-）を削除して、その次の文字を大文字にします。コロンの後の各セグメントの先頭文字は大文字にします。例：com.enonic.app.myapp:BlogPost → com_enonic_app_myapp_BlogPost。組み込みタイプの場合：portal:template-folder → portal_TemplateFolder。
2. インラインフラグメントを使用して、タイプ固有の data フィールドにアクセスします：... on <GraphQLTypeName> { data { ... } }。
3. コンテンツ参照（ContentSelector、ImageSelector、MediaSelector）では、参照先のタイプに対するネストされたインラインフラグメントを使って参照をたどります。
4. RichText / HtmlArea フィールドには、processedHtml と、必要に応じて links、images、macros サブフィールドを含めます。絶対 URL、srcset の幅（imageWidths）、またはレスポンシブサイズ（imageSizes）には、processHtml 入力引数を使用します。

ステップ 5：クエリのフィルターとソートを作成する

1. Query DSL 入力タイプを使用します。各 QueryDSLInput に含める式フィールドは必ず 1 つにします。
2. 複数の条件を組み合わせるには、must、should、mustNot、filter 配列を含む boolean を使用します。
3. 日付または数値の範囲には、gt / gte / lt / lte と、適切な DSLExpressionValueInput タイプ（localDate、localDateTime、instant、long、double）を指定した range 式を使用します。
4. ソートには、field と direction（ASC / DESC）を指定した SortDslInput を使用します。
5. クエリパターンが文書化された例に該当する場合は、references/examples.md を読みます。

ステップ 6：必要に応じて集計とハイライトを追加する

1. queryDslConnection に AggregationInput オブジェクトの配列として aggregations を渡します。
2. 各集計には、一意の name と、集計タイプのフィールド（terms、dateRange、stats など）が 1 つだけ必要です。
3. ハイライトする各フィールドの propertyName を指定した properties 配列とともに、highlight を渡します。
4. 接続結果の aggregationsAsJson と highlightAsJson から集計結果とハイライト結果を読み取ります。 ステップ 7：TypeScript 型を生成する（必要な場合）
5. assets/guillotine-query.template.ts を開始テンプレートとして読み込みます。
6. __APP_KEY__、__CONTENT_TYPE__、__GRAPHQL_TYPE__、__FIELDS__ のプレースホルダーを、実際のコンテンツタイプの値に置き換えます。
7. クエリで要求されているコンテンツタイプのスキーマフィールドに合わせて、Data インターフェースに型付きフィールドを追加します。
8. コネクションクエリでは、特定のコンテンツタイプを指定した ContentConnection<T> ジェネリックを使用します。

ステップ 8：サイトコンテキストを設定する（該当する場合）

1. クエリが特定のサイトを対象とする場合は、guillotine フィールドに siteKey を設定するか、呼び出し元に X-Guillotine-SiteKey HTTP ヘッダーを設定するよう指示します。
2. サイト相対クエリのパス引数では ${site} プレースホルダーを使用します。
3. サイト相対パスを返すには _path(type: siteRelative) を使用します。

ステップ 9：クエリを検証する

1. すべてのインラインフラグメント型名で、元の記述子形式ではなくアンダースコアが使用されていることを確認します。
2. 非推奨の query / queryConnection ではなく、queryDsl / queryDslConnection が使用されていることを確認します。
3. QueryDSLInput オブジェクトに式フィールドが 1 つだけ含まれていることを確認します。
4. DSLExpressionValueInput オブジェクトに値型フィールドが 1 つだけ含まれていることを確認します。
5. 集計とハイライトがコネクション版でのみ使用されていることを確認します。
6. Guillotine 7+ のプロジェクトでは、pageUrl / mediaUrl / imageUrl / attachmentUrl の params 引数に String ではなく Json 型が使用されていることを確認します。
7. クエリで予期しない null、空の結果、型エラーが返された場合は、references/troubleshooting.md を読みます。

エラー処理

• get が null を返す場合は、そのキーが有効なコンテンツパスまたは ID であること、また正しいブランチ（draft または master）が対象になっていることを確認します。
• インラインフラグメントのフィールドが null の場合は、GraphQL 型名にアンダースコアが使用され、コンテンツタイプの記述子と完全に一致していることを確認します。
• queryDsl が空の結果を返す場合は、データの存在を確認するために matchAll: {} に簡略化してから、フィルターを 1 つずつ再追加します。
• 集計またはハイライトの結果が null の場合は、クエリで queryDsl ではなく queryDslConnection が使用されていることを確認します。
• 非推奨の query フィールドが使用されている場合は、references/compatibility.md を読み、DSL 構文を使う queryDsl に移行します。
• scripts/find-guillotine-targets.mjs を実行できない場合は、ワークスペース内で Guillotine のマーカーを手動で検索し、作業を続けます。