尊享 VIP（C.XS443）前端对接文档

面向 App/H5 活动页与支付流程。协议约定与 Splay 2.0 前端对接文档 第 2 节相同：POST、登录态、snake_case、金额为 decimal 字符串、时间为 Unix 秒（int64 在 JSON 里可能是字符串或数字）。

管理后台改动见文末第 7 节。

1. 活动规则（展示用）

前端不要硬编码判断是否可买 / 是否结束，一律以后端 activity_started / activity_ended / purchase_open / started_at / ended_at 为准。

2. 页面状态机

主接口：POST /v1/premium_vip/get

type PremiumVipPage =
  | "not_eligible"
  | "not_started"
  | "activated"
  | "can_buy"
  | "purchase_ended";

function premiumVipPage(s: {
  eligible: boolean;
  activity_started: boolean;
  button_activated: boolean;
  purchase_open: boolean;
}): PremiumVipPage {
  if (!s.eligible) return "not_eligible";
  if (!s.activity_started) return "not_started";
  if (s.button_activated) return "activated";
  if (s.purchase_open) return "can_buy";
  return "purchase_ended";
}

角标建议：

3. C 端接口

3.1 活动页主数据

POST /v1/premium_vip/get

请求：空 body {}

响应：

legacy_coin_display 口径

金额均为 numeric 字符串，展示用 Decimal，勿用 JS 浮点做最终运算。

deposit_channels[]

不要用 POST /v1/order/deposit/channel/list（按整数硬币换算）来拉尊享 VIP 渠道；活动页已内置按 19.99 USD 过滤的列表。

3.2 下单（仅可购买用户）

POST /v1/order/create

{
  "product_type": "PRODUCT_TYPE_PREMIUM_VIP",
  "quantity": 1,
  "ref_id": 0
}

成功响应：

常见失败（业务码以网关 code 为准）：

不要调用 POST /v1/order/pay（硬币支付）；尊享 VIP 只走法币。

3.3 拉起法币支付

流程与充值/硬币包相同：

GetPremiumVipState
  → 选 deposit_channels 中一项
  → CreateOrder(PRODUCT_TYPE_PREMIUM_VIP)
  → 按 pay_type 调对应 Create*Pay（带 order_no + 渠道 params + 回跳 URL）
  → 三方收银台
  → 回跳后轮询/刷新 GetPremiumVipState 或 GetOrder

pay_type → 接口映射（与现有充值一致）：

支付成功回跳后：

1. 可调对应 Check*Pay（如 /v1/order/jaya/check）或 POST /v1/order/get
2. 再调 POST /v1/premium_vip/get：期望 activated=true、button_activated=true、premium_vip_source=2
3. 展示「VIP 已开通」弹窗；点「查看我的 VIP 卡」进入已开通页（角标「已开通」）

支付失败：提示失败并回到支付页 / 活动可购买态。

4. UI 字段对照（相对原型）

解锁说明文案（产品向）：开通后锁定的 1.0 硬币全部进入待兑换；每周兑换仍走原 1.0→2.0 周额度规则（POST /v1/legacy_point/exchange），本活动不自动兑换。

5. 枚举速查

6. 建议联调检查清单

• [ ] 非 1.0 用户：eligible=false，无购买入口
• [ ] 加速用户：活动开始后 button_activated=true，不能 CreateOrder
• [ ] 免费/未选：窗口内可下单 + 渠道支付；成功后 activated=true、source=2
• [ ] 硬币支付被拒（CODE_PAY_METHOD_ERROR）
• [ ] 窗口结束后 purchase_open=false，deposit_channels 为空，下单失败
• [ ] 开通后 legacy_coin_display 变为待兑换余额；周兑换流程仍可用
• [ ] 支付回跳后刷新活动态，弹开通成功窗

7. 管理后台（简要）

成交订单以 status=FINISHED 为准；若用户已获赠送后仍完成渠道扣款，服务端可能将订单置为 CANCELED 并打运维对账日志，前端管理列表勿把此类单当成交。