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

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

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

---

## 1. 活动规则（展示用）

| 项 | 说明 |
| --- | --- |
| 活动名 | 永久尊享 VIP（VIP Abadi） |
| 目标用户 | **仅 1.0 迁移用户**（`is_legacy_user = true`） |
| 上线时间 | **2026-09-08 16:00:00（东七区 / GMT+7）** |
| 可购买窗口 | 上线起 **7 天**：`[started_at, ended_at)` → 截止 **2026-09-15 16:00:00（东七区）** |
| 售价 | **19.99 USD**（页面文案可写「19.99 硬币」，实际为法币订单，**禁止用余额硬币支付**） |
| 加速方案用户 | 活动上线后**直接赠送**，不可购买；底部按钮「会员已激活」 |
| 免费方案 / 未选方案 | 窗口内法币支付开通 |
| 开通权益 | ① 剩余锁定的 1.0 硬币**全部解锁到待兑换**（不自动兑换）② 之后支持**普通机器人**活跃值 **+5%**（智投、AI SOLO 不加） |
| 有效期 | **永久**，无过期时间 |

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

---

## 2. 页面状态机

主接口：`POST /v1/premium_vip/get`

| 条件 | 页面建议 |
| --- | --- |
| `!eligible`（非 1.0） | 非活动对象：隐藏购买，或提示仅限迁移用户 |
| `!activity_started` | 未开始：倒计时到 `started_at` |
| `activity_started && button_activated` | **已开通态**：SVIP 角标「尊享赠予」或「已开通」；底部「会员已激活」；展示 `legacy_coin_display` |
| `activity_started && !button_activated && purchase_open` | **可购买态**：角标「19.99硬币」；底部「19.99·立即开通·全部解锁 →」；用 `deposit_channels` 拉起支付 |
| `activity_started && !button_activated && !purchase_open` | **购买结束且未开通**：展示结束态，不再展示支付渠道 |

```ts
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";
}
```

角标建议：

| 条件 | 角标文案 |
| --- | --- |
| `activated && premium_vip_source === 1` | 尊享赠予 |
| `activated && premium_vip_source === 2` | 已开通 |
| `button_activated && !activated`（加速待落库） | 可按「尊享赠予 / 会员已激活」展示 |
| 可购买 | 19.99硬币 |

---

## 3. C 端接口

### 3.1 活动页主数据

`POST /v1/premium_vip/get`

请求：空 body `{}`

响应：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `activity_started` | bool | 是否已到上线时间 |
| `activity_ended` | bool | 可购买窗口是否已结束 |
| `started_at` | int64 | 上线时间 Unix 秒 |
| `ended_at` | int64 | 可购买截止 Unix 秒 |
| `purchase_open` | bool | 当前是否可法币购买（已开始且未结束） |
| `is_legacy_user` | bool | 是否 1.0 迁移用户 |
| `eligible` | bool | 是否活动对象（同 `is_legacy_user`） |
| `activated` | bool | `premium_vip_at` 是否已落库（真正开通） |
| `premium_vip_at` | int64 | 开通时间 Unix 秒；未开通为 `0` |
| `premium_vip_source` | int32 | `0` 未开通 / `1` 加速赠予 / `2` 法币购买 |
| `scheme` | enum | 金库方案：`NONE(0)` / `REGULAR(1)` / `ACCELERATED(2)`（流水里的 `PREMIUM_VIP(3)` 不会作为金库当前 scheme） |
| `price` | string | 售价 USD，如 `"19.99"` |
| `legacy_coin_display` | string | 活动页「你的 1.0 硬币」展示额（见下） |
| `unlocked_unexchanged` | string | 真实已解锁未兑换 |
| `button_activated` | bool | `true` → 底部「会员已激活」；`false` → 「立即开通」 |
| `deposit_channels` | array | 可购买时返回；按 19.99 USD 换算 IDR 过滤后的法币渠道；否则 `[]` |

#### `legacy_coin_display` 口径

| 状态 | 展示额 |
| --- | --- |
| 已开通 `activated` | `unlocked_unexchanged`（真实待兑换） |
| 未开通 | `original_total - exchanged_total`（开通后待兑换宣传口径） |

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

