sap-commerce-cloud

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SAP Commerce Development

SAP Commerce开发

Overview

概述

SAP Commerce Cloud (formerly Hybris) is an enterprise e-commerce platform built on Java and Spring. This skill provides guidance for extension development, type system modeling, service layer implementation, data management, API customization, accelerator patterns, Composable Storefront (Spartacus/Angular) integration, CCv2 cloud deployment, SAP BTP/Kyma integration, SmartEdit customization, and testing patterns for both Cloud (CCv2) and On-Premise deployments.

Modern Storefront Note: The JSP-based Accelerator storefront (Spring Web Flow, JSP/JSTL) is the legacy approach. The modern recommended storefront is Composable Storefront (formerly Spartacus) — an Angular/TypeScript Single Page Application that communicates with the backend exclusively via OCC REST APIs. New projects should use Composable Storefront. See composable-storefront.md.

SAP Commerce Cloud（原Hybris）是基于Java和Spring构建的企业级电商平台。本技能为Cloud（CCv2）和On-Premise部署场景提供扩展开发、类型系统建模、服务层实现、数据管理、API定制、加速器模式、Composable Storefront（Spartacus/Angular）集成、CCv2云部署、SAP BTP/Kyma集成、SmartEdit定制以及测试模式的相关指导。

现代前端说明：基于JSP的Accelerator前端（Spring Web Flow、JSP/JSTL）属于传统方案。当前推荐的现代前端是Composable Storefront（原Spartacus）——一款Angular/TypeScript单页应用，仅通过OCC REST API与后端通信。新项目应采用Composable Storefront。请参阅composable-storefront.md。

Core Architecture

核心架构

Type System

类型系统

Data modeling via

items.xml

defines item types, attributes, relations, and enumerations. Types are compiled into Java classes during build. See type-system.md for syntax and patterns.

通过

items.xml

进行数据建模，定义项目类型、属性、关联关系和枚举类型。类型会在构建过程中编译为Java类。语法和模式请参阅type-system.md。

Extensions

扩展

Modular architecture where functionality lives in extensions. Each extension has

extensioninfo.xml

for metadata,

items.xml

for types, and

*-spring.xml

for beans. See extension-development.md.

采用模块化架构，功能以扩展形式存在。每个扩展包含用于元数据的

extensioninfo.xml

、用于类型定义的

items.xml

以及用于Bean配置的

*-spring.xml

。请参阅extension-development.md。

Service Layer

服务层

Four-layer architecture: Facade (API for controllers) → Service (business logic) → DAO (data access) → Model (generated from types). See service-layer-architecture.md.

四层架构：Facade（控制器的API层）→ Service（业务逻辑层）→ DAO（数据访问层）→ Model（由类型生成）。请参阅service-layer-architecture.md。

Data Management

数据管理

ImpEx: Scripting language for data import/export. See impex-guide.md. FlexibleSearch: SQL-like query language for items. See flexiblesearch-reference.md.

ImpEx：用于数据导入/导出的脚本语言。请参阅impex-guide.md。 FlexibleSearch：面向项目的类SQL查询语言。请参阅flexiblesearch-reference.md。

OCC API

RESTful web services exposing commerce functionality. Controllers use

DataMapper

for DTO conversion. See occ-api-development.md.

暴露电商功能的RESTful Web服务。控制器使用

DataMapper

进行DTO转换。请参阅occ-api-development.md。

Accelerators (Legacy JSP Storefront)

Accelerators（传统JSP前端）

Pre-built JSP/Spring MVC storefronts: B2C (retail) and B2B (enterprise with approval workflows). Legacy approach — new projects should use Composable Storefront or a headless approach. See accelerator-customization.md.

预构建的JSP/Spring MVC前端：B2C（零售）和B2B（带审批流程的企业级）。属于传统方案——新项目应采用Composable Storefront或无头架构。请参阅accelerator-customization.md。

Composable Storefront (Spartacus)

Composable Storefront（Spartacus）

Angular/TypeScript SPA that replaces JSP accelerators. Communicates exclusively via OCC APIs. Supports PWA, SSR, and feature libraries for B2C/B2B. See composable-storefront.md.

