Skip to content

Latest commit

 

History

History
192 lines (154 loc) · 16.1 KB

FIRST_RUN_SETUP.md

File metadata and controls

192 lines (154 loc) · 16.1 KB

首次使用助手

入口与界面

首次启动由 App.ShowInitialWindow 自动打开,复用主窗口的 MainViewModel。 首次显示时保存进入记录;即使未完成设置,下次启动也不自动弹出,已有进度通过手动入口继续。 手动入口同时保留在主界面应用偏好、投屏设置的应用模式区域、开发者选项。 向导期间暂停主窗口自动刷新,关闭后恢复现有完整、精简或托盘流程。

首次设置的应用模式默认选中“完整模式”,与新应用配置的默认值一致。用户可主动改选精简或托盘模式; 返回、关闭后继续及重新配置保留已有选择,跳过不会改写当前模式。 已有投屏或控制会话需要先停止;重新运行时复用设备档案。

每次进入时的状态检查

默认入口先显示独立的「正在检查你的设置」,再显示结果汇总。 SetupAssessment 使用 Completed、Incomplete、Invalid、NotRequired、Unknown 状态; SetupTaskPlanner 按依赖和设备身份合并任务,由现有向导页面执行配置或修复。 首次进入和主动重新检查时完整扫描。SetupAssessmentSession 在本次会话内保留检测证据;完成任务后留在当前页面,只刷新受该步骤影响的配置、组件或设备证据,再按依赖模型直接进入下一项。不会逐页重放检查动画或重复探测无关硬件。修复失败在本页显示原因,全部待办处理完后展示更新后的汇总。跳过不触发检测,返回使用已有汇总;新会话不会沿用旧检测缓存。 只有结果页的「重新配置全部设置」会打开完整欢迎流程;不会删除实际设备档案。

状态来自磁盘设置、设备档案及当前系统检测,而不是保存页码。 基础偏好读取 settings.json 并验证值;用途保留在检查点中。 控制介绍页可以明确关闭 USB 控制、无线投屏/控制、蓝牙控制;关闭的能力为 NotRequired。 历史检查点没有这些选择时,先引导选择,再进行相关硬件检查。 「跳过此项」只在本次暂后处理,下次重新检查,不会写成 Completed。

  • 驱动助手增加只读 diagnose IPC,分别返回 Apple 服务、驱动包、libusb 文件与服务、逐设备健康状态。 无设备时仍能检查公共组件;USB 设备身份由现有原生枚举确认。
  • 无线接收器复用现有运行时预检,验证实际组件完整性及依赖加载能力。
  • 绑定从磁盘只读加载,识别文件损坏或重复身份;扫描不清理档案。
  • 蓝牙检查适配器、无线电状态和 Windows 配对身份,不启动广播或发送输入。
  • 反控组件检查现有完整性清单与 --check-runtime;设备端新增 --check-setup --udid, 复用 Lockdown 与 Wi-Fi 同步读取,检查已有信任、开发者模式和所需无线同步设置。 此检查不主动配对、启用 Wi-Fi 同步、下载/挂载 DDI 或发送控制输入。

设备离线、检测超时或无法查询时为 Unknown,保留绑定,不宣布全部就绪。 新增设备独立进入待配置列表,不自动替换旧设备;修复后以重新检查为准。 组件和前置设置通过检查不代表完成实际投屏或输入测试;网络、防火墙、DDI 挂载仍由正常启动流程处理。 Apple 版本兼容性沿用现有驱动模块的能力,本次没有新增未经验证的版本白名单。

检查异步执行,保留取消和关闭后的任务所有权;快检查最多补足约 550ms 展示时间。 关闭 Windows 动画时不补足展示时间。动画为轻微呼吸、圆环旋转及图标回弹,文字不缩放。 检查中与汇总页共用同一卡片和行控件:行内圆环、状态文字随真实检测结果原位更新,结束后保留检测顺序,不重新排序。标题、卡片和操作区预留位置,避免阶段切换时跳动;关闭系统动画时仍正常显示状态。名称与状态分列对齐,异常原因显示在对应项下方,长列表在卡片内滚动。汇总页等待用户点击,重新检查与完整重配并排作为次要操作。

