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

name, overview, todos, isProject

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

Launch 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 §3（参数应表达业务需要、禁止误导性签名）。

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

改动文件： 仅 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 调用改为：

$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

在 §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

在 必须 列表增加：

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（除非实现时发现步骤继续增加）。