替代JSP加速器的Angular/TypeScript单页应用，仅通过OCC API通信。支持PWA、SSR以及面向B2C/B2B的功能库。请参阅composable-storefront.md。

Headless Commerce

无头电商

SAP Commerce Cloud as a headless backend — OCC APIs consumed by any frontend (React, Vue, mobile apps, etc.). The backend serves product, catalog, cart, order, and user data via REST. Composable Storefront is SAP's reference headless frontend, but custom frontends are supported.

SAP Commerce Cloud作为无头后端——OCC API可被任意前端（React、Vue、移动应用等）调用。后端通过REST提供商品、目录、购物车、订单和用户数据。Composable Storefront是SAP官方的参考无头前端，但也支持自定义前端。

CCv2 Cloud Deployment

CCv2云部署

SAP Commerce Cloud v2 (CCv2) is the managed cloud offering. Deployment is driven by

manifest.json

defining extensions, aspects (storefront/api/backoffice), and properties. See ccv2-deployment.md.

SAP Commerce Cloud v2（CCv2）是托管式云服务。部署由

manifest.json

驱动，该文件定义了扩展、组件（storefront/api/backoffice）和属性。请参阅ccv2-deployment.md。

SAP BTP Integration

SAP BTP集成

SAP Business Technology Platform integration via API Registry module and SAP BTP Extensions Integration Module (Kyma runtime). Allows microservices/serverless functions to react to Commerce events. See sap-btp-integration.md.

通过API Registry模块和SAP BTP Extensions Integration Module（Kyma运行时）实现SAP Business Technology Platform集成。允许微服务/无服务器函数响应Commerce事件。请参阅sap-btp-integration.md。

CronJobs & Task Engine

CronJobs & 任务引擎

Scheduled and asynchronous job execution. Define

AbstractJobPerformable

implementations, configure via

ServicelayerJob

CronJob

Trigger

in ImpEx. See cronjob-task-engine.md.

定时和异步任务执行。定义

AbstractJobPerformable

实现，通过ImpEx配置

ServicelayerJob

CronJob

Trigger

。请参阅cronjob-task-engine.md。

Business Processes

业务流程

Stateful workflows for order processing, returns, approvals, and custom flows. XML process definitions with action beans (

AbstractSimpleDecisionAction

AbstractAction

), wait states, and event triggers. See business-process.md.

用于订单处理、退货、审批和自定义流程的有状态工作流。包含动作Bean（

AbstractSimpleDecisionAction

、

AbstractAction

）、等待状态和事件触发器的XML流程定义。请参阅business-process.md。

Solr Search

Solr搜索

Product search and faceted navigation powered by Apache Solr. Configure indexed types, properties, value providers, and boost rules. See solr-search-configuration.md.

基于Apache Solr的商品搜索和分面导航。配置索引类型、属性、值提供器和权重规则。请参阅solr-search-configuration.md。

Promotions & Rule Engine

促销活动 & 规则引擎

Drools-based promotion rules with conditions and actions. Supports order/product/customer promotions, coupons, and custom actions. See promotions-rule-engine.md.

基于Drools的促销规则，包含条件和动作。支持订单/商品/客户促销、优惠券和自定义动作。请参阅promotions-rule-engine.md。

Caching

缓存

Multi-layered caching: platform region caches (entity, query, typesystem), Spring

@Cacheable

, and cluster-aware invalidation. See caching-guide.md.

多层缓存：平台区域缓存（实体、查询、类型系统）、Spring

@Cacheable

以及集群感知失效机制。请参阅caching-guide.md。

Backoffice

Administration UI customization via cockpitng: widget configuration, custom editors, search/list views, wizards, and deep links. See backoffice-configuration.md.

通过cockpitng定制管理UI：组件配置、自定义编辑器、搜索/列表视图、向导和深度链接。请参阅backoffice-configuration.md。

Common Workflows

常见工作流

Create a Custom Extension

创建自定义扩展

Generate structure with
```
ant extgen
```
or use template from
```
assets/extension-structure/
```
Configure
```
extensioninfo.xml
```
with dependencies
Define types in
```
items.xml
```
Configure beans in
```
*-spring.xml
```
Add to
```
localextensions.xml
```
Build:
```
ant clean all
```

Reference: extension-development.md | Template:

