[积分商城]优化对接API

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 → 商城）