对接文档-PlayX 调用积分商城接口说明

docs/H5-积分商城接口文档.md

@@ -159,6 +159,47 @@ curl "https://{域名}/api/v1/temLogin?username=test001"
 
 ---
 
+### 3.9 积分流水（领取/兑换/退回）
+
+**GET** ` /api/v1/mall/pointsLogs `
+
+鉴权：携带 `token` 或 `session_id` 或 `user_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）
+
+示例：
+
+```bash
+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`）。

docs/PlayX-对接文档（积分商城）.md

@@ -57,7 +57,7 @@ flowchart LR
 
 ### 4.1 登录鉴权（Iframe + token）
 
-> **接口与字段细节**以代码为准，完整说明见同目录《PlayX-接口文档.md》（§3 H5、§3.2 `temLogin`、§3.3 `verify-token`）。
+> **接口与字段细节**以代码为准，完整说明见同目录《PlayX-接口文档.md》（§3 H5、§3.2 `temLogin`、§3.3 `verifyToken`）。
 
 #### 4.1.1 身份与数据模型（商城侧）
 
@@ -71,7 +71,7 @@ flowchart LR
 
 1. 用户在 PlayX 内打开积分商城入口（iframe）。
 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`）发起校验。
+3. 商城 H5 调用商城后端 **`POST /api/v1/mall/verifyToken`**，由商城向 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）** 调用资产/领取等接口。
@@ -86,9 +86,9 @@ flowchart LR
 用于开发、联调前自测、或 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` 签发）。
+2. 此时 **`/api/v1/mall/verifyToken` 不会访问 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. 再用该 token 调用 **`verifyToken`** 可得到 **`session_id`**，与模式 A 一样供后续接口使用；或直接带 **`token` / `ba-token`** 调资产等接口（见《PlayX-接口文档》§3.1）。
 
 #### 4.1.4 会话续期与前端约定
 
@@ -159,7 +159,7 @@ flowchart LR
 
 - **目的**：推送昨日玩家数据，用于 T+1 计算入池与领取上限。
 - **幂等键**：`user_id + date`（date 建议为 PlayX 业务日）
-- **Method/Path（建议）**：`POST /api/v1/playx/daily-push`
+- **Method/Path（建议）**：`POST /api/v1/mall/dailyPush`
 
 请求字段说明（最小集合，来自现有资料）：
 
@@ -431,7 +431,7 @@ flowchart LR
 
 其中：
 
-- `PATH` 不含域名与 querystring（例如 `/api/v1/playx/daily-push`）。
+- `PATH` 不含域名与 querystring（例如 `/api/v1/mall/dailyPush`）。
 - `REQUEST_BODY_JSON` 使用原始 request body（不做 key 排序时，需双方约定序列化方式；更推荐双方统一为“key 排序后的紧凑 JSON”）。
 
 ## 8. 错误码与可观测（建议）

docs/PlayX-接口文档.md

@@ -823,6 +823,64 @@ curl -G 'http://localhost:1818/api/v1/mall/orders' --data-urlencode 'token=上
 
 ---
 
-### 3.11 同步额度（可选）
+### 3.11 积分流水（Points Logs）
+* 方法：`GET`
+* 路径：`/api/v1/mall/pointsLogs`
+
+#### 请求参数（鉴权）
+同 **3.1**（`session_id` / `token` / `user_id`）。
+
+#### Query 参数
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `limit` | int | 否 | 每页条数，默认 20，最大 100 |
+| `cursor` | string | 否 | 游标（上一页返回 `next_cursor`） |
+| `direction` | string | 否 | `IN` 仅入账 / `OUT` 仅扣减；不传返回全部 |
+
+#### 返回（成功 data）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.list` | array | 流水数组（时间倒序） |
+| `data.next_cursor` | string\|null | 下一页游标（本页最后一条记录的游标） |
+
+`list` 每一项字段：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `biz_type` | string | `CLAIM`/`REDEEM_BONUS`/`REDEEM_PHYSICAL`/`REDEEM_WITHDRAW`/`REFUND` |
+| `direction` | string | `IN`/`OUT` |
+| `points` | int | 积分变动值（正数，方向由 `direction` 表示） |
+| `ts` | int | Unix 秒 |
+| `ref_id` | string | 领取为 `claim_request_id`；订单为 `external_transaction_id` |
+| `order_no` | string | 订单号（非订单类为空） |
+| `order_status` | string | 订单状态（非订单类为空） |
+| `mallItem` | object\|null | 商品信息（非订单类为 null） |
+| `item_id` | int | 兼容字段：商品ID（非订单类为 0） |
+| `item_title` | string | 兼容字段：商品标题（非订单类为空） |
+| `item_type` | int | 兼容字段：商品类型（非订单类为 0；`1=BONUS 2=PHYSICAL 3=WITHDRAW`） |
+| `item_score` | int | 兼容字段：商品所需积分（非订单类为 0） |
+| `cursor` | string | 当前记录游标 |
+
+`mallItem` 字段（非隐私）：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | `mall_item.id` |
+| `title` | string | 商品名 |
+| `type` | int | 商品类型 |
+| `score` | int | 所需积分 |
+| `amount` | number | 现金面值 |
+| `multiplier` | int | 流水倍数 |
+| `category` | string | 红利业务类别 |
+| `category_title` | string | 类别展示名 |
+
+#### 示例
+```bash
+curl -G 'http://localhost:1818/api/v1/mall/pointsLogs' \
+  --data-urlencode 'token=上一步temLogin返回的token' \
+  --data-urlencode 'limit=20'
+```
+
+---
+
+### 3.12 同步额度（可选）
 当前代码未实现并未注册路由：`/api/v1/mall/syncLimit`。
 

docs/积分商城-内部对接与流程说明.md

@@ -270,7 +270,7 @@
 
 ### 6.2 发放请求状态机（商城内部）
 
-针对每个订单（BONUS/WITHDRAW），在商城内部维护发放子状态，例如：
+针对每个订单（BONUS/WITHDRAW），在商城内部维护推送playx状态，例如：
 
 - `NOT_SENT`：未发送给 PlayX。
 - `SENT_PENDING`：已发送，等待 PlayX 响应。
@@ -282,7 +282,7 @@
 
 - 只有在 `NOT_SENT` 或 `FAILED_RETRYABLE` 状态下才允许“再次发送”。
 - 一旦进入 `ACCEPTED`，不得再发请求（自动或人工）。
-- 订单业务状态（PENDING/COMPLETED/REJECTED）与发放子状态之间要有清晰映射：
+- 订单业务状态（PENDING/COMPLETED/REJECTED）与推送playx状态之间要有清晰映射：
   - `ACCEPTED` + 对账确认成功 → `COMPLETED`。
   - `FAILED_FINAL` → `REJECTED`（并退积分）。