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

93
docs/积分商城-PlayX对接实施方案.md
View File

@@ -11,7 +11,7 @@
接收 PlayX 每日 T+1 数据推送。
* 方法：`POST`
* 路径：`/api/v1/playx/daily-push`
* 路径：`/api/v1/mall/dailyPush`
##### 请求（Header）
当配置了 `playx.daily_push_secret`（Daily Push 签名校验）时，需要携带：
@@ -20,7 +20,7 @@
* `X-Signature`：签名（HMAC_SHA256）
签名计算逻辑（服务端）：
* 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：`hash_hmac('sha256', canonical, daily_push_secret)`
##### 请求（Body）
@@ -51,7 +51,7 @@
##### 示例
无签名校验（`PLAYX_DAILY_PUSH_SECRET` 为空）：
```bash
curl -X POST 'http://localhost:1818/api/v1/playx/daily-push' \
curl -X POST 'http://localhost:1818/api/v1/mall/dailyPush' \
-H 'Content-Type: application/json' \
-d '{
"request_id":"req_1001",
@@ -246,7 +246,7 @@ curl -G '${playx.api.base_url}/api/v1/transaction/status' \
### 1.3 商城内部 API（供 H5 前端调用）
#### Token 验证
* 方法：`POST`
* 路径：`/api/v1/playx/verify-token`
* 路径：`/api/v1/mall/verifyToken`
请求（Body）：
* `token`（必填，优先读取）
@@ -260,14 +260,14 @@ curl -G '${playx.api.base_url}/api/v1/transaction/status' \
示例：
```bash
curl -X POST 'http://localhost:1818/api/v1/playx/verify-token' \
curl -X POST 'http://localhost:1818/api/v1/mall/verifyToken' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=PLAYX_TOKEN_XXX'
```
#### 用户资产
* 方法：`GET`
* 路径：`/api/v1/playx/assets`
* 路径：`/api/v1/mall/assets`
请求参数（二选一）：
* `session_id`（优先）：从 `mall_playx_session` 查 user_id（并校验过期）
@@ -282,7 +282,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/verify-token' \
##### 示例
```bash
curl -G 'http://localhost:1818/api/v1/playx/assets' --data-urlencode 'session_id=7b1c....'
curl -G 'http://localhost:1818/api/v1/mall/assets' --data-urlencode 'session_id=7b1c....'
```
```json
@@ -301,7 +301,7 @@ curl -G 'http://localhost:1818/api/v1/playx/assets' --data-urlencode 'session_id
#### 领取（Claim）
* 方法：`POST`
* 路径：`/api/v1/playx/claim`
* 路径：`/api/v1/mall/claim`
请求：
* `claim_request_id`：幂等键（string，必填且唯一）
@@ -312,7 +312,7 @@ curl -G 'http://localhost:1818/api/v1/playx/assets' --data-urlencode 'session_id
##### 示例
（首次领取成功，可能返回 `msg=Claim success`；若幂等重复，`msg` 可能为空）
```bash
curl -X POST 'http://localhost:1818/api/v1/playx/claim' \
curl -X POST 'http://localhost:1818/api/v1/mall/claim' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'claim_request_id=claim_001' \
--data-urlencode 'session_id=7b1c....'
@@ -334,7 +334,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/claim' \
#### 商品列表
* 方法：`GET`
* 路径：`/api/v1/playx/items`
* 路径：`/api/v1/mall/items`
请求（可选）：
* `type=BONUS|PHYSICAL|WITHDRAW`
@@ -344,7 +344,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/claim' \
##### 示例
```bash
curl -G 'http://localhost:1818/api/v1/playx/items' --data-urlencode 'type=BONUS'
curl -G 'http://localhost:1818/api/v1/mall/items' --data-urlencode 'type=BONUS'
```
```json
@@ -370,7 +370,7 @@ curl -G 'http://localhost:1818/api/v1/playx/items' --data-urlencode 'type=BONUS'
#### 红利兑换（Bonus Redeem）
* 方法：`POST`
* 路径：`/api/v1/playx/bonus/redeem`
* 路径：`/api/v1/mall/bonusRedeem`
请求：
* `item_id`：商品 ID（BONUS）
@@ -382,7 +382,7 @@ curl -G 'http://localhost:1818/api/v1/playx/items' --data-urlencode 'type=BONUS'
##### 示例
```bash
curl -X POST 'http://localhost:1818/api/v1/playx/bonus/redeem' \
curl -X POST 'http://localhost:1818/api/v1/mall/bonusRedeem' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'item_id=123' \
--data-urlencode 'session_id=7b1c....'
@@ -401,13 +401,11 @@ curl -X POST 'http://localhost:1818/api/v1/playx/bonus/redeem' \
#### 实物兑换（Physical Redeem）
* 方法：`POST`
* 路径：`/api/v1/playx/physical/redeem`
* 路径：`/api/v1/mall/physicalRedeem`
请求：
* `item_id`：商品 ID（PHYSICAL）
* `receiver_name`
* `receiver_phone`
* `receiver_address`
* `address_id`：`mall_address.id`（当前用户资产下地址；订单写入 `mall_address_id` 与收货快照）
* 鉴权：`session_id` 或 `user_id`
成功返回：
@@ -416,12 +414,10 @@ curl -X POST 'http://localhost:1818/api/v1/playx/bonus/redeem' \
##### 示例
```bash
curl -X POST 'http://localhost:1818/api/v1/playx/physical/redeem' \
curl -X POST 'http://localhost:1818/api/v1/mall/physicalRedeem' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'item_id=200' \
--data-urlencode 'receiver_name=张三' \
--data-urlencode 'receiver_phone=18800001111' \
--data-urlencode 'receiver_address=北京市朝阳区XX路XX号' \
--data-urlencode 'address_id=10' \
--data-urlencode 'session_id=7b1c....'
```
@@ -435,7 +431,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/physical/redeem' \
#### 提现申请（Withdraw Apply）
* 方法：`POST`
* 路径：`/api/v1/playx/withdraw/apply`
* 路径：`/api/v1/mall/withdrawApply`
请求：
* `item_id`：商品 ID（WITHDRAW）
@@ -447,7 +443,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/physical/redeem' \
##### 示例
```bash
curl -X POST 'http://localhost:1818/api/v1/playx/withdraw/apply' \
curl -X POST 'http://localhost:1818/api/v1/mall/withdrawApply' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'item_id=321' \
--data-urlencode 'session_id=7b1c....'
@@ -466,7 +462,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/withdraw/apply' \
#### 订单列表
* 方法：`GET`
* 路径：`/api/v1/playx/orders`
* 路径：`/api/v1/mall/orders`
请求：
* `session_id` 或 `user_id`
@@ -476,7 +472,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/withdraw/apply' \
##### 示例
```bash
curl -G 'http://localhost:1818/api/v1/playx/orders' --data-urlencode 'session_id=7b1c....'
curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'session_id=7b1c....'
```
```json
@@ -502,7 +498,7 @@ curl -G 'http://localhost:1818/api/v1/playx/orders' --data-urlencode 'session_id
```
#### 同步额度
当前代码未实现并未注册路由：`/api/v1/playx/sync-limit`。
当前代码未实现并未注册路由：`/api/v1/mall/syncLimit`。
如需补齐，请在接口设计阶段新增对应实现与 PlayX API 对接。
---
@@ -607,29 +603,30 @@ curl -G 'http://localhost:1818/api/v1/playx/orders' --data-urlencode 'session_id
**表名**：`mall_playx_order`（或统一改造 mall_pints_order / mall_redemption_order）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键 |
| user_id | varchar(64) | 用户 ID |
| type | enum | BONUS / PHYSICAL / WITHDRAW |
| status | enum | PENDING / COMPLETED / SHIPPED / REJECTED |
| mall_item_id | int | 商品 ID |
| points_cost | int | 消耗积分 |
| amount | decimal(15,2) | 现金面值（红利/提现） |
| multiplier | int | 流水倍数 |
| external_transaction_id | varchar(64) | 外部交易幂等键 |
| playx_transaction_id | varchar(64) | PlayX 流水号 |
| 字段 | 类型 | 说明 |
|------|------|----------------------------------------------------------------------|
| id | int | 主键 |
| user_id | varchar(64) | 用户 ID |
| type | enum | BONUS / PHYSICAL / WITHDRAW |
| status | enum | PENDING / COMPLETED / SHIPPED / REJECTED |
| mall_item_id | int | 商品 ID |
| points_cost | int | 消耗积分 |
| amount | decimal(15,2) | 现金面值（红利/提现） |
| multiplier | int | 流水倍数 |
| external_transaction_id | varchar(64) | 订单号 |
| playx_transaction_id | varchar(64) | PlayX 流水号 |
| grant_status | enum | NOT_SENT / SENT_PENDING / ACCEPTED / FAILED_RETRYABLE / FAILED_FINAL |
| fail_reason | text | 失败原因 |
| retry_count | int | 重试次数 |
| reject_reason | varchar(255) | 驳回原因（实物） |
| shipping_company | varchar(50) | 物流公司 |
| shipping_no | varchar(64) | 物流单号 |
| receiver_name | varchar(50) | 收货人 |
| receiver_phone | varchar(20) | 收货电话 |
| receiver_address | text | 收货地址 |
| create_time | bigint | 创建时间 |
| update_time | bigint | 更新时间 |
| fail_reason | text | 失败原因 |
| retry_count | int | 重试次数 |
| reject_reason | varchar(255) | 驳回原因（实物） |
| shipping_company | varchar(50) | 物流公司 |
| shipping_no | varchar(64) | 物流单号 |
| mall_address_id | int unsigned, NULL | 实物兑换所选 `mall_address.id`（快照仍见 `receiver_*`） |
| receiver_name | varchar(50) | 收货人 |
| receiver_phone | varchar(20) | 收货电话 |
| receiver_address | text | 收货地址 |
| create_time | bigint | 创建时间 |
| update_time | bigint | 更新时间 |
**索引**：`user_id`、`external_transaction_id`、`type`、`status`