feat: complete mobile UI implementation

2026-09-04 19:54:33 +09:00
parent 9a4a044da5
commit b19d5b5dd3
132 changed files with 6643 additions and 180 deletions
@@ -0,0 +1,656 @@
+# 移动端 UI 与现有 PC UI 共存实施方案
+
+## 1. 目标与结论
+
+本方案用于把横屏移动端 UI 草图落地到现有 Godot 客户端，同时保留当前 PC UI、40250 交互语义、网络协议和玩法逻辑。
+
+草图入口：[`../.planning/sketches/001-mobile-hud/index.html`](../.planning/sketches/001-mobile-hud/index.html)
+
+总体结论：
+
+- 不重写网络、角色、物品、技能、任务、组队和商店数据逻辑。
+- PC 与移动端共用同一套客户端状态和业务控制器，分别使用不同的 HUD 与窗口布局。
+- 首页 HUD、虚拟摇杆、技能盘、菜单路由和移动端输入仲裁需要新增。
+- 高频窗口需要移动端专用布局；低频窗口可先套移动端容器，随后逐步重排。
+- 服务端或 NPC 上下文驱动的窗口不能被菜单强制打开，菜单只能展示入口条件或导航到对应场景。
+- 整体属于 UI 层中等偏大改动，但不是客户端重写。预计可复用约 70% 的现有功能逻辑。
+
+## 2. 已确定的移动端设计规则
+
+### 2.1 设备与视觉方向
+
+- 横屏为唯一移动端布局方向。
+- 设计基准为 844×390，布局必须适配更宽的 Android 屏幕、平板和刘海/挖孔安全区。
+- 风格采用现代手游半透明 HUD、暗色玻璃、暖铜金边框和低饱和背景。
+- 不直接复制其他游戏素材，只参考暗黑 ARPG 的信息层级、触控半径和功能收纳方式。
+
+### 2.2 首页 HUD
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│ 名称                                        背包  小地图  菜单 │
+│ 头像                                                         │
+│ HP/MP     目标名称与血条                                      │
+│ 队员 1                                                       │
+│ 队员 2                                  当前任务追踪           │
+│                                                              │
+│                       游戏世界                               │
+│                                                              │
+│ 移动摇杆                                        技能 / 普攻    │
+└──────────────────────────────────────────────────────────────┘
+```
+
+固定规则：
+
+- 玩家名称位于左上头像上方。
+- HP、MP 和职业资源条位于头像下方，宽度与头像一致。
+- 点击玩家头像进入角色、装备、技能、坐骑、表情和称号页面。
+- 角色功能不出现在右上菜单。
+- 组队后，队员头像、名称、HP 和距离显示在玩家头像下方；未组队时不占空间。
+- 队伍不出现在社交菜单，也不设置独立按钮。
+- 右上角从左到右为背包、小地图、菜单；点击小地图打开大地图。
+- 当前任务条直接打开任务日志，不放入菜单。
+- 底部中央不设置功能栏，只在左下和右下保留必要战斗控件。
+
+### 2.3 右上菜单
+
+菜单只保留五个一级分类：
+
+| 一级分类 | 二级内容 |
+|---|---|
+| 社交 | 聊天、好友、公会、情侣、观战 |
+| 成长 | 精炼、龙魂、Cube 制作 |
+| 活动 | 副本、钓鱼 |
+| 商业 | 商店、商城、交易、私人商店、仓库、兑换 |
+| 系统 | 系统设置、游戏设置、帮助、选择角色、登出、退出 |
+
+页面层级最多两层。二级页必须提供返回上一级和关闭两个操作。
+
+## 3. 当前代码基础
+
+### 3.1 UI 装配
+
+`project/game_scene.gd` 已负责创建并连接以下模块：
+
+- `Hud`
+- `InventoryUI`
+- `SkillUI`
+- `CharStatusUI`
+- `Quickbar`
+- `QuestLog`
+- `PartyUI`
+- `FriendUI`
+- `GuildUI`
+- `LoveUI`
+- `ShopUI`
+- `ExchangeUI`
+- `SafeboxUI`
+- `MallUI`
+- `CubeUI`
+- `RefineUI`
+- `DragonSoulUI`（当前功能开关关闭）
+- `Minimap`
+- `AtlasUI`
+- `SystemMenuUI`
+
+这些模块已经连接 `M2Client` 信号并负责现有功能行为。移动端不应复制这一套网络和状态处理。
+
+### 3.2 现有 HUD 接口可作为兼容协议
+
+`project/net_play.gd` 通过以下方法更新 `Hud`：
+
+```gdscript
+set_vitals(hp, max_hp, sp, max_sp)
+set_stamina(value, max_value)
+set_exp(xp, next_xp)
+set_level(level)
+set_energy(value, max_value)
+set_target(name, hp_pct)
+clear_target()
+```
+
+移动端 HUD 实现相同的方法后，可以直接作为 `net_play.setup(..., hud_node)` 的 HUD 参数，无需修改网络更新流程。
+
+### 3.3 PC 固定布局不能直接缩放成移动端
+
+当前工程基准分辨率为 1920×1080，`UiManager.screen` 也默认使用该尺寸。`hud.gd` 中状态条锚定左下且 HP 宽度为 240，现有 Python UI 脚本还包含大量固定坐标。
+
+因此不能把整个 PC CanvasLayer 等比缩小后直接作为最终移动端 UI，否则会出现：
+
+- 字体和触控目标过小。
+- 横屏短边空间不足。
+- 多窗口互相覆盖。
+- 标题栏拖动、右键、鼠标悬停等 PC 交互无法在触屏完成。
+- 刘海、圆角和系统手势区遮挡 UI。
+
+### 3.4 当前触摸能力
+
+现有代码已经具备：
+
+- 单指轻点地面移动或选择实体。
+- 单指拖动旋转镜头。
+- 双指缩放镜头。
+- `pointing/emulate_mouse_from_touch=false`，不会把触摸再次模拟成鼠标事件。
+
+当前已具备：
+
+- 虚拟摇杆连续移动，以及普攻、药水和 4 个技能触摸按钮。
+- UI 触点按 index 捕获，摇杆/战斗触点不会被世界点地和镜头误判；窗口打开时由 `UiManager` 阻断世界输入。
+- 双指世界手势不会生成点地移动；切后台、失焦和恢复时会释放摇杆/攻击状态。
+- 背包支持点按选择、再次点按使用、点另一格移动；交易、私人商店、仓库和商城支持移动端候选列表或点按操作。
+
+代码已覆盖：
+
+- 技能长按瞄准、拖动调整方向和松手释放；短按仍沿用现有目标/自动射程逻辑。
+- 角色属性/装备、技能、聊天/私聊、系统设置和游戏设置的移动横屏页面。
+- 物品长按详情与触摸拖放、技能拖入快捷栏、快捷栏槽位交换；无法拖放时仍保留点按替代路径。
+
+后续主要是 Android/iOS 真机上的 DPI、键盘、手势区和视觉验收。
+
+### 3.5 现有队伍 UI 可直接演进
+
+`PartyUI` 已经：
+
+- 监听 `party_changed` 和生命状态更新。
+- 队伍为空时自动隐藏。
+- 显示成员名字、HP、队长和角色状态。
+- 点击成员可选中对应角色。
+- 支持角色分配、踢人、经验分配和组队治疗。
+
+移动端只需要增加紧凑布局模式并更换挂载位置，无需重写队伍逻辑。
+
+## 4. 目标架构
+
+```text
+GameScene
+├── M2Client / NetPlay / PlayerController / GameCamera
+│   └── PC 与移动端共享，不复制协议和玩法状态
+│
+├── UiManager
+│   └── 继续管理功能窗口栈、模态遮罩和关闭顺序
+│
+├── DesktopUiRoot
+│   ├── 当前 Hud
+│   ├── 当前 Quickbar
+│   └── 当前 PC 窗口布局
+│
+└── MobileUiRoot
+    ├── MobileHud
+    │   ├── PlayerCard
+    │   ├── PartyHost
+    │   ├── TargetCard
+    │   ├── QuestTracker
+    │   ├── MinimapHost
+    │   └── TopRightActions
+    ├── MobileInputOverlay
+    │   ├── VirtualJoystick
+    │   ├── AttackButton
+    │   ├── SkillWheel
+    │   └── ContextAction
+    ├── MobileMenuDrawer
+    ├── MobileWindowHost
+    └── MobileUiRoot（当前同时承担路由职责）
+```
+
+职责边界：
+
+- `MobileHud` 只显示状态并发出点击信号，不直接发送网络包。
+- `MobileInputOverlay` 把触控动作转换为现有控制器调用。
+- `MobileUiRoot` 把头像、背包、小地图、任务和菜单项路由到现有 UI 控制器；后续如路由继续膨胀，再拆出独立 `MobileUiRouter`。
+- `MobileWindowHost` 负责安全区、全屏面板、返回键和过渡动画。
+- 原有 UI 控制器继续处理数据、服务器信号和业务动作。
+
+## 5. UI 模式选择
+
+新增 `UiProfile`，支持 `AUTO`、`DESKTOP`、`MOBILE` 三种模式。
+
+自动选择建议：
+
+```gdscript
+enum Mode { AUTO, DESKTOP, MOBILE }
+
+static func resolve(mode: Mode) -> Mode:
+    if mode != Mode.AUTO:
+        return mode
+    return Mode.MOBILE if OS.has_feature("mobile") else Mode.DESKTOP
+```
+
+要求：
+
+- Android 和 iOS 默认移动 UI。
+- macOS 默认 PC UI。
+- 桌面开发时允许通过项目设置或启动参数强制移动 UI，便于调试。
+- 自动判断只在进入游戏时执行，切换 UI 模式需要重建 UI 根节点，避免运行中残留窗口。
+
+建议新增项目配置：
+
+```text
+mt/ui/profile = auto | desktop | mobile
+mt/ui/mobile_scale = 1.0
+mt/ui/show_touch_debug = false
+```
+
+## 6. 建议文件结构
+
+```text
+project/ui/
+├── mobile/
+│   ├── mobile_ui_root.gd
+│   ├── mobile_hud.gd
+│   ├── mobile_input_overlay.gd
+│   ├── mobile_menu_drawer.gd
+│   ├── mobile_ui_router.gd
+│   ├── mobile_window_host.gd
+│   └── components/
+│       ├── player_card.gd
+│       ├── party_member_strip.gd
+│       ├── quest_tracker.gd
+│       ├── virtual_joystick.gd
+│       ├── skill_button.gd
+│       └── item_touch_slot.gd
+├── desktop/
+│   └── 可后续把当前 HUD 迁入，首期不要求移动文件
+└── ui_profile.gd
+```
+
+首期不要搬动所有现有文件，以减少路径变化和回归风险。
+
+## 7. 现有功能与移动端入口映射
+
+### 7.1 首页直达入口
+
+| 移动端入口 | 现有目标 | 接入方式 | 改动等级 |
+|---|---|---|---|
+| 玩家头像 | `CharStatusUI`、`SkillUI` | 头像打开角色容器；容器内调用现有角色/技能状态 | 中 |
+| 背包 | `InventoryUI.toggle()` | 右上按钮经路由器调用 | 低 |
+| 小地图 | `AtlasUI.toggle()` | 小地图自身保持显示，点击打开大地图 | 低 |
+| 当前任务 | `QuestLog.toggle()` | 任务条点击调用；不进入菜单 | 低 |
+| 队员条 | `PartyUI` | 增加 compact 模式，挂载到玩家头像下 | 中低 |
+| 普攻 | `NetPlay.set_attack_key()` | 按下设为 true，抬起设为 false | 中 |
+| 技能 | `Quickbar.activate(slot)` | 技能按钮使用现有槽位和冷却逻辑 | 中 |
+| 拾取/交互 | `GroundItems`、`NetPlay` | 使用现有拾取、实体选择和场景交互路径 | 中 |
+
+### 7.2 右上菜单路由
+
+| 分类 | 功能 | 当前可否直接打开 | 移动端行为 |
+|---|---|---|---|
+| 社交 | 聊天 | 可以 | 调用现有聊天日志入口 |
+| 社交 | 好友 | 可以 | 调用 `FriendUI.toggle()` |
+| 社交 | 公会 | 可以 | 调用 `GuildUI.toggle()` |
+| 社交 | 情侣 | 状态驱动 | 展示情侣状态；无关系时显示空状态 |
+| 社交 | 观战 | 场景状态驱动 | 展示观战说明或当前观战状态 |
+| 成长 | 精炼 | 服务器询问驱动 | 显示“前往精炼 NPC”，收到 `refine_ask` 后打开窗口 |
+| 成长 | 龙魂 | 当前禁用 | 在 `ENABLE_DRAGON_SOUL` 开启前隐藏或显示未开放 |
+| 成长 | Cube 制作 | NPC/服务器驱动 | 导航到制作 NPC；收到 `cube_opened` 后打开 |
+| 活动 | 副本 | 任务/场景驱动 | 展示目标与导航，不绕过服务端进入条件 |
+| 活动 | 钓鱼 | 场景驱动 | 展示说明；到达钓点后由情境按钮开始 |
+| 商业 | NPC 商店 | NPC 驱动 | 导航或提示靠近 NPC，不能本地强制打开 |
+| 商业 | 商城 | 服务器状态驱动 | 有商城会话时显示内容，否则显示不可用状态 |
+| 商业 | 玩家交易 | 玩家交互驱动 | 选择附近玩家后发起交易 |
+| 商业 | 私人商店 | 玩家/摊位驱动 | 点击摊位浏览；自己的商店进入管理模式 |
+| 商业 | 仓库 | NPC/服务器驱动 | 导航到仓库 NPC，服务器打开后显示 |
+| 商业 | 兑换 | NPC/任务上下文驱动 | 显示导航，不伪造兑换上下文 |
+| 系统 | 设置/帮助 | 可以 | 使用移动端全屏设置页或现有控制器适配页 |
+| 系统 | 选择角色/登出/退出 | 可以 | 二次确认后调用现有系统操作 |
+
+菜单只是功能入口，不改变原服务端授权条件。
+
+## 8. HUD 实施细节
+
+### 8.1 `MobileHud` 兼容接口
+
+`MobileHud` 实现与当前 `Hud` 相同的状态更新方法，并额外提供以下信号：
+
+```gdscript
+signal avatar_pressed
+signal inventory_pressed
+signal minimap_pressed
+signal menu_pressed
+signal quest_pressed(quest_id: int)
+signal party_member_pressed(vid: int)
+signal context_action_pressed(action: String)
+```
+
+`GameScene` 根据 UI 模式创建 `Hud` 或 `MobileHud`，并把最终对象继续传给 `NetPlay`。
+
+### 8.2 避免重复 HUD
+
+当前 `hud.gd` 自己创建状态条、小地图占位、快捷栏和背包占位，同时 `GameScene` 还创建正式 `Quickbar`、`InventoryUI` 和 `Minimap`。
+
+移动模式必须明确只有一个拥有者：
+
+- `MobileHud` 拥有首页状态、目标、任务、顶部按钮和触控布局。
+- `Quickbar` 继续拥有技能槽数据、冷却和激活逻辑，但其 PC 可视节点在移动模式隐藏。
+- `InventoryUI` 继续拥有背包数据和动作，但其 PC 入口隐藏。
+- `Minimap` 继续提供地图数据/绘制能力，移动模式把可视根节点挂入 `MobileHud.MinimapHost` 或增加 compact 布局。
+
+不能同时显示 PC HUD 和移动 HUD。
+
+### 8.3 安全区与缩放
+
+- 根布局使用 Godot anchors，不使用整页固定坐标。
+- 使用 `DisplayServer.get_display_safe_area()` 获取安全区。
+- 左上玩家区和右上按钮组至少保留安全区边距。
+- 基准触控目标不小于 48dp；普攻主按钮建议 80–96dp。
+- HUD 缩放按短边计算，并设置最小/最大范围，避免平板按钮过大。
+- 字体单独分级，不跟随 PC 窗口做纯比例缩放。
+
+## 9. 移动输入方案
+
+### 9.1 虚拟摇杆
+
+在 `PlayerController` 中增加移动轴输入，不模拟键盘事件：
+
+```gdscript
+var _mobile_axis := Vector2.ZERO
+
+func set_mobile_axis(axis: Vector2) -> void:
+    _mobile_axis = axis.limit_length(1.0)
+```
+
+移动优先级建议：
+
+```text
+虚拟摇杆 > PC 键盘 > 点地移动 > 无移动
+```
+
+摇杆输入不为零时：
+
+- 取消当前点地目标 `_is_going`。
+- 沿用现有相机相对方向、速度、阻挡、Actor 碰撞和动画逻辑。
+- 摇杆松开后 `_mobile_axis` 清零。
+- 受击、锁定、移动技能等现有移动门继续生效。
+
+### 9.2 普攻与技能
+
+- 普攻按钮按下调用 `NetPlay.set_attack_key(true)`，抬起或触摸取消调用 `false`。
+- 技能按钮点击调用 `Quickbar.activate(slot)`。
+- 技能长按进入瞄准态，拖动调整方向，松手调用 `Quickbar.activate_aimed()`；短按仍调用 `Quickbar.activate()`。
+- 方向计算、技能冷却、不可使用原因和目标选择继续由现有 `Quickbar`/`NetPlay` 处理。
+- 触摸取消必须清理攻击按下状态，避免切后台后持续攻击。
+
+### 9.3 触摸仲裁
+
+当前 `PlayerController` 和 `GameCamera` 都接收 `InputEventScreenTouch/Drag`。新增移动控件后必须防止同一个触点同时操作 UI 和世界。
+
+建议规则：
+
+1. `MobileInputOverlay` 在 `_gui_input` 中记录被 UI 捕获的 touch index。
+2. 被捕获的 index 不传给玩家点地和镜头控制。
+3. 摇杆、技能、菜单、窗口区域调用 `get_viewport().set_input_as_handled()`。
+4. 未被捕获的单指仍用于点地/选中或镜头拖动。
+5. 双指缩放只统计世界区域中的触点。
+6. 模态窗口打开时阻止所有世界输入。
+7. 应用暂停、失焦、死亡和过场时强制释放全部触点状态。
+
+建议把捕获状态集中到一个 `TouchRouter`，不要让每个按钮各自维护全局触点。
+
+## 10. 功能窗口适配策略
+
+### 10.1 三种适配级别
+
+#### A. 直接复用控制器并更换入口
+
+适用：背包开关、大地图、任务日志、好友、公会、系统菜单。
+
+首期由 `MobileUiRoot` 调用现有 `toggle/open/close` 方法。
+
+#### B. 同一控制器增加移动布局
+
+适用：队伍、快捷栏、小地图、聊天、系统设置。
+
+保留数据和信号，给 `_build()` 增加 `layout_mode`，分别构建 desktop/mobile 视图。
+
+#### C. 拆分逻辑和视图
+
+适用：背包、角色、技能、商店、交易、仓库、Cube 等固定坐标和拖放较重的窗口。
+
+逐步拆成：
+
+```text
+FeatureController：数据、信号、网络操作、校验
+DesktopFeatureView：现有 PC 布局
+MobileFeatureView：横屏全屏布局
+```
+
+首期允许保留现有控制器，并只在真正重做对应页面时拆分，避免一次性重构全部 UI。
+
+### 10.2 PC 专属交互的移动替代
+
+| PC 交互 | 移动端替代 |
+|---|---|
+| 鼠标悬停 tooltip | 短按选中、长按详情 |
+| 右键使用/出售 | 选中后显示主操作按钮 |
+| 标题栏拖动窗口 | 固定全屏或右侧面板 |
+| 键盘 I/K/C/N/M | 首页入口或五类菜单 |
+| 数字键/F1–F4 技能 | 右下技能盘 |
+| 鼠标拖动物品 | 长按进入拖动，松手落位 |
+| ESC 关闭 | 系统返回、面板关闭按钮、遮罩点击 |
+
+## 11. `GameScene` 接入方案
+
+建议把 UI 创建拆成三个阶段：
+
+```gdscript
+func _build_shared_feature_controllers() -> void:
+    # 创建背包、技能、任务、社交、商店等共享控制器
+
+func _build_desktop_presentation() -> void:
+    # 创建当前 Hud、PC Quickbar、PC 窗口入口
+
+func _build_mobile_presentation() -> void:
+    # 创建 MobileUiRoot、MobileHud、触控层和移动菜单
+```
+
+接入顺序：
+
+1. 创建 `UiManager` 和共享功能控制器。
+2. 检测 `UiProfile`。
+3. 创建 Desktop 或 Mobile 表现层。
+4. 把当前 HUD 实例传给 `NetPlay`。
+5. 将 `Quickbar`、`PlayerController`、`GameCamera`、`GroundItems` 注入 `MobileInputOverlay`。
+6. 将现有功能控制器注入 `MobileUiRoot` 的路由绑定。
+7. 地图切换或世界重载时，只重载世界相关 HUD 数据，不重建所有功能控制器。
+
+## 12. 开发阶段
+
+### 阶段 M1：双 UI 骨架（已完成，待真机验收）
+
+目标：PC UI 完全不变，桌面可强制预览移动 UI。
+
+- 增加 `UiProfile`。
+- 增加 `MobileUiRoot`、安全区和横屏约束。
+- `GameScene` 能在 Desktop/Mobile 表现层之间选择。
+- 移动 HUD 使用假数据完成布局，但不重复显示 PC HUD。
+
+验收：
+
+- macOS 默认仍显示现有 PC UI。
+- 强制 mobile 时只显示移动 HUD。
+- Android/iOS 自动选择移动 UI。
+
+### 阶段 M2：首页状态与入口（已完成，待真机验收）
+
+- 接入玩家名称、HP、MP、资源、经验、等级和状态效果。
+- 接入目标名称与目标 HP。
+- 接入背包、小地图、头像、任务条和五类菜单。
+- 接入左上队伍紧凑条。
+- 接入死亡、重连、副本目标等覆盖状态。
+
+验收：所有首页入口打开正确功能，返回后恢复场景输入。
+
+### 阶段 M3：移动与战斗触控（代码完成，待真机验收）
+
+- 新增虚拟摇杆连续移动。
+- 新增普攻、技能、药水和情境交互按钮。
+- 处理触摸 index 捕获、取消、切后台和模态窗口。
+- 接入技能冷却、不可使用原因和目标选择反馈。
+
+验收：移动、镜头、攻击、技能可同时使用且不串触摸。
+
+### 阶段 M4：高频功能页（部分完成）
+
+- 角色/装备/技能全屏页：角色属性/装备、技能分类和技能升级已有横屏专用布局；角色表情也提供移动触控页。
+- 背包和物品详情：背包点按操作、长按详情、数字键盘数量输入、跨窗口长按拖放已完成；仍需真机确认系统手势区和键盘共存体验。
+- 任务日志和大地图：已有移动托管；大地图支持单指拖动并在双指时冻结单指拖动。
+- 聊天与好友：聊天/私聊已有横屏输入页、触控按钮和弹窗返回处理，真机键盘体验待验收。
+
+验收：不依赖右键、鼠标悬停和键盘即可完成完整操作。
+
+### 阶段 M5：商业、制作与系统（部分完成）
+
+- 商店、商城、交易、私人商店、仓库和兑换：移动端入口/候选列表/点按操作已覆盖；服务端上下文仍需联机验收。
+- Cube、精炼、龙魂入口状态：Cube 配方/材料/制作和精炼按钮已有横屏触控布局，龙魂仍按功能开关控制。
+- 系统设置、游戏设置、帮助、角色切换、登出和退出：系统设置/游戏设置/帮助已有横屏专用布局；系统菜单增加移动端专用横屏入口，好友、公会创建、公会邀请、商城/仓库密码、商店确认等确认弹窗已扩大触控尺寸并接入返回处理。
+- 确保所有上下文窗口只在服务端允许时打开。
+
+### 阶段 M6：真机验收与视觉统一（未完成）
+
+- Android 和 iOS 安全区。
+- 不同屏幕比例、分辨率和 DPI。
+- 多指触控、后台恢复和断线重连（代码已接入，仍需真机/联机验收）。
+- GPU/CPU/内存与触控延迟。
+- 统一暗色玻璃、铜金边框、字号、按钮和动画。
+
+## 13. 测试方案
+
+### 13.1 自动化测试（已实现）
+
+以下移动端专项测试已经加入项目，并与现有 PC/业务测试一起运行：
+
+- `mobile_ui_test.gd`：模式解析、横屏保护、安全区、HUD 状态、菜单分类和 UI/世界触点仲裁。
+- `mobile_window_host_test.gd`：返回键、模态阻断和窗口栈。
+- `mobile_gesture_test.gd`：长按/拖动触摸状态、技能瞄准、技能拖入快捷栏、快捷栏交换和物品触摸拖放。
+- `chat_mobile_ui_test.gd`：横屏聊天日志、频道切换、私聊目标和数字键盘友好的输入页。
+- `gamescene_test.gd`：PC/移动 UI 装配互斥和移动根节点接线。
+- `char_status_ui_test.gd`、`inventory_ui_test.gd`：角色页、背包详情、数量输入和触摸操作。
+- `p8_test.gd`：交易候选列表、仓库取出和移动端仓库存入候选列表。
+- `shop_cube_mall_test.gd`：Cube 配方、材料添加/删除、制作按钮和移动端横屏布局。
+- `guild_creation_ui_test.gd`、`guild_war_skill_test.gd`、`help_ui_test.gd`：公会、帮助和确认弹窗的移动布局。
+- `system_menu_ui_test.gd`、`system_option_ui_test.gd`、`private_shop_ui_test.gd`：系统入口、设置和商业窗口的移动交互。
+
+完整测试集当前共 78 个 `*_test.gd`，现有 PC UI、业务、网络、战斗和移动端测试均通过。推荐命令：
+
+```bash
+for test in $(rg --files project -g '*test.gd' | sort); do
+  /opt/homebrew/bin/godot --headless \
+    --rendering-method gl_compatibility \
+    --rendering-driver opengl3 \
+    --audio-driver Dummy \
+    --log-file "/tmp/mtgodot-${test##*/}.log" \
+    --path project --script "${test#project/}" || exit 1
+done
+```
+
+### 13.2 桌面模拟验收
+
+- 844×390、16:9 平板、超宽屏三档。
+- 鼠标模拟触控验证所有移动入口。
+- 强制 mobile profile 后走完登录、角色选择和游戏内 UI。
+- 同一进程切换地图、死亡复活和断线重连。
+
+### 13.3 Android/iOS 真机验收
+
+- 刘海和系统手势区不遮挡按钮。
+- 左手持续移动时，右手可选目标、普攻和连续释放技能。
+- 两指缩放不会触发点地或技能。
+- 拖动物品时不会移动角色或旋转镜头。
+- 来电/切后台后，摇杆和普攻状态正确释放。
+- 队伍成员变化、HP 和距离能实时更新。
+- 商店、仓库、制作等页面不会绕过服务器上下文。
+
+## 14. 完成标准
+
+移动端 UI 可认为完成，必须同时满足：
+
+1. PC UI 默认行为和快捷键无回归。
+2. Android/iOS 自动进入移动 UI，桌面可强制预览。
+3. 首页严格符合已确认草图布局。
+4. 角色只从玩家头像进入。
+5. 队伍只在头像下方显示，不在社交菜单出现。
+6. 任务、小地图和背包保持首页直达。
+7. 右上菜单只有社交、成长、活动、商业、系统五类。
+8. 不使用键盘、鼠标右键或悬停，也能完成所有移动端操作。
+9. 所有功能继续使用现有服务器授权和网络包流程。
+10. 自动化测试、桌面模拟和 Android/iOS 真机测试均通过。
+
+## 15. 改动规模与主要风险
+
+### 15.1 改动规模
+
+| 层级 | 改动规模 | 说明 |
+|---|---|---|
+| 网络协议与服务端 | 小/无 | 继续使用现有 `M2Client` 与 40250 流程 |
+| 游戏状态与战斗逻辑 | 小 | 增加移动输入入口，不重写校验和攻击流程 |
+| 首页 HUD | 大 | 新建移动端表现层 |
+| 输入系统 | 中到大 | 摇杆、技能盘、多指仲裁是核心新增 |
+| 高频功能页 | 中到大 | 背包、角色、技能、任务需重排 |
+| 低频窗口 | 中 | 可分阶段适配 |
+| PC UI | 小 | 原样保留，只增加模式分流 |
+
+### 15.2 主要风险
+
+1. **触摸穿透**：技能或摇杆触摸同时触发地面移动/镜头。
+   - 对策：集中式 `TouchRouter`，按 touch index 捕获。
+2. **重复 HUD**：旧 HUD、Quickbar、Minimap 与新 HUD 同时显示。
+   - 对策：明确 Desktop/Mobile 表现层互斥创建。
+3. **固定坐标窗口过小**：PC Python UI 在移动端不可操作。
+   - 对策：高频页优先重排，低频页先用安全区容器过渡。
+4. **菜单绕过上下文**：直接打开商店、仓库、精炼等造成无效状态。
+   - 对策：`MobileUiRoot` 区分“可直接打开”和“需要 NPC/服务器状态”。
+5. **PC 回归**：共享控制器重构影响键盘和鼠标行为。
+   - 对策：首期新增并行表现层，拆分控制器时补双端测试。
+6. **横屏安全区差异**：按钮被刘海或系统边缘手势遮挡。
+   - 对策：运行时读取安全区并保留可配置边距。
+
+## 16. 推荐首个实现切片
+
+首个可真机验证的垂直切片已经完成，当前作为移动端联调基线：
+
+```text
+UI 模式选择
+→ 移动 HUD
+→ 头像/背包/地图/任务/菜单入口
+→ 左上队伍条
+→ 虚拟摇杆
+→ 普攻 + 4 个技能
+→ Android 真机战斗验证
+```
+
+该切片已让客户端具备可用的移动端首页和核心战斗能力；角色、背包、技能等全屏页也已按使用频率完成移动布局，剩余工作集中在真机/联机验收和视觉微调。
+
+## 17. 当前实现状态
+
+截至 2026-09-04，代码已完成首个垂直切片，并继续补齐了部分商业/制作页面：
+
+- `project/ui/ui_profile.gd`：`AUTO/DESKTOP/MOBILE` 模式选择，支持移动设备自动识别、`mt/ui/profile` 配置和 `--mobile-ui` / `--desktop-ui` 预览参数。
+- `project/ui/mobile/mobile_ui_root.gd`：移动端 CanvasLayer 根节点，按 844×390 横屏设计基准自适应缩放并处理功能路由。
+- `project/ui/mobile/mobile_hud.gd`：名称、头像、同宽 HP/MP、目标、队伍紧凑条、任务入口、背包/小地图/菜单入口。
+- `project/ui/mobile/mobile_input_overlay.gd`、`virtual_joystick.gd`、`mobile_touch_button.gd`：虚拟摇杆、普攻、药水、4 个技能触控按钮、触摸取消和失焦释放。
+- `project/ui/mobile/mobile_input_overlay.gd`、`project/player_controller.gd`：集中记录移动 UI 触点，避免“摇杆 + 世界触点”触发点地移动。
+- `project/ui/mobile/mobile_menu_drawer.gd`：社交、成长、活动、商业、系统五类两级菜单。
+- `project/player_controller.gd`：新增移动轴输入，沿用现有相机相对移动、阻挡、动画和状态门。
+- `project/ui/char_status_ui.gd`：角色属性/装备和表情移动横屏页面，属性点仍走原 `/stat` 命令。
+- `project/ui/skill_ui.gd`、`project/ui/quickbar.gd`：技能移动横屏列表、升级和一键放入快捷栏空位。
+- `project/ui/inventory_ui.gd`：物品长按详情、使用/选择操作和移动端数字键盘数量输入。
+- `project/ui/chat_ui.gd`：横屏聊天日志、频道切换和私聊输入页。
+- `project/ui/system_option_ui.gd`、`project/ui/game_option_ui.gd`：横屏系统/游戏设置页，保留原配置和服务器命令。
+- `project/ui/help_ui.gd`、`project/ui/system_menu_ui.gd`：横屏帮助页和移动模式下的帮助路由。
+- `project/ui/minimap.gd`：复用现有小地图绘制和数据，移动模式挂载到右上 HUD；点击地图仍打开大地图。
+- `project/ui/party_ui.gd`、`quickbar.gd`、`quest_log.gd`：移动模式隐藏 PC 表现层，保留原数据和业务控制器。
+- `project/game_scene.gd`：PC/移动表现层互斥装配，移动端控制器注入统一路由；PC HUD 默认路径保持不变。
+- `project/ui/safebox_ui.gd`：移动端背包候选列表，点按存入、点按取出和重复请求保护。
+- `project/ui/cube_ui.gd`：移动端横屏双列滚动布局，配方、材料添加/删除和制作按钮均可触摸。
+- `project/ui/refine_ui.gd`：移动端横屏精炼信息与操作布局。
+- `project/ui/guild_ui.gd`：移动端横屏公会四页布局、成员/技能/公会战/公告的触控按钮和创建公会弹窗。
+- `project/ui/system_menu_ui.gd`：保留桌面原始系统菜单，移动端使用横屏专用系统菜单，入口和服务器命令保持一致。
+- `project/ui/friend_ui.gd`、`project/game_scene.gd`、`project/ui/shop_ui.gd`、`project/ui/mall_ui.gd`、`project/ui/safebox_ui.gd`：确认弹窗移动触控尺寸与 Android 返回优先取消处理。
+- `project/ui/ui_manager.gd`、`project/ui/mobile/mobile_window_host.gd`：动态 Button 触摸桥接、原生确认弹窗登记、模态阻断、返回顺序和安全区变化重排。
+- `project/ui/reconnect_ui.gd`、`project/app_flow.gd`：游戏内断线保留 `GameScene`，显示移动重连遮罩，自动重新进入上次角色。
+- `project/project.godot`：增加移动 UI 配置项和横屏方向设置。
+
+当前验证结果：
+
+- 全部 78 个 `*_test.gd` 通过，包括 `app_flow_lifecycle_test.gd`、`p10_test.gd`、`mobile_ui_test.gd`、`mobile_window_host_test.gd` 和 `mobile_gesture_test.gd`；Godot 脚本解析检查通过。
+
+尚未完成的部分包括：Android/iOS 真机安全区、不同屏幕比例、多指、后台恢复、性能与触控延迟验收，以及商业页面在真实服务器上下文下的联机验收。断线重连的代码路径已经完成：游戏中断线会保留当前 `GameScene`、显示遮罩并自动重新进入上次角色，但仍需要在真机和真实服务器上验证网络切换、后台恢复及重连失败边界。低频页面仍需要在真机上做字号、键盘和安全区的视觉微调；当前不能据此视为最终移动端交付完成。