sap-commerce-cloud

SAP Commerce 开发

概述

SAP Commerce Cloud（原名 Hybris）是基于 Java 和 Spring 构建的企业级电子商务平台。本技能提供有关扩展开发、类型系统建模、服务层实现、数据管理、API 定制、Accelerator 模式、Composable Storefront（Spartacus/Angular）集成、CCv2 云部署、SAP BTP/Kyma 集成、SmartEdit 定制，以及适用于 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）——一个 Angular/TypeScript 单页应用，通过 OCC REST API 与后端通信。新项目应使用 Composable Storefront。请参阅 composable-storefront.md。

核心架构

类型系统

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

扩展

采用模块化架构，功能由扩展承载。每个扩展都包含用于元数据的 extensioninfo.xml、用于类型的 items.xml，以及用于 Bean 的 *-spring.xml。请参阅 extension-development.md。

服务层

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

数据管理

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

OCC API

用于公开商务功能的 RESTful Web 服务。控制器使用 DataMapper 转换 DTO。请参阅 occ-api-development.md。

Accelerators（旧版 JSP 店面）

预构建的 JSP/Spring MVC 店面：B2C（零售）和 B2B（含审批工作流的企业级店面）。这是旧版方案——新项目应使用 Composable Storefront 或无头方案。请参阅 accelerator-customization.md。

Composable Storefront（Spartacus）

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

无头商务

将 SAP Commerce Cloud 用作无头后端——由任何前端（React、Vue、移动应用等）调用 OCC API。后端通过 REST 提供产品、目录、购物车、订单和用户数据。Composable Storefront 是 SAP 的参考无头前端，同时也支持自定义前端。

CCv2 云部署

SAP Commerce Cloud v2（CCv2）是托管式云服务。部署由 manifest.json 驱动，用于定义扩展、方面（storefront/api/backoffice）和属性。请参阅 ccv2-deployment.md。

SAP BTP 集成

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

CronJob 与任务引擎

用于计划任务和异步任务执行。定义 AbstractJobPerformable 实现，并通过 ImpEx 配置 ServicelayerJob、CronJob 和 Trigger。参见 cronjob-task-engine.md。

业务流程

用于订单处理、退货、审批和自定义流程的有状态工作流。使用 XML 流程定义，其中包含操作 Bean（AbstractSimpleDecisionAction、AbstractAction）、等待状态和事件触发器。参见 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. 创建 DAO 接口，并使用 FlexibleSearch 实现 DAO
3. 创建 Service 接口和包含业务逻辑的实现
4. 创建用于外部 API 的 Facade 接口和实现
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 转换的 populator
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. 实现 AbstractJobPerformable<CronJobModel>，并编写 perform() 方法
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. 在 Spring 中使用 parent="abstractAction" 注册操作 Bean
4. 通过 ProcessDefinitionResource Spring Bean 注册流程定义
5. 使用 BusinessProcessService.createProcess() 和 startProcess() 启动流程

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

配置 Solr 产品搜索

1. 设置 SolrFacetSearchConfig，包括服务器、语言、货币和目录版本
2. 为 Product 定义 SolrIndexedType
3. 配置 SolrIndexedProperty 条目（可搜索、分面、可排序）
4. 设置索引器 CronJobs（每晚执行完整索引，每 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/

集成可组合店面（Spartacus）

1. 在 Commerce 后端设置 OCC 端点和 CORS
2. 从 SAP 兼容性矩阵中选择可组合店面版本
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. 使用 API Registry 实现基于 webhook 的出站通信

参考：sap-btp-integration.md

为自定义扩展编写测试

1. 为单元测试添加 @UnitTest 注解，为集成测试添加 @IntegrationTest 注解
2. 单元测试：使用 Mockito 模拟对象，不使用 Spring 上下文，放置在 testsrc/ 中
3. 集成测试：继承 ServicelayerTest 或 ServicelayerTransactionalTest
4. OCC API 集成测试：使用 REST Assured 或 MockMvc，对运行中的 OCC 端点进行测试
5. 使用 importCsv("/myext/test/testdata.impex", "utf-8") 加载测试数据
6. 在本地运行：ant unittests -Dtestclasses.extensions=myextension
7. 在 manifest.json 的 "tests" 下配置 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.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 包替换为实际包名，并在投入生产前调整为符合项目特定业务规则的内容。