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

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

## 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 时是否提示玩家切回原生手牌显示