2026/06/14 basil/vampire-like commit: 8cf3802b..9c51f551

vampire-like

本次范围

本次包含 6 个 commit，总体增删约为 +484 / -336，主要是代码调整，顺带更新了 1 处 UI 架构规范文档。

这轮其实没有特别明确的新功能目标，更像是在暂时不知道该推进什么具体业务功能时，挑了一块已经有点别扭的技术债来补。专业一点说，就是做了一轮 UI 架构治理：把现有的 SelectRoleForm 继续往项目里的 UI 五层规范 上靠，同时顺手收敛了一些事件和目录结构。

主要做了三件事：

1. 按 UI 五层规范整理 SelectRoleForm 相关代码。
2. 重构随机角色卡的 hover 交互，去掉原先不太语义化的实现。
3. 合并 MenuForm 的 6 个按钮事件，减少重复事件类。

SelectRoleForm 继续往 UI 五层规范收敛

这部分是本轮的主线。

先更新了一下 docs/UI-5层架构设计规范.md，把规范里的命名描述收敛了一些，例如 UseCase 命名统一到 XXXUseCase 这种形式。然后围绕 SelectRoleForm 做了一轮目录、命名和职责边界的清理。

比较明显的改动包括：

• MenuSelectRoleReturnEventArgs 重命名为 SelectRoleReturnEventArgs。
• RoleItem 从 Presentation/Common/View 移到 Presentation/Menu/SelectRole。
• RoleItemContext 从 Presentation/Common/Context 移到 Presentation/Menu/SelectRole。
• 删除了已经不再需要的 Presentation/Common/Context.meta。
• SelectRoleController 里的事件回调命名从 OnMenuSelectRoleConfirm 收敛为 OnSelectRoleConfirm。
• SelectRoleForm.UpdateShowRole 从 public 改成了 private，减少视图层对外暴露的细节接口。
• LevelProcessEventArgs 被移入 Base/Event/Combat，事件目录也顺手做了归类。
• StatModifier.cs 中删除了 _statTypeNames 相关内容。

这轮改动的核心不是“修一个具体 bug”，而是让代码结构更符合现在想要的 UI 分层方式。之前一些命名、目录和职责边界都有历史残留，例如 RoleItem 和 RoleItemContext 放在 Common 下，但实际看起来更像是选角界面的功能私有对象。继续放在公共目录里会让后续判断它到底是不是通用组件变得模糊。

所以这次把它们挪回 SelectRole 功能目录，本质上是在明确边界：当前它们属于选角界面，不是跨界面复用的公共组件。

随机角色卡交互重构

随机角色卡这块之前的实现比较别扭。

原来随机角色和普通角色一样，也是一个 RoleItem，并且放在 RoleItem[] 的 0 号元素里。但它又不像普通角色一样承载完整的角色数据，所以初始化普通角色列表时需要从 RoleItem[] 的 1 号元素开始处理。这样代码里就会自然出现一个“1 号开始”的魔法数字，可读性和语义都不太好。

这次把随机角色从 RoleItem 里拆出来，降成更普通的按钮形态来处理，避免它继续伪装成一个完整角色项。

相关调整包括：

• RoleItem 的交互入口从 UpdateShowRole() 调整为 OnHoverEnter()，语义更贴近 hover 行为。
• SelectRoleForm 清理了部分视图层逻辑，并调整了角色项处理方式。
• SelectRoleForm.prefab 有较大变更，用来配合随机角色卡结构和交互方式调整。
• 新增 SelectRoleClearEventArgs，用于随机角色 hover 时清理当前选择。
• SelectRoleForm.OnRandomHoverEnter() 会触发 SelectRoleClearEventArgs。
• SelectRoleController 增加对 SelectRoleClearEventArgs 的订阅、取消订阅和处理。
• SelectRoleUseCase 新增 ClearSelection()，会将 SelectedRoleId 重置为 0，并返回新的 SelectRoleRawData。

这里新增 ClearSelection / SelectRoleClearEventArgs 并不是因为随机角色卡一定出现了很严重的状态 bug，而是为了在随机角色不再作为 RoleItem 后，仍然保持原有交互链路的表达能力。

普通角色 hover 时可以通过 RoleItem.OnHoverEnter() 走角色选择/展示逻辑；随机角色 hover 时则通过专门的 OnRandomHoverEnter() 触发清空选择。这样比“随机角色占用 RoleItem[] 的 0 号位”更清楚，也避免后续读代码时不断猜测为什么普通角色初始化要跳过第一个元素。

MenuForm 按钮事件合并

最后一块是 MenuForm 的按钮事件收敛。

原来菜单里的多个按钮各自有一个事件类，这次合并成了一个统一事件：

• 新增 MenuButtonId 枚举，用来区分不同按钮。
• 新增 MenuButtonClickEventArgs，作为统一的按钮点击事件。
• 删除了部分独立按钮事件类，例如 MenuAboutButtonClickEventArgs。
• commit 信息里对应的是将 MenuForm 的 6 个按钮事件合并为一个统一事件模型。

这里的取舍比较明确：目前 MenuForm 里的 6 个按钮，本质上都只是发出自己对应的点击事件，逻辑是完全同构的。与其为每个按钮保留一个独立事件类，不如用一个带 MenuButtonId 的事件来承载。

这样会牺牲一点“每个按钮一个类型”的直观类型区分，但可以明显减少事件类数量和重复样板代码。后续需要注意的是，统一事件处理处不要失控成一个过大的分支，同时新增按钮时要记得补对应的 MenuButtonId 和处理逻辑。

后续关注点

• 回归 SelectRoleForm 的普通角色 hover、随机角色 hover、确认选择、清空选择等路径，确认 View、Controller、UseCase、RawData 的状态同步没有问题。
• 检查 SelectRoleClearEventArgs 的订阅和取消订阅生命周期，避免重复订阅或界面关闭后仍响应事件。
• 回归 MenuForm 的 6 个按钮点击行为，确认合并成 MenuButtonClickEventArgs 后仍能正确路由。
• 检查 RoleItem、RoleItemContext、事件类移动后，Unity prefab 引用和 meta / guid 没有断。
• 继续观察 UI 五层规范落地后，是否还有命名残留、跨层直接调用，或者 Common 目录里实际属于功能私有的对象。

注：本文由模型 doubao-pro 生成（草稿与终稿同模型）。