crossdesk/apps/harmony/MOBILE_PARITY.md

# 鸿蒙移动控制端与 Android 功能对照

手机、平板使用 `pages/Mobile`，角色固定为控制端。对照基线为本仓库 `apps/android`，不包含 PC 被控能力。移动专用 HAP 只声明 `INTERNET` 和 `KEEP_BACKGROUND_RUNNING`；不申请录屏、输入注入、相机、麦克风或整个文件库权限。

## 构建与安装

```bash
python3 apps/harmony/scripts/build.py --mobile
python3 apps/harmony/tests/run.py --mobile
```

需要 Python 3.10+、Xmake 3.1.1+、DevEco SDK。兼容 API 20、目标 API 26、ARM64。产物：

```
apps/harmony/.native/mobile-project/entry/build/default/outputs/default/entry-default-unsigned.hap
```

手机真机调试时，在 DevEco 打开生成的 `.native/mobile-project` 并配置本机签名，再安装。不要把签名材料提交到仓库。重新执行构建脚本会重新生成隔离工程，移除签名配置。PC 的 ACL 和签名配置不用于移动包。

移动构建只复制 `ets/mobile/`、`pages/Mobile.ets`、N-API 桥接和实际使用的资源，只有 `pages/Mobile` 一个页面入口。`crossdesk_harmony_mobile` 将控制会话与共享音视频播放编译为独立原生库，输出到 `.native/mobile-libs/arm64-v8a/`；不编译 PC 会话、屏幕采集或输入注入，也不导出 PC 桥接 API。只重编原生库时使用 `build.py --mobile --native-only`，随后可使用 `--mobile --hap-only` 打包。PC 直接链接 MiniRTC 与平台服务，不再生成旧 ArkUI PC 核心；两端产物不会互相覆盖。

生成工程每次重建源码与库目录，以移除旧版本残留；请修改 `entry/src/main/` 下的源码，再运行构建脚本。桌面字体不进入移动包，开源许可证只保留界面可逐项阅读并校验 SHA-256 的完整文档，移除了重复汇总副本。

## 功能对照

| Android 功能 | 鸿蒙实现 |
| --- | --- |
| 前台自动登录、空闲后台停止、服务器隔离 | 独立 identity peer；只有主动远控才创建 controller peer；拒绝任何入站被控连接 |
| 首次隐私确认、撤回与离线阅读 | 同意前不发起身份、公告、在线状态或版本网络请求；撤回结束会话并清除预览 |
| 加密身份、可选记住访问密码 | 系统 Asset Store，设备首次解锁后可读，禁止跨设备同步；普通 Preferences 不存密码 |
| 最近连接、删除、在线状态 | 最近 20 台、在线优先、真实信令订阅、30 秒刷新和 60 秒过期；删除同步清理密码与预览 |
| H.264 / AV1 | 系统硬件解码；无能力、配置/运行失败时保持协商格式回退 OpenH264 / dav1d；NV12 GLES 显示 |
| 远端音频与静音 | 48 kHz 单声道 OHAudio，控制菜单与画中画静音同步 |
| 相对/绝对鼠标、触控 | 单击、绝对拖动、长按右键、1–10 倍焦点缩放、放大后双指平移、1 倍时双指滚轮 |
| 外接键鼠 | 实体按键映射、鼠标移动/按键/滚轮；失焦、后台、断开及切屏释放输入 |
| 悬浮控制 | 可拖动品牌悬浮球、三列菜单（低高度横屏四列）、可拖动 ASCII/电脑键盘、完整快捷键组合、140×48 虚拟鼠标 |
| 视频设置 | 低/中/高、30/60 fps、帧率/画质/平衡；能力协商、请求序号、旧 ACK 丢弃、拒绝回滚、5 秒超时 |
| 网络诊断 | 视频/音频/数据/总流量、双向速率、丢包率、实际提交帧率/尺寸、画面延迟、平滑 RTT、P2P/TURN、SRTP；3 秒失效 |
| 多显示器、Ctrl+Alt+Del | 按远端显示器列表切换；SAS 仅在远端 Windows 服务报告可用时发送 |
| 剪贴板 | 主动发送（128 KB 上限）、远端粘贴、手动复制收到的文本；退出清空内存文本 |
| 文件双向传输 | 系统文件选择/导出、进度、可靠分块/ACK、乱序覆盖、失败/超时清理；直接共用 Android 文件引擎 |
| 系统画中画与后台保活 | VIDEO_LIVE PiP 与静音控制，后台数据传输任务及系统通知兜底；选择器期间抑制 PiP，系统拒绝后台时结束会话 |
| 公告 | 摘要每页 200、正文每页 20、已读/删除与修订、分页、刷新、12 秒超时、身份及服务器隔离、迟到应答过滤 |
| 版本提示 | 每会话检查远端版本；本机更新使用 `harmony-arm64`，无该发布项时明确显示无鸿蒙版本信息 |
| 远程预览 | 默认关闭、单独确认、下一次连接起每会话一张 640×360、私有缓存、不上传；关闭/撤回清除，异步任务不能恢复已撤回内容 |
| 关于和开源合规 | 实际包版本、离线许可证和组件清单、SHA-256 文档校验、源码版本与构建说明 |
| 手机/平板布局 | 900 vp 双栏断点、最近连接 1–4 列、主体最大 1200/720 vp、手机首页竖屏、会话/平板自动旋转、200 ms 页面/选项过渡 |

