# 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`