webman-buildadmin-mall/docs/H5-积分商城接口文档.md

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：秒

示例：

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