salla-app-settings

Salla 应用设置流程

通过使用 Salla Partners MCP 工具执行操作，为 Salla 应用设置每个商家的配置。按顺序执行步骤——完成每个关卡后再继续。

适用于公开、私有和通信应用。 商家设置表单（salla_settings define_form / set_validation_url）适用于这些应用类型。配送应用没有商家设置表单——它们通过 salla_shipping（区域/设置）配置配送，这是一个独立的概念；Portal 会拒绝配送应用的 POST /settings。对于配送应用，请转到 salla-shipping-app。

关键规则： 运行时，每次设置 POST 都必须发送所有键。省略某个键会将其设为 null——不支持部分更新。

危险信号

容易产生的想法	错误原因
“为这个配送应用定义一个 salla_settings 表单。”	配送应用没有商家设置表单；Portal 会拒绝配送应用的 POST /settings。请通过 salla_shipping 配置区域/设置 → salla-shipping-app。

工具

工具	操作	功能
salla_settings	define_form	注册商家设置表单（字段对象）
salla_settings	set_validation_url	设置服务端验证 URL
salla_settings	list_features	读取应用支持的功能
salla_settings	set_features	设置支持的功能

前置条件： 必须已连接 Salla Partners MCP 服务。每项操作都需要应用的 app_id。如果工具返回“Salla session expired”，请重新执行登录流程。

---

步骤 0 — 了解需求

开始前先询问：

1. 你的应用需要商家输入哪些内容？（API 密钥、URL、开关、数字？）
2. 在 Salla 保存这些值之前，是否需要进行服务端验证？
3. 首次写入设置的时机是什么？ 安装时，还是商家填写表单时？

---

步骤 1 — 设计设置架构

Salla 会根据表单构建器架构渲染商家表单：每个字段都使用下方分类体系中的真实 type + format 组合。请使用真实组合（像 toggle / text / select 这样的裸别名无法通过 Portal 验证）。规则如下：

• 仅限扁平结构——不得包含嵌套对象。
• id 使用 snake_case（stock_threshold，而不是 stockThreshold）——只有使用 snake_case，已安装应用的保存路径才可靠。
• 每个必填字段都必须带有默认 value——这是首次激活／保存所必需的。
• 标签优先使用阿拉伯语。 Salla 商家大多使用阿拉伯语——请用阿拉伯语填写 label／description；设置 multilanguage: true 以同时提供英文。multilanguage 仅适用于字符串类型的 text／textarea 字段（构建器通过 supportsMultilanguage 控制此功能）。
• public: true 表示该值可安全地在客户端读取。店面代码片段通过 salla.config.get('app.<key>') 读取公开设置；public: false 的值仅保留在服务端。→ salla-snippets。
• 机密信息（API 密钥、密码、令牌）使用 format: "password"，在运行时加密存储，且只能在服务端或通过 context.settings 读取。密码字段天然为非公开字段——构建器的密码控件带有 hide: true，这会移除公开选项，因此机密信息绝不会暴露给店面（请保留 public: false，以明确表达这一意图）。OAuth／商家访问令牌不属于设置——请通过 salla-app-auth 处理。
• 权限范围。 渲染表单或接收 app.settings.updated 无需设置权限范围；只有在激活由合作伙伴端触发（而非通过商家控制面板触发）时，才需要设置权限范围，以便通过 Admin API 读写值。如果应用监听任何店铺事件，则需要 Webhooks 权限范围。

请使用以下精选核心 type + format 组合：

type	format（核心）
boolean	checkbox（switch 表示相同的布尔值，只是切换 UI）
string	text、textarea、password、url、email
string（值选择器）	color、image、date、time、datetime
number	integer、float
items	dropdown-list、radio-list、checkbox-list

优先选择最简单且适合数据的类型。 number（带有 minimum／maximum／step）可以满足滑块或单位输入框的用途——不要使用这些类型。checkbox 可表示开／关（switch 表示相同的布尔值）。多行文本请使用 textarea。

还有一些高级格式，但会增加复杂性——除非确有需要，否则请避免使用： richtext（除非必须使用富文本格式，否则使用 textarea）、code、icon、嵌套的 collection 类型（可重复的子字段组），以及 static 显示块（title／description／line）。优先使用核心类型；只有用例确实需要时才使用这些类型。

常用属性：id（snake_case）、type、format、label、value（默认值）、required、public、icon、placeholder、labelHTML、multilanguage。数字类型使用 minimum／maximum／step；字符串类型使用 minLength／maxLength；items 使用 options 和标量默认 value。multilanguage 仅适用于字符串类型的 text／textarea。复选框示例：

{
  "id": "hurrify_enabled",
  "type": "boolean",
  "format": "checkbox",
  "label": "تفعيل هيرفاي",
  "icon": "sicon-toggle-off",
  "value": true,
  "required": false,
  "public": true
}

字段对象参考 → references/form-builder.md

字段架构文档位于其 docs.salla.dev/<id>.md 页面中的 OpenAPI 块（通过 salla-docs 查找）；请根据该架构验证每个字段对象，包括 type／format 组合、required 和枚举，并在调用 define_form 之前修正。请遵循 salla-api-core 中的读取架构 → 构建 → 验证 → 修正 → 重试循环。

检查项：“每个字段是否都使用 type+format、snake_case ID、阿拉伯语标签，并且每个必填字段都有默认值？”

---

第 2 步 — 注册表单

