ok

plans/launch_logic_参数与规范_8e5808ea.plan.md

@@ -0,0 +1,93 @@
+---
+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（除非实现时发现步骤继续增加）。