跳到正文
Indiana
控制台
文档
章节目录 / 积分与用量

积分与用量

查询余额，原子消费，预扣并结算异步任务。

SDK 0.0.1更新于

查询余额

配置当前 credit 费率

产品与计费 → 权益 → credit

当前组件的隔离示例截图；未持久化、未访问真实服务。

  1. 报价与执行分开

    quoteBalance 用于只读预估；可信后端 mutateBalance 执行 consume、reserve、confirm、release 或 refund，并保留原幂等键。

完成后检查固定费率随不可变权益版本发布，不创建旧独立 Credit Pool。消费使用原子余额协议。

app/credits.tsTypeScript
const { holdings } = await grow.readHoldings();const { quote } = await grow.quoteBalance({  operation: "quote", entitlementId, quantity: "1", properties: {},});const { ledger } = await grow.readLedger({  type: null, from: null, to: null, after: null, limit: 50,});// 只用于展示。消费必须在可信服务端完成。

浏览器使用当前客户 Token 与 credits:read。数量传十进制字符串；quoteBalance 只用于展示，不替代真正扣量。共享池、费率与来源由当前功能配置和固定套餐条款确定。

原子消费

  • 需要私密服务端 Key 的 credits:consume 权限；customerId 来自可信登录身份映射。
  • 同客户、同操作、同幂等键与同参数重试返回原收据，换参数会冲突；响应丢失不能换键再扣。
  • 拒绝结果也保持幂等。余额补足后要发起新的业务尝试，使用新的键。
server/consume.tsTypeScript
const { receipt } = await groove.mutateBalance({  customerId: authenticatedGrooveCustomerId,  command: {    operation: "consume", entitlementId, quantity: "1", properties: {},    idempotencyKey: `job:${jobId}:consume`,  },});if (!receipt.accepted) throw new Error(receipt.reason ?? "Credits unavailable");

预扣与结算

异步任务先预扣，成功确认实际数量，失败 release。最长预扣 24 小时；确认、释放和超时最多一个终态。补扣不足时确认回滚，预扣仍保持 pending。退款引用原成功交易，使用原价格和来源。

server/reserve.tsTypeScript
const { receipt: hold } = await groove.mutateBalance({  customerId: authenticatedGrooveCustomerId,  command: {    operation: "reserve", entitlementId, quantity: "10", properties: {},    expiresInSeconds: 300, idempotencyKey: `job:${jobId}:reserve`,  },});if (!hold.accepted) throw new Error("Insufficient credits");await groove.mutateBalance({  customerId: authenticatedGrooveCustomerId,  command: {    operation: "confirm", operationId: hold.id, quantity: "8",    idempotencyKey: `job:${jobId}:confirm`,  },});// 失败时通过 mutateBalance 的 release 命令释放 hold.id，不传 quantity。