cursor/plans/startdto_去重与规范_edd8c0a8.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
StartDTO 去重与规范	收紧 `GameLaunchSessionStartDTO` 为仅组合两个子 DTO + accessor 派生字段，简化 `launchWithSession` 编排；并在 `php-clean-code.mdc` 增加「禁止编排层双份拷贝 / DTO 重复标量」规则。	id content status refactor-start-dto GameLaunchSessionStartDTO：仅 2 子 DTO + uid/providerCode/gameCode accessor completed id content status refactor-launch-logic 简化 launchWithSession；findReusableLaunch 收 StartDTO；createLaunchSession 用 accessor completed id content status update-rules-dto-dup php-clean-code §3 增加「编排上下文与聚合 DTO」；§8 与 agent-completion-gate 补充自查 completed id content status verify-start-dto docker php -l + SLOT_ROOT verify-slot-backend.sh completed	false

StartDTO 去重重构 + 规范加固

问题

launchWithSession 中：

$uid = (int) $gameLaunchDto->uid;
$providerCode = $gameLaunchContext->providerCode;
$gameCode = $gameLaunchDto->gameCode;
// ...
new GameLaunchSessionStartDTO($gameLaunchDto, $gameLaunchContext, $uid, $providerCode, $gameCode);

GameLaunchSessionStartDTO 同时持有 gameLaunchDto、gameLaunchContext 以及 可从二者推导的 uid / providerCode / gameCode，属于 编排层双份拷贝，违反 DRY 与 php-clean-code.mdc「参数应表达业务需要、聚合 DTO 不重复字段」精神。

flowchart LR
  subgraph before [当前]
    DTO[GameLaunchDTO]
    CTX[GameLaunchContextDTO]
    locals[uid providerCode gameCode]
    Start[GameLaunchSessionStartDTO 5 fields]
    DTO --> locals
    CTX --> locals
    DTO --> Start
    CTX --> Start
    locals --> Start
  end

一、代码重构

1. 收紧 GameLaunchSessionStartDTO

文件： slot-pwa/app/api/dto/GameLaunchSessionStartDTO.php

• 构造函数仅保留：
  • GameLaunchDTO $gameLaunchDto
  • GameLaunchContextDTO $gameLaunchContext
• 派生字段通过 accessor 提供（单一数据源）：
  • uid(): int ← (int) $gameLaunchDto->uid
  • providerCode(): string ← $gameLaunchContext->providerCode
  • gameCode(): string ← $gameLaunchDto->gameCode

2. 简化 launchWithSession

文件： slot-pwa/app/api/logic/GameLaunchSessionLogic.php

目标形态（可读性优先）：

public function launchWithSession(GameLaunchDTO $gameLaunchDto): GameLaunchSessionResultDTO
{
    $launchStart = new GameLaunchSessionStartDTO(
        $gameLaunchDto,
        $this->resolveGameLaunchContext($gameLaunchDto)
    );

    $reusedLaunch = $this->findReusableLaunch($launchStart);
    if ($reusedLaunch !== null) {
        return $reusedLaunch;
    }

    return $this->createLaunchSessionAndFetchUrl($launchStart);
}

• 删除 $gameLaunchContext / $uid / $providerCode / $gameCode 四个中间局部变量。

3. findReusableLaunch 收参为 StartDTO

将签名由 (int $uid, string $providerCode, string $gameCode) 改为：

private function findReusableLaunch(GameLaunchSessionStartDTO $launchStart): ?GameLaunchSessionResultDTO

方法内使用 $launchStart->uid()、providerCode()、gameCode()，避免再次拆三个标量传递。

4. createLaunchSessionAndFetchUrl 统一 accessor

• $launchStart->uid 等改为 $launchStart->uid()（及 providerCode()、gameCode()）
• Provider launch() 调用统一为 $launchStart->uid() + $launchStart->gameLaunchContext->externalGameCode（不再混用 $launchStart->gameLaunchDto->uid）

改动范围： 仅上述 2 个 PHP 文件，无 API / 路由变更。

二、用户级规范更新

php-clean-code.mdc

在 §3「参数与日志」 后增加小节 「编排上下文与聚合 DTO」：

• 禁止编排方法先把子 DTO/Context 字段拆成局部变量，再原样传入聚合 DTO（双份拷贝）。反例：$uid = $dto->uid 后 new StartDTO($dto, $ctx, $uid, ...)。
• 禁止聚合 DTO 构造函数同时接收「可从已有只读字段推导」的重复标量。反例：同时存 gameLaunchDto 与 gameCode。
• 聚合上下文 DTO 应 只组合 子对象；派生值用 uid() / providerCode() 等 accessor 从子对象读取，或在用例方法内直接使用子 DTO 字段（二选一，不并存）。
• 子步骤 private 方法若需多字段，优先传 一个 聚合 DTO，而不是再拆 3 个标量参数。

§8 Agent 自查 增加：

• 是否存在「局部变量 + 聚合 DTO」双份承载同一业务字段？
• 聚合 DTO 是否包含可推导的重复标量？

agent-completion-gate.mdc

在 Logic 自查条（现有第 5 条）中补充：§3 编排上下文与聚合 DTO。

三、验收

1. launchWithSession 无仅用于组 DTO 的 $uid / $providerCode / $gameCode 局部变量。
2. GameLaunchSessionStartDTO 构造函数仅 2 个参数。
3. docker exec -w /app/www/ray/slot-pwa php82 php -l 对相关文件通过。
4. SLOT_ROOT=/Users/ray/Documents/project/www/ray ~/.cursor/hooks/verify-slot-backend.sh → PASS。

范围外

• 不改动 GameLaunchContextDTO / GameLaunchSessionCreateParams 结构。
• 不修改 verify 脚本（仍依赖规则 + 自查）。