顶部固定显示三大类,所有用途分支使用相同分类,前进、返回和恢复时高亮当前类别:

类别 包含步骤
基础设置 欢迎、语言、应用模式、外观、使用用途
设备连接 连接方式、控制介绍、发现设备、驱动环境、身份读取、有线/无线/蓝牙绑定、逐设备摘要
投屏体验 显示偏好、画质、帧率、解码、保存确认、完成摘要

类别使用圆点、勾选和细连接线表示进度。设置使用并排卡片,图标使用灰阶 WPF 矢量图形,不依赖 emoji 字体;主题色用于选中状态、当前阶段和主按钮。 欢迎页文字居中,依次淡入并轻微上移。翻页动画直接作用于实际控件,不截图、不缩放文字。 语言切换更新现有控件资源,不重建卡片;保留悬停、按压及选中反馈。 动画尊重 Windows 关闭动画的设置。

默认 880×760 窗口设置页无需上下滚动,长选项、设备清单及完成摘要使用分页。 窄窗口与较长诊断内容保留滚动兜底。等待任务使用原地呼吸圆点;只有下载提供 真实百分比时显示确定进度条,不使用横向循环滑动条。

状态与分支

FirstRunSetupState 编排步骤与检查点,不管理设备连接。

Welcome → Preferences(语言)→ ApplicationMode → Appearance → Usage
  仅投屏 → MirrorConnection
    无线 → WirelessBackend → Wireless → Display → Validation → Completed
    有线 → Connection
      → [Environment → ReDetection → Profile → DeviceComplete] × 每台设备
      → Display → Validation → Completed
  投屏 + 控屏 → ControlIntroduction(三种方式同页)→ Connection
    → [Environment → ReDetection → Profile(统一设备绑定)→ DeviceComplete] × 每台设备
    → Display → Validation → Completed

所有步骤均可跳过,耗时操作提供“取消操作”;运行中点击跳过,先取消并等待当前操作安全结束再继续。 控制方式介绍仅显示说明,不再提供功能勾选。USB、AirPlay 和蓝牙统一在一次设备绑定中管理, 无线和蓝牙可稍后添加。纯无线路径跳过无线接收方式时直接进入显示偏好。 跳过设备发现可以不连接设备直接完成向导。 跳过身份读取或档案保存时,一并跳过依赖该身份的后续绑定;未保存有线档案的设备不会进入视频参数页。 跳过项独立保留为 Skipped,结束页显示尚未完成的提示;没有配置任何设备时仅进入主界面,不强制投屏。 有线路径按需检查和准备驱动;纯无线路径不调用 USB 枚举或驱动助手。 Display 可沿用当前配置或逐项调整:无线画质(已使用无线时),然后为每台有线设备 调整画质、帧率、解码方式。纯无线路径在 AirPlay 绑定之前选择无线接收方式; 投屏加控屏路径在打开绑定器时自动启动当前接收器。

旧枚举数字保持不变,新步骤追加;加载旧检查点时迁移拆分的介绍页、旧控制测试页和 独立设备列表页,以及投屏加控屏路径中分开的无线、蓝牙绑定页。first-run-setup.json 在当前用户 LocalApplicationData/iPhoneMirror 下原子保存。New、InProgress、Deferred、Completed 独立记录;保存失败保留当前页面, 损坏或不兼容检查点使用新的流程意图,再进入状态检查;实际设置和设备档案仍重新读取。 无线接收方式及画质草稿随检查点保存;默认重新进入以当前持久化配置检查,避免旧草稿覆盖新设置。 只有主动完整重配才建立新的流程状态,实际设置和档案保留。 跳过身份步骤后的返回操作回到对应身份步骤,不进入依赖它的绑定页。切换用途保留语言、外观等公共步骤记录。 导航与结束保存失败会还原内存状态;检查点中缺失身份前置条件的绑定页会退回身份读取或档案保存。

