[积分商城]优化对接API

2026-03-30 11:47:32 +08:00
parent b30ef21780
commit 4a42899bfe
55 changed files with 835 additions and 1241 deletions
--- a/docs/PlayX-对接文档（积分商城）.md
+++ b/docs/PlayX-对接文档（积分商城）.md
@@ -1,7 +1,7 @@
 ## 0. 交付说明（给 PlayX）

 - **交付物**：本文件（接口清单 + 业务流程 + 联调验收清单）。
- **建议联调顺序**：Token 验证 → 每日推送 → 领取 → 红利发放 → 提现入账 → 实物后台处理。
+- **建议联调顺序**：Token 验证（远程 PlayX 或本地 `verify_token_local_only`）→ 每日推送 → 领取 → 红利发放 → 提现入账 → 实物后台处理。
 - **约定**：接口 URL、字段最终表、签名细节以 PlayX 提供的最终口径为准；本文档负责把流程、幂等、重试与最小字段集合先对齐。

 ## 1. 文档目的与范围
@@ -29,6 +29,8 @@ flowchart LR
  MallBackend -->|"BonusGrantAPI/BalanceCreditAPI"| PlayXBackend
 ```

+> 当 **`playx.verify_token_local_only=true`** 时，「Token 验证」一步在商城内完成，**不经过** `PlayXBackend` 的 Token Verification API；详见 **§4.1**。
+
 ## 3. 关键业务对象与状态机

 ### 3.1 资产口径（最小集合）
@@ -55,17 +57,43 @@ flowchart LR

 ### 4.1 登录鉴权（Iframe + token）

+> **接口与字段细节**以代码为准，完整说明见同目录《PlayX-接口文档.md》（§3 H5、§3.2 `temLogin`、§3.3 `verify-token`）。
+
+#### 4.1.1 身份与数据模型（商城侧）
+
+- **商城用户**：表 `mall_user`（H5 临时登录、后台创建等均落此表）。
+- **PlayX 资产扩展**：表 `mall_playx_user_asset`，与 `mall_user` **一对一**（`mall_user_id`、`playx_user_id` 均唯一）。
+- **业务侧用户标识**：对外接口中的 `user_id`（字符串）在多数场景下即 **`playx_user_id`**（PlayX 玩家 ID）。  
+  - 若用户仅通过商城 **临时登录** 进入、尚无 PlayX 正式 ID，商城会生成占位 ID，形如 **`mall_{mall_user.id}`**，与每日推送中的真实 `user_id` 区分（避免与纯数字 ID 混淆）。
+- **H5 调业务接口时**：服务端内部统一解析为 **`mall_user.id`**，再查资产与订单（解析规则见《PlayX-接口文档》§3.1）。
+
+#### 4.1.2 模式 A：联调 PlayX（生产/预发，远程校验 token）
+
 1. 用户在 PlayX 内打开积分商城入口（iframe）。
-2. PlayX 前端通过 postMessage 发送 `token/session` 给商城前端。
-3. 商城后端调用 PlayX 的 **Token Verification API** 校验 token。
-4. PlayX 返回 `user_id`、`username`（以及会话有效期等）。
-5. 商城建立会话，返回会员资产与商品列表数据。
+2. PlayX 前端通过 postMessage 将 **PlayX 下发的 token**（及必要上下文）传给商城 H5。
+3. 商城 H5 调用商城后端 **`POST /api/v1/playx/verify-token`**，由商城向 PlayX 的 **Token Verification API**（`playx.api.base_url` + `playx.api.token_verify_url`）发起校验。
+4. **前提**：配置 **`playx.verify_token_local_only = false`**，且 **`playx.api.base_url`** 已配置为可访问的 PlayX 基地址。
+5. PlayX 返回 **`user_id`、`username`**（及可选会话过期时间等）。
+6. 商城写入 **`mall_playx_session`**（`session_id` + 上述 `user_id`/`username` + 过期时间），后续 H5 可用 **`session_id`** 或 **`token`（商城临时 token，见模式 B）** 调用资产/领取等接口。

-幂等、安全与会话续期：
+幂等与安全：

- 前端不信任 `user_id` 直传；只接收 token/session。
- Token 验证接口需要签名/鉴权（见第 7 节）。
- **会话续期**：由于玩家访问积分商城可能停留时间较长，当商城调用任意 API 遇到 Token 校验过期（如 HTTP 401）时，商城前端会通过 postMessage 向 PlayX 父级页面请求派发新的 Token 以实现静默续期，请 PlayX 配合予以支持。
+- H5 **不要**把 PlayX 的 `user_id` 当作唯一可信凭据直传下单；**以 token 换 session** 或由商城签发 token 的流程为准。
+- PlayX 侧 Token Verification API 的鉴权/签名（若有）按双方约定（可参考《PlayX-接口文档》§2.1）。
+
+#### 4.1.3 模式 B：本地 / 无 PlayX 环境（商城自校验，不请求 PlayX）
+
+用于开发、联调前自测、或 PlayX 接口未就绪时：
+
+1. 配置 **`playx.verify_token_local_only = true`**（环境变量 **`PLAYX_VERIFY_TOKEN_LOCAL_ONLY`**，默认可为开启，以项目 `config/playx.php` 为准）。
+2. 此时 **`/api/v1/playx/verify-token` 不会访问 PlayX**，仅在商城内校验 **商城临时 token**（token 表类型 **`muser`**，由下方 `temLogin` 签发）。
+3. 调用 **`GET/POST /api/v1/temLogin?username=...`**（需 **`buildadmin.agent_auth.temp_login_enable = true`**）：不存在则创建 **`mall_user`**，并保证存在 **`mall_playx_user_asset`**（含 `playx_user_id`，默认 **`mall_{id}`**），返回 **`userInfo.token`**、**`playx_user_id`**、**`expires_in`** 等。
+4. 再用该 token 调用 **`verify-token`** 可得到 **`session_id`**，与模式 A 一样供后续接口使用；或直接带 **`token` / `ba-token`** 调资产等接口（见《PlayX-接口文档》§3.1）。
+
+#### 4.1.4 会话续期与前端约定
+
+- **会话续期**：玩家停留时间较长时，若商城 API 返回 token/session 失效（如 401），H5 可通过 postMessage 请 PlayX 父页面 **重新派发 PlayX token**（模式 A）；模式 B 下可重新 **`temLogin`** 或走 **`/api/common/refreshToken`**（`muser-refresh`）换取新 access token。
+- 具体错误码与 Header（如 `ba-token`）以前端与《PlayX-接口文档》为准。

 ### 4.2 每日 T+1 入池（PlayX → 商城）

--- a/docs/PlayX-接口文档.md
+++ b/docs/PlayX-接口文档.md
@@ -1,6 +1,6 @@
 # PlayX 接口文档（按调用方向拆分）

-说明：本文档严格依据当前代码 `app/api/controller/v1/Playx.php` 与定时任务 `app/process/PlayxJobs.php` 整理。
+说明：本文档严格依据当前代码 `app/api/controller/v1/Playx.php`、`app/api/controller/v1/Auth.php`（临时登录）、`config/playx.php` 与定时任务 `app/process/PlayxJobs.php` 整理。

 三类接口分别为：
 - `积分商城 -> PlayX`（PlayX 调用商城）
@@ -31,8 +31,8 @@
 |------|------|------|------|
 | `request_id` | string | 是 | 外部推送请求号（原样返回） |
 | `date` | string(YYYY-MM-DD) | 是 | 业务日期（入库到 `mall_playx_daily_push.date`） |
-| `user_id` | string | 是 | PlayX 用户 ID（用于幂等） |
-| `username` | string | 否 | 展示冗余 |
+| `user_id` | string | 是 | PlayX 用户 ID（用于幂等；入库 `mall_playx_daily_push.user_id` 等；服务端会映射/创建 `mall_user` 与 `mall_playx_user_asset`） |
+| `username` | string | 否 | 展示冗余（同步到商城用户侧逻辑时使用） |
 | `yesterday_win_loss_net` | number | 否 | 昨日净输赢（仅当 `< 0` 时计算新增保障金） |
 | `yesterday_total_deposit` | number | 否 | 昨日总充值（用于计算今日可领取上限） |
 | `lifetime_total_deposit` | number | 否 | 历史总充值 |
@@ -101,9 +101,10 @@ curl -X POST 'http://localhost:1818/api/v1/playx/daily-push' \

 ## 2. PlayX -> 积分商城（商城调用 PlayX）

-> 下面这些接口由 PlayX 提供。商城侧仅按“请求参数 + 期望返回判定条件”发起调用与处理结果。
+> 下面这些接口由 PlayX 提供。商城侧仅按“请求参数 + 期望返回判定条件”发起调用与处理结果。  
+> **说明**：H5 调商城的 **`/api/v1/playx/verify-token`** 在配置 **`playx.verify_token_local_only=true`**（默认）时**不会请求**本节接口，而是在商城内校验 `muser` token；远程对接 PlayX 时见 **3.3** 与下文 **2.1**。

-### 2.1 Token Verification API
+### 2.1 Token Verification API（PlayX 侧实现，远程验证时使用）
 * 方法：`POST`
 * URL：`${playx.api.base_url}${playx.api.token_verify_url}`
  * 默认：`/api/v1/auth/verify-token`
@@ -257,48 +258,134 @@ curl -X POST 'http://localhost:1818/api/v1/playx/daily-push' \

 ## 3. 积分商城 -> H5（服务端提供给 H5 的接口）

-说明：鉴权与用户解析规则由 `resolveUserIdFromRequest()` 决定。
-* 优先使用 `session_id`（在 `mall_playx_session` 查到且未过期）
-* 其次使用 `user_id`
+### 3.0 数据模型说明（与代码一致）

-公共鉴权字段：
-* `session_id`：字符串
-* `user_id`：字符串
+* **商城用户**：表 `mall_user`（主键 `id`）。
+* **PlayX 资产扩展**：表 `mall_playx_user_asset`，与 `mall_user` **一对一**（`mall_user_id` 唯一，`playx_user_id` 唯一）。
+* **对外业务 ID**：接口里返回或订单里使用的 `user_id` 字符串多为 **PlayX 侧用户 ID**（`playx_user_id`）；H5 临时登录场景若尚无真实 PlayX ID，会生成形如 **`mall_{mall_user.id}`** 的占位 ID（见 `temLogin`）。
+* **服务端内部**：`Playx` 控制器内部用 **`mall_user.id`**（整型）解析资产；`session_id` / `token` / `user_id` 会映射到该 `mall_user`。
+
+### 3.1 鉴权解析规则（`resolveMallUserIdFromRequest`）
+
+以下接口在服务端最终都会解析出 **商城用户 `mall_user.id`**，再按该用户查询 `mall_playx_user_asset` 等。
+
+优先级（由高到低）：
+
+1. **`session_id`**（`post` 优先，`get` 兼容）  
+   * 在 `mall_playx_session` 中存在且未过期：用会话里的 `user_id`（即 `playx_user_id`）在 `mall_playx_user_asset` 反查 `mall_user_id`。  
+   * 若会话无效：兼容把 `session_id` 参数误当作 **商城 token** 再试一次（UUID 形态 token）。
+2. **`token`**（`post` / `get` 或请求头 **`ba-token`** / **`token`**）  
+   * 校验 `token` 表：类型为会员 `user` 或商城临时 **`muser`**（`mall_user` 登录），未过期则 `user_id` 字段即为 **`mall_user.id`**。
+3. **`user_id`**（`post` / `get` 兼容）  
+   * **纯数字**：视为 **`mall_user.id`**。  
+   * **非纯数字**：视为 **`playx_user_id`**，在 `mall_playx_user_asset` 查找对应 `mall_user_id`。

 > 注意：请求参数的取值方式是 `post()` 优先，`get()` 兼容（即同字段既可传 post 也可传 get）。

 ---

-### 3.1 Token 验证
-* 方法：`POST`
+### 3.2 临时登录（获取商城 token）
+
+* 方法：`GET`（推荐）或 `POST`
+* 路径：`/api/v1/temLogin`
+* 开关：`config/buildadmin.php` → `agent_auth.temp_login_enable` 为 `true`；有效期 `agent_auth.temp_login_expire`（秒）。
+
+#### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `username` | string | 是 | 商城用户名（唯一）；不存在则自动创建 `mall_user` |
+
+#### 行为说明
+
+* 若 `mall_user` 不存在：创建用户（随机占位手机号、随机密码等，与后台「商城用户」一致）。
+* **无论是否新用户**：保证存在 **`mall_playx_user_asset`** 一条记录（`MallPlayxUserAsset::ensureForMallUser`），`playx_user_id` 默认 **`mall_{mall_user.id}`**（与 PlayX 真实 ID 冲突概率低）。
+* 签发 **商城 token**（类型 **`muser`**，非会员表 `user`），并签发 `muser-refresh` 刷新令牌。
+
+#### 返回（成功 data.userInfo）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | `mall_user.id` |
+| `username` | string | 用户名 |
+| `nickname` | string | 同 `username` |
+| `playx_user_id` | string | 资产表中的 `playx_user_id`（如 `mall_12`） |
+| `token` | string | 访问 H5 接口时携带 |
+| `refresh_token` | string | 调用 `/api/common/refreshToken` 时使用（类型 `muser-refresh`） |
+| `expires_in` | int | token 有效秒数 |
+
+#### 示例
+
+```bash
+curl -G 'http://localhost:1818/api/v1/temLogin' --data-urlencode 'username=demo_h5'
+```
+
+用户名含 `+` 等号时需 URL 编码（如 `%2B60123456789`）。
+
+---
+
+### 3.3 Token 验证（换 session）
+
+* 方法：`POST`（推荐 `GET` 传 `token` 亦可）
 * 路径：`/api/v1/playx/verify-token`

-#### 请求 Body
+#### 配置：本地验证 vs 远程 PlayX
+
+* 配置项：`config/playx.php` → **`verify_token_local_only`**（环境变量 **`PLAYX_VERIFY_TOKEN_LOCAL_ONLY`**，未设置时默认为 **`1` / 开启本地验证）。
+* **`verify_token_local_only = true`（默认）**  
+  * **不请求** PlayX HTTP。  
+  * 仅接受商城临时登录 token（类型 **`muser`**），校验 `token` 表后，根据 `mall_user` 与 `mall_playx_user_asset` 写入 `mall_playx_session`。  
+  * 返回的 `data.user_id` 为 **`playx_user_id`**（无资产记录时回退为 `mall_user.id` 字符串，一般 temLogin 后已有资产）。
+* **`verify_token_local_only = false`**（生产对接 PlayX）  
+  * 需配置 **`playx.api.base_url`**，由商城向 PlayX 发起 `POST` 校验（见下文「远程模式」）。  
+  * 若未配置 `base_url`，返回 `PlayX API not configured`。
+
+#### 请求参数
+
 必填其一：
-* `token`（优先读取）
-* `session`（兼容字段，当 `token` 为空时会被当作 token）
+
+* `token`（Body 优先；`session` 兼容字段；Query 也可传 `token`）

 #### 返回（成功 data）
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `session_id` | string | 写入 `mall_playx_session` |
-| `user_id` | string | PlayX 用户 ID |
+| `user_id` | string | PlayX 用户 ID（即 `playx_user_id`，会话内与订单/推送一致） |
 | `username` | string | 用户名 |
 | `token_expire_at` | string | ISO 字符串（服务端 `date('c', expireAt)`） |

 失败：
-* token 为空：HTTP 401，msg=`INVALID_TOKEN`
-* PlayX 未配置：msg=`PlayX API not configured`

-#### 示例
-请求：
+* token 为空：HTTP 401，msg=`INVALID_TOKEN`
+* 远程模式且 PlayX 未配置：`msg=PlayX API not configured`
+
+#### 示例（本地验证）
+
 ```bash
 curl -X POST 'http://localhost:1818/api/v1/playx/verify-token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
