qemby/ai/qml-migration-status.md

qEmby QML 迁移状态

更新时间：2026-07-15

结论与口径

当前架构是 Widgets 应用壳 + QQuickWidget 局部页面，还不是纯 QML 应用：MainWindow、登录/主页导航、侧栏、标题栏和页面栈仍由 Widgets 负责；QuickPageHost 把 QML 页面嵌入 QStackedWidget/SlidingStackedWidget。迁移完成的判定必须同时满足“QML 页面存在、由实际导航入口加载、核心交互可用”，不能只以 .qml 文件存在为准。

代码依据：

• src/qEmbyApp/CMakeLists.txt 的 qt_add_qml_module(qEmbyApp ...) 是当前 QML 模块清单。
• src/qEmbyApp/quick/quickpagehost.cpp 使用 QQuickWidget，并处理主题底色、context property、image provider 与加载错误。
• src/qEmbyApp/views/settings/settingsview.cpp 实际加载 5 个设置 QML 页面。
• src/qEmbyApp/views/admin/manageview.cpp 保留 Widgets 管理壳，但仪表盘和六个管理页的页面主体均已由各自的 QuickPageHost 加载 QML。
• src/qEmbyApp/views/user/homeview.cpp 仍负责主路由，并创建 Dashboard/Favorites/Category/Library/Detail/Season/Search/Player/Settings/Manage 等 QWidget 页面。
• src/qEmbyApp/quick/navigationcontroller.* 已实现规范 route、参数/权限校验、会话清理和 UI state；HomeView 已旁路接入并与旧 m_navStack 并行运行。

状态口径：done = 已接入实际入口；in-progress = 已分配并正在迁移；ready = 前置基本具备，可领取；blocked = 应先完成列出的依赖；legacy = 迁移期间刻意保留的原生边界。

已迁移并接入

子系统	页面	QML / 数据层	owner	status	验收命令
设置	通用	SettingsGeneralPage.qml / SettingsViewModel	core	done	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2
设置	外观	SettingsAppearancePage.qml / SettingsViewModel	core	done	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2
设置	媒体库	SettingsLibraryPage.qml / SettingsViewModel	core	done	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2
设置	播放器	SettingsPlayerPage.qml / SettingsViewModel	core	done	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2
设置	关于	SettingsAboutPage.qml / AboutViewModel	core	done	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2
管理	仪表盘	ManageDashboardPage.qml / DashboardViewModel、EmbyImageProvider	core	done	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；登录管理员账号后检查 2 秒刷新、重启/关机确认框

说明：设置与管理的左侧导航容器仍是 Widgets；About 的许可证窗口以及管理仪表盘的确认框/Toast 仍通过 Widgets 打开，因此这里的 done 指页面主体，不代表其父壳和所有弹窗都已迁移。

待迁移清单

以下 owner 是任务归属，不是 C++ 类所有者。login-agent 与 search-agent 已按本轮协作安排标为进行中。