发现、准备与身份绑定

  • 连接页面持续调用驱动管理器 PnP 枚举,每轮结束后间隔 1.5 秒,直到离开页面。 上方实时显示已连接 iPhone 数量,插拔更新队列;找到第一台后仍继续扫描。 队列保留首次观察顺序,同时出现的设备沿用枚举顺序,无法还原向导启动前的插入时间。 恢复页面先完成新的扫描再允许下一步;点击下一步时采纳当前扫描结果,避免用已拔出设备的旧记录继续。 离开页面停止循环,进入驱动步骤前等待当前只读扫描安全结束;扫描也可取消或重新开始。
  • FirstRunDriverHost 复用原驱动管理器的 scan、inspect、prepare 能力。 命名管道限制当前用户,沿用原 Apple 支持安装、签名校验、UAC、快照、回滚与安全取消。 主程序不直接写驱动,不提升权限。 提权进程清空环境变量后,公共数据目录仍从 HKLM 的系统目录注册信息解析为绝对路径。 安装结果、日志与回滚备份不会落入提权启动器随后清理的临时目录。
  • 有线身份通过现有原生枚举读取 UDID,再按标准化序列号对应 PnP 设备。 使用 DeviceBindingManager 创建或复用档案,不启动有线控制测试。
  • 环境页先执行只读检查,只有确认缺少组件才显示安装说明和按钮。 取消、失败或外部修复后可重新检测;检测正常后隐藏安装操作,直接继续。
  • 无线启动现有接收器,等待用户实际 AirPlay 投屏,记录接收器提供的稳定身份地址。 与已有有线档案关联时,在向导中明确选择设备;纯无线为发现的设备分别保存档案。
  • 蓝牙遵循设备绑定器流程:启动配置外设、等待订阅客户端、选择设备、保存绑定、停止配置外设。 不要求启动控制、校准或执行输入测试。
  • 返回设备绑定页时,若磁盘上的有线档案仍存在,可直接继续,也可再次打开绑定器添加无线或蓝牙。 助手读取同一档案中已保存的三种身份,保留无线显示偏好的后续配置;档案已删除时仍需重新绑定。
  • 最终保存页继续确认档案身份;完整重配结束后进入统一状态汇总,区分已完成、暂后处理及无法确认项。

选择无线接收方式只保存草稿;点击“下一步”后,如 UxPlay 组件缺失, 向导内调用现有 UxPlayComponent.InstallAsync 下载和安装。 沿用既有来源、完整性校验与取消逻辑,显示实际下载百分比、数据量和速率;错误提示支持重试。 已安装时直接复用;下一步及启动接收器前也检查组件,避免漏装。

视频参数通过现有每设备状态和 UpdateSettingsStore 保存,无线参数使用现有设置持久化,写入失败不会被标记为完成。 更改无线画质后,已运行的接收器按新设置重新启动,并提示用户重新选择屏幕镜像;未运行时仅保存供下次启动使用。 未完成或已跳过无线绑定时,不在最终步骤应用无线接收设置。视频偏好写入失败也还原已持久化设置的内存副本。 开始投屏仅选择本次向导保存且仍在当前列表中的设备,不沿用旧的选中设备。 没有引入新的驱动、投屏、控制或绑定子系统。

生命周期

关闭时先内联确认,保存进度并取消任务。身份读取与绑定轮询有超时;持续发现页没有 找到首台即结束或固定 75 秒结束的限制。驱动安装最多等待 12 分钟后请求安全取消, 后台安装事务仍需到安全边界才结束,不强杀安装器。只读驱动探测单次最多等待 45 秒。 取消后保持操作所有权直到清理结束,避免导航后旧任务继续写入新步骤;蓝牙启动结束后再执行停止清理。 取消设备扫描立即禁用“下一步”,即使迟到的扫描报告成功也不会重新放行,需重新扫描。 关闭窗口时,仍在退出的只读扫描也保留设置助手所有权,清理结束后才恢复主窗口刷新。 原生调用使用现有 _coreGate。 原生探测取消后会等待不可中断的底层调用结束,保留任务所有权,防止迟到结果在新步骤写入状态。

