用途
commerce-app-eventing 用于为 Adobe Commerce 应用添加或修改事件订阅，覆盖两类事件源：Commerce 原生事件（eventing.commerce）和来自第三方系统（如 ERP、CRM）的外部事件（eventing.external）。它作用于已有的 app.commerce.config.ts，只负责事件扩展域；webhooks、业务配置等其他扩展域由各自技能单独处理。
前置条件
使用前需确认项目已脚手架化并完成初始化，而非仅存在配置文件。需要同时满足：项目根目录存在 app.commerce.config.ts，并且已生成 src/commerce-extensibility-1/ 目录且安装了 node_modules（包含 @adobe/aio-commerce-lib-app 依赖）。若配置缺失，应先调用 commerce-app-init；若配置存在但项目未初始化，要先运行 npx @adobe/aio-commerce-lib-app init（该命令幂等，会找到已有配置、跳过交互提示、安装依赖并生成项目文件）。
只有在项目具备 TypeScript 构建设置（webpack-config.cjs 与根 tsconfig.json）时，动作才能用 TypeScript 编写，否则使用 JavaScript。同时需确保 Developer Console 工作区已订阅 CloudIntegrationSDK（I/O Events）和 commerceeventing（Adobe I/O Events for Adobe Commerce），可通过 aio console workspace api list 查看，缺失时用 aio console workspace api add 重新订阅（该命令会替换订阅列表，需带上现有与缺失的全部服务码）。若 commerceeventing 报“product profile required”，需询问用户 profile 名称并用 --license-config commerceeventing=<profile> 重试。
主要能力与配置规则
配置前需先明确用户意图：配置 Commerce 事件、外部事件还是两者。Commerce 事件名称遵循 plugin.<segments> 或 observer.<segments>，外部事件名称自由格式 [\w\-_.]+。每个事件源需要收集 Provider 标签、描述、可选 key，以及每个事件的名称、标签、描述、处理该事件的运行时动作（格式 <package>/<action>）；仅 Commerce 事件还需指定从事件负载中提取的字段（空数组表示捕获完整负载）和可选的过滤规则，还可选指定事件适用的 Commerce 环境（env）。
校验规则包括：Commerce 事件名以 plugin. 或 observer. 开头、各段匹配 [a-z_]+、最长 180 字符；外部事件名匹配 [\w\-_.]+、最长 180 字符；Provider 标签最长 100 字符，描述最长 255 字符，key 可选且仅限字母数字与连字符、最长 50 字符；事件标签最长 100 字符，描述最长 255 字符；字段名匹配 [a-zA-Z0-9_\-.[\]]+ 或 *；规则操作符为 greaterThan、lessThan、equal、regex、in 或 onChange；运行时动作为 <package>/<action>；事件 env 可选，为非空的 "paas"/"saas" 数组，省略表示所有环境。
使用方式
在 app.commerce.config.ts 中合并写入 eventing.commerce 和/或 eventing.external，保留其他扩展域；若已存在 eventing 键则扩展而非替换。随后为 runtimeActions 引用的事件在 src/actions/ 下创建动作文件，并在 src/commerce-extensibility-1/ext.config.yaml 中注册用户自定义包（名称不可用保留的 app-management），动作函数路径相对 src/commerce-extensibility-1/ 解析。事件处理程序接收 CloudEvents 形状的负载：params.data.value 是事件负载（即 fields 声明的字段或完整负载），params.data._metadata 是 Commerce 实例元数据，params.data.source 是商户/环境 ID 对。
若需从处理程序调用 Commerce REST API，使用 @adobe/aio-commerce-lib-app 的 getCommerceClient，而非自定义 .env 变量或业务配置字段；客户端基础 URL 已包含 REST 前缀与 API 版本，只需传资源路径。
若事件扩展是配置中首个需要安装的扩展域，需重新运行 npx @adobe/aio-commerce-lib-app init 以生成安装动作，否则事件源能构建部署但 Commerce 不会真正订阅。最后运行 aio app build 验证配置。
适用场景
适用于在 Adobe Commerce 应用开发中配置事件驱动扩展、接入第三方系统事件、为事件处理程序补充 Commerce REST API 调用，以及在完成事件配置后继续串联 webhooks、业务配置、Admin UI 扩展或持久化存储等能力。
限制
外部事件不支持 fields 属性，该属性仅对 Commerce 事件有效；runtimeActions 必须为小写字母数字与连字符组成的 <package>/<action>；app-management 包名为框架保留；函数路径不得使用 src/ 或项目根相对路径；runtimeActions 引用的动作必须已存在于项目中；数字外观字段不保证为数字，使用前需校验与转换。