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