assets/extension-structure/

使用
```
ant extgen
```
生成结构，或使用
```
assets/extension-structure/
```
中的模板
在
```
extensioninfo.xml
```
中配置依赖
在
```
items.xml
```
中定义类型
在
```
*-spring.xml
```
中配置Bean
添加到
```
localextensions.xml
```
构建：
```
ant clean all
```

参考：extension-development.md | 模板：

assets/extension-structure/

Define Custom Item Types

定义自定义项目类型

Create or modify
```
*-items.xml
```
in extension
Define itemtype with attributes, relations
Build to generate model classes
Use in services/DAOs

Reference: type-system.md | Templates:

assets/item-type-definition/

在扩展中创建或修改
```
*-items.xml
```
定义包含属性、关联关系的itemtype
构建以生成模型类
在服务/DAO中使用

参考：type-system.md | 模板：

assets/item-type-definition/

Implement Service Layer

实现服务层

Create DTO class for data transfer
Create DAO interface and implementation with FlexibleSearch
Create Service interface and implementation with business logic
Create Facade interface and implementation for external API
Configure beans in
```
*-spring.xml
```

Reference: service-layer-architecture.md | Templates:

assets/service-layer/

创建用于数据传输的DTO类
创建带FlexibleSearch的DAO接口和实现
创建带业务逻辑的Service接口和实现
创建用于外部API的Facade接口和实现
在
```
*-spring.xml
```
中配置Bean

参考：service-layer-architecture.md | 模板：

assets/service-layer/

Import Data with ImpEx

使用ImpEx导入数据

Create
```
.impex
```
file with header and data rows
Use INSERT_UPDATE for create/modify operations
Define macros for reusable values
Import via HAC or
```
ant importImpex
```

Reference: impex-guide.md | Templates:

assets/impex-scripts/

创建包含表头和数据行的
```
.impex
```
文件
使用INSERT_UPDATE进行创建/修改操作
定义可重用值的宏
通过HAC或
```
ant importImpex
```
导入

参考：impex-guide.md | 模板：

assets/impex-scripts/

Query with FlexibleSearch

使用FlexibleSearch查询

sql

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

Reference: flexiblesearch-reference.md | Examples:

assets/flexiblesearch-queries/

sql

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/

Customize OCC API

定制OCC API

Create controller with
```
@Controller
```
and
```
@RequestMapping
```
Create WsDTO for response data
Create populator for model-to-DTO conversion
Register in
```
*-web-spring.xml
```

Reference: occ-api-development.md | Templates:

assets/occ-customization/

创建带
```
@Controller
```
和
```
@RequestMapping
```
的控制器
创建用于响应数据的WsDTO
创建用于模型转DTO的populator
在
```
*-web-spring.xml
```
中注册

参考：occ-api-development.md | 模板：

assets/occ-customization/

Extend Accelerator Checkout

扩展Accelerator结账流程

Create custom checkout step implementing
```
CheckoutStep
```
Configure in checkout flow XML
Create JSP for step UI
Register beans in
```
*-spring.xml
```

Reference: accelerator-customization.md | Templates:

assets/checkout-customization/

创建实现
```
CheckoutStep
```
的自定义结账步骤
在结账流程XML中配置
为步骤UI创建JSP
在
```
*-spring.xml
```
中注册Bean

参考：accelerator-customization.md | 模板：

assets/checkout-customization/

Create a Scheduled Job (CronJob)

创建定时任务（CronJob）

Implement

AbstractJobPerformable<CronJobModel>

with

perform()

method

Register Spring bean with
```
parent="abstractJobPerformable"
```
Create
```
ServicelayerJob
```
,
```
CronJob
```
, and
```
Trigger
```
via ImpEx
Test via HAC > Platform > CronJobs

Reference: cronjob-task-engine.md | Templates:

assets/cronjob/

实现带

perform()

方法的

AbstractJobPerformable<CronJobModel>

注册继承
```
parent="abstractJobPerformable"
```
的Spring Bean
通过ImpEx创建
```
ServicelayerJob
```
、
```
CronJob
```
和
```
Trigger
```
通过HAC > Platform > CronJobs测试

参考：cronjob-task-engine.md | 模板：

assets/cronjob/

