mojiahui/webman-buildadmin-mall

Fork 0

Files

zhenhui f2543b9aa4 更新接口不通过user_id绑定数据

2026-07-27 14:24:53 +08:00

8.8 KiB

Raw Blame History

H5 积分商城接口文档（含流程说明）

面向：H5（活动页/积分商城前台）调用
基础路径：/api/v1
返回结构：BuildAdmin 通用 code/msg/time/data（成功 code=1）

1. 总体流程说明

1.1 流程 A：H5 临时登录（推荐）

适用场景：H5 只需要“用户名级别”的轻量登录，不依赖 playX 的 token。

H5 调用 GET/POST /api/v1/temLogin?username=xxx 获取 商城 token（类型 muser）
H5 后续请求统一携带该 token（推荐放在 Header：token: <muser_token>，也可用参数 token）
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 /api/v1/mall/order 按订单 ID 查询单笔订单（含状态）
- GET/POST /api/v1/mall/address* 管理地址（addressList/addressAdd/addressEdit/addressDelete）

1.2 流程 B：playX token 换取 session（兼容）

适用场景：H5 已经拿到了 playX 下发的 token，希望换取商城侧 session_id。

H5 调用 POST /api/v1/mall/verifyToken（传 token 或 session）
服务端返回 data.session_id
H5 后续请求携带 session_id（优先级高于 token）

2. 身份与鉴权（重要）

以下接口通过服务端解析「当前资产主体」，仅支持：

session_id（GET/POST）：对应表 mall_session，未过期则可映射到资产主体
token（GET/POST 或 Header token / ba-token）：会员 token 或 H5 临时登录签发的 muser token

不再支持单独传 user_id 作为鉴权参数（避免越权）。

推荐做法：

H5 统一使用 Header token（muser 或 playX 换 session 后的凭证），避免 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

成功返回 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（推荐 Header 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

data.order_id
data.status（通常 PENDING）

3.6 实物兑换（提交订单）

POST /api/v1/mall/physicalRedeem

参数：

item_id：必填
address_id：必填，收货地址主键（mall_address.id，须为当前用户资产下地址）
身份参数：token / session_id

说明：服务端会将该地址在下单时刻的 收货人 / 电话 / 完整地址 写入订单字段（快照），并写入 mall_order.mall_address_id 关联所选地址。

3.7 提现申请（提交订单）

POST /api/v1/mall/withdrawApply

参数：

item_id：必填
身份参数：token / session_id

3.8 订单列表

GET /api/v1/mall/orders

鉴权：token / session_id

说明：

返回最多 100 条
订单里包含 mallItem（商品信息）

3.8.1 单笔订单查询（按 ID）

GET /api/v1/mall/order

鉴权：token / session_id（同订单列表）

参数（Query）：

order_id：必填，商城订单主键 mall_order.id（兼容参数名 id）

说明：

仅能查询当前鉴权用户本人名下的订单；订单不存在或不属于当前用户时返回「记录不存在」，不泄露他人订单信息。

返回（成功 data）：

order_id：订单 ID
status：订单状态（PENDING / COMPLETED / SHIPPED / REJECTED）
order：订单详情（字段与订单列表单条一致，含 reject_reason、grant_status、mallItem 等）

示例：

curl -G "https://{域名}/api/v1/mall/order" \
  -H "token: <muser_token>" \
  --data-urlencode "order_id=123"

3.9 积分流水（领取/兑换/退回）

GET /api/v1/mall/pointsLogs

鉴权：携带 token 或 session_id

参数（Query）：

limit：可选，每页条数（默认 20，最大 100）
cursor：可选，游标（上一页响应返回的 next_cursor，传入后获取下一页）
direction：可选，IN（入账）/OUT（扣减），不传返回全部

返回（成功 data）：

list[]：流水数组（按时间倒序）
- biz_type：CLAIM（领取入账）/ REDEEM_BONUS|REDEEM_PHYSICAL|REDEEM_WITHDRAW（兑换扣分）/ REFUND（订单驳回或终态失败退回）
- direction：IN / OUT
- points：积分变动值（正数，方向由 direction 表示）
- ts：时间戳（Unix 秒）
- ref_id：关联业务号（领取为 claim_request_id；订单为 external_transaction_id）
- order_no：订单号（非订单类为空）
- order_status：订单状态（非订单类为空）
- mallItem：商品信息（非订单类为 null）
  - id：商品ID
  - title：商品名
  - type：商品类型（1=BONUS 2=PHYSICAL 3=WITHDRAW）
  - score：所需积分
  - amount：现金面值（红利/提现档位）
  - multiplier：流水倍数
  - category：红利业务类别
  - category_title：类别展示名
- item_id/item_title/item_type/item_score：兼容字段（建议优先使用 mallItem）
- cursor：当前记录游标（用于分页）
next_cursor：下一页游标（为本页最后一条的 cursor；若本页为空则为 null）

示例：

curl -G "https://{域名}/api/v1/mall/pointsLogs" \
  -H "token: <muser_token>" \
  --data-urlencode "limit=20"

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、phone、detail_address（完整收货地址，必填）；实物兑换下单快照使用上述字段。

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

可选 lang：zh / ZH / zh-cn 返回中文 msg（默认中文），en / EN 返回英文；可通过请求头、Query 或与本接口 Body 同传的表单字段传入。

建议 Content-Type: application/json，Body 示例：{"token":"..."}。使用 multipart/form-data 时同样只传 token（及可选 lang）即可。

成功返回：

data.session_id
data.user_id
data.username
data.token_expire_at

本地联调（不请求 PlayX）：在 .env 中设置 PLAYX_VERIFY_TOKEN_LOCAL_ONLY=true，并配置：

PLAYX_VERIFY_TOKEN_LOCAL_DEFAULT_USER_ID：写入 mall_session.user_id / 资产 playx_user_id
PLAYX_VERIFY_TOKEN_LOCAL_DEFAULT_USERNAME：写入 mall_session.username 与资产展示名

此时任意（或空）token 均视为验证通过，返回的 user_id / username 以上述环境变量为准。生产环境请保持 PLAYX_VERIFY_TOKEN_LOCAL_ONLY=false 并配置 PLAYX_TOKEN_VERIFY_URL。

6. 常见错误与排查

401 登录态过期：token/session 过期或不匹配；请重新 temLogin 或重新 verifyToken
提示缺少必填字段：按各接口参数补齐（如 claim_request_id、item_id、address_id（实物）、地址中收货人/电话/完整地址等）
积分不足/无可领取积分：locked_points<=0 或已达 today_limit

8.8 KiB Raw Blame History Unescape Escape