salla-app-functions-test

App Functions — 在演示商店中测试（预览）

使用 salla_functions action=preview 运行已保存的函数：它会在服务端针对演示商店调用该函数并返回响应。在 save 后使用它，可在发布前验证行为——无需 Portal。

save 和 deploy_status 也会返回一个 preview URL。请忽略它：该 URL 需要身份验证，无法由客户端调用，因此应使用 action=preview 运行函数——它会携带该 URL 所需的身份验证信息。

1. 等待部署完成

save 会返回一个部署 job。部署完成前，函数无法运行：

• 轮询 salla_functions action=deploy_status，并传入 job（action=save 返回的值）→ status 为 COMPLETED 表示已就绪；FAILED → 查看 failure_reason 并修复。
• 或直接调用 salla_functions action=preview——就绪前它会返回“仍在部署……约 30 秒后重试”。

2. 收集表单输入（真实 ID）

preview 需要触发器的表单字段（函数的 form）。调用前通过 salla_functions 确认确切的字段名称，而不是假设为 order_id / shipment_id。有两种类型：

• store_id（始终必需）——已安装应用的演示商店。使用 salla_apps action=demo_stores 列出，并选择一个 connected 商店。
• 资源 ID（order_id、shipment_id 等）——必须是真实记录，因为 preview 会针对真实数据运行真实函数。使用该商店的访问令牌，通过 Salla Admin API 获取或创建这些记录（参见 salla-api-core）。

令牌处理请参见 salla-app-auth（令牌通过 app.store.authorize webhook 到达；应用必须持有与所获取资源匹配的 scope——只申请所需的 scope）。 webhook 签名验证和幂等性请参见 salla-webhooks。请前往对应文档；不要在此处重复实现这些逻辑。

**密钥/PII 安全规范：**商店访问令牌是商户的有效凭证——请将其保存在内存中，并限定用于其所属的演示商店。使用包含合成记录的演示商店，并在测试后还原你更改过的任何配置。

3. 调用

示例——将下方占位符替换为真实 ID：

salla_functions action=preview
  app_id   = 2133776579
  trigger  = shipment.created
  store_id = 660806774
  payload  = { shipment_id: 12312 }   # the form fields, minus store_id

该工具会在服务端运行函数，并原样返回其响应（http_status + response）。success:false / Resp.error() 结果是需要检查的真实函数结果，并非工具故障。

这与 Portal 的保存并预览面板一致 (测试)。请检查返回的 response：执行状态（成功/失败）、响应数据、执行时间、console.log() 输出以及任何错误。测试多种场景——正常路径、边界情况（null/空字段）和错误情况（API 故障、超时）。发布前，更改会保留在沙盒中。

错误

• “仍在部署或部署失败” → 等待约 30 秒 / 检查 deploy_status。
• “缺少必需的表单字段” → 将这些字段作为真实 ID 添加到 payload。
• “store_id 为必填项” → 传入来自 salla_apps demo_stores 的 connected 演示商店。
• 应用未安装 / 在商店中未启用 → 先在演示商店中安装/启用该应用 （使用来自 salla_apps demo_stores 的 connected 商店）。
• 获取资源 ID 时出现 401 / 403 → 令牌或 scope 问题；令牌请参见 salla-app-auth， 并确认应用持有该资源所需的 scope。

关卡：“预览是否在演示商店中返回了预期响应？”→ 使用 salla-app-functions-release 发布。