Tip 支付成功结果 API 接口定义

1. 文档状态

本文档定义咖啡打赏支付成功后，前端展示累计打赏次数和角色感谢语所需的接口扩展，供后端实现和前后端联调使用。

本次不新增 Endpoint，仅扩展现有订单状态接口：

GET /api/payment/order-status?order_id=<ORDER_ID>

2. 身份与统计口径

订单状态查询保持当前认证规则。前端存在 Token 时继续发送 Bearer Token，没有 Token 时不增加 Authorization Header。

tipCount 表示包含当前订单在内，同一付款身份向同一 recipientCharacterId 成功打赏的累计次数：

付款身份	统计方式
正式用户 Login Token	按用户 ID 与收款角色 ID 统计
游客 Guest Token	按游客 ID 与收款角色 ID 统计
无 Token 匿名用户	无法可靠跨订单识别，当前订单固定返回 `1`

只有最终支付成功的 Tip 订单计入次数。pending、failed 或取消订单不增加次数。

3. 请求定义

3.1 请求地址

GET <API_BASE_URL>/api/payment/order-status?order_id=<ORDER_ID>

3.2 Query 参数

字段	类型	是否必填	说明
`order_id`	string	是	创建支付订单接口返回的订单 ID。

3.3 请求示例

curl 'https://api.banlv-ai.com/api/payment/order-status?order_id=tip_order_123' \
  -H 'Authorization: Bearer <TOKEN>'

匿名 Tip 订单不发送 Authorization Header：

curl 'https://api.banlv-ai.com/api/payment/order-status?order_id=tip_order_123'

4. 响应定义

4.1 paid Tip 订单

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "orderId": "tip_order_123",
    "status": "paid",
    "orderType": "tip",
    "planId": "tip_coffee_usd_9_99",
    "tipCount": 2,
    "thankYouMessage": "You always know how to make my day a little sweeter."
  }
}

字段	类型	说明
`orderId`	string	当前订单 ID。
`status`	`pending \| paid \| failed`	当前支付状态。
`orderType`	string	Tip 订单固定为 `tip`。
`planId`	string	当前订单套餐 ID。
`tipCount`	integer \| null	当前身份向当前角色累计成功打赏次数，最小值为 `1`。
`thankYouMessage`	string \| null	收款角色配置的纯文本感谢语。

thankYouMessage 不得包含 HTML。后端可以返回换行，前端会按纯文本保留展示。

4.2 pending、failed 和非 Tip 订单

非 paid Tip 订单不生成打赏成功结果，两个扩展字段必须返回 null：

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "orderId": "pay_order_456",
    "status": "pending",
    "orderType": "vip_monthly",
    "planId": "vip_monthly",
    "tipCount": null,
    "thankYouMessage": null
  }
}

角色感谢语配置缺失时，后端允许 paid Tip 响应中的 thankYouMessage 为 null，前端会展示本地通用感谢文案。

5. 幂等与一致性

后端在订单首次从非 paid 状态转换为 paid 时，必须原子完成以下操作：

标记支付订单成功；
将当前 Tip 计入付款身份和收款角色的累计次数；
保存当前订单对应的 tipCount；
从 recipientCharacterId 对应的角色配置读取并保存 thankYouMessage。

同一支付回调重复执行时不得重复累计。对同一个 order_id 重复查询必须返回相同的 tipCount 和 thankYouMessage，后续新订单不能改变旧订单的成功结果。

6. 验收标准

正式用户和 Guest 对不同角色的累计次数相互独立。
无 Token 匿名用户的成功 Tip 订单返回 tipCount=1。
首次成功返回 tipCount=1，第二次成功返回 tipCount=2。
pending、failed 和非 Tip 订单返回两个 null 扩展字段。
同一支付回调重试不会重复增加次数。
同一订单重复轮询得到稳定的次数和感谢语。
感谢语为角色配置的纯文本，不返回 HTML。

4.0 KiB Raw Blame History Unescape Escape