#### `deposit_channels[]`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `pay_type` | enum | 映射到对应 Create*Pay 接口 |
| `display_name` | string | 渠道展示名 |
| `params` | map<string,string> | 创建支付时原样带回（如 `method` / `payment`） |
| `min_amount` / `max_amount` | int64 | IDR 限额，`0`=不限 |

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

---

### 3.2 下单（仅可购买用户）

`POST /v1/order/create`

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

| 字段 | 要求 |
| --- | --- |
| `product_type` | **必须** `PRODUCT_TYPE_PREMIUM_VIP`（值为 `6`） |
| `quantity` | 固定 `1` |
| `ref_id` | `0`（无商品 catalog id） |
| `pay_type` | 可先不传；**禁止**传硬币类：`INTEGRAL` / `INTEGRAL_CONSUME` / `INTEGRAL_CONSUME_MIX` |

成功响应：

| 字段 | 说明 |
| --- | --- |
| `no` | 订单号，用于拉起三方支付 |

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

| 场景 | 典型 code |
| --- | --- |
| 非购买窗口 / 无权限 | `CODE_FORBIDDEN` |
| 已开通或加速用户不可买 | `CODE_ALREADY_VIP` |
| 已有未支付尊享 VIP 单 | `CODE_ORDER_STATUS_ERROR` |
| 硬币支付 | `CODE_PAY_METHOD_ERROR` |

**不要调用** `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` → 接口映射（与现有充值一致）：

| `pay_type` | 创建接口 | 说明 |
| --- | --- | --- |
| `PAY_TYPE_JAYA` | `POST /v1/order/jaya/create` | body 含 `order_no`、`callback_url`、`method`（来自 params） |
| `PAY_TYPE_FUTUREPAY` | `POST /v1/order/future/create` | `order_no`、`return_url` |
| `PAY_TYPE_UNISPAY` | `POST /v1/order/unispay/create` | 按现有 Unispay 参数 |
| `PAY_TYPE_EASYPAY` | `POST /v1/order/easypay/create` | 按现有 EasyPay 参数 |
| `PAY_TYPE_YDP` | `POST /v1/order/ydp/create` | `payment` 等来自 params |
| `PAY_TYPE_HAIPAY` | `POST /v1/order/haipay/create` | 按现有 Haipay 参数 |
| … | … | 以后台启用的 `deposit_channels` 为准 |

支付成功回跳后：

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 字段对照（相对原型）

| 原型位置 | 数据来源 |
| --- | --- |
| SVIP 卡右上角角标 | 见第 2 节角标表 |
| 「你的 1.0 硬币」余额 | `legacy_coin_display` |
| 底部主按钮 | `button_activated` |
| 支付方式列表 | `deposit_channels` |
| 价格文案 | `price`（USD 字符串） |

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

---

## 5. 枚举速查

| 枚举 | 值 | 含义 |
| --- | ---: | --- |
| `PRODUCT_TYPE_PREMIUM_VIP` | 6 | 尊享 VIP 商品（新建，勿用旧 `PRODUCT_TYPE_VIP=3`） |
| `LegacyUnlockScheme_NONE` | 0 | 未选方案 |
| `LegacyUnlockScheme_REGULAR` | 1 | 免费解锁 |
| `LegacyUnlockScheme_ACCELERATED` | 2 | 加速方案 |
| `LegacyUnlockScheme_PREMIUM_VIP` | 3 | **仅解锁流水**展示用，金库 `scheme` 不会变成该值 |
| `premium_vip_source` | 1 / 2 | 赠予 / 法币购买 |

---

## 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. 管理后台（简要）

| 能力 | 说明 |
| --- | --- |
| 用户详情 | `POST /v1/man/users/get` 新增 `premium_vip_at`（Unix 秒，`0`=未开通）；展示格式 `yyyy-mm-dd hh:mm:ss` |
| 1.0 解锁流水 | 现有 `POST /v1/man/users/legacy_point/unlock_ledger/list`；若 `scheme = PREMIUM_VIP(3)`，期数/方案文案均展示「尊享VIP」，比例 `1` |
| 法币订单 | 现有 `POST /v1/man/order/list`；商品类型筛选项增加 `PRODUCT_TYPE_PREMIUM_VIP(6)`。列表：商品名「尊享VIP」、数量 1、单价/合计/实付 `19.99` |

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