---
name: Launch Logic 参数与规范
overview: 重构 `GameLaunchSessionLogic` 中仅为日志传递的 `$gameCode` 参数，并在用户级 `php-clean-code.mdc` / `agent-completion-gate.mdc` 中增加「参数必须服务于业务」的硬性约束与完成前自查项。
todos:
  - id: refactor-find-methods
    content: 重构 GameLaunchSessionLogic：去掉 find* 中仅用于日志的 gameCode 参数，日志改用本步真实字段
    status: completed
  - id: update-php-clean-code
    content: php-clean-code.mdc §3 增加「参数与日志」、§8 增加自查项
    status: pending
  - id: update-completion-gate
    content: agent-completion-gate.mdc 增加 Logic 自查与 SLOT_ROOT=www/ray 校验说明
    status: pending
  - id: verify
    content: docker php -l + SLOT_ROOT verify-slot-backend.sh，回复粘贴完整输出
    status: completed
isProject: false
---

# Launch Logic 参数重构 + 规范加固

## 问题

[`GameLaunchSessionLogic.php`](slot-pwa/app/api/logic/GameLaunchSessionLogic.php) 中以下方法将 `$gameCode` 作为入参，但**不参与查询/判断**，仅用于 `Log::error`：

- `findActivePlatformMapping(GGameModel $gameModel, string $gameCode)`
- `findPlatformById(int $platformId, string $gameCode)`
- `findProviderGameService(GPlatformModel $platformModel, string $gameCode)`

违反 [`php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) §3（参数应表达业务需要、禁止误导性签名）。

## 一、代码重构（企业做法：查询方法只收查询条件）

**改动文件：** 仅 [`slot-pwa/app/api/logic/GameLaunchSessionLogic.php`](slot-pwa/app/api/logic/GameLaunchSessionLogic.php)

| 方法 | 调整后签名 | 失败日志字段（用已有入参） |
|------|------------|---------------------------|
| `findActivePlatformMapping` | `(GGameModel $gameModel)` | `game_id`、`active_platform_id` |
| `findPlatformById` | `(int $platformId)` | `platform_id` |
| `findProviderGameService` | `(GPlatformModel $platformModel)` | `provider_code`（`$platformModel->code`） |

`resolveGameLaunchContext` 调用改为：

```php
$gameModel = $this->findGameByCode($gameLaunchDto->gameCode);
$platformMapping = $this->findActivePlatformMapping($gameModel);
$platformModel = $this->findPlatformById((int) $gameModel->active_platform_id);
$providerGameService = $this->findProviderGameService($platformModel);
```

**不引入** `GameLaunchResolveContext`（当前仅 3 步解析，编排层已有 `gameLaunchDto->gameCode`，避免过度设计）。

**保留** `findGameByCode(string $gameCode)`：`gameCode` 即查询条件，合理。

**可选增强（本计划内做）：** 在 `resolveGameLaunchContext` 最外层若需串联排障，可在 public 入口 `launchWithSession` 的 catch 中统一补 `game_code`（已有 `launch game session fail` 日志，解析阶段失败由各 `find*` 用自身字段即可）。

## 二、用户级规范更新

### 1. [`php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc)

在 **§3 方法规则** 末尾新增小节 **「参数与日志」**：

- **禁止**为打日志、排障单独增加与该方法业务无关的参数（反例：`findPlatformById($id, $gameCode)` 且 `$gameCode` 只出现在 `Log::error`）。
- **查询/校验类方法**（`find*`、`ensure*`）的参数必须等于该步骤的查询条件或判断依据。
- 跨多步共享的排障字段（如 `game_code`）应在 **用例编排方法**（public Logic 入口或 `resolveXxx` 编排 private）集中记录；子步骤日志只写本子步骤真实使用的字段（`platform_id`、`provider_code` 等）。
- 若多步都需要同一追溯上下文且步骤 ≥4，再引入 readonly `XxxResolveContext`，**禁止**向每个 private 方法重复挂相同标量。

在 **§8 Agent 自查** 增加一项：

- 是否存在「仅用于日志」的多余参数？

### 2. [`agent-completion-gate.mdc`](/Users/ray/.cursor/rules/agent-completion-gate.mdc)

在 **必须** 列表增加：

5. 修改 `app/**/Logic/**/*.php` 时，完成前对照 `php-clean-code` **§3 参数与日志** 与 **§8 自查**（不仅依赖 verify 脚本）。
6. 工作区在 `www/ray` 时，执行校验须：`SLOT_ROOT=/Users/ray/Documents/project/www/ray ~/.cursor/hooks/verify-slot-backend.sh`（避免 `PASS (no changed files)` 误判）。

### 3. 不改动 verify 脚本（本计划）

`verify-slot-backend.sh` 难以可靠检测「参数仅用于日志」；以 **规则 + Agent 自查** 为主。若后续误报多，再考虑启发式检查。

## 三、验收

1. `findPlatformById` / `findActivePlatformMapping` / `findProviderGameService` 签名中无仅日志用的 `$gameCode`。
2. `docker exec -w /app/www/ray/slot-pwa php82 php -l app/api/logic/GameLaunchSessionLogic.php` 通过。
3. `SLOT_ROOT=/Users/ray/Documents/project/www/ray ~/.cursor/hooks/verify-slot-backend.sh` 输出 `PASS`（有 diff 时）。
4. 规范文件已更新，Agent 自查项可对照执行。

## 范围外

- 不重构 `GameController` 响应格式。
- 不新增 `GameLaunchResolveContext` DTO（除非实现时发现步骤继续增加）。