commerce-app-business-config

配置 Commerce App 业务配置

在现有的 app.commerce.config.ts 中添加或修改 businessConfig.schema 数组。 数组中的每个条目都定义一项商家可配置的设置，Commerce Admin 会将其呈现为 UI 字段。 其他可扩展性领域（webhooks、events）需通过各自的技能单独添加。

前提条件

• 确认应用已完成脚手架搭建并初始化，不能仅凭配置文件存在就判断。以下两项都必须满足：
  • 项目根目录中存在 app.commerce.config.ts，并且
  • 项目已初始化 — 可通过生成的 src/commerce-extensibility-1/ 目录和已安装的 node_modules（@adobe/aio-commerce-lib-app 依赖项）确认。
• 如果缺少 app.commerce.config.ts，请停止并先调用 commerce-app-init（它会写入配置，然后运行初始化）。
• 如果配置文件存在，但项目尚未初始化（缺少 src/commerce-extensibility-1/ 或 node_modules），请先运行 npx @adobe/aio-commerce-lib-app init，再继续。初始化具有幂等性 — 它会找到现有配置、跳过交互式提示、安装依赖项并生成项目文件。

步骤 1 — 了解意图

对于用户想要公开的每项设置，请收集：

• 名称 — 字段的机器标识符（应用在运行时读取的配置键）
• 类型 — 以下类型之一：list、text、password、email、url、tel、boolean
• 标签（可选）— 在 Admin 中显示的易读标签
• 说明（可选）— 在 Admin 中与字段一同显示的帮助文本
• 默认值（可选，取决于类型 — 请参阅步骤 2 中的约束）
• 对于 list 字段，还需提供：selectionMode（"single" 或 "multiple"）和 options（每项都包含一个 label 字符串和一个 value 字符串）

第 2 步 — 推导配置值

写入前，请应用以下各类型的验证规则。继续之前，请将任何问题反馈给用户。

字段	约束
name	必填，非空字符串
type	必填；必须是 list、text、password、email、url、tel、boolean 之一
label	可选字符串
description	可选字符串
list.selectionMode	列表字段必填："single" 或 "multiple"
list.options	列表字段必填；每个选项都必须包含 label 和 value 字符串
list/single 默认值	必填；必须与某个选项的 value 字符串匹配（非空）
list/multiple 默认值	可选字符串数组（默认为 []）；每个元素都必须与某个选项的值匹配
text 默认值	可选字符串（默认为 ""）
password 默认值	必须为 "" — 为防止配置中包含机密信息，任何非空默认值都会被拒绝
email 默认值	可选；必须为 "" 或完全有效的电子邮件地址
url 默认值	可选；必须为 "" 或完全有效的绝对 URL
tel 默认值	可选；必须为 "" 或匹配 /^\+?[0-9\s\-()]+$/（数字、空格、连字符、括号，以及可选的 +）
boolean 默认值	可选布尔值（默认为 false）

businessConfig.schema 必须至少包含一个字段 — 空数组会在构建时被拒绝。

第 3 步 — 更新 app.commerce.config.ts

在顶层 businessConfig.schema 数组中添加（或合并）字段，并保留所有其他域。如果配置中已有 businessConfig 键，请追加到 businessConfig.schema，而不是替换它。

最简示例：

businessConfig: {
  schema: [
    // Password (masked input — API keys, secrets)
    { name: "api_key", type: "password", label: "API Key", default: "" },

    // Single-select list
    {
      name: "region", type: "list", selectionMode: "single",
      label: "Region",
      options: [{ label: "EU", value: "eu" }, { label: "US", value: "us" }],
      default: "eu",   // required; must match an option value
    },

    // Boolean toggle
    { name: "debug_mode", type: "boolean", label: "Enable Debug Mode", default: false },

    // Dynamic list — options resolved at runtime via a factory that receives the action's params.
    // Required `default` factory for single-select; optional for multiple (falls back to []).
    {
      name: "paymentMethod", type: "dynamicList", selectionMode: "single",
      label: "Default Payment Method",
      options: async (params) => {
        const methods = await fetchPaymentMethods(params.SOME_API_KEY);
        return methods.map((m) => ({ label: m.title, value: m.code }));
      },
      default: (resolvedOptions) => resolvedOptions[0].value,
    },
  ],
}

