HarmonyOS 6.1.1 ArkWeb：交付门户下载资料前-为什么必须先登记下载代理与来源字段

影像资料从交付门户进入验收队列时，最难补的往往不是文件名，而是来源上下文。事后如果只留下一个下载地址，复核人员无法判断它是页面当前请求的地址、资源最初指向的地址，还是从哪一个页面跳转而来。资料一旦出现版本争议、来源不明或异常下载，缺少这些字段就只能靠人工回忆还原。

因此，下载代理不应等到文件已经进入处理阶段才安装。它的作用不是替验收人员给资料下结论，而是在下载对象出现时，先把能读取到的来源字段和回调状态保留下来。当前项目采用受控下载：页面先绑定下载代理，再触发测试下载；回调中依次读取字段并取消测试下载。它能证明字段读取和取消调用发生在当前回调内，不能证明外部文件已经删除、真实资料已经清理，或来源本身可信。

一、为什么下载地址不足以承担来源复核

下载动作里至少存在三种容易混淆的地址事实：当前请求地址、原始地址、引用页地址。它们可能相同，也可能完全不同；引用页还可能返回空字符串。把三者压缩成"下载链接"，会让来源链在第一步就失去区分能力。

字段	当前能说明的事实	对素材复核的意义	不代表什么
请求地址	本次下载对象报告的当前地址。	有助于回看本次动作直接面对的对象。	文件已经保存或地址安全。
原始地址	下载对象报告的原始来源地址。	有助于区分跳转后的请求和最初资源。	原始页面已通过来源审核。
引用页地址	下载动作带回的页面上下文。	有助于回看资料是从何处被触发。	引用页一定存在或一定非空。
回调状态	页面是否已经收到对象并完成当前轮读取。	避免把预设文案当作实际字段。	后台已经生成审计档案。

对影像质量与素材验收来说，地址字段不是质量结论，而是让后续质量结论能追到对象来源的基础事实。字段缺失时，应如实保留"空字符串"或"等待回调"，而不是根据页面标题、文件名或预期门户地址补写。

二、下载代理为什么必须在触发前完成绑定

如果先触发下载，再考虑是否要留痕，下载对象可能已经错过能够读取字段的时机。当前项目把代理安装放在受控页面加载之前：代理创建成功后才继续加载触发页，并在控制器准备好后安排测试下载。这条顺序的目的不是增加步骤，而是保证对象出现时已有接收方。

ts 复制代码

private attachController(): void {
  if (this.loadScheduled || !this.installDownloadDelegate()) {
    return;
  }
  this.loadScheduled = true;
  this.webController.loadData(/* 受控页面 */);
  this.scheduleAutomaticDownload();
}

这段代码能够证明，当前页面先尝试安装下载代理；代理安装失败时，不会继续安排这次受控下载。它不能证明所有门户或所有设备上的下载都会遵循同一时序，更不能证明代理绑定成功后一定取得某个字段。

对复核人员而言，代理已绑定只能作为"具备接收本轮下载对象的准备条件"记录。真正的来源事实仍要等到回调出现，并逐项读取后再写入记录。

三、字段读取和测试取消应当保持明确顺序

下载对象到达时，当前项目先尝试读取请求地址、原始地址和引用页地址，再调用取消操作。读取与取消放在同一个回调中，但它们承担不同职责：前者保留来源事实，后者阻止这次受控测试继续走向落盘。

ts 复制代码

delegate.onBeforeDownload((item: webview.WebDownloadItem) => {
  requestUrl = item.getUrl();
  originalUrl = item.getOriginalUrl();
  referrerUrl = item.getReferrerUrl();
  item.cancel();
});

这段代码能够证明当前回调按"读取字段在前、调用取消在后"的顺序组织。它不能证明取消后外部文件一定不存在，也不能证明设备文件系统中从未留下任何内容；文件落盘边界需要另有设备侧证据。

这个顺序直接关系到资料可追溯性：若先取消且没有字段快照，后续只剩"未放行"的状态，却不知道本轮试图处理哪一个来源；若读取完成却不区分取消结果，则又容易把"字段已取得"误写成"下载已被安全处置"。

四、同一次回调里，哪些结果可以写入本地复核项

当前项目在字段读取没有异常且取消调用未抛出异常时，会更新回调次数、回调时间、三项地址、页面状态和本地审计状态。它们适合组成一条"本轮来源链已采集"的页面记录，但这条记录仍属于本地会话，不是后台审计单。

页面事实	可以怎样记录	不应怎样放大
回调次数与时间	本轮已收到第几次下载对象及其页面时间。	某一外部资料已经完成交付。
三项来源字段	字段值、空字符串或读取异常。	地址本身已经可信或已被授权。
取消调用状态	测试下载已尝试取消，或取消调用出现异常。	文件已清理完成。
本地审计提示	页面保留了当前轮次的来源链摘要。	审计记录已持久化并可跨设备查询。

特别需要保留的是空值。引用页返回空字符串并不自动意味着读取失败；相反，如果 API 已经返回空字符串，补上一个"看起来合理"的页面地址才会破坏原始事实。验收记录应把空值写成空值，把错误写成错误，把未回调写成未回调。

五、来源字段进入验收记录后，还缺哪些关键事实

一条完整的素材验收记录通常还需要资料标识、版本、文件哈希、业务任务、复核人员和最终判断。当前项目没有这些外部业务字段，也没有把本地审计状态写入服务端。因此，来源字段在这里的角色很明确：为后续人工核验提供入口线索，而不是替代整份验收档案。

当页面显示"真实下载对象已回调，测试下载已取消"时，可以记录为：本轮受控下载对象已在页面回调中读取来源字段，测试取消调用已完成，仍待核对文件落盘边界。不能改写为：资料已经取消、外部文件已清理、来源已审批或素材已准入。

六、回调未到或字段读取失败时，怎样把缺口交给人工

下载代理安装失败、受控页面加载失败、回调未到、字段读取异常和取消调用异常，分别意味着不同的证据缺口。它们不能被统一写成"下载失败"，更不应通过重置页面把已经出现的异常覆盖掉。

当前项目提供人工复核入口：当回调状态不是"已取得来源字段"时，人员可以登记当前队列项的人工复核出口；页面明确标注这不会放行下载，也不会生成缺失的回调字段。合理的交接内容应包括当前页面状态、已读到的字段、仍缺的字段、错误文字和本轮操作时间。

必要条件｜从SDK到设备的依赖链路

本文技术点的运行链路必须按以下顺序成立：

SDK/API ：工程使用 HarmonyOS 6.1.1（API 24），DevEco Studio 和 Hvigor 能完成 entry 模块构建。
Kit ：源码实际引入本文所需 Kit，例如 @kit.CameraKit、@kit.MapKit、@kit.NotificationKit、@kit.SpeechKit 或 @kit.VisionKit。
模块/页面 ：页面路由写入 main_pages.json，模块保持 Stage 配置，相关权限写入 entry/src/main/module.json5。
权限：动态能力调用前完成 CAMERA、MICROPHONE 或其他系统授权；网络页面确认 INTERNET 已声明。
系统能力/硬件 ：设备满足本文 API 和能力要求。相机、麦克风、地图、CardRecognition 等能力缺失时必须进入降级分支。

MapKit文章在上述链路后增加服务配置：在 AppGallery Connect 创建或选择项目，绑定与工程一致的包名和签名证书，进入服务管理开通 MapKit，并按控制台要求完成应用服务凭据/授权配置；不要在文章或源码中公开 App ID、Client ID、API 密钥或私钥。完成后再验证地图初始化、搜索或事件回调。