5.8 KiB
梦三手牌 UI 子扩展
模块边界
这是术樱包内部的必需子模块，由梦三战斗加载，不是另一个可安装扩展。 没有单独关闭开关。JS 或样式加载失败时进入既有战斗异常处理流程， 保留存档并提供返回模式选择入口；不会静默略过必需模块。
| 位置 | 职责 |
|---|---|
ui/hand/index.js |
挂载、同步、局部输入适配、回退和幂等卸载 |
ui/hand/adapter.js |
校验引擎容器并读取真实卡牌，识别第二容器离线结构 |
ui/hand/overlays.js |
费用与强化覆盖层，仅维护当前手牌的显示节点 |
ui/hand/style.css |
独立排列、尺寸、间距、选中标记及隔离样式 |
ui/hand/diagnostics.js |
生命周期、回退和加载失败诊断日志 |
tools/test-hand-ui.cjs |
浏览器隔离验证，非发布资源 |
verification/hand-ui/ |
本地验证报告、截图和清单，非发布资源 |
logs/log.txt |
游戏内生成的最近 100 条诊断，非发布资源 |
cards/personal-piles.js 只负责个人牌堆业务，原先的手牌 DOM 显示逻辑
已移入本模块。旧的 ui/hand-upgrade.js 和通用样式文件中的对应规则
已移除，避免两套覆盖层并行维护。发布入口仍为 register.js。
交互方案与证据
本体 noname/ui/click/index.js 的 card() 使用真实 this 操作
ui.selected.cards 并调用 game.check()。本体 card.updateTransform()
检查卡牌祖先是否为 ui.me。十周年 core/layout.js、cardDragSort.js
也依赖真实节点的父容器和变换。因此首期选用真实节点原位复用，
不复制卡面，不移动手牌容器，不替换全局原型或布局函数。
排列使用独立命名空间的 flex 样式；默认卡牌 90×110、间距 8， 小屏卡牌 80×100，牌多时横向滚动。具体尺寸集中在本模块 CSS。 卡面继续采用当前引擎/主题生成的内容。选择、取消、出牌、响应和 选目标继续交给引擎，模块不另行计算卡牌可用性或提交出牌事件。
引擎仍维护节点上的 selected、selectable 等状态。本模块通过这些
原有类显示选择状态，保留 DOM 顺序作为引擎排序的依据。
检测到移动手势时临时退回既有排列，释放或取消后恢复独立排列；
触屏水平滚动保留独立排列。首期没有另做手动拖动排序系统。
费用调用既有 cardCost，强化读取既有 cardUpgradeLevel。
覆盖层只在自己的子节点 dataset 上保存显示值，使用伪元素显示文字，
避免十周年对出牌子节点 innerText 的扫描误识别费用数字。
覆盖层不接收指针事件；离开手牌区即回收，返回手牌区重新生成。
若业务直接修改卡牌 storage，修改者应调用返回控制器的 refresh()。
十周年 uiCreateMe() 的第二手牌容器默认离线。
适配器允许“主容器连接、第二容器离线且为空”的结构。
未知或被替换的容器退回原排列，保留覆盖层，并通过游戏日志和
诊断文件报告，不依赖 decadeUI 的内部坐标接口。
生命周期与日志
mode.js 在玩家初始化后、开局摸牌前等待 mountHandUI()。
模块资源登记到 battle-session，逆序释放早于个人牌堆和玩家资源。
正常战斗结束和流程异常另有显式卸载入口；DOM 根节点被移除时
观察器会触发卸载。加载中取消会结束等待并取消计时器。
卸载移除覆盖层、观察器、局部监听、样式链接、自己的类名，并恢复
自己改过的属性；多次调用安全。它不销毁真实卡牌或重置选择状态。
支持引擎文件接口时，日志写入安装目录下
extension/术樱包/mengsan/logs/log.txt，包含时间、战斗 session ID、
挂载、回退、卸载与加载错误。最近 100 条覆盖写入，串行提交。
没有文件接口时保留控制台日志；布局回退也写入游戏日志。
验证结果及边界
本次参考安装源码：本体 game/update.js 为 1.11.5.2；
十周年 info.json 为 1.3.1。
十周年 STYLE_TO_SKIN 将 off/on/othersOff 映射到
shousha/shizhounian/xinsha，配置菜单显示名与规划文档略有不同。
浏览器验证加载安装目录中的本体 CSS、十周年实际基础样式组合及
手杀/十周年/新杀的按钮和技能样式，以匹配 uiCreateMe() 的 DOM 结构
构造测试场景；点击测试使用安装源码中的真实 ui.click.card 函数体，
其 game.check 等引擎服务为测试替身，不代表完整游戏事件链验证。
| 场景 | 桌面 1280×720 | 小屏 540×360 | 完整游戏实测 |
|---|---|---|---|
| 原生 UI | 隔离验证通过 | 隔离验证通过 | 待验证 |
| 手杀 off/shousha | 隔离验证通过 | 隔离验证通过 | 待验证 |
| 十周年 on/shizhounian | 隔离验证通过 | 隔离验证通过 | 待验证 |
| 新杀 othersOff/xinsha | 隔离验证通过 | 隔离验证通过 | 待验证 |
已验证真实节点父级及点击身份、选择/取消、费用与强化移除、 手牌离开/返回、横向滚动处理、手势布局退让、会话结束、重复卸载、 根节点移除、加载中取消、CSS 加载失败、回退覆盖层及属性恢复。 已有梦三逻辑回归 44 项通过。发布清单包含本模块全部 JS/CSS， 不包含 tools、verification、.planning 和 log.txt。
尚需真实游戏验证出牌/响应、技能虚拟牌、选目标/取消、引擎自动排序、 十周年拖拽排序插件及真实手机触屏。本次没有改动已安装的游戏文件， 也没有把隔离场景结果标记为游戏内实测通过。
运行浏览器测试：node mengsan/tools/test-hand-ui.cjs。
可用 NONAME_APP 指向本体目录、CODEX_NODE_MODULES 指向提供 Playwright
的依赖目录；脚本使用本机 Chrome 的无界面独立实例。