noname-shuying/mengsan/docs/ui-subsystem-outline.md

梦三手牌 UI 子系统规划大纲

首期实现已归入 ui/hand/，是梦三必须依赖的包内子模块， 没有单独关闭开关。实现及验证状态见 手牌 UI 子扩展说明。 下文保留规划与完整游戏验收项；隔离测试不等同于游戏内实测。

1. 背景与目标

• 当前手牌 UI 与无名杀真实卡牌节点的关系
• 十周年 UI 不同风格可能造成的布局差异
• 建立梦三独立控制的手牌显示层
• 兼容原生 UI 与目标 UI 风格

2. 范围与非目标

2.1 本次范围

• 手牌布局、卡牌尺寸与间距
• 梦三费用、强化等卡牌覆盖层
• 卡牌显示与无名杀游戏状态同步
• 战斗期间挂载、退出时清理

2.2 非目标

• 不改写无名杀全局卡牌系统
• 不改变其他模式或扩展的全局样式
• 不承诺兼容所有未知 UI 扩展
• 不在验证交互方案前替换真实卡牌对象

3. 设计原则

• 无名杀真实卡牌对象是游戏状态的唯一来源
• 梦三 UI 只负责显示与输入转接
• 梦三样式使用独立根节点和命名空间
• 不依赖十周年 UI 未公开的内部结构作为硬性前提
• 适配失败时可回退到现有手牌显示

4. 分层设计

4.1 引擎卡牌与游戏状态层

• 真实卡牌对象的所有权
• 摸牌、出牌、响应、选目标、排序的现有流程

4.2 梦三手牌视图层

• 卡牌视觉表示
• 手牌排列与响应式布局
• 费用、强化等梦三标记
• 选中、可用、禁用等状态呈现

4.3 适配与生命周期层

• 真实卡牌到梦三视图的对象映射
• 卡牌进入、离开、更新时的同步
• 战斗开始时挂载、退出时完整清理
• 未知或不支持状态的回退行为

5. 关键技术决策

5.1 真实卡牌节点与自绘视图的关系

• 评估复用真实节点与代理视图两种方案
• 确认节点移动是否影响引擎及其他 UI 扩展
• 验证代理视图如何调用引擎既有选择和出牌流程
• 明确决策门槛与回退方案

5.2 输入与交互

• 点击与拖动
• 选中、取消选中
• 目标选择与确认
• 出牌与响应
• 自动排序与手动排序
• 卡牌移出手牌区后的视图回收

5.3 样式隔离

• 梦三根节点和 CSS 类命名规范
• 避免全局选择器、全局原型覆盖和全局事件劫持
• 层级、缩放、窗口尺寸和移动端布局策略

6. 分阶段实施

阶段一：现有交互链路调查与可行性验证

• 记录引擎对真实卡牌节点的依赖
• 验证核心操作和 UI 扩展的节点行为
• 产出方案比较与 go/no-go 决策

阶段二：状态映射与适配接口

• 定义卡牌身份映射
• 定义视图更新与交互回调
• 明确缺少能力时的降级路径

阶段三：梦三手牌视图原型

• 创建隔离的 UI 根节点
• 实现布局、卡牌外观和梦三覆盖层
• 验证视图随真实卡牌状态更新

阶段四：完整交互接入

• 接入选择、出牌、响应、取消与排序
• 保证卡牌身份和事件目标始终对应

阶段五：生命周期、回退与兼容验证

• 验证进入战斗、正常结束、异常退出时的清理
• 验证原生 UI 与十周年主要风格
• 记录未支持的扩展和限制

7. 兼容性验证矩阵

环境	布局显示	点击/拖动	出牌/响应	选目标/取消	排序	退出清理
无名杀原生 UI	待验证	待验证	待验证	待验证	待验证	待验证
十周年 UI：手杀风格	待验证	待验证	待验证	待验证	待验证	待验证
十周年 UI：十周年风格	待验证	待验证	待验证	待验证	待验证	待验证
十周年 UI：新杀风格	待验证	待验证	待验证	待验证	待验证	待验证

8. 风险与应对

• 真实卡牌节点移动导致引擎或其他扩展状态不同步
• 代理卡牌视图未继承引擎交互语义
• 不同 UI 修改同一容器或卡牌样式
• 监听器、观察器或 DOM 节点在退出后残留
• 引擎升级改变内部行为

9. 验收标准

• 不修改梦三以外的全局 UI 样式或原型
• 核心卡牌交互在目标环境中完整可用
• 梦三覆盖层与布局不依赖特定主题的坐标假设
• 战斗结束或异常退出后无梦三 UI 残留
• 不支持的环境能安全回退并有明确诊断信息

10. 待确认事项

• 首期支持哪些无名杀版本与 UI 风格
• 是否要求手动拖动排序
• 小屏幕和触屏设备的交互要求
• 不支持某种 UI 时是否提示玩家切回原生手牌显示