sap-commerce-cloud

SAP Commerce の開発

概要

SAP Commerce Cloud（旧称 Hybris）は、Java と Spring を基盤とするエンタープライズ向け e コマースプラットフォームです。このスキルでは、拡張機能の開発、型システムのモデル化、サービスレイヤーの実装、データ管理、API のカスタマイズ、アクセラレーターパターン、Composable Storefront（Spartacus/Angular）との統合、CCv2 クラウドへのデプロイ、SAP BTP/Kyma との統合、Cloud（CCv2）とオンプレミス両方のデプロイメント向けのテストパターンについて解説します。

プラットフォームのベースライン： 例では SAP Commerce Cloud 2211-jdk21.1 以降を対象とし、JDK 21、Spring 6、Jakarta API、OpenAPI 3 を使用します。CCv2 では commerceSuiteVersion: "2211-jdk21" を使用すると、この系列の最新アップデートに準拠できます。jdk21-migration.md を参照してください。

最新のストアフロントに関する注意： JSP ベースの Accelerator ストアフロント（Spring Web Flow、JSP/JSTL）は従来の方式です。推奨される最新のストアフロントは Composable Storefront（旧称 Spartacus）です。これは、バックエンドと OCC REST API のみで通信する Angular/TypeScript のシングルページアプリケーションです。新しいプロジェクトでは Composable Storefront を使用してください。composable-storefront.md を参照してください。

コアアーキテクチャ

型システム

items.xml を使用したデータモデリングによって、アイテムタイプ、属性、リレーション、列挙型を定義します。ビルド時に型が Java クラスにコンパイルされます。構文とパターンについては、type-system.md を参照してください。

拡張機能

機能を拡張機能に配置するモジュール型アーキテクチャです。各拡張機能には、メタデータを定義する extensioninfo.xml、型を定義する items.xml、Bean を定義する *-spring.xml があります。extension-development.md を参照してください。

サービスレイヤー

4 層アーキテクチャです：ファサード（コントローラー向け API）→ サービス（ビジネスロジック）→ DAO（データアクセス）→ モデル（型から生成）。service-layer-architecture.md を参照してください。

データ管理

ImpEx：データのインポート／エクスポートに使用するスクリプト言語です。impex-guide.md を参照してください。 FlexibleSearch：アイテム向けの SQL ライクなクエリ言語です。flexiblesearch-reference.md を参照してください。

OCC API

コマース機能を公開する RESTful Web サービスです。コントローラーは DTO 変換に DataMapper を使用します。occ-api-development.md を参照してください。

アクセラレーター（従来型 JSP ストアフロント）

構築済みの JSP/Spring MVC ストアフロントです。B2C（小売）と B2B（承認ワークフローを備えたエンタープライズ向け）があります。従来の方式であり、新しいプロジェクトでは Composable Storefront またはヘッドレス方式を使用してください。accelerator-customization.md を参照してください。

Composable Storefront（Spartacus）

JSP アクセラレーターに代わる Angular/TypeScript の SPA です。OCC API のみで通信します。B2C/B2B 向けの PWA、SSR、機能ライブラリーをサポートしています。composable-storefront.md を参照してください。

ヘッドレスコマース

SAP Commerce Cloud をヘッドレスバックエンドとして使用し、OCC API をあらゆるフロントエンド（React、Vue、モバイルアプリなど）から利用できます。バックエンドは、商品、カタログ、カート、注文、ユーザーのデータを REST 経由で提供します。Composable Storefront は SAP が提供するリファレンス用のヘッドレスフロントエンドですが、カスタムフロントエンドもサポートされています。

CCv2 クラウドへのデプロイ

SAP Commerce Cloud v2（CCv2）はマネージドクラウドサービスです。拡張機能、アスペクト（storefront/api/backoffice）、プロパティを定義する manifest.json に基づいてデプロイします。ccv2-deployment.md を参照してください。

SAP BTP との統合

API Registry モジュールと SAP BTP Extensions Integration Module（Kyma ランタイム）を介して SAP Business Technology Platform と統合します。マイクロサービス／サーバーレス関数で Commerce のイベントに対応できます。sap-btp-integration.md を参照してください。

CronJobs とタスクエンジン

スケジュール実行および非同期のジョブ実行です。AbstractJobPerformable の実装を定義し、ImpEx で ServicelayerJob、CronJob、Trigger を設定します。cronjob-task-engine.md を参照してください。

ビジネスプロセス

注文処理、返品、承認、カスタムフロー向けのステートフルなワークフローです。アクション Bean（AbstractSimpleDecisionAction、AbstractAction）、待機状態、イベントトリガーを含む XML プロセス定義を使用します。business-process.md を参照してください。

Solr 検索

