206 lines
5.5 KiB
Markdown
206 lines
5.5 KiB
Markdown
# H5 积分商城接口文档（含流程说明）
|
||
|
||
> 面向：H5（活动页/积分商城前台）调用
|
||
> 基础路径：`/api/v1`
|
||
> 返回结构：BuildAdmin 通用 `code/msg/time/data`（成功 `code=1`）
|
||
|
||
---
|
||
|
||
## 1. 总体流程说明
|
||
|
||
### 1.1 流程 A：H5 临时登录（推荐）
|
||
|
||
适用场景：H5 只需要“用户名级别”的轻量登录，不依赖 PlayX 的 token。
|
||
|
||
1. H5 调用 `GET/POST /api/v1/temLogin?username=xxx` 获取 **商城 token**（类型 `muser`）
|
||
2. H5 后续请求统一携带该 token（推荐放在 Header：`token: <muser_token>`，也可用参数 `token`）
|
||
3. H5 调用：
|
||
- `GET /api/v1/mall/assets` 获取资产
|
||
- `POST /api/v1/mall/claim` 领取积分（幂等）
|
||
- `GET /api/v1/mall/items` 获取商品
|
||
- `POST /api/v1/mall/bonusRedeem` / `physicalRedeem` / `withdrawApply` 提交兑换/提现
|
||
- `GET /api/v1/mall/orders` 查询订单
|
||
- `GET/POST /api/v1/mall/address*` 管理地址（addressList/addressAdd/addressEdit/addressDelete）
|
||
|
||
### 1.2 流程 B：PlayX token 换取 session（兼容）
|
||
|
||
适用场景：H5 已经拿到了 PlayX 下发的 token，希望换取商城侧 `session_id`。
|
||
|
||
1. H5 调用 `POST /api/v1/mall/verifyToken`（传 `token` 或 `session`）
|
||
2. 服务端返回 `data.session_id`
|
||
3. H5 后续请求携带 `session_id`（优先级高于 token）
|
||
|
||
---
|
||
|
||
## 2. 身份与鉴权（重要）
|
||
|
||
以下接口都会通过服务端逻辑解析“当前资产主体”，优先级如下：
|
||
|
||
1. **`session_id`**（GET/POST）：对应表 `mall_session`，未过期则可映射到资产主体
|
||
2. **`token`**（GET/POST 或 Header）：支持会员 token 或 `muser` token（H5 临时登录签发）
|
||
3. **`user_id`**（GET/POST）：
|
||
- 纯数字：视为 `mall_user_asset.id`
|
||
- 非纯数字：按 `mall_user_asset.playx_user_id` 查找
|
||
|
||
推荐做法：
|
||
- H5 统一只用 **Header `token`**（值为 `muser` token），避免 URL 泄露与参数歧义。
|
||
|
||
---
|
||
|
||
## 3. 接口列表（H5 常用）
|
||
|
||
### 3.1 H5 临时登录
|
||
|
||
**GET/POST** ` /api/v1/temLogin `
|
||
|
||
参数：
|
||
- `username`：必填，用户名（字符串）
|
||
|
||
成功返回 `data.userInfo`：
|
||
- `id`：资产主键（`mall_user_asset.id`）
|
||
- `username`：用户名
|
||
- `playx_user_id`：映射的 PlayX 用户标识（字符串）
|
||
- `token`：**muser token**（后续请求使用）
|
||
- `refresh_token`：刷新 token（当前前端未强依赖可不接）
|
||
- `expires_in`：秒
|
||
|
||
示例：
|
||
|
||
```bash
|
||
curl "https://{域名}/api/v1/temLogin?username=test001"
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 资产查询
|
||
|
||
**GET** ` /api/v1/mall/assets `
|
||
|
||
鉴权：携带 `token` 或 `session_id` 或 `user_id`
|
||
|
||
成功返回 `data`：
|
||
- `locked_points`：待领取积分
|
||
- `available_points`：可用积分
|
||
- `today_limit`：今日可领取上限
|
||
- `today_claimed`：今日已领取
|
||
- `withdrawable_cash`：可提现现金（积分按配置比例换算）
|
||
|
||
---
|
||
|
||
### 3.3 领取积分（幂等）
|
||
|
||
**POST** ` /api/v1/mall/claim `
|
||
|
||
参数：
|
||
- `claim_request_id`：必填，幂等键（建议：`{业务前缀}_{assetId}_{毫秒时间戳}`）
|
||
- 身份参数：`token` / `session_id` / `user_id` 三选一（推荐 `token`）
|
||
|
||
说明：
|
||
- 同一个 `claim_request_id` 重复提交会直接返回成功（不会重复入账）
|
||
- 会受 `today_limit/today_claimed/locked_points` 限制
|
||
|
||
---
|
||
|
||
### 3.4 商品列表
|
||
|
||
**GET** ` /api/v1/mall/items `
|
||
|
||
参数：
|
||
- `type`：可选，`BONUS | PHYSICAL | WITHDRAW`
|
||
|
||
---
|
||
|
||
### 3.5 红利兑换（提交订单）
|
||
|
||
**POST** ` /api/v1/mall/bonusRedeem `
|
||
|
||
参数：
|
||
- `item_id`：必填
|
||
- 身份参数：`token` / `session_id` / `user_id`
|
||
|
||
返回：
|
||
- `data.order_id`
|
||
- `data.status`（通常 `PENDING`）
|
||
|
||
---
|
||
|
||
### 3.6 实物兑换（提交订单）
|
||
|
||
**POST** ` /api/v1/mall/physicalRedeem `
|
||
|
||
参数：
|
||
- `item_id`：必填
|
||
- `address_id`：必填，收货地址主键（`mall_address.id`，须为当前用户资产下地址）
|
||
- 身份参数：`token` / `session_id` / `user_id`
|
||
|
||
说明：服务端会将该地址在下单时刻的 **收货人 / 电话 / 完整地址** 写入订单字段（快照），并写入 `mall_order.mall_address_id` 关联所选地址。
|
||
|
||
---
|
||
|
||
### 3.7 提现申请（提交订单）
|
||
|
||
**POST** ` /api/v1/mall/withdrawApply `
|
||
|
||
参数：
|
||
- `item_id`：必填
|
||
- 身份参数：`token` / `session_id` / `user_id`
|
||
|
||
---
|
||
|
||
### 3.8 订单列表
|
||
|
||
**GET** ` /api/v1/mall/orders `
|
||
|
||
鉴权：`token` / `session_id` / `user_id`
|
||
|
||
说明：
|
||
- 返回最多 100 条
|
||
- 订单里包含 `mallItem`（商品信息）
|
||
|
||
---
|
||
|
||
## 4. 地址管理（H5）
|
||
|
||
> 地址与资产主体通过 `playx_user_asset_id` 关联（即 `mall_user_asset.id`）。
|
||
|
||
### 4.1 地址列表
|
||
**GET** ` /api/v1/mall/addressList `
|
||
|
||
### 4.2 新增地址
|
||
**POST** ` /api/v1/mall/addressAdd `
|
||
|
||
Body 含 `receiver_name`（收货人，建议填写；实物兑换下单快照需要非空的收货人、电话与拼接后的完整地址）。
|
||
|
||
### 4.3 编辑地址
|
||
**POST** ` /api/v1/mall/addressEdit `
|
||
|
||
### 4.4 删除地址
|
||
**POST** ` /api/v1/mall/addressDelete `
|
||
|
||
---
|
||
|
||
## 5. session 换取（可选）
|
||
|
||
### 5.1 token 换 session
|
||
|
||
**POST** ` /api/v1/mall/verifyToken `
|
||
|
||
参数（二选一）：
|
||
- `token`
|
||
- `session`
|
||
|
||
成功返回：
|
||
- `data.session_id`
|
||
- `data.user_id`
|
||
- `data.username`
|
||
- `data.token_expire_at`
|
||
|
||
---
|
||
|
||
## 6. 常见错误与排查
|
||
|
||
- **401 登录态过期**：token/session 过期或不匹配；请重新 `temLogin` 或重新 `verifyToken`
|
||
- **提示缺少必填字段**：按各接口参数补齐（如 `claim_request_id`、`item_id`、`address_id`（实物）、地址中收货人/电话/完整地址等）
|
||
- **积分不足/无可领取积分**：`locked_points<=0` 或已达 `today_limit`
|
||
|