Define a Business Process

定义业务流程

Create process definition XML in
```
resources/processes/
```
Implement action beans extending
```
AbstractSimpleDecisionAction
```
Register action beans in Spring with
```
parent="abstractAction"
```
Register process definition via
```
ProcessDefinitionResource
```
Spring bean

Start process via

BusinessProcessService.createProcess()

and

startProcess()

Reference: business-process.md | Templates:

assets/business-process/

在
```
resources/processes/
```
中创建流程定义XML
实现继承
```
AbstractSimpleDecisionAction
```
的动作Bean
注册继承
```
parent="abstractAction"
```
的动作Bean到Spring
通过
```
ProcessDefinitionResource
```
Spring Bean注册流程定义

通过

BusinessProcessService.createProcess()

和

startProcess()

启动流程

参考：business-process.md | 模板：

assets/business-process/

Configure Solr Product Search

配置Solr商品搜索

Set up
```
SolrFacetSearchConfig
```
with server, languages, currencies, catalog versions
Define
```
SolrIndexedType
```
for Product
Configure
```
SolrIndexedProperty
```
entries (searchable, facet, sortable)
Set up indexer CronJobs (full nightly, incremental every 5 min)
Test search via HAC > Platform > Solr

Reference: solr-search-configuration.md | Templates:

assets/solr-configuration/

设置包含服务器、语言、货币、目录版本的
```
SolrFacetSearchConfig
```
为Product定义
```
SolrIndexedType
```
配置
```
SolrIndexedProperty
```
条目（可搜索、分面、可排序）
设置索引器CronJobs（夜间全量索引，每5分钟增量索引）
通过HAC > Platform > Solr测试搜索

参考：solr-search-configuration.md | 模板：

assets/solr-configuration/

Set Up Promotions

设置促销活动

Create
```
PromotionGroup
```
for your store
Define
```
PromotionSourceRule
```
with conditions and actions
Configure coupons (
```
SingleCodeCoupon
```
/
```
MultiCodeCoupon
```
) if needed
Publish rules to activate them
Test in Backoffice > Marketing > Promotion Rules

Reference: promotions-rule-engine.md | Templates:

assets/promotions/

为店铺创建
```
PromotionGroup
```
定义包含条件和动作的
```
PromotionSourceRule
```
按需配置优惠券（
```
SingleCodeCoupon
```
/
```
MultiCodeCoupon
```
）
发布规则以激活
在Backoffice > Marketing > Promotion Rules中测试

参考：promotions-rule-engine.md | 模板：

assets/promotions/

Integrate Composable Storefront (Spartacus)

集成Composable Storefront（Spartacus）

Set up OCC endpoints and CORS on the Commerce backend

Scaffold Angular app:

ng add @spartacus/schematics@latest --base-url <OCC_URL> --base-site=<SITE_ID> --ssr

Configure

SpartacusConfigurationModule

with

provideConfig

Customize CMS components via
```
cmsComponents
```
mapping in
```
provideConfig
```
Override services by providing custom service classes in feature modules

Reference: composable-storefront.md | Templates:

assets/composable-storefront/

在Commerce后端设置OCC端点和CORS

搭建Angular应用：

ng add @spartacus/schematics@latest --base-url <OCC_URL> --base-site=<SITE_ID> --ssr

使用

provideConfig

配置

SpartacusConfigurationModule

通过
```
provideConfig
```
中的
```
cmsComponents
```
映射定制CMS组件
在功能模块中提供自定义服务类以覆盖原有服务

参考：composable-storefront.md | 模板：

assets/composable-storefront/

Deploy to CCv2

部署到CCv2

Configure

manifest.json

at repository root with

commerceSuiteVersion

extensions

aspects

Set environment properties in CCv2 Cloud Portal or property files
Push to connected repository to trigger build
Promote build through environments (dev → staging → production)

Reference: ccv2-deployment.md

在仓库根目录配置

manifest.json

，包含

commerceSuiteVersion

、

extensions

、

aspects

在CCv2云门户或属性文件中设置环境属性
推送至关联仓库触发构建
在环境间推广构建版本（开发 → 预发布 → 生产）

参考：ccv2-deployment.md

Integrate SAP BTP / Kyma