1. 调用 salla_settings，并传入 action: "define_form"、app_id 和 settings（第 1 步中的字段对象数组）。为每个字段设置纯字符串 label；如果字符串类型的 text / textarea 字段中的文本需要翻译，请设置 multilanguage: true。
2. 可选的验证 URL — 仅用于验证，不用于存储。 若要在 Salla 保存输入前拒绝无效输入，请调用 salla_settings，并传入 action: "set_validation_url"、app_id 和 validation_url。Salla 会在保存前向该 URL POST 提交拟保存的值；返回字段错误（以阻止保存）或 200 OK（以允许保存）。这是一个没有签名的公共端点——验证这些值并作出响应即可，不要做其他操作。数据通过 app.settings.updated webhook 存储（第 4 步）。接口约定 → references/form-builder.md。

手动备用方案： Portal → 打开应用 → App Settings 表单构建器。

关卡（保存冒烟测试）：“表单已注册 — 在演示商店安装应用（salla_apps action=demo_stores → 打开某个商店的 install_url，然后打开 dashboard_url），进入其设置页面，更改一个值并点击 SAVE，确认更改已保存。Portal 接受 schema 并不能证明已安装应用的表单能保存 — 请测试实际保存流程。”

验证配置用法（本技能负责接口约定）。 你在此处定义的公共字段，就是店面代码片段可通过 salla.config.get('app.<key>') 读取的键。每次调用 define_form 后，请确认：(a) 字段 schema 有效（第 1 步中的 type+format / snake_case / 必填项默认值检查），且 (b) 代码片段读取的每个 salla.config.get('app.<key>') 都对应此处定义且 public: true 的字段 — 缺失或私有键在店面读取时会返回 undefined。设置定义接口约定；这些读取操作的浏览器端检查见 salla-snippets。

---

第 3 步 — 声明支持的功能

大多数应用可跳过此步骤 — 通信应用发布前必须完成（频道声明；请参阅 salla-communication-app）。使用此工具管理标志：

• 读取当前设置：salla_settings action=list_features、app_id。注意： 非通信应用会返回 404 — 这是预期行为；list_features 仅适用于通信类型的应用。
• 设置功能标志：salla_settings action=set_features、app_id、features: [...]。

---

第 4 步 — 安装时写入默认值（运行时）

没有 MCP 工具可用于写入每个商家的值 — 这需要在运行时使用商家的 access_token 完成。安装时触发 app.store.authorize 后，写入所有必需的默认值，让商家一开始就拥有可用的配置。

app.settings.updated 是存储的唯一可信来源 （文档）。商家保存表单、激活应用时都会触发此事件，并通过 data.settings 携带完整设置 — 每次激活或更新时都要持久化这些数据。此事件具有权威性（且可能在你获得令牌之前到达），因此应依赖它，而不是使用 GET。负载：

{
  "event": "app.settings.updated",
  "merchant": 1234509876,
  "data": {
    "id": 6789012345,
    "app_type": "public",
    "settings": {
      "door_to_door": true,
      "pickup_time": "09:00:00",
      "box_size": ["25x25", "10x10"],
      "ads_activated": "true"
    }
  }
}

请注意，布尔值可能以字符串 "true" 的形式到达 — 请进行防御性类型转换。接入方式 → salla-app-lifecycle。

安装时写入默认值（即使你只会重新读取这些值，也要处理此步骤）：

POST https://api.salla.dev/admin/v2/apps/{app_id}/settings
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "api_key": "",
  "fast_delivery": false,
  "contact_no": null
}

发送每个键 — 即使值为空。完整安装模式 → references/settings-patterns.md

---

第 5 步 — 读取和更新设置（运行时）

读取：

GET https://api.salla.dev/admin/v2/apps/{app_id}/settings
Authorization: Bearer {access_token}

{
  "status": 200,
  "success": true,
  "data": {
    "app_id": "513499943",
    "settings": { "api_key": "sk-abc123", "fast_delivery": true }
  }
}

仅通过 Partners MCP 更新表单定义（字段、格式、默认值、Validation URL）——salla_settings action=define_form。这是更改架构的唯一受支持方式；不应编写脚本绕过这一方式，在 Portal 端手动编辑。

更新每个商家的值（运行时）——始终发送所有键（先读取，合并更改，再写入全部值）：

POST https://api.salla.dev/admin/v2/apps/{app_id}/settings
Authorization: Bearer {access_token}
Content-Type: application/json

{ "api_key": "sk-abc123", "fast_delivery": true, "contact_no": 50 }

POST 响应正文并不重要——不要解析或依赖其回显内容。 将 2xx 视为已接受，然后通过后续 GET 确认（或通过作为存储事实来源的 app.settings.updated webhook 确认）。

API 规范 → references/api-spec.md · 安全的单键更新 → references/settings-patterns.md

检查点：“POST 完整的设置对象，并确认 GET 返回更新后的值。”

---

第 6 步 — 在应用函数中访问设置

在任何应用函数中，设置都位于 context 对象上——无需调用 API：

export default async function (context: AppContext) {
  const apiKey = context.settings?.api_key;
  const fastDelivery = context.settings?.fast_delivery;
  // always use optional chaining — undefined until merchant configures them
}

App Functions context 结构 → salla-app-functions

---

资源

主题	链接
构建应用设置表单	references/form-builder.md
Salla Admin API 参考文档	https://docs.salla.dev/421117m0.md