关于 salla-app-functions-design
salla-app-functions-design 是用于在实现前选择 Salla 应用函数触发器和执行类型的开发 Skill。它指导核实事件契约，并区分阻塞式同步操作与异步事件及其超时限制。
主要功能
- 01查看并核实触发器定义
- 02确认事件载荷字段
- 03选择同步或异步执行
- 04了解超时预算
- 05将安全工作交由相关 Skill
适用场景
- 01为 Salla 应用函数选择触发器
- 02使用事件字段前核对载荷
- 03判断操作是否应阻塞流程
- 04按执行超时限制规划实现
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/salla-app-functions-design确认已加载。
附带文件references/event-contexts.md
详细介绍
App Functions — 设计触发器与执行类型
编写代码之前，先决定运行_什么_以及_何时_运行。
第 1 步 — 确认事件约定
以文档为依据的事件目录——按商家与客户分组的所有触发器、其同步／异步类型，以及文档中 payload.data 的结构——位于 references/event-contexts.md。使用它选择触发器并查看上下文结构；切勿臆测负载。
权威来源：salla_functions action=list_triggers（无需 app_id），用于获取实时触发器名称和类别；salla_functions action=get，用于获取触发器的权威 .d.ts。客户事件文档提供的负载仅供示例；依赖字段名称之前，请通过 action=get 或架构文档确认。
检查点：“你是否已确认此事件的 payload.data 字段名称？”
第 2 步 — 选择执行类型
| 类型 | 时机 | 会阻塞用户吗？ | 超时 | 返回值的影响 |
|---|---|---|---|---|
| 异步事件 | 操作之后 | 否 | 30 s | 即发即弃：会记录日志，不会影响流程。 |
| 同步操作 | 操作之前 | 是 | 总计 5 s | 阻塞式：可以修改参数，或拒绝／阻止操作。 |
- 同步操作正是
merchant_actions类别——shipment.creating和shipment.cancelling（请通过salla_functions action=list_triggers确认类别，而非根据动词形式判断）。它们会在生命周期完成之前拦截流程：出错会取消操作，成功则可以修改其数据。shipment.creating是文档中的同步示例，返回的是Shipment（(context: Shipments): Promise<Shipment>），而不是普通的Resp——它会设置运单号／标签。构建器机制 → salla-app-functions-handler。 - 异步事件（例如
order.created、product.added）会在带外运行；返回有效的成功／错误结果，以便将其记录到日志中。
超时预算
| 类型 | 总超时 | 每次内部异步调用 |
|---|---|---|
| 同步 | 硬性限制 5 s，目标 < 500 ms | < 2 s，使用 AbortController 限定时长 |
| 异步 | 30 s | 使用 AbortController 限定时长 |
同步操作期间商家会被阻塞，因此应以 < 500 ms 为目标，并将 5 s 视为上限。为每次 fetch／等待中的 I/O 设置时限，可避免某个上游响应缓慢导致超出预算（AbortController 机制 → salla-app-functions-handler）。超时会阻塞（同步）或丢弃（异步）此次运行。
检查点：“已决定使用同步还是异步，并了解超时预算了吗？”
安全性与数据交接
如果处理器会接触令牌、商家身份验证或出站调用，请将其分流处理：令牌存储／OAuth／商家访问令牌 → salla-app-auth；Webhook 签名验证与幂等性 → salla-webhooks。完整交接清单 → references/event-contexts.md。
下一步：使用 salla-app-functions-handler 编写实现。