Apache Solr を利用した商品検索とファセットナビゲーションです。インデックス対象タイプ、プロパティ、値プロバイダー、ブーストルールを設定します。solr-search-configuration.md を参照してください。

プロモーションとルールエンジン

条件とアクションを使用する、Drools ベースのプロモーションルールです。注文、商品、顧客向けのプロモーション、クーポン、カスタムアクションに対応しています。promotions-rule-engine.md を参照してください。

キャッシュ

プラットフォームのリージョンキャッシュ（エンティティ、クエリ、型システム）、Spring の @Cacheable、クラスター対応の無効化による多層キャッシュです。caching-guide.md を参照してください。

Backoffice

cockpitng による管理 UI のカスタマイズです。ウィジェット設定、カスタムエディター、検索／リストビュー、ウィザード、ディープリンクを扱います。backoffice-configuration.md を参照してください。

一般的なワークフロー

カスタム拡張機能の作成

1. ant extgen で構造を生成するか、assets/extension-structure/ のテンプレートを使用します
2. 依存関係を指定して extensioninfo.xml を設定します
3. items.xml で型を定義します
4. *-spring.xml で Bean を設定します
5. localextensions.xml に追加します
6. ビルドします：ant clean all

参考資料：extension-development.md | テンプレート：assets/extension-structure/

カスタムアイテムタイプの定義

1. 拡張機能内の *-items.xml を作成または変更します
2. 属性とリレーションを含む itemtype を定義します
3. ビルドしてモデルクラスを生成します
4. サービス／DAO で使用します

参考資料：type-system.md | テンプレート：assets/item-type-definition/

サービスレイヤーの実装

1. データ転送用の DTO クラスを作成します
2. FlexibleSearch を使用して DAO のインターフェースと実装を作成します
3. ビジネスロジックを含むサービスのインターフェースと実装を作成します
4. 外部 API 用のファサードのインターフェースと実装を作成します
5. *-spring.xml で Bean を設定します

参考資料：service-layer-architecture.md | テンプレート：assets/service-layer/

ImpEx によるデータのインポート

1. ヘッダーとデータ行を含む .impex ファイルを作成します
2. 作成／変更操作には INSERT_UPDATE を使用します
3. 再利用可能な値にはマクロを定義します
4. HAC または ant importImpex でインポートします

参考資料：impex-guide.md | テンプレート：assets/impex-scripts/

FlexibleSearch によるクエリ

SELECT {pk} FROM {Product} WHERE {code} = ?code
SELECT {p.pk} FROM {Product AS p JOIN Category AS c ON {p.supercategories} = {c.pk}} WHERE {c.code} = ?category

参考資料：flexiblesearch-reference.md | 例：assets/flexiblesearch-queries/

OCC API のカスタマイズ

1. @Controller と @RequestMapping を使用してコントローラーを作成します
2. レスポンスデータ用の WsDTO を作成します
3. モデルから DTO への変換用のポピュレーターを作成します
4. *-web-spring.xml に登録します

参考資料：occ-api-development.md | テンプレート：assets/occ-customization/

Accelerator チェックアウトの拡張

1. CheckoutStep を実装するカスタムチェックアウトステップを作成します
2. チェックアウトフロー XML で設定します
3. ステップ UI 用の JSP を作成します
4. *-spring.xml に Bean を登録します

参考資料：accelerator-customization.md | テンプレート：assets/checkout-customization/

スケジュール済みジョブ（CronJob）を作成する

1. perform() メソッドを実装した AbstractJobPerformable<CronJobModel> を実装します
2. parent="abstractJobPerformable" を指定して Spring Bean を登録します
3. ImpEx で ServicelayerJob、CronJob、Trigger を作成します
4. HAC > Platform > CronJobs でテストします

参考：cronjob-task-engine.md | テンプレート：assets/cronjob/

ビジネスプロセスを定義する

1. resources/processes/ にプロセス定義 XML を作成します
2. AbstractSimpleDecisionAction を継承するアクション Bean を実装します
3. parent="abstractAction" を指定して Spring にアクション Bean を登録します
4. ProcessDefinitionResource Spring Bean を使ってプロセス定義を登録します
5. BusinessProcessService.createProcess() と startProcess() を使ってプロセスを開始します

参考：business-process.md | テンプレート：assets/business-process/

Solr の商品検索を設定する

1. サーバー、言語、通貨、カタログバージョンを指定して SolrFacetSearchConfig を設定します
2. 商品用の SolrIndexedType を定義します
3. SolrIndexedProperty エントリー（検索可能、ファセット、ソート可能）を設定します
4. インデクサー CronJob（毎晩の全件実行、5 分ごとの差分実行）を設定します
5. HAC > Platform > Solr で検索をテストします

参考：solr-search-configuration.md | テンプレート：assets/solr-configuration/

プロモーションを設定する

