mojiahui/webman-buildadmin-mall
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化接口以及后台页面样式

Browse Source
This commit is contained in:
zhenhui
2026-03-31 15:37:32 +08:00
parent 2868899253
commit 520e950dc5
28 changed files with 1241 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/PlayX-调用积分商城接口说明.md
View File

@@ -12,7 +12,7 @@
将下列路径拼在积分商城对外域名之后，例如：
`https://{商城域名}/api/v1/playx/daily-push`
`https://{商城域名}/api/v1/mall/dailyPush`
（联调时请向商城方索取正式环境与测试环境地址。）
@@ -78,7 +78,7 @@ sequenceDiagram
participant M as 积分商城
Note over PX,M: 按约定配置 HMAC 密钥
PX->>M: POST /api/v1/playx/daily-push（JSON Body）
PX->>M: POST /api/v1/mall/dailyPush（JSON Body）
M-->>PX: code=1, data.accepted / deduped
```
@@ -88,14 +88,14 @@ sequenceDiagram
### 2.2 用户侧（H5 / 内嵌页）→ 商城：会话与业务接口
以下接口多由 **用户在浏览器内**打开积分商城 H5 后调用，通过 **`session_id`**（先调 `verify-token` 获取）或 **`token`**（商城 `muser` 类 token）标识用户，**不一定由 PlayX 后端直接调用**：
以下接口多由 **用户在浏览器内**打开积分商城 H5 后调用，通过 **`session_id`**（先调 `verifyToken` 获取）或 **`token`**（商城 `muser` 类 token）标识用户，**不一定由 PlayX 后端直接调用**：
- `POST /api/v1/playx/verify-token`：用 PlayX token 换商城 `session_id`
- `GET /api/v1/playx/assets`：查询资产
- `POST /api/v1/playx/claim`：领取积分
- `GET /api/v1/playx/items`：商品列表
- `POST /api/v1/playx/bonus/redeem` / `physical/redeem` / `withdraw/apply`：兑换与提现申请
- `GET /api/v1/playx/orders`：订单列表
- `POST /api/v1/mall/verifyToken`：用 PlayX token 换商城 `session_id`
- `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`：订单列表
若 PlayX 后端需要代替用户调用上述接口，须同样携带有效的 `session_id` 或 `token`，并遵守同一用户身份规则（见 **§4 身份说明**）。
@@ -112,7 +112,7 @@ sequenceDiagram
| 项目 | 值 |
|------|-----|
| 方法 | `POST` |
| 路径 | `/api/v1/playx/daily-push` |
| 路径 | `/api/v1/mall/dailyPush` |
### 3.2 鉴权（按商城部署配置，可组合）
@@ -133,7 +133,7 @@ sequenceDiagram
签名原文与计算：
```
canonical = X-Timestamp + "\n" + X-Request-Id + "\nPOST\n/api/v1/playx/daily-push\n" + sha256(json_body)
canonical = X-Timestamp + "\n" + X-Request-Id + "\nPOST\n/api/v1/mall/dailyPush\n" + sha256(json_body)
expected = HMAC_SHA256( canonical , PLAYX_DAILY_PUSH_SECRET )
```
@@ -150,7 +150,7 @@ expected = HMAC_SHA256( canonical , PLAYX_DAILY_PUSH_SECRET )
### 3.3 Body 参数（JSON）
`/api/v1/playx/daily-push` 支持 **两种入参格式**（按字段自动识别）：
`/api/v1/mall/dailyPush` 支持 **两种入参格式**（按字段自动识别）：
#### 格式 A：旧版单条上报（兼容）
| 字段 | 类型 | 必填 | 说明 |
@@ -215,7 +215,7 @@ expected = HMAC_SHA256( canonical , PLAYX_DAILY_PUSH_SECRET )
### 3.6 请求示例
```bash
curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
curl -X POST 'https://{商城域名}/api/v1/mall/dailyPush' \
-H 'Content-Type: application/json' \
-H 'X-Request-Id: req_1700000000_123456' \
-H 'X-Timestamp: 1700000000' \
@@ -279,7 +279,7 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
> 下列均为 **BuildAdmin 通用 `code/msg/time/data` 结构**；成功时 `code=1`。
### 5.1 `POST /api/v1/playx/verify-token`
### 5.1 `POST /api/v1/mall/verifyToken`
用于将 **PlayX token**（或本地联调 token）换 **商城 `session_id`**。
@@ -300,7 +300,7 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
---
### 5.2 `GET /api/v1/playx/assets`
### 5.2 `GET /api/v1/mall/assets`
查询积分资产；需 **§4** 身份。
@@ -316,7 +316,7 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
---
### 5.3 `POST /api/v1/playx/claim`
### 5.3 `POST /api/v1/mall/claim`
领取积分；需 **§4** 身份。
@@ -328,7 +328,7 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
---
### 5.4 `GET /api/v1/playx/items`
### 5.4 `GET /api/v1/mall/items`
商品列表。
@@ -340,7 +340,7 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
---
### 5.5 `POST /api/v1/playx/bonus/redeem`
### 5.5 `POST /api/v1/mall/bonusRedeem`
红利兑换；需 **§4** 身份。
@@ -352,20 +352,18 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
---
### 5.6 `POST /api/v1/playx/physical/redeem`
### 5.6 `POST /api/v1/mall/physicalRedeem`
实物兑换；需 **§4** 身份。
| 参数 | 必填 |
|------|------|
| `item_id` | 是 |
| `receiver_name` | 是 |
| `receiver_phone` | 是 |
| `receiver_address` | 是 |
| 参数 | 必填 | 说明 |
|------|------|------|
| `item_id` | 是 | 实物商品 ID |
| `address_id` | 是 | `mall_address.id`（当前用户下地址）；订单保存 `mall_address_id` 与地址快照 |
---
### 5.7 `POST /api/v1/playx/withdraw/apply`
### 5.7 `POST /api/v1/mall/withdrawApply`
提现类兑换申请；需 **§4** 身份。
@@ -375,7 +373,7 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
---
### 5.8 `GET /api/v1/playx/orders`
### 5.8 `GET /api/v1/mall/orders`
订单列表；需 **§4** 身份。
@@ -389,40 +387,40 @@ curl -X POST 'https://{商城域名}/api/v1/playx/daily-push' \
#### 5.9.1 获取收货地址列表
- **方法**：`GET`
- **路径**：`/api/v1/playx/address/list`
- **路径**：`/api/v1/mall/addressList`
返回 `data.list`：地址数组（按 `default_setting` 优先，其次 id 倒序）。
#### 5.9.2 添加收货地址
- **方法**：`POST`
- **路径**：`/api/v1/playx/address/add`
- **路径**：`/api/v1/mall/addressAdd`
Body（表单或 JSON 均可，建议 JSON）：
| 字段 | 必填 | 说明 |
|------|------|------|
| `receiver_name` | 是 | 收货人 |
| `phone` | 是 | 联系电话 |
| `region` | 是 | 地区（可传数组或逗号分隔字符串） |
| `detail_address` | 是 | 详细地址（短文本） |
| `address` | 是 | 地址补充（可长文本） |
| `default_setting` | 否 | `1` 设为默认地址；`0` 或不传为非默认 |
成功返回：`data.id` 为新地址 id。
#### 5.9.3 修改收货地址（含设置默认）
- **方法**：`POST`
- **路径**：`/api/v1/playx/address/edit`
- **路径**：`/api/v1/mall/addressEdit`
Body：
| 字段 | 必填 | 说明 |
|------|------|------|
| `id` | 是 | 地址 id |
| `phone/region/detail_address/address/default_setting` | 否 | 需要修改的字段（只更新传入项） |
| `receiver_name/phone/region/detail_address/default_setting` | 否 | 需要修改的字段（只更新传入项） |
当 `default_setting=1`：会自动把该用户其他地址的 `default_setting` 置为 0。
#### 5.9.4 删除收货地址
- **方法**：`POST`
- **路径**：`/api/v1/playx/address/delete`
- **路径**：`/api/v1/mall/addressDelete`
Body：
| 字段 | 必填 | 说明 |
@@ -438,7 +436,7 @@ Body：
| 环境变量 / 配置 | 作用 |
|-----------------|------|
| `PLAYX_DAILY_PUSH_SECRET` | 非空则 Daily Push 必须带合法 HMAC 头 |
| `PLAYX_VERIFY_TOKEN_LOCAL_ONLY` | 为 true 时 verify-token 不请求 PlayX 远程 |
| `PLAYX_VERIFY_TOKEN_LOCAL_ONLY` | 为 true 时 verifyToken 不请求 PlayX 远程 |
| `PLAYX_API_BASE_URL` | 商城调用 PlayX 接口时使用（与「PlayX 调商城」方向相反） |
---