-  --data-urlencode 'token=PLAYX_TOKEN_XXX'
+  --data-urlencode 'token=上一步TemLogin返回的token'
 ```

+#### 远程模式（`verify_token_local_only=false` + 已配置 `base_url`）
+
+商城侧请求 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 |
+
+#### 返回（期望）——仅远程模式
+
+* HTTP 状态码必须为 `200`
+* 且响应体中必须包含 `user_id`
+
 响应（成功示例）：
+
 ```json
 {
  "code": 1,
@@ -314,13 +401,17 @@ curl -X POST 'http://localhost:1818/api/v1/playx/verify-token' \

 ---

-### 3.2 用户资产
+### 3.4 用户资产（Assets）
 * 方法：`GET`
 * 路径：`/api/v1/playx/assets`

 #### 请求参数（鉴权）
-* `session_id`（优先）
-* `user_id`（兼容）
+
+以下任选其一即可（与 **3.1 鉴权解析规则** 一致）：
+
+* `session_id`
+* `token`（或请求头 `ba-token` / `token`）
+* `user_id`（纯数字为 `mall_user.id`，否则为 `playx_user_id`）

 #### 返回（成功 data）
 若未找到资产：返回 0。
@@ -334,7 +425,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/playx/assets' --data-urlencode 'token=上一步temLogin返回的token'
 ```

 响应（示例）：
@@ -355,15 +446,16 @@ curl -G 'http://localhost:1818/api/v1/playx/assets' --data-urlencode 'session_id

 ---

-### 3.3 领取（Claim）
+### 3.5 领取（Claim）
 * 方法：`POST`
 * 路径：`/api/v1/playx/claim`

 #### 请求 Body
 必填：
+
 * `claim_request_id`：幂等键（string，唯一）
-鉴权：
-* `session_id` 或 `user_id`
+
+鉴权：同 **3.1**（`session_id` / `token` / `user_id`）

 #### 返回（成功 data）
 与 `用户资产` 返回字段一致（资产快照）。
@@ -376,7 +468,7 @@ curl -G 'http://localhost:1818/api/v1/playx/assets' --data-urlencode 'session_id
 curl -X POST 'http://localhost:1818/api/v1/playx/claim' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'claim_request_id=claim_001' \
-  --data-urlencode 'session_id=7b1c....'
+  --data-urlencode 'token=上一步temLogin返回的token'
 ```

 响应（首次领取，示例）：
@@ -413,7 +505,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/claim' \

 ---

-### 3.4 商品列表
+### 3.6 商品列表
 * 方法：`GET`
 * 路径：`/api/v1/playx/items`

@@ -456,15 +548,14 @@ curl -G 'http://localhost:1818/api/v1/playx/items' --data-urlencode 'type=WITHDR

 ---

-### 3.5 红利兑换（Bonus Redeem）
+### 3.7 红利兑换（Bonus Redeem）
 * 方法：`POST`
 * 路径：`/api/v1/playx/bonus/redeem`

 #### 请求 Body
 必填：
 * `item_id`：商品 ID（要求 `mall_item.type=BONUS` 且 `status=1`）
-鉴权：
-* `session_id` 或 `user_id`
+鉴权：同 **3.1**（`session_id` / `token` / `user_id`）

 #### 返回（成功）
 * `msg`：`Redeem submitted, please wait about 10 minutes`
@@ -494,7 +585,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/bonus/redeem' \

 ---

-### 3.6 实物兑换（Physical Redeem）
+### 3.8 实物兑换（Physical Redeem）
 * 方法：`POST`
 * 路径：`/api/v1/playx/physical/redeem`

@@ -504,8 +595,7 @@ curl -X POST 'http://localhost:1818/api/v1/playx/bonus/redeem' \
 * `receiver_name`：收货人
 * `receiver_phone`：收货电话
 * `receiver_address`：收货地址
-鉴权：
-* `session_id` 或 `user_id`
+鉴权：同 **3.1**（`session_id` / `token` / `user_id`）

 #### 返回（成功）
 * `msg`：`Redeem success`
@@ -534,15 +624,14 @@ curl -X POST 'http://localhost:1818/api/v1/playx/physical/redeem' \

 ---

-### 3.7 提现申请（Withdraw Apply）
+### 3.9 提现申请（Withdraw Apply）
 * 方法：`POST`
 * 路径：`/api/v1/playx/withdraw/apply`

 #### 请求 Body
 必填：
 * `item_id`：商品 ID（要求 `mall_item.type=WITHDRAW` 且 `status=1`）
-鉴权：
-* `session_id` 或 `user_id`
+鉴权：同 **3.1**（`session_id` / `token` / `user_id`）

 #### 返回（成功）
 * `msg`：`Withdraw submitted, please wait about 10 minutes`
@@ -572,20 +661,23 @@ curl -X POST 'http://localhost:1818/api/v1/playx/withdraw/apply' \

 ---

-### 3.8 订单列表
+### 3.10 订单列表
 * 方法：`GET`
 * 路径：`/api/v1/playx/orders`

-#### 请求参数
-* `session_id` 或 `user_id`
+#### 请求参数（鉴权）
+
+同 **3.1**（`session_id` / `token` / `user_id`）。

 #### 返回（成功 data）
+
 * `list`：订单列表（最多 100 条），并包含关联的 `mallItem`（关系对象）
+* 列表项中的 `user_id` 为 **PlayX 侧 `playx_user_id`**（字符串），与 `mall_playx_order.user_id` 一致

 #### 示例
 请求：
 ```bash
-curl -G 'http://localhost:1818/api/v1/playx/orders' --data-urlencode 'session_id=7b1c....'
+curl -G 'http://localhost:1818/api/v1/playx/orders' --data-urlencode 'token=上一步temLogin返回的token'
 ```

 响应（示例，简化）：
@@ -619,6 +711,6 @@ curl -G 'http://localhost:1818/api/v1/playx/orders' --data-urlencode 'session_id

 ---

-### 3.9 同步额度（可选）
+### 3.11 同步额度（可选）
 当前代码未实现并未注册路由：`/api/v1/playx/sync-limit`。