阶段	子系统	页面/范围（现有 Widgets 事实）	owner	status	依赖	验收命令
1	公共入口	登录 views/public/LoginView	login-agent	done	主题输入框、按钮、忙碌/错误状态；认证 ViewModel	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；冷启动后完成服务器选择、登录成功/失败各一次
1	搜索	搜索结果 views/search/SearchView	search-agent	done	媒体列表模型、MediaCard、分页/空态	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；提交关键词并验证结果、空结果、进入详情、返回
1	公共基础	QML 弹窗/Toast/确认框、菜单、空态/错误态	feedback-agent	done	Theme、现有 ModernDialog.qml	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；键盘 Esc/Enter、焦点回收、明暗主题各冒烟一次
1	公共基础	MediaCard + 可复用 List/Grid + 图片加载/占位/错误	media-primitives-agent	done	EmbyImageProvider 泛化、QAbstractListModel 角色契约	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；100+ 项滚动、图片失败、键鼠激活检查
2	用户首页	首页 views/user/DashboardView	dashboard-agent	done	MediaCard/List、首页 section 模型、请求取消	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；继续观看/最新/推荐/媒体库分区加载与跳转
2	用户首页	收藏 views/user/FavoritesView	favorites-agent	done	MediaCard/List、收藏模型	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；分类、详情、文件夹、人物跳转及返回
2	用户首页	分类 views/user/CategoryView	category-agent	done	MediaCard/List、筛选/分页模型	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；分类切换、分页、空态、返回状态保持
2	媒体浏览	媒体库/人物/过滤结果（共用 views/media/LibraryView）	library-agent	done	MediaCard/Grid、排序筛选菜单、分页模型	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；海报/平铺视图、排序筛选、滚动续载、人物页
2	应用壳	MainWindow 标题栏、全局搜索、HomeView 侧栏与路由栈	core	in-progress	NavigationController、单引擎 Router.qml、Home/Favorites/Search/Category/Library/Person/Filtered 已接入；待 Detail/Season、侧栏与标题导航	cmake --build cmake-build-debug --target qEmbyNavigationTest qEmbyApp_qmllint qEmbyApp -j2 && ./cmake-build-debug/bin/qEmbyNavigationTest；登录→首页→分类→媒体库→人物/过滤→搜索→返回→详情→返回→退出全链路，检查窗口按钮与托盘
3	媒体详情	详情 views/media/DetailView	detail-agent	done	MediaCard、Flow/Tag、动作菜单、编辑/识别弹窗桥接	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；电影/剧集/人物各一项，播放、收藏、版本选择、编辑入口
3	媒体详情	季 views/media/SeasonView	season-agent	done	Episode 列表模型、MediaCard、播放动作	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；切季、剧集续播/播放、已播状态、返回
3	管理	媒体库 PageLibraries	admin-libraries-agent	done	管理卡片/Grid、拖拽排序、Library CRUD 对话框	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；新增/编辑/删除/扫描/取消扫描/排序
3	管理	合集/播放列表 PageCollections	admin-collections-agent	done	管理卡片/Grid、拖拽排序、文本/确认弹窗	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；创建/重命名/删除/批量删除/排序
3	管理	转码 PageTranscoding	admin-transcoding-agent	done	表单组件、折叠区、编解码器模型与复杂校验	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；加载、修改、保存、校验失败、编解码器参数弹窗
3	管理	用户 PageUsers	admin-users-agent	done	用户卡片模型、Add/Edit User 对话框	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；新增、编辑、启停、删除及权限错误
3	管理	任务 PageTasks	admin-tasks-agent	done	任务列表模型、TaskEdit 对话框	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；启动、停止、编辑任务及轮询刷新
3	管理	日志 PageLogs	admin-logs-agent	done	日志树/列表、文件保存桥接	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；日志列表、内容加载、失败态、另存为
4	播放	播放页面/OSD views/media/PlayerView 与 components/player*	unassigned	blocked	QML 视频承载方案、PlaybackManager 契约、所有 OSD/字幕/弹幕组件	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；libmpv 播放/暂停/seek/音量/字幕/弹幕/全屏/退出，重复 10 次无崩溃
4	对话框	媒体编辑/识别/图片、播放列表、下载、WebDAV、代理、许可证等 components/*dialog*	unassigned	blocked	QML Overlay/Dialog 框架；文件选择器与原生能力桥接	cmake --build cmake-build-debug --target qEmbyApp_qmllint qEmbyApp -j2；按对话框建立交互矩阵，覆盖接受/取消/错误/窗口关闭
4	平台集成	系统托盘、无边框窗口、文件选择器、外部播放器/IPC	platform	legacy	纯 QML 壳稳定后再决定是否包装；不要求强行 QML 重写	cmake --build cmake-build-debug --target qEmbyApp -j2；Linux/Windows/macOS 各执行关闭到托盘、恢复、退出和窗口按钮冒烟

建议阶段与依赖顺序

1. 固定 QML 契约：先完成登录、搜索，以及弹窗/Toast、MediaCard/List/Grid；统一 ViewModel 的 loading/error/empty/cancelled 生命周期。没有这些基础件，后续页面会复制临时控件和异步处理。
2. 迁移高复用浏览链路：Dashboard、Favorites、Category、Library/Person/Filtered。它们共享卡片、图片、分页和导航，是验证模型契约与性能的最佳批次。
3. 替换应用壳：浏览链路稳定后，再把 MainWindow/HomeView 的标题栏、侧栏、路由栈换成 QML；期间 QuickPageHost 继续充当兼容层。壳迁移必须保留托盘、窗口按钮、主题切换和返回栈行为。
4. 迁移复杂业务页：详情/季与六个剩余管理页。先提取 C++ ViewModel/QAbstractListModel，QML 不直接持有 service 协程或业务缓存。
5. 最后处理播放与长尾弹窗：播放器涉及 libmpv/OpenGL/原生窗口和输入焦点，是最高风险项。平台集成可以保留 C++，目标应是“QML 表现层 + C++ 原生能力”，而不是消灭所有 QWidget/C++。

当前开发批次（2026-07-15）：导航 Phase 0/1 已落地，Phase 2 首批完成。新增强类型 NavigationRoute、NavigationController 和轻量契约测试；Widgets 页面统一先转换为规范 route，再进入旧页面栈。QuickRouterHost 以单个 QML engine 承载 Router.qml，Home/Favorites 共享该 host 与图片 provider，并由 HomeQuickRouterView 协调 ViewModel 生命周期和 BaseView 媒体动作。其他 route 暂时保持旧 Widgets host，切入时 Router 保留底层页面且暂停生命周期，避免过渡闪屏。可用 QEMBY_USE_LEGACY_HOME_PAGES=1 临时回退旧 Home/Favorites 双 host。

Phase 2 第二批（2026-07-15）：Search 已加入根 Router。HomeView::triggerSearch() 现在生成规范 search route；同一 Quick host 内的 Home/Favorites/Search 切换只更新 Controller/Loader，进入 legacy 详情页时仍保存兼容历史。SearchViewModel 新增 active/generation 生命周期，隐藏或离开搜索时淘汰在途结果，返回时仅按需恢复；旧 SearchView 默认 active 行为保持兼容。

Phase 2 第三批（2026-07-15）：Category、Library、Person、Filtered 已加入根 Router。HomeView 的首页媒体库、侧栏媒体库、文件夹、人物和过滤入口统一生成规范 route；Favorite Category 在 key 中具有独立身份。Category/Library ViewModel 在 inactive 时只保存最新参数，并用 generation 淘汰详情探测、首屏与 loadMore 的过期回写；旧包装器继续保持默认 active 兼容。当前 Category 和 Library 系列各使用一个会话级 ViewModel，返回已完成 route 时可复用数据，切换参数时重建当前状态；尚未实现每个历史 route 独立的 LRU ViewModel 与滚动位置。下一批优先接 Detail/Season，再统一 uiState.scrollY。

阶段门禁：每阶段至少通过 QML 静态检查、Debug 构建、明暗主题、窗口缩放、键盘焦点、页面反复进入退出、网络失败/空数据检查；依赖真实服务器的行为必须用 Emby/Jellyfin 各冒烟一次。

公共组件与基础设施缺口

• 导航：声明式 route、参数、返回栈、页面缓存/销毁策略；当前契约散落在 HomeView::create*View() 与动态 routeType 属性中。
• 异步状态：统一 loading/error/empty/refreshing、请求去重、页面销毁后的取消/弱引用；当前 Dashboard VM 是可参考样例，但尚无通用基类。
• 媒体模型：统一 QAbstractListModel roles、分页、排序、筛选、收藏/已播状态增量更新，避免 QML 读取复杂 Core DTO。
• 视觉组件：MediaCard、Section、IconButton、Menu/ContextMenu、Dialog/MessageBox、Toast、Busy/Skeleton、Error/Empty、Tabs、Tag/Chip、拖拽排序、文件/目录选择入口。
• 图片：现有 EmbyImageProvider/AdaptiveIconProvider 只在管理仪表盘 host 中显式注册；全局 QML 引擎需要统一注册、缓存策略、取消和失败占位。
• 可访问性与输入：焦点环、Tab 顺序、快捷键、右键菜单、触屏/高 DPI、屏幕阅读器语义。
• 测试：仓库当前没有 qEmbyApp 页面级自动测试；应增加 Qt Quick Test（组件/VM）与最小导航冒烟，避免只靠截图判断。
• 国际化：新 QML 文案需进入现有 qEmby_zh_CN.ts/qEmby_fr_FR.ts 流程，并核验运行时语言切换/重启语义。

高风险边界

1. QQuickWidget 只是过渡层：它使用离屏 FBO；仓库已经为透明合成黑底加了不透明 clear color。嵌入页越多，渲染、焦点、弹窗层级和显存成本越高，应避免把每个小组件都拆成独立 QQuickWidget。
2. 播放器：PlayerView、MpvWidget、OpenGL 与大量 player* 控件耦合，且有全屏、长按、字幕、弹幕、媒体源切换。先做单一播放器原型和压力冒烟，再决定 QQuickFramebufferObject/原生纹理/保留 QWidget 视频面方案。
3. 生命周期与协程：页面快速返回、切服务器或退出时，QCoro 任务、WebSocket 与定时刷新不能回调已销毁的 QML 对象。管理仪表盘已有 active/hidden 控制，但尚未形成全局规则。
4. 业务逻辑回流 QML：现有 Widgets 页面体量大（尤其详情、转码、媒体库管理）；迁移应先抽取 ViewModel/模型，不能把 API 编排、配置序列化和缓存策略复制进 JavaScript。
5. 导航状态兼容：HomeView 当前重建历史页面并依赖 routeId/routeTitle/routeExtraId；切换为 QML 路由时必须保留人物、过滤、季、管理、设置等返回参数和滚动状态。
6. 原生能力：托盘、无边框窗口、文件保存、外部播放器 IPC 适合继续放在 C++；“全面迁移到 QML”应限定为 UI/交互层迁移。
7. 主题双栈：Widgets 仍走 QSS/ThemeManager，QML 走 QuickTheme/Themed controls。过渡期必须以同一 token 为源，验证实时明暗切换，避免两套颜色和尺寸继续分叉。

每个迁移任务的完成定义

• 实际导航已切到 QML，旧 Widgets 页面不再是默认路径；需要回退时必须有明确 feature flag。
• C++ 只暴露稳定属性、模型、信号和 invokable；QML 不直接编排网络 service 或持有 Core DTO。
• qEmbyApp_qmllint 与 qEmbyApp 构建通过，无新增 QML runtime error/warning。
• loading/error/empty/disabled、键鼠焦点、明暗主题、窗口缩放和中英文至少完成一次验证。
• 页面进入/退出及刷新至少重复 10 次；涉及异步或播放器的任务额外验证退出、切服务器和应用关闭。
• 删除旧实现应单独提交，在 QML 路径稳定后进行，便于回退与差异核对。