所有字段类型的完整参考示例，请参见 assets/business-config.ts。

第 4 步 — 注册扩展点

运行 init，将 commerce/configuration/1 添加到 app.config.yaml 和 install.yaml，并安装所需的 @adobe/aio-commerce-lib-config 依赖。此操作具有幂等性 — 即使扩展已注册，也可以安全运行。

npx @adobe/aio-commerce-lib-app init

第 5 步 — 验证

构建项目，确认更新后的配置有效：

aio app build

如果构建失败并显示验证错误，错误会直接指出有问题的字段。

在运行时操作中读取配置

使用 @adobe/aio-commerce-lib-config 读取商家在 Commerce Admin 中设置的值。 每次调用操作时，都必须先使用生成的 schema 初始化该库，然后才能调用任何配置接口。

基本模式

import {
  initialize,
  getConfigurationByKey,
  getConfiguration,
  byCodeAndLevel,
} from "@adobe/aio-commerce-lib-config";
// Schema is generated by `aio app build` into .generated/configuration-schema.json
// under the commerce-configuration-1 extension; adjust the relative path for your action.
import schema from "../../.generated/configuration-schema.json" with { type: "json" };

export async function main(params) {
  await initialize({ schema });

  // Read a single field — config is null if the key has never been set
  const { config } = await getConfigurationByKey(
    "api_key", // the `name` from your schema
    byCodeAndLevel("global", "global"), // scope
  );
  const apiKey = config?.value ?? "";

  // Read all fields for a scope
  const { config: allConfig } = await getConfiguration(
    byCodeAndLevel("global", "global"),
  );
  // allConfig is an array of { name, value, origin } entries

  return { statusCode: 200, body: { success: true } };
}

范围选择器

选择器	使用场景
byCodeAndLevel("global", "global")	应用级设置 — 适用于所有商店
byCodeAndLevel(storeCode, "store_view")	单个商店视图（最具体）
byCode(storeCode)	使用该范围的默认级别解析
byScopeId(scopeId)	已知 Commerce 中范围的数字 ID 时使用

值会继承自父级范围 — 在 store_view 上未设置的字段会依次回退到 store、website，然后是 global。

密码字段

aio app build 首次遇到密码字段时，会自动将 AIO_COMMERCE_CONFIG_ENCRYPTION_KEY 写入 .env（并在后续构建时验证该密钥）。无需手动设置。

要在运行时解密值，操作必须能够访问该密钥。在操作的 ext.config.yaml 中将其配置为输入：

inputs:
  AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: $AIO_COMMERCE_CONFIG_ENCRYPTION_KEY

配置好密钥后，getConfigurationByKey 会返回明文值 — 无需额外编写解密代码。

常见问题

• 缺少 list/single 默认值：单选列表字段必须有 default — 不能省略。它必须与某个选项的 value 字符串完全一致。
• 找不到 defineConfig：确保已安装 @adobe/aio-commerce-lib-app，并且从 @adobe/aio-commerce-lib-app/config 导入了 defineConfig。

质量标准

• aio app build 成功完成且无错误

后续步骤

aio app build 通过后：

• 添加 webhook 拦截器 — 调用 commerce-app-webhooks，在 Commerce 操作执行前或执行后进行拦截
• 添加事件订阅 — 调用 commerce-app-eventing，订阅 Commerce 或外部事件
• 扩展 Admin UI — 调用 commerce-app-admin-ui，在 Commerce Admin 中添加自定义列、批量操作、订单视图按钮或菜单项

参考资料

• assets/business-config.ts — 参考配置，展示所有字段类型，并附有行内约束注释