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-04-21 16:00:02 +08:00
parent 7b9187fb62
commit ca0a9e75e0
42 changed files with 1178 additions and 438 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,20 +1,20 @@
# 积分商城 PlayX 对接实施方案
# 积分商城 playX 对接实施方案
> 基于《积分商城-内部对接与流程说明.md》和《PlayX-对接文档（积分商城）.md》整理，结合当前项目结构给出具体落地方案。
> 基于《积分商城-内部对接与流程说明.md》和《playX-对接文档（积分商城）.md》整理，结合当前项目结构给出具体落地方案。
---
## 一、接口创建
### 1.1 商城需对外提供的接口（PlayX 调用商城）
### 1.1 商城需对外提供的接口（playX 调用商城）
#### Daily Push API
接收 PlayX 每日 T+1 数据推送。
接收 playX 每日 T+1 数据推送。
* 方法：`POST`
* 路径：`/api/v1/mall/dailyPush`
##### 请求（Header）
当配置了 `playx.daily_push_secret`（Daily Push 签名校验）时，需要携带：
当配置了 `playX.daily_push_secret`（Daily Push 签名校验）时，需要携带：
* `X-Request-Id`：请求 ID
* `X-Timestamp`：时间戳
* `X-Signature`：签名（HMAC_SHA256）
@@ -28,7 +28,7 @@
|------|------|------|------|
| `request_id` | string | 是 | 外部推送请求号（原样返回） |
| `date` | string(YYYY-MM-DD) | 是 | 业务日期（入库到 `mall_playx_daily_push.date`） |
| `user_id` | string | 是 | PlayX 用户 ID（幂等键组成部分） |
| `user_id` | string | 是 | playX 用户 ID（幂等键组成部分） |
| `username` | string | 否 | 展示冗余 |
| `yesterday_win_loss_net` | number | 否 | 昨日净输赢（仅当 `< 0` 时计算新增保障金） |
| `yesterday_total_deposit` | number | 否 | 昨日总充值（用于计算今日可领取上限） |
@@ -81,18 +81,18 @@ curl -X POST 'http://localhost:1818/api/v1/mall/dailyPush' \
---
### 1.2 商城需调用的 PlayX 接口（外部，由 PlayX 提供）
以下为商城侧调用（由 PlayX 提供）。
### 1.2 商城需调用的 playX 接口（外部，由 playX 提供）
以下为商城侧调用（由 playX 提供）。
#### Token Verification API
* 方法：`POST`
* URL：`${playx.api.base_url}${playx.api.token_verify_url}`（默认 `/api/v1/auth/verify-token`）
* URL：`${playX.api.base_url}${playX.api.token_verify_url}`（默认 `/api/v1/auth/verify-token`）
##### 请求 Body
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `request_id` | string | 是 | 服务端生成，如 `mall_{uniqid}` |
| `token` | string | 是 | 前端传入的 PlayX token |
| `token` | string | 是 | 前端传入的 playX token |
##### 返回（期望）
HTTP 状态码 `200`，响应体需包含：
@@ -118,14 +118,14 @@ HTTP 状态码 `200`，响应体需包含：
#### Bonus Grant API
* 方法：`POST`
* URL：`${playx.api.base_url}${playx.api.bonus_grant_url}`（默认 `/api/v1/bonus/grant`）
* URL：`${playX.api.base_url}${playX.api.bonus_grant_url}`（默认 `/api/v1/bonus/grant`）
##### 请求 Body
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `request_id` | string | 是 | 如 `mall_bonus_{uniqid}` |
| `externalTransactionId` | string | 是 | 订单幂等键：`external_transaction_id` |
| `user_id` | string | 是 | PlayX 用户 ID |
| `user_id` | string | 是 | playX 用户 ID |
| `amount` | number | 是 | 订单金额：`MallPlayxOrder.amount` |
| `rewardName` | string | 是 | `mall_item.title` |
| `category` | string | 是 | `mall_item.category`，默认 `daily` |
@@ -169,14 +169,14 @@ HTTP 状态码 `200`，响应体需包含：
#### Balance Credit API
* 方法：`POST`
* URL：`${playx.api.base_url}${playx.api.balance_credit_url}`（默认 `/api/v1/balance/credit`）
* URL：`${playX.api.base_url}${playX.api.balance_credit_url}`（默认 `/api/v1/balance/credit`）
##### 请求 Body
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `request_id` | string | 是 | 如 `mall_withdraw_{uniqid}` |
| `externalTransactionId` | string | 是 | 订单幂等键：`external_transaction_id` |
| `user_id` | string | 是 | PlayX 用户 ID |
| `user_id` | string | 是 | playX 用户 ID |
| `amount` | number | 是 | 订单金额：`MallPlayxOrder.amount` |
| `multiplier` | int | 是 | `MallPlayxOrder.multiplier` |
@@ -215,14 +215,14 @@ HTTP 状态码 `200`，响应体需包含：
#### Transaction Status Query API（交易终态查询）
* 方法：`GET`
* URL：`${playx.api.base_url}${playx.api.transaction_status_url}`（默认 `/api/v1/transaction/status`）
* URL：`${playX.api.base_url}${playX.api.transaction_status_url}`（默认 `/api/v1/transaction/status`）
##### Query
* `externalTransactionId`：订单幂等键
##### 示例（请求）
```bash
curl -G '${playx.api.base_url}/api/v1/transaction/status' \
curl -G '${playX.api.base_url}/api/v1/transaction/status' \
--data-urlencode 'externalTransactionId=BONUS_ORD2026....'
```
@@ -238,7 +238,7 @@ curl -G '${playx.api.base_url}/api/v1/transaction/status' \
示例（failed）：
```json
{ "status": "FAILED", "message": "grant rejected by PlayX" }
{ "status": "FAILED", "message": "grant rejected by playX" }
```
---
@@ -499,7 +499,7 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'session_id=
#### 同步额度
当前代码未实现并未注册路由：`/api/v1/mall/syncLimit`。
如需补齐，请在接口设计阶段新增对应实现与 PlayX API 对接。
如需补齐，请在接口设计阶段新增对应实现与 playX API 对接。
---
@@ -526,7 +526,7 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'session_id=
- 发货：录入物流公司、单号 → `SHIPPED`
- 驳回：录入驳回原因 → `REJECTED`，自动退回积分
- **红利/提现订单**：
- 展示 `external_transaction_id`、推送 playx 状态
- 展示 `external_transaction_id`、推送 playX 状态
- 手动重试：仅对 `FAILED_RETRYABLE` 状态，记录 `retry_request_id`、操作者、原因
### 2.3 用户资产与人工调账
@@ -546,7 +546,7 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'session_id=
**方案 A：改造 mall_player**
- 将 `user_id` 作为主键（PlayX 的 user_id）或与现有 id 并存
- 将 `user_id` 作为主键（playX 的 user_id）或与现有 id 并存
- 新增字段：
- `locked_points`（待领取积分）
- `available_points`（可用积分）
@@ -556,7 +556,7 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'session_id=
**方案 B：新建 mall_playx_user_asset**
- `user_id`（PlayX 用户 ID，主键或唯一）
- `user_id`（playX 用户 ID，主键或唯一）
- `username`（冗余展示）
- `locked_points`、`available_points`、`today_limit`、`today_claimed`、`today_limit_date`
- `create_time`、`update_time`
@@ -613,7 +613,7 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'session_id=
| points_cost | int | 消耗积分 |
| amount | decimal(15,2) | 现金面值（红利/提现） |
| multiplier | int | 流水倍数 |
| external_transaction_id | varchar(64) | 订单号（商城侧幂等/对账主键；Angpow 流程不单独落库 PlayX 内部流水号） |
| external_transaction_id | varchar(64) | 订单号（商城侧幂等/对账主键；Angpow 流程不单独落库 playX 内部流水号） |
| grant_status | enum | NOT_SENT / SENT_PENDING / ACCEPTED / FAILED_RETRYABLE / FAILED_FINAL |
| fail_reason | text | 失败原因 |
| retry_count | int | 重试次数 |
@@ -676,7 +676,7 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'session_id=
## 六、待确认事项
- PlayX 提供的 **Token Verification API**、**Bonus Grant API**、**Balance Credit API**、**交易终态查询 API** 的 URL、鉴权方式、字段最终表
- playX 提供的 **Token Verification API**、**Bonus Grant API**、**Balance Credit API**、**交易终态查询 API** 的 URL、鉴权方式、字段最终表
- `date` 的时区定义（如 UTC+8）
- 返还比例、解锁比例、提现折算的具体数值
- 是否启用「同步额度」功能（需 PlayX 提供对应 API）
- 是否启用「同步额度」功能（需 playX 提供对应 API）