# G502 X PLUS：G HUB 功能与交互基准

2026-10-23，通过用户截图和本机已安装 G HUB 的页面资源、中文文案、设备定义核对。先通过本机资源核对，再通过 UI Automation 导航和 PrintWindow 取得设备分配、灵敏度、LIGHTSYNC、宏命名/类型/序列编辑、设备设置页。用户新增后台验收偏好后，不再还原或操作 G HUB 窗口；后续使用已有参考图与新应用自身后台渲染。

## 产品目标

沿用现有 WinUI 3、MVVM、导航、设置和日志架构。设备配置流程与 G HUB 对齐，在此基础上新增直接板载写入。协议参数、十六进制数值和脚本文本不能成为普通设置的必经步骤。

## 已核对的来源

- `C:\Program Files\LGHUB\resources\app.asar`：当前安装版的页面组件与状态结构。
- `C:\ProgramData\LGHUB\depots\876190\core\data\strings\common\zh-CN.yaml`：功能分类、宏类型、宏序列分段、录制、标准延迟、DPI、LIGHTSYNC、板载设置的文案。
- 设备资源 `8807090d-3e9c-4dfe-a6a6-a863d7b688d4` 与 `97b085d9-0fde-406b-8bcd-b244746387e7` 的 `manifest.json`、`metadata.json`、`defaults_override.json`、`light_map.json`：G502 X PLUS 视图、按键位置、默认设置、X/Y DPI、8 个灯区。
- 用户提供的“按键分配 / 宏”截图。

页面 JS/CSS 仅在被忽略的 artifacts/ghub-reference 中供核对，没有复制为应用实现。设备图和字体已用于用户要求的本地还原，详见 ASSET-PROVENANCE.md。

## 功能与交互

| 区域 | G HUB 行为 | 本项目对应要求 |
| --- | --- | --- |
| 设备页 | 型号、配置选择、设备设置入口 | 保留设备中心；板载槽作为配置目的地 |
| 按键分配 | 命令、按键、操作、宏、系统五个分类；搜索；拖至鼠标点位 | 分类和鼠标点选为主要操作，隐藏底层编码 |
| 设备视图 | 正面、侧面；点位与功能标签相连 | 两个视图共用同一组真实绑定 |
| G-Shift | 默认层与 G-Shift 层切换 | 独立编辑和保存，不能清空另一层 |
| 鼠标操作 | 左右中键、前后退、横滚、DPI、配置循环等 | 可选的人类可读命令，不能要求手输枚举 |
| 系统 | 媒体、编辑、鼠标、软件控制、启动应用 | 区分固件可执行动作和需要主机的动作 |
| 宏 | 不重复、按住时重复、触发、序列 | 四种模式；序列为点击、按住、松开三个片段 |
| 宏编辑 | 录制、开始/停止、标准延迟、按下/释放、插入延迟、文本、系统/程序动作 | 可视化步骤编辑，文本脚本仅作高级入口 |
| 灵敏度 | 预设、五档 DPI、活动/默认/Shift、X/Y 分离、有线/无线回报率 | 保留这些概念，逐项映射到设备能力 |
| LIGHTSYNC | 预设、自由、动画；颜色、速度、亮度；8 个灯区 | 支持区分设备端效果、软件动态效果和动画 |
| 设备设置 | 板载模式、配置槽、固件、电量、电源管理、灯光设置 | 板载模式仍可编辑，增加备份、恢复和写入校验 |

## 需要纠正的初版设计

- 普通用户不应通过 `special` 参数、HID 键码或脚本给鼠标分配常用操作。
- 配置页不能用一组协议表单替代 G HUB 的设备点位、分类库和宏编辑流程。
- 主机模式和板载模式需要共用用户可理解的配置模型；不能把软件模式的所有能力直接当作固件能力。
- “序列宏”和启动应用、软件集成、屏幕取色、音频响应等依赖主机的功能，必须有相应的软件执行实现；不能将它们显示为已支持的板载功能。
- 未经该型号实测的写入不能标注为完整适配或已验证。

## 已读取的实际设备

G502 X PLUS 经 LIGHTSPEED 接收器 `046D:C547`，HID++ 地址 `01`，描述字节为 `01 0A 01 05 02 0B 10 00 FF 0A 04`。

- 配置格式 10、宏格式 1、5 个配置槽、11 个物理按键、16 × 255 字节。
- 普通按键表从 `0x20` 起，G-Shift 表从 `0x60` 起，名称区从 `0xA0` 起。
- 当前用户配置 CRC 校验通过；读取时为主机模式，活动板载地址为 0。
- 旧格式中的回报间隔字节为 `FF`，不能解释成 255 ms 或自动显示为 1000 Hz。
- `0x56..0x5F` 出现第二组 DPI 数据，应保留，不能当作普通按键记录覆盖。
- 已执行基础单次连点宏和固件预设灯效的实机写入/读回；G5 物理触发 5 次点击，平均间隔 101.997ms；已恢复原始 19 扇区及模式/活动配置。断电保持、按住/触发循环、完整序列仍未完成物理实测。

## 本轮交互核对与实测边界

继续只读分析本机已提取的页面组件、样式、中文文案与动画数据，没有使用电脑技能，也没有重新激活 G HUB。下列 G HUB 操作逻辑来自本机资源；新软件的控件路径使用程序调用 WinUI 控件和状态转换验证，不能将其等同于对当前 G HUB 的完整运行交互测试。

- 宏：名称输入并按 Enter → 选择四种类型 → 编辑事件 → 保存；取消创建移除临时条目，取消编辑恢复原内容。实际保存按钮通过自动化控件接口调用，并读回独立宏库文件。
- 动画：内置动画编辑生成副本；选帧、单灯区着色、过渡曲线、帧时长、插入/复制/删除/重排、预览/定位、缩放、方向与默认速度；保存写入动画库，取消恢复进入前的快照。指针拖放没有被全局输入模拟，重排验证使用与拖放处理器相同的方法。
- HERO：介绍 → 源鼠标/DPI → 同时移动约 10 英寸 → 传感器完成/失败 → 详情/命名。G HUB 在板载模式禁用该入口。本机 `0x2202` 能力为 `0x0D`：板载模式函数 8 返回 `0x05`，切到实际软件模式后正常读到宽 60、长 125、400×400 DPI。现已按模式控制入口，并在切换配置后刷新能力；此前将该错误归为固件故障的判断已纠正。双鼠标成功测量/保存尚未物理实测。
- LIGHTFORCE：`0x8090` 状态位 0，混合/仅光学为设备级设置，按四字节掩码更新并保留其他位。已切换两种值并读回、恢复。
- 启动效果：`0x8071` 非易失配置，保留六个不透明参数；已开/关切换并读回、恢复。
- 板载配置：选择板载槽即启用自动保存；有效编辑合并 200ms 手势后写入，备份、串行、读回一致后显示已保存。切换配置前等待未完成事务；不将软件草稿覆盖到同编号的板载槽。

对应证据在 `work/visual/advanced-build/`。HERO 成功测量与保存、自定义动画 EEPROM 播放、G HUB 云端/游戏集成以及真实指针拖放和录制全流程仍不能标记为全部验证。

## 视觉核验

最终验收需求冻结于 `work/visual/requirements.json`。应用以原尺寸导出 RenderTargetBitmap 与可见控件布局；使用 background-visual-check 的原图、原比例分块、局部放大、OCR、同尺寸并排和差异图核对，并逐项记录 pass/fail/uncertain。测试通过不等于全部视觉达标。

仍存在 G HUB 高级功能与细节差异，不能将设备页的局部还原写成整个 G HUB 的一比一完成。