@@ -1,519 +0,0 @@
# FancyInput WPF → Qt 6 (QML + C++) 迁移方案
> 版本：v2.1 · 日期：2026-08-20 · 状态：待评审
> 源项目：`WPF\FancyInput`（
> 目标框架：**Qt 6.8.3（ ）
> 目标：**UI 布局完全一致、逻辑相同**，代码用 QML + C++ 重写
> 构建约束：**CMake + MinGW（
> 许可约束：**只使用可免费商用的组件，不使用 GPL/AGPL 强传染许可的开源模块**
---
## 新会话快速上手（★ 新开会话先读这里）
> 本工程已通过 **阶段 0（Hello World）+ 构建基础设施**，全部验证通过。以下信息足以让一个新会话立刻上手，详细踩坑记录见仓库记忆 `/memories/repo/qt-build-notes.md`（新会话会自动加载）。
### 当前工程结构（已验证可构建可运行）
```
Qt\
├── CMakeLists.txt # 顶层工程（两个 QML 模块 + 部署裁剪）
├── CMakePresets.json # MinGW_64_Debug / MinGW_64_Release 预设
├── MIGRATION_PLAN.md # 本文档
├── .vscode\settings.json # qmlls import paths + cmake preset
├── src\
│ ├── main.cpp # QGuiApplication + addImportPath("qrc:/") + loadFromModule
│ └── qml\
│ ├── Main.qml # 主窗口（ApplicationWindow 600×
│ └── controls\ # ★ 用户自定义控件目录（URI: FancyInput.Controls）
│ └── Theme.qml # 全局主题单例（pragma Singleton）
├── bin\{Debug,Release}\ # exe + windeployqt 部署的 Qt 运行库（最终产物）
└── build\MinGW_64_{Debug,Release}\ # 中间产物 + QML 模块目录（qmlls 用）
```
### QML 模块架构（关键！）
| 模块 | 类型 | URI | 内容 | 说明 |
|---|---|---|---|---|
| `FancyInputControls` | **静态库 ** （ `STATIC` 关键字写在 `qt_add_qml_module` 内） | `FancyInput.Controls` | `src/qml/controls/*.qml` （GLOB 自动收集） | 以后**新增控件只需放 .qml 文件，无需改 CMakeLists** |
| `FancyInputQt` | 可执行文件主模块 | `FancyInputQt` | `src/qml/Main.qml` | `DEPENDENCIES FancyInputControls` |
必须记住的三条铁律（踩过坑）：
1. **静态 QML 模块必须链接插件 target ** ： `target_link_libraries(FancyInputQt PRIVATE FancyInputControls FancyInputControlsplugin ...)` ，否则运行时报 "plugin FancyInputControlsplugin not found"；
2. * * `pragma Singleton` 不会被自动识别**：必须 `set_source_files_properties(Theme.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)` **且放在 `qt_add_qml_module` 调用之前 ** ；
3. * * `QT_QML_OUTPUT_DIRECTORY` 必须设置**：在**所有** `qt_add_qml_module` 之前写 `set(QT_QML_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}")` ——否则库模块输出到 build 根目录（Qt6QmlMacros.cmake:1430 警告）且 qmlls 找不到模块。
### 构建与验证命令（终端）
``` powershell
# 终端 PATH（每次新终端都要先执行）
$env:Path = " D:/Qt/6.8.3/mingw_64/bin;D:/Qt/Tools/mingw1310_64/bin;C:\Windows\System32;C:\Windows "
Set-Location " d:\Projects\FancyInput\Qt "
# 配置（仅首次或 CMakeLists 变更时）
& " C:\Program Files\CMake\bin\cmake.exe " - -preset MinGW_64_Debug
# 编译（每次改完代码；干净重建加 --clean-first）
& " C:\Program Files\CMake\bin\cmake.exe " - -build - -preset MinGW_64_Debug
# 运行验证（GUI 程序无控制台输出，用窗口标题确认）
# 先切干净 PATH 再运行，验证独立运行（不带 Qt bin 目录）：
$env:Path = " C:\Windows\System32;C:\Windows "
Start-Process " bin\Debug\FancyInputQt.exe " -PassThru | Select-Object MainWindowTitle
# 期望标题："FancyInput · Qt 迁移版（阶段 0）
# QML 模块解析验证（无输出 = 成功）
& " D:\Qt\6.8.3\mingw_64\bin\qmllint.exe " -I build / MinGW_64_Debug -I D: / Qt / 6.8 . 3 / mingw_64 / qml src / qml / Main . qml src / qml / controls / Theme . qml
```
### 许可状态（2026-08-20 已核对，全部 LGPL 安全 ✅）
- 部署的 Qt DLL 全部为 LGPL v3 官方模块（SPDX 核对 qtbase/qtdeclarative/qtsvg： `Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only` ，开源版按 LGPL v3 使用）；
- MinGW 运行时 DLL（ **GCC Runtime Library Exception ** （ `D:\Qt\Tools\mingw1310_64\licenses\gcc\COPYING.RUNTIME` 已确认），允许闭源商用；
- **Qt6VirtualKeyboard（ `GPL_COMPONENTS` 块强制裁剪**（
- bin/Release 实测 24 个 DLL（
### 下一步
**进入阶段 1（通用函数与数据结构） ** ，从 `src\core\common\Enums.h` 开始。详见下文第四、五节的分阶段计划。
---
## 〇、许可合规策略（重要）
**核心原则：全部组件要么是 LGPL 动态链接（可免费闭源商用），要么是宽松许可（MIT/zlib/BSD），一律避开 GPL/AGPL。 **
### Qt 模块选型（Qt 6.8.3 开源版，LGPL v3）
| Qt 模块 | 许可 | 商用方式 | 本项目用途 | 采用 |
|---|---|---|---|---|
| Qt6Core / Gui / Qml / Quick | LGPL v3 | **动态链接 DLL ** + 附 LGPL 声明 → 可闭源免费商用 | 基础/界面 | ✅ |
| Qt6QuickControls2 | LGPL v3 | 同上 | 控件库 | ✅ |
| Qt6Network | LGPL v3 | 同上 | 更新检查 | ✅ |
| Qt6Multimedia | LGPL v3 | 同上 | GIF/音效（可延后） | ✅ |
| Qt6Svg | LGPL v3 | 同上 | 图标渲染（可选） | ✅ |
| Qt6QuickShapes | LGPL v3 | 同上 | 矢量图标（替代 PathData）
| Qt6Charts | **GPL v3 ** | 需商业授权 | 不需要 | ❌ |
| Qt6DataVisualization | **GPL v3 ** | 需商业授权 | 不需要 | ❌ |
| QtGamepad | **仅商业版 ** | 开源版没有该模块 | 手柄（改用自写 XInput/SDL3 封装） | ❌ |
> **LGPL 合规要点（务必遵守）**：
> 1. **动态链接** Qt 共享库（默认方式），**禁止** `-static` 静态链接 Qt；
> 2. 发布时附带 `LGPLv3` 许可文本 + 使用的 Qt 版本/模块清单；
> 3. 随包分发 Qt DLL（
> 4. 应用自身代码可完全闭源。
### 第三方依赖选型
| 库 | 许可 | 商用 | 用途 | 采用 |
|---|---|---|---|---|
| SDL3（ ） **zlib ** | ✅ 免费商用 | 手柄读取后端 | ✅ |
| XInput（ ）
| ViGEmClient | **MIT ** | ✅ 免费商用 | 虚拟 Xbox 手柄（延后阶段） | ✅ |
| HidHideCLI.exe | **GPL v3 ** | ❌ 需授权/分发限制 | 隐藏真实手柄（WPF 中已注释） | ❌ 不迁移 |
| MouseKeyHook | BSD-2 | ✅ | WPF 用；Qt 侧改用 Raw Input，
| WpfAnimatedGif | MIT | ✅ | WPF 用；Qt 侧用 QML AnimatedImage/QMovie | ❌ |
**结论 ** ：所有用到的组件均可免费商用；HidHide 因 GPL 放弃迁移（WPF 中本就是注释代码）。
---
## 一、现状盘点
### 1.1 WPF 项目结构（迁移源）
| 层 | 文件数 | 行数 | 说明 |
|---|---|---|---|
| `Models/` | 13 | ~4,569 | InputParser / RawInputParser / InputHandler / InputGenerator / XImage / OverlayParser / Macro 引擎 |
| `ViewModels/` | 14 | ~5,435 | MainWindow / ElementTree / ElementViewModel×
| `Views/Controls/` | 22 | ~2,050 | IconButton / AnimatedImage / 五面板 / Terminal / FormRow 等 |
| `Views/Elements/` | 22 | ~1,610 | 10 种叠层元素编辑器 + ElementTest |
| `Views/Macro/` | 12 | ~1,440 | 宏窗口 / 轨道 / 动作按钮 / 属性面板 |
| `Views/` （根+窗口） | 26 | ~3,800 | 主窗 / 叠层窗 / 元素树窗 / 图像编辑器 / 辅助窗口 |
| `Common/` | 5 | ~340 | 枚举 / PathData / 转换器 |
| 根目录 | 7 | ~1,900 | App / MainWindow |
| **XAML 样式 ** | 10 | ~2,888 | 全局主题（紫色 #FF651F65 + Cascadia Mono）
### 1.2 功能模块清单
1. **输入捕获 ** ：键盘（RawInput + 全局钩子双路径）、鼠标按键/移动/滚轮、XInput 手柄、SDL3 手柄（可切换）、Guide 键
2. **输入合成（反向链路） ** ：
3. **叠层系统 ** ：透明置顶穿透窗口、多窗口管理、10 种元素（键盘/鼠标/手柄按钮/滚轮/摇杆/扳机/玩家灯/DPad/鼠标移动/贴图）、帧切换驱动
4. **元素树编辑器 ** ：列表 + 画布 + 属性面板、拖拽/框选/对齐/移动绑定、图集生成、PNG+JSON / .fip 项目文件导出
5. **图像编辑器 ** ：裁剪/缩放/通道分离合并/圆形擦除/四方向合并/图集打包/拼接/GIF
6. **宏系统 ** ：三轨道（Pre/On/Post）、6 种动作（命令/键盘/鼠标按键/鼠标移动/滚轮/延迟）、Once/Hold/Toggle 触发、录制、.fipm 文件
7. **工坊 ** ：宏管理入口 + 默认路径
8. **主窗口五面板 ** ：读取 / 创建 / 管理 / 工坊 / 设置
9. **辅助窗口 ** ：关于 / 更新提示 / 版本时间线 / 二维码 / 控制台 / 开源声明 / 帮助 / 自定义消息框
10. **系统级 ** ：单实例（Mutex + 命名管道）、托盘图标、管理员自提权、在线更新检查、config.json 持久化
### 1.3 本机 Qt 环境（已确认可用）
```
D:\Qt\6.8.3\mingw_64 ← Qt 6.8.3 MinGW 套件（qmake 已确认）
D:\Qt\Tools\mingw1310_64 ← MinGW 13.1.0（ ）
cmake 4.3.2（ ）
QML 模块：QtQuick / QuickControls2 / Network / Multimedia / Svg 全部可用（LGPL）
注意：
- QtGamepad 模块开源版不存在 → 手柄后端用 SDL3（zlib）
- 无 Ninja → 用 "MinGW Makefiles" 生成器 + mingw32-make
- QtCharts / DataVisualization 为 GPL → 不用
```
---
## 二、目标架构（Qt 6 + QML + C++）
### 2.1 目录结构（在 `Qt\` 下新建）
```
Qt\
├── CMakeLists.txt # 顶层工程（Qt6 + QML 模块）
├── MIGRATION_PLAN.md # 本文档
├── resources\
│ ├── icons\ # Icon.ico / Icon.png（拷贝自 WPF）
│ ├── qrcodes\ # bilibili.jpg / wechat.jpg / xlworkspace.jpg
│ ├── styles\ # 主题 qmldir + QML 样式组件
│ └── Update.txt # 本地更新说明
├── src\
│ ├── core\ # 纯 C++ 逻辑层（不依赖 QML）
│ │ ├── input\ # InputParser / RawInputFilter / InputHandler / InputGenerator
│ │ │ ├── enums.h/.cpp # 全部枚举（FipKeys/FipRawKeys/InputDevice/…）
│ │ │ ├── inputevent.h # InputEvent 统一事件结构（Q_GADGET）
│ │ │ ├── win32rawinputfilter.h/.cpp # QAbstractNativeEventFilter + RawInput
│ │ │ ├── inputparser.h/.cpp # 统一采集器（QTimer 心跳 + 双手柄后端）
│ │ │ ├── xinputbackend.h/.cpp # XInput LoadLibrary 封装
│ │ │ ├── sdl3backend.h/.cpp # SDL3 手柄封装（链接 SDL3 C API）
│ │ │ ├── inputhandler.h/.cpp # 事件→元素状态分发
│ │ │ ├── inputgenerator.h/.cpp # SendInput / ViGEm / HidHide
│ │ │ └── vigemmanager.h/.cpp # ViGEmClient C++ SDK 封装
│ │ ├── image\ # XImage 算法层（QImage 重写）
│ │ │ ├── ximage.h/.cpp # Crop/ReSize/EraseCircle/Merge/PackImages/ConcatImages
│ │ │ └── gifplayer.h/.cpp # QImageReader/QMovie 帧延迟封装
│ │ ├── overlay\ # 叠层数据模型 + 序列化
│ │ │ ├── overlayparser.h/.cpp # OverlayRoot/OverlayElement JSON 读写
│ │ │ └── overlaytypes.h # OverlayElement struct
│ │ ├── macro\ # 宏引擎
│ │ │ ├── macroaction.h/.cpp # 6 种动作 + DTO 序列化
│ │ │ ├── macroplayer.h/.cpp # 播放引擎（QTimer 状态机 + QProcess）
│ │ │ ├── macrotrack.h/.cpp # 三轨道 + 录制
│ │ │ └── macro.h/.cpp # MacroViewModel 等价（触发/循环/保存）
│ │ └── app\ # 应用服务
│ │ ├── appconfig.h/.cpp # config.json / .fips / 单实例 / 托盘
│ │ ├── updatechecker.h/.cpp # QNetworkAccessManager 更新检查
│ │ └── singleinstance.h/.cpp # QLocalServer/QLocalSocket 单实例 + 管道消息
│ ├── models\ # QObject 模型层（QML 可绑定）
│ │ ├── elementviewmodel.h/.cpp # ElementViewModel（ ）
│ │ ├── elementtreeviewmodel.h/.cpp# 元素树模型（QAbstractListModel + DTO）
│ │ ├── overlaywindowviewmodel.h/.cpp
│ │ ├── mainwindowviewmodel.h/.cpp # 主窗 VM（配置/面板/叠层集合）
│ │ ├── macrowindowviewmodel.h/.cpp
│ │ └── imageeditorviewmodel.h/.cpp
│ └── qml\ # QML 视图层
│ ├── Main.qml # 主窗口（五面板 + 标题 + 状态栏）
│ ├── pages\ # ReadPage / CreatePage / ManagePage / WorkshopPanel / SettingsPage
│ ├── overlay\ # OverlayWindow.qml + 元素渲染组件（Repeater + Image 换帧）
│ ├── editor\ # ElementTreeWindow.qml + ElementEditor*.qml
│ ├── macro\ # MacroWindow.qml / MacroTrack.qml / MacroActionPanel.qml
│ ├── imageeditor\ # ImageEditor.qml
│ ├── dialogs\ # About / UpdatePrompt / RgbInput / AppMessageBox / …
│ └── controls\ # IconButton / AnimatedImage / FormRow / ToggleSwitch / Slider / …
```
### 2.2 架构原则
1. **分层 ** ： `core/` （纯 C++ 逻辑，可单测）→ `models/` （ `qml/` （纯视图，不做业务逻辑）
2. **与 WPF 的 MVVM 同构 ** ： `QObject` （ ；
3. **UI 一致 ** ：主题色 #FF651F65 / #953895 、Cascadia Mono 字体、圆角 8/10、阴影、滑动开关、现代滑杆、圆角 ComboBox——全部用 QML 自定义组件复刻
4. **行为一致 ** ：所有阈值（200ms 滚轮停止、100ms 移动停止、XInput 20 / SDL 2000 / SDL 扳机 5、10 帧扳机缓存、12 样本滑动平均去极值、DPad 1~8 帧映射等）原样保留
5. **数据兼容 ** ： `.fip` / `.fips` / `.fipm` / config.json / Overlay JSON 与 WPF 完全互通
---
## 三、逐子系统迁移方案
### 3.1 输入子系统（最高技术风险）
| WPF 组件 | Qt 6 对应 | 关键点 |
|---|---|---|
| `RawInputParser` （ ） `Win32RawInputFilter : QAbstractNativeEventFilter` | `qApp->installNativeEventFilter()` ； `MSG.message == WM_INPUT` 分支；`RegisterRawInputDevices` （ `_pressedKeys` 去重；修饰键/Lock 检测（GetKeyState）；`WM_ENTERSIZEMOVE/EXITSIZEMOVE` 拖拽时注销/注册 |
| `Gma.System.MouseKeyHook` 全局钩子 | ① RAWMOUSE `usButtonFlags` 补齐按钮/滚轮（推荐，去掉钩子依赖）② 或 `SetWindowsHookEx(WH_MOUSE_LL)` 封装 | 二选一，推荐① |
| `InputParser` （ ） `QTimer(Qt::PreciseTimer)` + `QElapsedTimer` ×
| XInput 手柄 | `LoadLibrary("xinput1_4.dll")` + `GetProcAddress` （无第三方依赖） | 4 个 pad、`IsConnected` 过滤、按钮按位边沿、摇杆阈值 20、扳机无阈值 |
| SDL3 手柄 | SDL3 C API 静态链接（仅手柄子系统，不与 Qt 冲突） | `SDL_UpdateGamepads()` 热插拔差分；阈值 2000/5；Y 轴反转；扳机 ×
| `InputHandler` 分发 | C++ `InputHandler` （
| `InputGenerator` （ ） ）
| `VirtualControllerManager` （ **ViGEmClient C++ SDK 静态链接 ** （ ） `vigem_alloc/connect/target_xbox360_alloc/add` ； `submit_report` ；
| `HidHideManager` | `QProcess` 调 HidHideCLI.exe（改异步防卡 UI）
| `Screen` / `Cursor` / DPI | `QScreen` / `QCursor` / `devicePixelRatio` | 高 DPI 自动处理，叠层物理像素对齐时用 devicePixelRatio |
### 3.2 叠层与元素系统
| WPF | Qt 6 对应 |
|---|---|
| `OverlayWindow` （透明置顶穿透） | QML `Window { flags: Qt.FramelessWindowHint \| Qt.WindowStaysOnTopHint \| Qt.Tool; color: "transparent" }` ；穿透用 `Qt.WindowTransparentForInput` 运行时切换（替代 WS_EX_TRANSPARENT P/Invoke）
| 黄色边框/去边框模式 | `margin` /`x` /`y` /`width` /`height` 联动 + 切换时 `opacity` 过渡（UpdateWindowSize 逻辑照搬） |
| 缩放 `2^Scale` | C++ 属性 `currentWidth = initialWidth * pow(2, scale)` + QML 绑定 |
| 元素渲染（Canvas+ItemsControl） `Repeater` + `Item { x: model.posX; y: model.posY }` + `Image { source: model.currentFrame }` ——帧切换驱动换图，架构不变 |
| 多窗口 / 索引 / 置顶顺序 | C++ `MainWindowViewModel` 持有 `QList<OverlayWindowViewModel*>` ； `raise()` /`lower()` ；
| 拖拽窗口 | `MouseArea` + C++ 算坐标（或 `QWindow::startSystemMove()` ）
| 11 种元素 | `ElementViewModel` （QObject）复用同一模型；每种元素渲染组件 + 编辑器组件 |
| 元素树编辑器 | `ElementTreeWindow.qml` ：左 ListView + 中 Flickable 画布（scale 缩放、锚点缩放公式照搬）+ 右属性面板 + `SplitView` 分栏 |
| 图集生成 | `QImage` + `QPainter` 重写 `PackImages` /`ConcatImages` （含 SPACE_BETWEEN_IMAGES=3；
| DTO 序列化 | `QJsonDocument` 重写 `.fip` （含 base64 内嵌 PNG/GIF 字节）；Overlay JSON 字段名不变 |
### 3.3 图像编辑器
| WPF（
|---|---|
| BGRA32 像素数组 | `QImage::Format_ARGB32` （小端同为 BGRA 字节序，可逐字节对照） |
| `Crop` （越界透明填充） | `QImage::copy` 不透明填充 → 需 `canvas.fill(Qt::transparent)` + `QPainter::drawImage` 保持语义 |
| `ReSize` / `Scale` | `QImage::scaled(..., Qt::SmoothTransformation)` |
| `EraseCircle` | `QPainter` + `QPainterPath::addEllipse` + `CompositionMode_Clear` （含包围盒优化） |
| `ExtractChannels` / `MergeChannels` | `QImage::bits()` 逐像素循环，逻辑 1:1（注意参数顺序 r,g,b,a,h,w 保留） |
| 四方向 `Merge` | 像素级照搬（percentage 语义表：Up/Down/Left/Right 的 splitPos 公式一字不差） |
| `PackImages` | QPainter drawImage 照搬（保持 WPF 的"按高度降序单行/行打包"输出一致） |
| `ConcatImages` | QPainter drawImage + spacing |
| GIF 帧/延迟 | `QImageReader::imageCount()/jumpToNextImage()/nextImageDelay()` （已处理 1/100s→ms 与 0→100ms）
| GIF 播放 | QML `AnimatedImage` （内部 QMovie）替代 WpfAnimatedGif |
| 编辑器 UI | `ImageEditor.qml` ：
### 3.4 宏系统
| WPF | Qt 6 对应 |
|---|---|
| 宏模型（三轨道 + 6 动作） | C++ `Macro` /`MacroTrack` /`MacroAction` （
| 触发（Once/Hold/Toggle + Press/Release） `QQueue<TriggerCommand>` + 互斥；校验逻辑（Hold 禁止 Release、宏包含触发动作禁止启用、总时长 <200ms 禁止）照搬 |
| 播放引擎 | C++ 状态机：`QTimer::singleShot` 链式执行各动作 + 取消令牌；Hold/Toggle 循环 10ms 间隔 |
| 命令动作 | `QProcess` （ ）
| 键盘/鼠标/滚轮/延迟动作 | 调 `InputGenerator` （
| 录制 | 输入事件流 → 动作追加；5000ms 阈值拆分、滚轮合并、距离/10 步数——录制状态机照搬 |
| 取消安全语义 | 取消时补发 Release、防 Start/Stop 竞态（`_isMacroRunning` 由 Play 收尾复位） |
| .fipm 保存 | `QJsonDocument` + 反射 DTO 改为手写字段序列化（字段名与 WPF 一致保证互通） |
| 宏窗口 UI | `MacroWindow.qml` ：三栏（宏列表 / 轨道+终端 / 属性面板），WrapPanel → `Flow` ，模板切换 → `Loader` ，录制红点/停止按钮 |
### 3.5 主窗口与 UI 主题
| WPF | Qt 6 对应 |
|---|---|
| 标题（Fancy/Input 双色 80px Cascadia Mono） `Text` × （ #FF651F65 + 默认黑） |
| 五面板切换按钮（读取/创建/管理/工坊/设置） | QML `Button` 自定义样式（选中 FancySelectedButton / 未选 FancyButton）
| `TabControl` | QML `StackLayout` + 按钮切换（与 WPF 面板切换行为一致） |
| 状态栏（调试圆点 + 文字） | QML `Row` + `Rectangle` （绿/红）+ `Text` |
| 托盘 | `QSystemTrayIcon` （C++）+ QML 信号桥；左键显示窗口 |
| 单实例 | `QLocalServer` /`QLocalSocket` （对应 Mutex + NamedPipe）；`--restart-as-admin` 参数处理照搬 |
| 管理员自提权 | `QProcess::startDetached` 重启 + `--restart-as-admin` |
| 更新检查 | `QNetworkAccessManager` + `QJsonDocument` （API 地址、版本比较、忽略版本持久化照搬） |
| config.json | `QJsonDocument` 读写 `%APPDATA%/FancyInput/config.json` （字段一致） |
### 3.6 主题样式（QML 复刻）
| WPF 样式 | QML 复刻 |
|---|---|
| FancyButton / RoundCornerButton | 自定义 `FancyButton.qml` （ #FF953895 、按下 #AA953895 、DropShadow）
| FancyTextBox / RoundCornerTextBox | `FancyTextBox.qml` （ #FF805C8F ）
| SimpleToggleSwitch（滑动开关） | `ToggleSwitch.qml` （ × #9C27B0 滑入动画 0.2s、按下缩放 0.9） |
| ModernSlider | `FancySlider.qml` （8px 轨道、紫色渐变进度、28px 圆形滑块 + 阴影） |
| RoundCornerComboBox | `FancyComboBox.qml` （ ×
| SimpleScrollViewer | QML `ScrollView` + 自定义 `ScrollBar` （ #A8B3C2 ）
| RoundedLabel / InfoTipBorder | `RoundedLabel.qml` / `InfoTip.qml` |
| IconButton（ ） `IconButton.qml` ： `Shape` /`Path` 解析 SVG PathData 字符串（Qt 支持 path 子集），属性 PathFill/PathStroke/CornerRadius/IsFlipped 照搬 |
| AnimatedImage | QML `AnimatedImage` （ ）
---
## 四、实施阶段划分（渐进式，每步可编译可调试）
> **核心原则**：按依赖顺序分 8 个阶段推进，每个阶段结束都有可运行、可验证的产物（编译通过 + 可运行 + 可见结果）。**宏系统、虚拟手柄、GIF 等锦上添花功能整体后移**，不污染前期代码。
**每阶段通用验收流程 ** （适用于所有阶段）：
1. 编写/调整代码 → 2. `cmake --build` 就地编译 → 3. 运行程序验证 → 4. 有变化才进入下一步
**每阶段通用的构建命令 ** （ `Qt\` 目录下，已改用 CMakePresets）：
``` powershell
# 终端 PATH
$env:Path = " D:/Qt/6.8.3/mingw_64/bin;D:/Qt/Tools/mingw1310_64/bin;C:\Windows\System32;C:\Windows "
# 配置（仅首次或 CMakeLists 变更时）
& " C:\Program Files\CMake\bin\cmake.exe " - -preset MinGW_64_Debug
# 编译（每次改完代码）
& " C:\Program Files\CMake\bin\cmake.exe " - -build - -preset MinGW_64_Debug
# 运行（exe 在 bin\Debug\ 下，非 build 目录）
. \ bin \ Debug \ FancyInputQt . exe
```
---
### 阶段 0：
**目标 ** ：
- [x] `Qt\CMakeLists.txt` ： `find_package(Qt6 COMPONENTS Core Gui Qml Quick QuickControls2)` ； `qt_add_executable(FancyInputQt ...)` + `qt_add_qml_module`
- [x] `src\main.cpp` ： `QGuiApplication` + `QQmlApplicationEngine` 加载 QML（ `objectCreationFailed` 兜底退出）
- [x] `src\qml\Main.qml` ： `ApplicationWindow` 600× ）
- [x] `src\qml\controls\Theme.qml` ：全局主题单例（主色 `#651F65` 、背景 `#1E1E24` 、字体 `Cascadia Mono` ）——**注意在 `controls\` 目录**（属 `FancyInput.Controls` 模块），不在 qml 根目录；用 `Theme.xxx` 引用
- [x] 双 QML 模块架构：`FancyInput.Controls` （静态库，GLOB 自动收集 controls/ 下所有 .qml） `FancyInputQt` （主模块）——以后加控件零改 CMakeLists
- [x] 构建基础设施：CMakePresets（
- [ ] 资源目录 `resources\icons\` （拷贝 Icon.png/ico，阶段 4 主界面时补）
**产出 ** ： `bin\Debug\FancyInputQt.exe` 可运行，窗口显示、主题色正确（已验证，2026-08-19 至 08-20）。
### 阶段 1：通用函数与数据结构（纯 C++，不依赖 UI）
**目标 ** ：先把所有"不依赖其他代码"的通用模块落地并单测，为输入识别打基础。
- [x] `src\core\common\Enums.h` ： （ `FipKeys` /`FipRawKeys` /`KeyBoardCodeType` /`InputDevice` /`ElementType` /`FIPGamepadButtonflags` /`MoveState` /`TriggerMode` 等，数值一致）
- [ ] `src\core\common\InputEvent.h` ： `InputEvent` 结构（对应 WPF `InputArgs` ），Q_GADGET 便于 QML 消费
- [ ] `src\core\image\XImage.h/.cpp` ：
- [ ] `src\core\overlay\OverlayParser.h/.cpp` ： （ ）
- [ ] `src\core\common\Utility.h/.cpp` ：剪贴板 Win32 封装（带重试）
- [ ] 单元测试：枚举值对拍、XImage 像素操作对拍（用 WPF 生成的样本图）、Overlay JSON 往返一致
**产出 ** ：核心算法库可用，单测全绿；不涉及任何 UI。
### 阶段 2：输入识别核心（技术风险最高，优先做）
**目标 ** ：全局键盘/鼠标/手柄捕获 → 统一 `InputEvent` 事件流；先做**识别**（Read），合成（Write）下一阶段。
- [ ] `src\core\input\Win32RawInputFilter.h/.cpp` ： `QAbstractNativeEventFilter` + `RegisterRawInputDevices` （键盘 usage 0x06 / 鼠标 0x02 + RIDEV_INPUTSINK）；`WM_INPUT` 解析；扫描码→`FipRawKeys` 映射表（60+ 分支照搬）；`_pressedKeys` 去重；修饰键/Lock 检测
- [ ] `src\core\input\InputParser.h/.cpp` ： `MoveState` 语义；TimerInterval 钳制 [5,1000]
- [ ] 鼠标按键/滚轮：RAWMOUSE `usButtonFlags` 补齐（**不依赖 MouseKeyHook**）
- [ ] `src\core\input\XInputBackend.h/.cpp` ： `LoadLibrary("xinput1_4.dll")` + `GetProcAddress` （系统组件，无第三方依赖）；4 pad 轮询、按钮边沿、摇杆阈值 20
- [ ] `src\core\input\Sdl3Backend.h/.cpp` ：
- [ ] 调试界面：`src\qml\pages\InputDebugPage.qml` ——实时显示键盘/鼠标/手柄事件（替换 WPF 的 `DebubTest` 状态栏）
- [ ] 单元测试：键码映射对照、阈值行为
**产出 ** ：程序运行时能实时看到全局输入事件流（键盘/鼠标/手柄），验证识别正确性。
### 阶段 3：输入合成（SendInput + 虚拟手柄，延后项前置部分）
**目标 ** ：识别之外，把"模拟输出"打通（先键盘/鼠标，虚拟手柄后置）。
- [ ] `src\core\input\InputGenerator.h/.cpp` ： `SendInput` （
- [ ] `src\core\input\InputMacro.h/.cpp` ：渐变动画辅助（MouseMoveAnimation/MouseWheelAnimation/GamepadTriggerAnimation/KeyPress——先实现键鼠部分）
- [ ] ~~虚拟手柄（ViGEm， ） ：
**产出 ** ：能向系统发送模拟键鼠输入（用记事本验证）；虚拟手柄留到后期。
### 阶段 4：主界面（五面板 + 主题控件库）
**目标 ** ：WPF 主窗口布局完全一致的 QML 实现。
- [ ] `src\qml\controls\` 主题控件库：FancyButton / FancyTextBox / ToggleSwitch / FancySlider / FancyComboBox / ScrollViewer / IconButton（
- [ ] `src\qml\Main.qml` 完整化：顶部 "Fancy/Input" 标题（80px Cascadia Mono 双色）+ 5 面板按钮（读取/创建/管理/工坊/设置）+ `StackLayout` 切换 + 底部状态栏（调试圆点 + 文字）
- [ ] `src\models\MainWindowViewModel.h/.cpp` ： `PanelType` /`SelectedPanelIndex` /5 按钮状态/配置加载保存（`%APPDATA%/FancyInput/config.json` ， ）
- [ ] 五个占位面板：ReadPage / CreatePage / ManagePage / WorkshopPanel / SettingsPage（先静态布局，业务后续填）
- [ ] 系统托盘 `QSystemTrayIcon` （退出菜单 + 双击恢复）
**产出 ** ：主窗口与 WPF 布局逐像素一致，面板可切换，托盘可用。
### 阶段 5：各个分窗口（元素编辑窗 + 辅助对话框）
**目标 ** ：10 种元素编辑窗 + 通用对话框，UI 布局与 WPF 一致。
- [ ] `src\models\ElementViewModel.h/.cpp` ：
- [ ] `src\qml\elements\` ：
- [ ] `src\qml\controls\ElementViewPanel.qml` ：贴图面板（加载/编辑/复制/粘贴）
- [ ] `src\qml\dialogs\` ：
- [ ] `src\models\ImageEditorViewModel.h/.cpp` + `ImageEditor.qml` ：裁切/通道偏移/蒙版（**可延后**，先放按钮占位）
**产出 ** ：元素编辑窗可打开、可配置，对话框可用。
### 阶段 6：
**目标 ** ：透明置顶覆盖窗口 + 元素树编辑器，实现"输入驱动叠层动画"的核心闭环。
- [ ] `src\qml\overlay\OverlayWindow.qml` ：
- [ ] `src\models\OverlayWindowViewModel.h/.cpp` ：位置/尺寸/置顶/隐藏/去黄边逻辑（照搬 WPF）
- [ ] `src\models\ElementTreeViewModel.h/.cpp` ：元素集合（QAbstractListModel）、选择矩形、锁定/隐藏、图集生成（XImage.PackImages）、导出 PNG+JSON/.fip
- [ ] `src\core\input\InputHandler.h/.cpp` ：输入事件 → 元素状态分发（响应者字典/扳机帧索引/DPadShift/鼠标滑动平均——全部照搬）
- [ ] `src\qml\editor\ElementTreeWindow.qml` ：三栏（列表/画布/属性）
- [ ] `src\qml\pages\ReadPage.qml` 完成：加载 PNG+JSON / .fip； `ManagePage.qml` 完成：多窗口管理列表
- [ ] `FullScreenMask` （坐标拾取）
**产出 ** ：加载 WPF 生成的 PNG+JSON 工程，覆盖窗口显示一致，真实输入驱动元素动画。
### 阶段 7：宏系统 + 工坊（延后功能，单独成块）
**目标 ** ：宏录制/编辑/播放，不影响前面任何代码。
- [ ] `src\core\macro\` ： （
- [ ] `src\qml\macro\MacroWindow.qml` ：三栏（宏列表 / 轨道+动作 / 属性面板）+ MacroTrack / MacroButton / FormRow / MacroActionPropertyPanel
- [ ] 工坊面板（WorkshopPanel）：宏管理入口 + 默认路径
- [ ] `.fipm` 文件与 WPF 互通验证
### 阶段 8：锦上添花 + 收尾（GIF / 更新 / 发布）
- [ ] GIF 支持（QML AnimatedImage / QMovie，替代 WpfAnimatedGif）
- [ ] 在线更新检查（QNetworkAccessManager，
- [ ] 虚拟手柄完善（ViGEm 若未在前置做）+ 终端页（QProcess cmd/PowerShell）
- [ ] 管理员自提权、单实例、命令行参数（.fip/.fips 打开）
- [ ] `windeployqt` 发布打包 + LGPL 合规文件（LGPLv3 文本 + Qt 版本声明）——**许可已核对（2026-08-20）**：全部部署组件 LGPL 安全（见文首快速上手章节），打包时需附 LGPLv3 文本 + 保留 DLL 可替换性
- [ ] UI 逐屏对照验收 + 行为对照验收
---
## 五、风险清单与对策
| # | 风险 | 等级 | 对策 |
|---|---|---|---|
| 1 | RawInput + 全局钩子是 Win32 深度集成 | 高 | QAbstractNativeEventFilter 是官方支持路径；键盘/鼠标全部收敛到 nativeEventFilter；保留 RAWMOUSE 按钮字段可去掉全局钩子 |
| 2 | 像素级图像算法（XImage）格式语义差异 | 高 | QImage ARGB32 与 BGRA32 字节序同为 BGRA（小端）；用 WPF 样本图做像素级对拍单测；Crop 透明填充必须手工补 |
| 3 | ViGEm 从反射改 C++ SDK | 中 | 官方 C++ 客户端 MIT 许可，API 一一对应；预留 QLibrary 动态加载兜底 |
| 4 | SDL3-CS → SDL3 C API | 中 | 同名枚举（SDL_GAMEPAD_BUTTON_SOUTH…），映射表照搬 |
| 5 | GIF 动画（WpfAnimatedGif → QMovie）
| 6 | QtGamepad 模块缺失 | 中 | 不用；手柄走 SDL3/XInput C++ 封装，QML 只消费结果 |
| 7 | 宏播放时序（Task 协程 → QTimer 状态机） | 中 | 顺序执行语义用 singleShot 链实现；取消令牌 + 补发 Release 照搬；防竞态锁照搬 |
| 8 | DPI/多屏（WPF 逻辑像素 vs Qt 高 DPI）
| 9 | 图标 PathData（ `Path` 支持 path 子集；少数不兼容的几何用 Canvas 兜底 |
| 10 | 反射式 DTO 序列化 | 低 | 改手写字段序列化，字段名/结构保持一致即可互通 |
---
## 六、工作量与里程碑估算
| 阶段 | 内容 | 估算 |
|---|---|---|
| 0 | Hello World 工程骨架 | 0.5 天 |
| 1 | 通用函数与数据结构（枚举/XImage/OverlayParser）
| 2 | 输入识别核心（RawInput/InputParser/XInput）
| 3 | 输入合成（SendInput 键鼠） | 1 天 |
| 4 | 主界面五面板 + 主题控件库 | 3 天 |
| 5 | 分窗口（元素编辑窗 + 对话框） | 3 天 |
| 6 | Overlay 叠层 + 元素树编辑器 | 4 天 |
| 7 | 宏系统 + 工坊 | 3 天 |
| 8 | 锦上添花 + 发布 | 2 天 |
| **合计 ** | | **约 21.5 人日 ** （单人全职约 5 周） |
> 说明：阶段 1/2/3 为"核心功能前置"，阶段 4/5/6 为"UI 主界面→分窗口"推进，阶段 7/8 为延后功能，**互不污染**，每阶段独立可编译调试。
**里程碑 ** ：
- M0（阶段 0 完成）：Qt/MinGW 工程骨架跑通，QML 窗口显示 → 后续所有开发的基座
- M1（阶段 2 完成）：**输入识别核心**可用，实时看到全局输入事件流 → 技术风险解除
- M2（阶段 4 完成）：主窗口五面板 + 主题控件库，UI 与 WPF 一致
- M3（阶段 6 完成）：叠层窗口 + 元素树编辑器闭环，.fip/PNG+JSON 与 WPF 互通
- M4（阶段 8 完成）：宏/手柄/GIF/更新全功能对齐，验收通过
---
## 七、验收标准
1. **UI 一致 ** ：主窗口/叠层/编辑器/宏窗口/辅助窗口逐屏截图对比，布局、配色（#FF651F65 主题）、字体（Cascadia Mono）、控件样式（圆角/阴影/开关/滑杆）一致
2. **逻辑一致 ** ：
- 输入：同一套按键/手柄输入在两版下产生相同元素帧切换（对拍测试）
- 图像：同一 PNG 经 Crop/Merge/PackImages 等处理后像素输出一致（对拍测试）
- 宏：同一 .fipm 在两版下播放行为一致（含触发模式/时序/取消）
- 配置：config.json / .fip / .fips 双向读写互通
3. **性能 ** ：输入延迟、叠层渲染帧率、宏触发响应不低于 WPF 版
---
## 八、待用户确认事项
1. **工程形式 ** ：纯 CMake 工程（已定，用 MinGW Makefiles 生成器）
2. **构建工具 ** ：
3. **手柄后端 ** ： （ ）
4. **GIF 支持 ** ：延后到阶段 8（已定，QML AnimatedImage 原生支持）
5. **虚拟手柄（ViGEm） ** ： ； （
6. **范围 ** ：按上表全功能迁移，宏系统/图像编辑器/在线更新延后（已定）
7. **代码中已注释掉的逻辑 ** （
8. **第三方依赖 DLL 存放方案 ** ：待确认是否按 `bin/<config>/thirdparty/` 子目录存放第三方库（SDL3/ViGEmClient 等），与 Qt DLL 分离，便于许可管理（尚未实施，等 SDL3 接入时确认）
