185 lines
8.3 KiB
Markdown
185 lines
8.3 KiB
Markdown
---
|
||
name: 实现 Launch Session
|
||
overview: 在 slot-pwa 中实现子需求 01：基于现有 GameLogic.launch 链路增加 game_launch_session 落库、Redis 短窗口防重复、Session 关闭接口与过期定时任务；本期跳过 game_gateway_control / 风险画像检查。
|
||
todos:
|
||
- id: ddl-launch-session
|
||
content: 新增 slot-pwa/db/game_launch_session.sql（DDL 与需求一致）
|
||
status: completed
|
||
- id: model-launch-session
|
||
content: 新增 GameLaunchSessionModel + 状态常量与查询/更新方法
|
||
status: completed
|
||
- id: logic-launch-session
|
||
content: 新增 GameLaunchSessionLogic：Redis 去重、创建/关闭 Session、编排 Provider launch
|
||
status: completed
|
||
- id: api-routes
|
||
content: 改造 GameController.launch 响应；新增 close 接口与 route/Validate/DTO
|
||
status: completed
|
||
- id: expire-command
|
||
content: 新增 game:launch-session:expire 命令 + game.php TTL 配置
|
||
status: completed
|
||
- id: refactor-game-logic
|
||
content: GameLogic 委托新 Logic；IdGenerator/RedisKey 扩展；跑 verify 脚本
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 实现子需求 01：Launch Session（slot-pwa）
|
||
|
||
## 现状
|
||
|
||
- 需求文档：[01_launch_session.md](docs/requirements/game_gateway/01_launch_session.md)
|
||
- 服务仓库：`slot-pwa`（PRD 中的 slot-pwa）
|
||
- **已有**：[`GameController::launch`](slot-pwa/app/api/controller/GameController.php) → [`GameLogic::launch`](slot-pwa/app/api/logic/GameLogic.php) → 查 `g_game` / `g_platform` → 调 Provider `launch()` 返回 URL
|
||
- **缺失**：`game_launch_session` 表、Model、Session 创建/关闭/过期、Redis 去重、`POST /slot-game/session/close` 路由
|
||
- **本期不做**（你已确认）：`game_gateway_control`、`game_user_risk_profile_01` 准入检查
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client
|
||
participant GameController
|
||
participant GameLaunchSessionLogic
|
||
participant Redis
|
||
participant DB as game_launch_session
|
||
participant Provider
|
||
|
||
Client->>GameController: launch(gameCode)
|
||
GameController->>GameLaunchSessionLogic: launchWithSession
|
||
GameLaunchSessionLogic->>Redis: 短窗口去重
|
||
alt 命中有效 Session
|
||
GameLaunchSessionLogic-->>Client: 复用 launch_url 或重新拉 URL 策略见下
|
||
else 新启动
|
||
GameLaunchSessionLogic->>DB: INSERT status=1
|
||
GameLaunchSessionLogic->>Provider: launch
|
||
GameLaunchSessionLogic->>DB: 更新 launch_url_hash
|
||
GameLaunchSessionLogic-->>Client: url + session_id
|
||
end
|
||
|
||
Client->>GameController: session/close(session_id)
|
||
GameController->>GameLaunchSessionLogic: closeSession
|
||
GameLaunchSessionLogic->>DB: status=2, closed_at
|
||
```
|
||
|
||
## 实现策略
|
||
|
||
### 1. 数据库迁移
|
||
|
||
新增 SQL：[slot-pwa/db/game_launch_session.sql](slot-pwa/db/game_launch_session.sql)
|
||
|
||
- DDL 与需求文档 **逐字一致**（`game_launch_session` 全字段 + 索引）
|
||
- 部署：在 Docker MySQL 中执行（`goMysql` / 项目 `mysql` 连接）
|
||
|
||
### 2. Model 层
|
||
|
||
新建 [`slot-pwa/app/model/game/GameLaunchSessionModel.php`](slot-pwa/app/model/game/GameLaunchSessionModel.php)
|
||
|
||
- `connection = mysql`，`table = game_launch_session`
|
||
- 状态常量：`STATUS_ACTIVE=1` … `STATUS_RISK_BLOCKED=6`（与 PRD 一致）
|
||
- 查询方法（业务语义命名）：
|
||
- `findActiveBySessionId(string $sessionId)`
|
||
- `findLatestActiveByUidProviderGame(int $uid, string $providerCode, string $gameCode)`（Redis 未命中时兜底）
|
||
- `markClosed(int $id): void` / `markExpiredBatch(): int`（供定时任务）
|
||
|
||
### 3. Logic 层（核心）
|
||
|
||
新建 [`slot-pwa/app/api/logic/GameLaunchSessionLogic.php`](slot-pwa/app/api/logic/GameLaunchSessionLogic.php)，从 [`GameLogic`](slot-pwa/app/api/logic/GameLogic.php) 抽离并编排：
|
||
|
||
| 步骤 | 说明 |
|
||
|------|------|
|
||
| 解析游戏 | 复用现有 `GGameModel` / `GGamePlatformMappingModel` / `GPlatformModel` 校验；`provider_code` = `GPlatformModel.code` |
|
||
| Redis 去重 | Key：`game:launch:dedup:{uid}:{provider_code}:{game_code}`，TTL **8s**（需求 5~10s 取中值）；Value：`session_id` |
|
||
| 命中去重 | 查 DB 中 `status=1` 且未过期的 Session；**若存在且 Provider 允许**，直接返回已有 `session_id` + 不再请求 Provider（避免重复 LaunchURL）；若 Session 无效则走新启动 |
|
||
| 创建 Session | 生成 `session_id`、`launch_request_id`（`bin2hex(random_bytes(16))` 或类似 UUID 风格）；`id` 复用 [`IdGenerator`](slot-pwa/app/service/IdGenerator.php) 模式新增 `nextLaunchSessionId()` |
|
||
| 调 Provider | 调用现有 `BaseGameService::getGameService()->launch()` |
|
||
| 写回 | `launch_url_hash = hash('sha256', $url)`；失败时 `status=4` + `remark` |
|
||
| 关闭 | `closeSession(uid, session_id)`：校验归属 → `status=2`，`closed_at=now`；**不**调 wallet / round / 盈利统计 |
|
||
|
||
重构 [`GameLogic::launch`](slot-pwa/app/api/logic/GameLogic.php)：
|
||
|
||
- 薄封装：委托 `GameLaunchSessionLogic::launchWithSession(GameLaunchDTO)`，保持 `game:launch` 命令兼容
|
||
|
||
### 4. API 层
|
||
|
||
**改造 Launch 响应**（[`GameController::launch`](slot-pwa/app/api/controller/GameController.php)）：
|
||
|
||
```php
|
||
// 返回扩展示例
|
||
['url' => $url, 'session_id' => $sessionId, 'launch_request_id' => $launchRequestId]
|
||
```
|
||
|
||
**新增关闭接口**：
|
||
|
||
| 项 | 内容 |
|
||
|----|------|
|
||
| 路由 | `POST /slot-game/session/close`（写入 [`config/route.php`](slot-pwa/config/route.php)） |
|
||
| Controller | 新建 `GameLaunchSessionController` 或扩展现有 `GameController` |
|
||
| Validate | `session_id` require；`uid` 从 Auth 中间件 / 请求体（与现有 launch 一致用 body `uid`） |
|
||
| DTO | `GameLaunchSessionCloseDTO` |
|
||
|
||
错误处理：将 `RuntimeException` 逐步改为 `Webman\Exception\BusinessException` + 明确错误码（与项目 exception handler 对齐）；关键日志带 `uid`、`game_code`、`session_id`。
|
||
|
||
### 5. Redis Key 管理
|
||
|
||
在 [`ShareRedisKeyManagerService`](slot-pwa/app/service/ShareRedisKeyManagerService.php) 或 [`RedisKeyManagerService`](slot-pwa/app/service/RedisKeyManagerService.php) 增加：
|
||
|
||
```php
|
||
getGameLaunchDedupKey(int $uid, string $providerCode, string $gameCode): string
|
||
```
|
||
|
||
### 6. Session 过期任务
|
||
|
||
新建 Console 命令 [`slot-pwa/app/command/GameLaunchSessionExpire.php`](slot-pwa/app/command/GameLaunchSessionExpire.php)：
|
||
|
||
- 名称：`game:launch-session:expire`
|
||
- SQL 逻辑同需求文档：`status=1 AND expired_at < NOW(3)` → `status=3`
|
||
- 可由 crontab / 运维定时 `docker exec ... php webman game:launch-session:expire`
|
||
|
||
配置项（[`config/game.php`](slot-pwa/config/game.php) 或 `params.php`）：
|
||
|
||
- `launch_session_ttl_seconds`（默认如 7200，写入 `expired_at`）
|
||
- `launch_dedup_ttl_seconds`（默认 8）
|
||
|
||
### 7. 验收对照（子需求 §6）
|
||
|
||
| 验收项 | 实现方式 |
|
||
|--------|----------|
|
||
| session_id / launch_request_id 唯一 | DB UNIQUE + 生成逻辑 |
|
||
| Redis 短窗口不重复 LaunchURL | dedup key + 复用 active session |
|
||
| 退出 status=2，无资金副作用 | close 仅 UPDATE session |
|
||
| 过期 status=3 | 定时命令 |
|
||
|
||
## 文件清单（新增/修改）
|
||
|
||
| 操作 | 路径 |
|
||
|------|------|
|
||
| 新增 | `slot-pwa/db/game_launch_session.sql` |
|
||
| 新增 | `slot-pwa/app/model/game/GameLaunchSessionModel.php` |
|
||
| 新增 | `slot-pwa/app/api/logic/GameLaunchSessionLogic.php` |
|
||
| 新增 | `slot-pwa/app/api/controller/GameLaunchSessionController.php`（或扩展 GameController） |
|
||
| 新增 | `slot-pwa/app/api/dto/GameLaunchSessionCloseDTO.php` |
|
||
| 新增 | `slot-pwa/app/api/validate/GameLaunchSessionValidate.php` |
|
||
| 新增 | `slot-pwa/app/command/GameLaunchSessionExpire.php` |
|
||
| 修改 | `slot-pwa/app/api/logic/GameLogic.php` |
|
||
| 修改 | `slot-pwa/app/api/controller/GameController.php` |
|
||
| 修改 | `slot-pwa/config/route.php` |
|
||
| 修改 | `slot-pwa/app/service/IdGenerator.php`（+ RedisKey 常量） |
|
||
| 修改 | `slot-pwa/config/game.php`（TTL 配置） |
|
||
|
||
## 测试建议（实现后）
|
||
|
||
```bash
|
||
# 建表
|
||
docker exec -i goMysql mysql -uroot -p<pwd> <db> < slot-pwa/db/game_launch_session.sql
|
||
|
||
# Launch
|
||
docker exec -w /app/www/slot/slot-pwa php82 php webman game:launch <uid> -c <gameCode>
|
||
|
||
# 过期
|
||
docker exec -w /app/www/slot/slot-pwa php82 php webman game:launch-session:expire
|
||
```
|
||
|
||
手工：连续两次 launch（8s 内）应复用 session；`POST /slot-game/session/close` 后 DB `status=2`。
|
||
|
||
## 完成门禁
|
||
|
||
实现 PHP 后执行 `~/.cursor/hooks/verify-slot-backend.sh`，最终回复粘贴完整输出。
|