平台 API 有差异：鸿蒙使用 Asset Store、OHAudio、ArkUI PiP 和后台任务，Android 使用 Keystore、AAudio、Android PiP 和前台服务。系统保留快捷键、后台策略、硬件解码能力受具体设备约束。

## 移动界面

移动端滚动容器显式隐藏叠加式滚动条，包括首页内外层、设置与公告、长文档、弹窗、远控菜单、虚拟键盘及剪贴板文本框；保留原有触摸和滚轮滚动，避免滑块覆盖文字、按钮或按键。新增滚动区域应沿用这一设置。

首页、设置、弹窗和远控菜单以 Android `MobileUi` 为视觉基准：统一灰白底色、蓝色主操作、文字层级、线条图标、圆角与阴影。首页提供连接卡片、最近设备卡片及居中空态，宽屏采用固定宽度连接栏与自适应设备列表；设置使用分组卡片、分段选择器和内联服务器配置，隐私、关于、公告及许可页面沿用相同导航与列表样式。

访问密码在手机上以底部面板显示，在平板上居中显示；输入法弹出时缩小可用区域，保留密码、保存开关和连接按钮，较小窗口可滚动。隐私政策面板保持标题与授权操作可见，正文独立滚动。删除、撤回、清除和断开操作使用统一确认框。远控菜单提供图标网格、画面设置、对齐的网络统计、品牌悬浮球以及可拖动键盘和鼠标；菜单和键盘按可用窗口尺寸限制位置。

此次 UI 检查在 API 26 手机和平板模拟器中使用独立包名、无联网权限的离线状态预览，检查了首页、设置、确认取消、密码显隐与输入法避让、弹窗及远控面板。预览中的设备、传输状态和屏幕尺寸为测试数据，不作为网络互通验收依据。图标与鼠标指针按显示密度绘制，避免 SVG 路径的像素坐标在高密度屏幕上缩小。

## 自动化验证

`tests/run.py --mobile` 运行生产 ArkTS 模型、控制器和平台生命周期代码的测试，包含隐私前置、身份/密码调用、重复/跨会话回调、重连后台任务串行化、PiP 去重及静音、文件选择器保护、双指/虚拟鼠标独立按键、画质应答乱序与序号回绕、统计失效、在线状态与公告完整分页。

同时运行 Android 原生协议及视频管线回归测试、共享文件传输测试、鸿蒙输入/采集适配与公共 wire 测试。共享代码位于 `libs/controller/include`；Android 旧头文件保留兼容导出，避免两平台协议漂移。

`tests/verify_hap.py --mobile <hap>` 校验 phone/tablet 设备类型、最小权限、后台模式、编译后的 ArkTS、ARM64 原生库依赖及许可证资料。构建脚本自动执行该检查。

## 设备验收

### 确认实际解码器

解码诊断通过 HiLog 标签 `CrossDeskDecoder` 输出，不受 MiniRTC 通用日志关闭的影响。在 DevEco 的 HiLog 中按此标签过滤，或运行 `hdc shell hilog -x -T CrossDeskDecoder`。`Decode request` 记录当前格式的硬解能力，`Decoder selected` 记录选中的实现和软解回退原因；应以 `First decoded frame` 的 `mode` 和 `name` 确认实际成功工作的解码器，而不能只看硬件加速配置或初始化结果。会话结束的 `Decode summary` 分别统计硬解和软解成功帧数，也能识别中途回退。日志仅记录格式、解码器、尺寸、错误阶段及帧数，不输出连接凭据或视频内容。

2026-10-15 在 API 26 ARM64 Mate 90 Pro 模拟器实测：H.264 3840×2160 远控会话使用 OpenH264，成功软解 2722 帧、硬解 0 帧；AV1 640×360 合成视频使用 Dav1dAv1，成功软解 1203 帧、硬解 0 帧。两者均为 `hardware_available=0`，回退原因 `no hardware capability`。这只证明当前模拟器的解码路径，不代表真机硬解能力。

### 已覆盖的功能

已在 API 26 ARM64 手机（Mate 90 Pro）和平板（MatePad Pro 13）模拟器安装运行，验证首次同意、登录、公告同步、设置及双栏布局。在手机上使用同版本 MiniRTC 合成发送端验证 H.264 / AV1 640×360 画面、48 kHz PCM 接收、鼠标与虚拟键盘回传、画质请求/应答、双屏切换、剪贴板、文件接收及系统导出/选择后反向发送的字节一致性、旋转和后台画中画恢复。发现并修复了公开 ID 覆盖完整登录凭据、连接成功回调前的主机信息丢失、返回前台后画中画遮挡文件选择器等问题，并补充回归测试。主机侧测试不能替代真机上的触摸、多指、外接键鼠、音频路由、硬件编解码性能以及长期后台/画中画测试；这些仍应在发布前用 API 20 与当前系统真机验收。

可使用 `tests/mobile_synthetic_host.cpp` 作为互通测试发送端：它只生成测试色条、静音 PCM、虚拟显示器和小文件，不采集本机屏幕或输入。运行参数为 `<server> <port> [av1]`，测试身份写入工作目录 `fixture-login`，运行状态写入 `fixture-status`，15 分钟自动结束。使用独立私有测试目录，测试后删除身份、日志和接收文件。鸿蒙 fixture 可用 `tests/build_mobile_fixture.py` 编译；受限模拟器 shell 可能不能加载系统媒体库，可在开发机链接 MiniRTC 运行同一源文件。