插件统一交易接口：令牌、幂等与结果核对

适用版本：会员插件 1.3.3 · 核对日期：2026-10-10

用途

由可信插件后端为已有会员增加或扣减一种账户资产，并记录可关联业务的流水。

前置条件

开启插件统一接入，为已安装调用插件配置唯一服务令牌；pluginId 使用调用方 plugin.yaml 的 metadata.name。会员存在，余额操作还需余额总开关。

操作入口

会员插件设置 → 插件接入。接口前缀：/apis/public.member.muyin.site/v1alpha1/integration。请求头：X-Muyin-Member-Token: <调用插件服务令牌>。

操作步骤

先调用 POST /self-check 核对开关、令牌识别和调用方身份。
创建稳定 requestId，明确用户、账户差额、交易类型、业务类型和业务 ID。
调用 POST /transactions；单笔只允许积分或余额一种非零变化。
保存返回的交易 ID 与业务结果，核对账户和流水。
发生超时或返回不明确时，调用 POST /transactions/lookup 并携带原交易指纹。
同一业务重试使用原请求 ID 和一致内容；发现冲突或结果仍不明确时先人工核对。

预期结果与核对

服务令牌解析得到调用插件身份。已成功记录在相同 pluginId + requestId 下用于识别重试；不一致的交易内容返回冲突。查询返回 found 及已找到交易的信息。

限制与注意事项

令牌只用于后端，不能写进主题、公开 JavaScript 或文档样例。单笔同时改变积分和余额会被拒绝，两者都为 0 也会被拒绝。类型和正负方向必须一致。未找到成功流水不能证明一次网络超时绝对没有改变账户；必须核对原账户与流水，不能更换 ID 盲目重放。

常见问题

401/403？ 核对插件授权、统一开关、令牌与实际 RBAC 放行入口。
400？ 查必填字段、枚举类型、账户变化和余额开关。
409？ 同一请求 ID 被不同内容使用，保留原业务指纹排查。

请求与查询示例

以下是某任务业务补发 20 分的请求体；用户名、业务 ID 和令牌均需替换为自己的真实值。调用前应确认业务未重复发放。

{
  "requestId": "task-submission-001-reward",
  "userId": "alice",
  "scoreDelta": 20,
  "balanceDelta": 0,
  "transactionType": "SCORE_TASK_REWARD",
  "businessType": "TASK",
  "businessId": "submission-001",
  "description": "任务审核奖励",
  "metadata": {"taskId": "task-001"}
}

核对接口 POST /transactions/lookup 的请求体：

{
  "requestId": "task-submission-001-reward",
  "userId": "alice",
  "scoreDelta": 20,
  "balanceDelta": 0,
  "transactionType": "SCORE_TASK_REWARD",
  "businessType": "TASK",
  "businessId": "submission-001"
}

两个接口均携带同一调用方服务令牌。transactionType、businessType 必须使用插件支持的枚举，不使用任意字符串如 CUSTOM_ORDER。