245 lines
11 KiB
Markdown
245 lines
11 KiB
Markdown
---
|
||
name: Provider Callback Log
|
||
overview: 在 slot-pwa 按分库分表（对齐 GameResultLogModel）落地 game_provider_callback_log_{NN}，并实现 POP 回调全链路（收包落库 → 验签/解析/处理状态）。其余厂商后续 PR 扩展。
|
||
todos:
|
||
- id: shard-ddl-model
|
||
content: CreateSharedTable 增加 callback_log 分表 DDL；shard/GameProviderCallbackLogModel + Params + IdGenerator
|
||
status: completed
|
||
- id: callback-service
|
||
content: ProviderCallbackLogService（按 shardUid 路由）+ config/game_gateway.php
|
||
status: completed
|
||
- id: pop-middleware
|
||
content: ProviderCallbackLogMiddleware + pop 中间件链 + POPAuthMiddleware 验签回写
|
||
status: completed
|
||
- id: pop-logic
|
||
content: CashLogic/CashController parse/process 状态（含重复 tid、BALANCE）
|
||
status: completed
|
||
- id: tests
|
||
content: Feature 测试（shard 写入/更新）+ docker phpunit；verify-slot-backend.sh
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# Provider 原始回调日志（02）实现计划
|
||
|
||
## 范围（已确认）
|
||
|
||
- **本期**：分库分表 DDL + Shard Model/Service + POP 两条路由接入 + PHPUnit
|
||
- **后续 PR**：gasea / quick / jsgame / bbgt / jdb
|
||
|
||
**明确不做**（属 [03_provider_tx.md](docs/requirements/game_gateway/03_provider_tx.md)）：`game_provider_tx_01`、wallet 改造、Round 聚合。
|
||
|
||
**文档与 DDL**：已与 [02 §4.1](docs/requirements/game_gateway/02_provider_callback_log.md)、[`slot-pwa/db/game_provider_callback_log_shard.sql`](slot-pwa/db/game_provider_callback_log_shard.sql) 对齐（无 `gateway_version`；含分库分表说明）。
|
||
|
||
---
|
||
|
||
## 现状与约束
|
||
|
||
| 项 | 现状 |
|
||
|---|---|
|
||
| POP 路由 | [`config/route.php`](slot-pwa/config/route.php) `/pop/Cash/Get`、`/pop/Cash/TransferInOut` |
|
||
| POP 验签 | [`POPAuthMiddleware`](slot-pwa/app/middleware/POPAuthMiddleware.php) 验签在 Controller 前 |
|
||
| **分表参考（本期主参考）** | [`app/model/shard/GameResultLogModel.php`](slot-pwa/app/model/shard/GameResultLogModel.php) + [`CreateSharedTable`](slot-pwa/app/command/CreateSharedTable.php) |
|
||
| 非分表参考 | [`GameLaunchSessionModel`](slot-pwa/app/model/game/GameLaunchSessionModel.php) 仅用于 Launch Session，**不**用于 callback_log |
|
||
| ID 生成 | [`IdGenerator::nextGameResultId()`](slot-pwa/app/service/IdGenerator.php) 同款 Redis 序号 + 毫秒时间戳 |
|
||
|
||
需求文档表名 `game_provider_callback_log_01` 表示**逻辑表前缀**；物理表为 `user_transaction_{dbNN}.game_provider_callback_log_{tableNN}`（与 `game_result_log_{NN}` 同库族）。
|
||
|
||
---
|
||
|
||
## 分库分表设计
|
||
|
||
### 路由规则（对齐 GameResultLog）
|
||
|
||
```php
|
||
// GameResultLogModel
|
||
getPreDatabase() => 'user_transaction'
|
||
getPreTable() => 'game_provider_callback_log' // 物理表 game_provider_callback_log_01..NN
|
||
getShardKey() => 'uid'
|
||
```
|
||
|
||
- 构造：`new GameProviderCallbackLogModel($shardUid)`，由 [`ShardService`](slot-pwa/app/service/ShardService.php) `crc32($shardUid) % (库数×表数)` 定位库表。
|
||
- 写入：[`insertData()`](slot-pwa/app/model/shard/SelfBaseModel.php)（同 `TransactionLog::insertGameResult`）。
|
||
- 更新：[`updateByWhere()`](slot-pwa/app/model/shard/SelfBaseModel.php)，条件必须含 `id` + `uid`（分片键），例如 `['id' => $id, 'uid' => $shardUid]`。
|
||
|
||
### 分片键 `uid` 的选取（收包时）
|
||
|
||
| 场景 | shardUid |
|
||
|------|----------|
|
||
| POP 已带 `userid` | `(int) post.userid` |
|
||
| 尚未解析 / 验签失败但 body 无 uid | `0`（需求允许 `uid=0`，仍落同一分片桶，保留审计） |
|
||
| 解析成功后 uid 与收包时不一致 | **不迁移分片**；仅 `UPDATE` 修正行内 `uid` 等业务字段（行已在收包分片，避免跨库搬家） |
|
||
|
||
**Request 上下文**（Middleware 写入，Logic/Middleware 读取）：
|
||
|
||
- `providerCallbackLogId` — 雪花主键
|
||
- `providerCallbackShardUid` — 分片键，后续所有 UPDATE 必带
|
||
|
||
### 与 `GameResultLog` 的差异
|
||
|
||
| 项 | GameResultLog | callback_log |
|
||
|----|---------------|----------------|
|
||
| 汇总库 `s_all.*` | 有 [`app/model/all/GameResultLogModel`](slot-pwa/app/model/all/GameResultLogModel.php) + MQ 同步 | **本期不做**（无跨分片报表需求；后续若要全局检索再加 DBSync） |
|
||
| 字段 | 精简结果字段 | 需求全文：raw_body/headers、验签/解析/处理状态等 |
|
||
|
||
---
|
||
|
||
## 处理顺序
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Provider
|
||
participant LogMW as ProviderCallbackLogMiddleware
|
||
participant PopAuth as POPAuthMiddleware
|
||
participant Logic as CashLogic
|
||
participant Shard as user_transaction_XX.game_provider_callback_log_YY
|
||
|
||
Provider->>LogMW: POST
|
||
LogMW->>LogMW: resolveShardUid from post
|
||
LogMW->>Shard: INSERT id=nextProviderCallbackLogId
|
||
LogMW->>PopAuth: request + logId + shardUid
|
||
PopAuth->>Shard: UPDATE verify_status
|
||
PopAuth->>Logic: handler
|
||
Logic->>Shard: UPDATE parse/process
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 数据库（分表 DDL）
|
||
|
||
### 修改 [`CreateSharedTable`](slot-pwa/app/command/CreateSharedTable.php)
|
||
|
||
在 `createShareTable()` 循环内、`createGameResultTable()` 之后增加 `createGameProviderCallbackLogTable($db, $num)`：
|
||
|
||
- 库：`user_transaction_01` … `user_transaction_{share_database_num}`
|
||
- 表：`game_provider_callback_log_01` … `game_provider_callback_log_{share_table_num}`
|
||
- 字段/索引以 [02 §4.1](docs/requirements/game_gateway/02_provider_callback_log.md) 为准，**除外**：不建 `gateway_version`、不建 `idx_gateway_version`；其余 KEY（`idx_provider_tx`、`idx_round`、`idx_uid_received`、`idx_body_hash`、`idx_process_status`）保留
|
||
- 主键 `id` **非自增**，应用写入 `IdGenerator::nextProviderCallbackLogId()`
|
||
|
||
### 参考 SQL（文档用，非单库执行）
|
||
|
||
新增 [`slot-pwa/db/game_provider_callback_log_shard.sql`](slot-pwa/db/game_provider_callback_log_shard.sql)：单分片模板 + 注释说明需通过 `php webman createSharedTable`（或项目既有命令）批量建表。
|
||
|
||
部署：`docker exec ... php webman createSharedTable`（与现有 `user_transaction_log` / `game_result_log` 相同流程）。
|
||
|
||
---
|
||
|
||
## 2. 配置
|
||
|
||
[`config/game_gateway.php`](slot-pwa/config/game_gateway.php)：
|
||
|
||
| 配置项 | 用途 |
|
||
|--------|------|
|
||
| `callback_request_id_prefix` | 如 `creq_` |
|
||
| `route_callback_map` | 路径 → 默认 `callback_type` |
|
||
| `provider_shard_uid_field` | 厂商 → POST 分片字段（POP：`userid`） |
|
||
|
||
[`RedisKeyManagerService`](slot-pwa/app/service/RedisKeyManagerService.php)：`PROVIDER_CALLBACK_LOG_NEXT_ID`
|
||
[`IdGenerator`](slot-pwa/app/service/IdGenerator.php)：`nextProviderCallbackLogId()`（对齐 `nextGameResultId`）
|
||
|
||
---
|
||
|
||
## 3. 领域层
|
||
|
||
### Shard Model — [`app/model/shard/GameProviderCallbackLogModel.php`](slot-pwa/app/model/shard/GameProviderCallbackLogModel.php)
|
||
|
||
继承 [`BaseShardModel`](slot-pwa/app/model/shard/BaseShardModel.php)：
|
||
|
||
```php
|
||
protected function getPreDatabase(): string { return 'user_transaction'; }
|
||
protected function getPreTable(): string { return 'game_provider_callback_log'; }
|
||
protected function getShardKey(): string { return 'uid'; }
|
||
```
|
||
|
||
- 状态常量：`VERIFY_*` / `PARSE_*` / `PROCESS_*`
|
||
- 数据访问（均需构造时传入 `$shardUid`）：
|
||
- `insertReceived(GameProviderCallbackLogReceiveParams $params): void`（内部 `insertData`）
|
||
- `updateVerifyStatus(int $id, ...)`
|
||
- `updateParseResult(int $id, GameProviderCallbackLogParseParams $params)`
|
||
- `updateProcessStatus(int $id, ...)`
|
||
- `findById(int $id): ?array`（`findOne(['id' => $id, 'uid' => $this->_shardVal])`）
|
||
|
||
### Value Objects（可放 `app/model/game/` 或 `app/entity/game/`）
|
||
|
||
- `GameProviderCallbackLogReceiveParams` — 含 `shardUid`、落库字段
|
||
- `GameProviderCallbackLogParseParams` — 解析后业务字段
|
||
|
||
### Service — [`app/service/game/ProviderCallbackLogService.php`](slot-pwa/app/service/game/ProviderCallbackLogService.php)
|
||
|
||
- `recordReceivedFromRequest(Request $request): void` — 解析 `shardUid`、生成 `id`/`request_id`、**同步** `new GameProviderCallbackLogModel($shardUid)->insertReceived(...)`，设置 `$request->providerCallbackLogId` / `providerCallbackShardUid`
|
||
- `markVerify*(int $shardUid, int $id, ...)`
|
||
- `markParse*(int $shardUid, int $id, ...)`
|
||
- `markProcess*(int $shardUid, int $id, ...)`
|
||
|
||
所有 mark 方法内部统一：`new GameProviderCallbackLogModel($shardUid)->updateByWhere(['id' => $id, 'uid' => $shardUid], ...)`
|
||
|
||
---
|
||
|
||
## 4. Middleware（POP 本期）
|
||
|
||
- 新增 [`ProviderCallbackLogMiddleware`](slot-pwa/app/middleware/ProviderCallbackLogMiddleware.php) — **最先**执行
|
||
- [`config/middleware.php`](slot-pwa/config/middleware.php) `'pop' => [ProviderCallbackLogMiddleware, POPAuthMiddleware]`
|
||
- [`POPAuthMiddleware`](slot-pwa/app/middleware/POPAuthMiddleware.php)：验签结果写回 callback_log；失败 `VERIFY_FAILED` + `PROCESS_REJECTED`
|
||
- `/pop/admin/` 跳过落库
|
||
|
||
---
|
||
|
||
## 5. POP Logic
|
||
|
||
[`CashLogic`](slot-pwa/app/pop/logic/CashLogic.php) / [`CashController`](slot-pwa/app/pop/controller/CashController.php)：
|
||
|
||
- 从 `$request` 读取 `providerCallbackLogId` + `providerCallbackShardUid`
|
||
- `balance` / `modifyTransferInOut`：parse/process 状态；重复 tid → `PROCESS_DUPLICATE`
|
||
- Validate 失败：`PARSE_FAILED` + `PROCESS_REJECTED`（保留已落库的 raw 证据）
|
||
|
||
---
|
||
|
||
## 6. 测试
|
||
|
||
参照分表写入方式（非 LaunchSession 单表）：
|
||
|
||
- [`tests/Support/ProviderCallbackLogTestCase.php`](slot-pwa/tests/Support/ProviderCallbackLogTestCase.php) — 固定测试 `shardUid`，`insertReceived` + teardown `delete`
|
||
- [`tests/Feature/GameProviderCallbackLogShardModelTest.php`](slot-pwa/tests/Feature/GameProviderCallbackLogShardModelTest.php)
|
||
- 初始 `verify_status=0`、`process_status=0`
|
||
- `updateByWhere` 后终态、`processed_at` 写入
|
||
- 同 `body_hash`、同/不同 `shardUid` 可各插一条
|
||
|
||
`docker exec -w /app/www/slot/slot-pwa php82 ./vendor/bin/phpunit`
|
||
|
||
---
|
||
|
||
## 7. 验收对照（POP + 分表）
|
||
|
||
| 验收项 | 实现 |
|
||
|--------|------|
|
||
| 原始请求可追溯 | `raw_body` / `raw_headers` 写入对应分片表 |
|
||
| 验签/解析失败仍有行 | Middleware 先 INSERT（shardUid 可为 0） |
|
||
| BALANCE 仅 callback_log | 无 provider_tx |
|
||
| 重复回调多条 log | 每次 INSERT；tid 重复 → `process_status=3` |
|
||
| 分库分表 | 与 GameResultLog 相同 `user_transaction_*` 族 |
|
||
|
||
---
|
||
|
||
## 8. 后续 PR
|
||
|
||
- 其它厂商 Middleware + `provider_shard_uid_field`
|
||
- 可选：`app/model/all/GameProviderCallbackLogModel` + DBSync（仅当需要 `s_all` 汇总检索时）
|
||
|
||
---
|
||
|
||
## 关键文件
|
||
|
||
| 操作 | 路径 |
|
||
|------|------|
|
||
| 修改 | `app/command/CreateSharedTable.php` |
|
||
| 新增 | `db/game_provider_callback_log_shard.sql`（模板） |
|
||
| 新增 | `app/model/shard/GameProviderCallbackLogModel.php` |
|
||
| 新增 | `app/model/game/GameProviderCallbackLog*Params.php` |
|
||
| 新增 | `app/service/game/ProviderCallbackLogService.php` |
|
||
| 新增 | `app/middleware/ProviderCallbackLogMiddleware.php` |
|
||
| 修改 | `IdGenerator.php`, `RedisKeyManagerService.php`, `middleware.php`, `POPAuthMiddleware.php` |
|
||
| 修改 | `app/pop/logic/CashLogic.php`, `app/pop/controller/CashController.php` |
|
||
| 新增 | `tests/Feature/GameProviderCallbackLogShardModelTest.php` |
|
||
|
||
完成编码后执行 `~/.cursor/hooks/verify-slot-backend.sh` 并粘贴输出。
|