只读扫描/检查取消时先发送取消通知并断开管道,等待一秒后若子进程仍未退出,仅结束该只读子进程。 安装/修复不使用此强制退出逻辑,仍等待事务安全退出。只读助手不占用跨进程安装信号量,避免取消后留下锁。 同一应用内的重试等待旧助手清理,可再次取消等待;重新扫描会清除旧错误,不累积重复错误信息。

验证

dotnet build src/App.Runtime.Tests/IPhoneMirror.App.Runtime.Tests.csproj --no-restore

# 手动界面测试:独立临时检查点,自动硬件操作关闭
& 'src/App.Runtime.Tests/bin/Debug/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.exe' --ui-preview Light setup

& 'src/App.Runtime.Tests/bin/Debug/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.exe' --first-run-setup outputs/first-run-setup-review-v3
& 'src/App.Runtime.Tests/bin/Debug/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.exe' --first-run-driver-probe 'src/DriverInstaller/bin/Debug/net10.0-windows/win-x64/iPhoneMirror.Driver.exe'

# 状态检查模型、实际 WPF 入口/退出与多语言双主题;历史验证范围见下文
& 'src/App.Runtime.Tests/bin/Debug/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.exe' --setup-assessment outputs/setup-assessment-final

# 独立检查页交互预览,使用隔离的设置检查点及检测结果
& 'src/App.Runtime.Tests/bin/Debug/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.exe' --setup-assessment-preview outputs/setup-assessment-windows-mcp

# 实际组件、蓝牙环境和已连接设备的只读前置条件检查
& 'src/App.Runtime.Tests/bin/Debug/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.exe' --setup-runtime-probe 'src/DriverInstaller/bin/Debug/net10.0-windows/win-x64/iPhoneMirror.Driver.exe'

以下为早期专项验证记录,语言数和场景数保留当时范围;当前界面已支持五种语言,新增语言的专项记录见台湾本地化。本次文档整理未重跑 UI 矩阵。

向导测试覆盖两级用途选择、三种分支、设备顺序、全步骤跳过、依赖步骤跳过、回退、恢复及损坏检查点。 布局覆盖 23 个活动页面 × 4 种语言 × 2 个主题 × 2 个尺寸,共 368 组,检查默认尺寸 无滚动、卡片文字边界、九设备分页、逐设备参数导航及关闭清理,并生成高 DPI 预览。 生产动画路径检查文字不缩放、欢迎页居中淡入、语言切换保持控件实例与位置。

连续扫描及组件下载测试注入替代委托,覆盖设备数变化、取消扫描、真实数值进度映射、 已有组件复用、下载失败和取消后的导航恢复。另覆盖最后一轮扫描发现拔线、恢复时旧设备列表不能直接前进、 运行中取消和排队跳过、无线设置写入失败回滚,以及全部跳过后无设备结束向导。 此类测试不会安装驱动或执行真实网络下载。 驱动探测单独执行真实 PnP 枚举和只读检查,不安装驱动。 驱动安装器回归测试另在环境变量清空及 ProgramData 被覆盖的子进程中校验结果、日志、备份路径一致。 --first-run-driver-cancel <驱动助手路径> 使用真实只读助手,覆盖启动后 0/50/300/900/1400 ms 取消, 立即重新扫描、锁等待取消和无残留进程检查;不会安装或修复驱动。

实际驱动安装、UAC、多台实机插拔、AirPlay 网络连接、蓝牙配对和真实组件网络下载仍需 在对应环境验收,UI 与替代委托测试不代表这些硬件场景已通过。

FirstRunSetupUsabilityTests 另覆盖点击下一步才下载、绑定复用和档案删除、 当前设备提示、只读重检与安装按钮、取消后迟到结果、延后保存失败回滚及关闭扫描清理。