集成SAP BTP / Kyma

Configure API Registry module to expose Commerce APIs and events
Connect Kyma runtime via SAP BTP Extensions Integration Module
Implement microservices/lambdas to react to Commerce events
Use API Registry for webhook-based outbound communication

Reference: sap-btp-integration.md

配置API Registry模块以暴露Commerce API和事件
通过SAP BTP Extensions Integration Module连接Kyma运行时
实现微服务/Lambda以响应Commerce事件
使用API Registry实现基于Webhook的出站通信

参考：sap-btp-integration.md

Write Tests for Custom Extension

为自定义扩展编写测试

Annotate unit tests with
```
@UnitTest
```
, integration tests with
```
@IntegrationTest
```
Unit tests: use Mockito mocks, no Spring context, place in
```
testsrc/
```

Integration tests: extend

ServicelayerTest

ServicelayerTransactionalTest

OCC API integration tests: use REST Assured or MockMvc against a running OCC endpoint

Load test data via

importCsv("/myext/test/testdata.impex", "utf-8")

Run locally:

ant unittests -Dtestclasses.extensions=myextension

Configure CCv2 test run in
```
manifest.json
```
under
```
"tests"
```

Reference: testing-guide.md

单元测试标注
```
@UnitTest
```
，集成测试标注
```
@IntegrationTest
```
单元测试：使用Mockito模拟，无需Spring上下文，放置在
```
testsrc/
```

集成测试：继承

ServicelayerTest

或

ServicelayerTransactionalTest

OCC API集成测试：针对运行中的OCC端点使用REST Assured或MockMvc

通过

importCsv("/myext/test/testdata.impex", "utf-8")

加载测试数据

本地运行：

ant unittests -Dtestclasses.extensions=myextension

在
```
manifest.json
```
的
```
"tests"
```
下配置CCv2测试运行

参考：testing-guide.md

Quick Reference

快速参考

Task	Reference	Assets	Script
Extension setup	extension-development.md	`assets/extension-structure/`	`scripts/generate-extension.sh`
Type definitions	type-system.md	`assets/item-type-definition/`	-
Service layer	service-layer-architecture.md	`assets/service-layer/`	-
Data import	impex-guide.md	`assets/impex-scripts/`	`scripts/validate-impex.sh`
Queries	flexiblesearch-reference.md	`assets/flexiblesearch-queries/`	`scripts/query-items.sh`
API customization	occ-api-development.md	`assets/occ-customization/`	-
Checkout/Storefront (legacy)	accelerator-customization.md	`assets/checkout-customization/`	-
Composable Storefront	composable-storefront.md	`assets/composable-storefront/`	-
CCv2 deployment	ccv2-deployment.md	-	-
SAP BTP/Kyma	sap-btp-integration.md	-	-
Testing	testing-guide.md	-	-
Spring config	spring-configuration.md	-	-
Data patterns	data-modeling-patterns.md	-	-
Troubleshooting	troubleshooting-guide.md	-	-
CronJobs	cronjob-task-engine.md	`assets/cronjob/`	-
Business processes	business-process.md	`assets/business-process/`	-
Solr search	solr-search-configuration.md	`assets/solr-configuration/`	-
Promotions	promotions-rule-engine.md	`assets/promotions/`	-
Caching	caching-guide.md	-	-
Backoffice	backoffice-configuration.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	-	-
测试	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	-	-

Resources

资源

scripts/

Utility scripts for common tasks:

```
generate-extension.sh
```
- Scaffold new extension structure
```
validate-impex.sh
```
- Validate ImpEx syntax before import
```
query-items.sh
```
- Execute FlexibleSearch queries via HAC

用于常见任务的实用脚本：

```
generate-extension.sh
```
- 生成新扩展结构
```
validate-impex.sh
```
- 导入前验证ImpEx语法
```
query-items.sh
```
- 通过HAC执行FlexibleSearch查询

references/

Detailed guides for each topic area. Load as needed for in-depth information.

各主题领域的详细指南。按需加载以获取深入信息。

assets/

Production-quality code templates ready to copy and customize. Organized by domain (service-layer, impex-scripts, etc.).

可直接复制并定制的生产级代码模板。按领域（服务层、ImpEx脚本等）组织。