1. ストア用の PromotionGroup を作成します
2. 条件とアクションを含む PromotionSourceRule を定義します
3. 必要に応じてクーポン（SingleCodeCoupon / MultiCodeCoupon）を設定します
4. ルールを公開して有効化します
5. Backoffice > Marketing > Promotion Rules でテストします

参考：promotions-rule-engine.md | テンプレート：assets/promotions/

Composable Storefront（Spartacus）を統合する

1. Commerce バックエンドで OCC エンドポイントと CORS を設定します
2. SAP の互換性マトリックスから Composable Storefront のバージョンを選択します
3. Angular アプリをスキャフォールドします：ng add @spartacus/schematics@<COMPATIBLE_VERSION> --base-url <OCC_URL> --base-site=<SITE_ID> --ssr
4. provideConfig を使って SpartacusConfigurationModule を設定します
5. provideConfig の cmsComponents マッピングを使って CMS コンポーネントをカスタマイズします
6. 機能モジュールでカスタムサービスクラスを提供してサービスをオーバーライドします

参考：composable-storefront.md | テンプレート：assets/composable-storefront/

CCv2 にデプロイする

1. リポジトリのルートにある manifest.json で commerceSuiteVersion、extensions、aspects を設定します
2. CCv2 Cloud Portal またはプロパティファイルで環境プロパティを設定します
3. 接続済みのリポジトリにプッシュしてビルドを開始します
4. 環境間でビルドを昇格します（dev → staging → production）

参考：ccv2-deployment.md

SAP BTP / Kyma を統合する

1. API Registry モジュールを設定して Commerce の API とイベントを公開します
2. SAP BTP Extensions Integration Module を介して Kyma ランタイムに接続します
3. Commerce イベントに応答するマイクロサービス／ラムダを実装します
4. Webhook ベースのアウトバウンド通信に API Registry を使用します

参考：sap-btp-integration.md

カスタム拡張機能のテストを作成する

1. 単体テストには @UnitTest、統合テストには @IntegrationTest を付けます
2. 単体テストでは Mockito モックを使用し、Spring コンテキストは使わず、testsrc/ に配置します
3. 統合テストでは ServicelayerTest または ServicelayerTransactionalTest を継承します
4. OCC API 統合テストでは、稼働中の OCC エンドポイントに対して REST Assured または MockMvc を使用します
5. importCsv("/myext/test/testdata.impex", "utf-8") でテストデータを読み込みます
6. ローカルで実行します：ant unittests -Dtestclasses.extensions=myextension
7. "tests" の下にある manifest.json で CCv2 のテスト実行を設定します

参考：testing-guide.md

クイックリファレンス

タスク	リファレンス	アセット	スクリプト
拡張機能のセットアップ	extension-development.md	assets/extension-structure/	scripts/generate-extension.sh
型定義	type-system.md	assets/item-type-definition/	-
サービスレイヤー	service-layer-architecture.md	assets/service-layer/	-
データインポート	impex-guide.md	assets/impex-scripts/	scripts/validate-impex.sh
クエリ	flexiblesearch-reference.md	assets/flexiblesearch-queries/	scripts/query-items.sh
API のカスタマイズ	occ-api-development.md	assets/occ-customization/	-
チェックアウト／ストアフロント（レガシー）	accelerator-customization.md	assets/checkout-customization/	-
Composable Storefront	composable-storefront.md	assets/composable-storefront/	-
CCv2 のデプロイ	ccv2-deployment.md	-	-
SAP BTP／Kyma	sap-btp-integration.md	-	-
JDK 21 への移行	jdk21-migration.md	-	-
テスト	testing-guide.md	-	-
Spring の設定	spring-configuration.md	-	-
データパターン	data-modeling-patterns.md	-	-
トラブルシューティング	troubleshooting-guide.md	-	-
CronJobs	cronjob-task-engine.md	assets/cronjob/	-
ビジネスプロセス	business-process.md	assets/business-process/	-
Solr 検索	solr-search-configuration.md	assets/solr-configuration/	-
プロモーション	promotions-rule-engine.md	assets/promotions/	-
キャッシュ	caching-guide.md	-	-
Backoffice	backoffice-configuration.md	-	-

リソース

scripts/

一般的なタスクに使用するユーティリティスクリプト：

• generate-extension.sh - 新しい拡張機能の構成をひな形から作成します
• validate-impex.sh - インポート前に ImpEx の構文を検証します
• query-items.sh - HAC 経由で FlexibleSearch クエリを実行します

references/

各トピックの詳細ガイドです。詳しい情報が必要な場合に読み込んでください。

assets/

分野ごとに整理された、特定用途向けのリファレンステンプレートです。タスクに関連するファイルのみをコピーし、com.example パッケージを置き換え、本番環境で使用する前にプロジェクト固有のビジネスルールに合わせて調整してください。