巡检员在地下设备层填写完检查备注,刚按下保存,手机却失去网络。最让人不安的不是转圈,而是界面已经显示“已完成”,重新进入后又回到了“处理中”。这类不一致往往不出在按钮上,而是把表单校验成功、本地接收成功、服务端确认成功混成了同一个事件。本阶段继续前面三篇的巡检工作台:保持 InspectionRecord 中 id、location、device、owner、status、note 字段,保留 selectedId 和 filterStatus 的含义,在原有 validateInspection() 通过后,引入可持久化的待提交队列。

设计目标很明确:无网时保存用户已经确认的修改,重新打开应用仍能找到它;恢复网络后按顺序补发;服务端确认前明确显示“待同步”,发生冲突时保留待处理记录,而不是悄悄吞掉。这里把用户可见的“保存到本机”和最终“业务提交成功”区分开,是为了让状态提示与真正的系统承诺相匹配。

巡检离线提交技术封面

一、先画清楚三个状态,而不是先写重试循环

上一阶段的状态机描述的是业务进度:待巡检、处理中、已完成。新增的同步状态不是第四种业务进度,它应该与业务字段并列:pending 表示已经保存在本地等待发送,sending 表示正在进行一次请求,confirmed 才是服务端已确认,conflict 表示服务端拒绝了当前版本。比如一条“已完成”的检查记录完全可以同时是“待同步”;如果把两个状态直接合在一个 status 字段里,列表筛选和提交校验都得重写。

另一方面,保存按钮要遵守原先的准入规则。直接从“待巡检”跳到“已完成”的请求不应进入离线队列;备注为空或超过二百字也应在排队前拒绝。网络断开不是绕过校验的理由。队列保存成功后,可以在列表上立即显示草稿的业务值,但必须附带同步标识,让用户知道“当前结果尚待服务端确认”。

业务状态与同步状态双轴关系图

实际失败至少有四类:本机写盘失败、网络连接失败、服务端业务校验冲突、服务端可能成功但客户端未收到响应。前两类需分别向用户解释;第三类不能无限重试;第四类必须靠幂等请求标识解决,不能靠“再点一次保存”蒙混过关。如果服务端没有去重机制,重复请求可能变成重复审计记录,简单的重试功能反而制造新问题。

二、把一次提交变成具有唯一标识的待办记录

InspectionRecord 沿用上一阶段的六个字段,不因为新增存储而改名。待提交队列单独承载版本号、请求标识、重试次数和下一次允许发送的时刻。这样之后接入服务端乐观锁时,客户端清楚知道自己基于哪个版本修改。下列文件建议位于 entry/src/main/ets/services/InspectionOutbox.ets;它存储的是待传输的小型 JSON 文本,例子用 ArkData 的 Preferences,数据量很大或要求多条事务一致性时应评估关系型数据库而不是持续堆积到 KV 字段中。

// entry/src/main/ets/services/InspectionOutbox.ets
import { preferences } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';

export interface PendingCommit {
  requestId: string;
  recordId: number;
  baseVersion: number;
  nextStatus: string;
  nextNote: string;
  retryCount: number;
  nextAttemptAt: number;
  blocked: boolean;
}

export class InspectionOutbox {
  private store?: preferences.Preferences;
  private readonly key: string = 'inspection_pending_v1';

  async open(context: common.UIAbilityContext): Promise<void> {
    this.store = await preferences.getPreferences(context,
      { name: 'inspection_outbox' });
  }

  async read(): Promise<PendingCommit[]> {
    if (!this.store) { throw new Error('本地队列尚未初始化'); }
    const raw = await this.store.get(this.key, '[]') as string;
    return JSON.parse(raw) as PendingCommit[];
  }

  async replace(items: PendingCommit[]): Promise<void> {
    if (!this.store) { throw new Error('本地队列尚未初始化'); }
    await this.store.put(this.key, JSON.stringify(items));
    await this.store.flush();
  }

  async append(item: PendingCommit): Promise<void> {
    const items = await this.read();
    if (items.some((it: PendingCommit) => it.requestId === item.requestId)) {
      return;
    }
    items.push(item);
    await this.replace(items);
  }
}

其中 put() 修改缓存,flush() 才负责将 XML 类型的 Preferences 改动持久化;因此必须等待两步结束,再向用户报告“已保存到本地”。如果抛出异常,界面应继续保留草稿,并显示“本机保存失败”,不能先弹成功提示。这段示例以页面串行调用为前提,不适合多进程共用同一个 Preferences 文件;多个页面可能同时写队列时,还要在应用层增加串行写入器或迁移到支持事务的数据层。

三、真正处理网络不确定性:成功才出队

提交接口以示例 POST /v1/inspection/commit 为契约,包含 requestId、recordId、baseVersion、status、note。服务端需要以 requestId 做幂等去重并校验记录版本;HTTP 409 表示需要人工解决冲突,而不是自动覆盖。客户端使用 NetworkKit 的 HTTP 请求能力,真实部署时应替换为本项目的 HTTPS 地址和鉴权方式;不要把令牌写入仓库。下面的发送函数实现了请求创建、状态分类和资源释放。

// entry/src/main/ets/services/InspectionSender.ets
import { http } from '@kit.NetworkKit';
import { PendingCommit } from './InspectionOutbox';

export type SendResult = 'confirmed' | 'conflict' | 'retry';

export async function sendInspection(item: PendingCommit,
  endpoint: string): Promise<SendResult> {
  const req = http.createHttp();
  try {
    const response = await req.request(endpoint, {
      method: http.RequestMethod.POST,
      header: {
        'Content-Type': 'application/json',
        'Idempotency-Key': item.requestId
      },
      extraData: JSON.stringify({
        requestId: item.requestId,
        recordId: item.recordId,
        baseVersion: item.baseVersion,
        status: item.nextStatus,
        note: item.nextNote
      }),
      connectTimeout: 5000,
      readTimeout: 8000
    });
    const code = response.responseCode;
    if (code >= 200 && code < 300) return 'confirmed';
    if (code === 409 || (code >= 400 && code < 500 && code !== 429)) {
      return 'conflict';
    }
    return 'retry';
  } catch (_) {
    return 'retry';
  } finally {
    req.destroy();
  }
}

网络请求前需要在模块 module.json5 的 requestPermissions 中声明 ohos.permission.INTERNET,且应使用有效 HTTPS 域名;认证信息与网络失败策略应由真实服务端协议决定。客户端无法自行断言超时前请求没有被服务端处理,因此**同一条提交记录重试时复用原来的 requestId**。不要每次重试生成一个新编号,否则会破坏幂等保证。只有收到可认定的成功响应,才能从待办队列删除对应项。

网络超时、冲突与重试间隔图

重试不应该无限密集。可以使用 Math.min(60000, 1000 * Math.pow(2, retryCount)) 计算简单的指数退避,再加少量随机抖动,避免同一批设备同时拥向服务端。推荐在应用进入前台、用户点击“立即同步”或网络恢复信号到来时检查 nextAttemptAt,而不是在后台无条件无限循环。本地应用退出不会自动意味着后台任务仍在运行,系统调度和后台策略必须单独研究。

在页面提交入口中,把第03篇的 validateInspection(before, after, note) 作为第一道门禁。进入队列时生成一次请求号,初始化退避和冲突标记;随后等待持久化完成,才更新 @State 的同步提示。这里 baseVersion 要来自服务端返回的记录版本,若原来的示例数据尚未接入版本管理,必须先在业务层取得该值,不能一直写成零并期待服务器正确处理冲突。

// InspectionPage 的服务调用片段,recordVersion 来自已加载的服务端记录
private async enqueueConfirmedDraft(recordVersion: number): Promise<void> {
  const current = this.findRecord(this.selectedId);
  if (!current) { this.formError = '记录已不存在'; return; }
  const error = validateInspection(current.status,
    this.draftStatus, this.draftNote);
  if (error.length > 0) { this.formError = error; return; }
  const change: PendingCommit = {
    requestId: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
    recordId: current.id,
    baseVersion: recordVersion,
    nextStatus: this.draftStatus,
    nextNote: this.draftNote,
    retryCount: 0, nextAttemptAt: 0, blocked: false
  };
  try {
    await this.outbox.append(change);
    this.formError = '已保存到本机,等待同步';
  } catch (_) {
    this.formError = '本机保存失败,请保留当前草稿';
  }
}

此处的 outbox 是已通过页面 getContext(this) 对应的 UIAbilityContext 初始化过的 InspectionOutbox 实例;为避免多次点击与多处同步并行,页面应在调用期间禁用提交按钮,并由应用级的单例服务串行处理队列。示例请求号用于说明单次生成、跨重试复用的原则;对分布式业务更推荐由服务端或成熟 UUID 实现提供更严格的唯一性保障。

四、队列回放要先保存结果,再改页面提示

一条记录在本地保存后可以乐观展示,但不要立刻从队列抹掉。对于成功响应,要先把“已确认”状态和新的服务端版本保存到可信状态存储,再删除待办项;下面的示例简化为只维护待办队列,业务数据最终仍需要由服务端拉取并对账。对于 conflict,保留原始请求内容并把记录标记为“需处理”;如果只是网络超时,增加 retryCount 和 nextAttemptAt。重点在于出错后不能把失败当作已经同步。

// 页面服务层串行调用,避免并发写同一个 Preferences 实例
import { InspectionOutbox, PendingCommit } from './InspectionOutbox';
import { sendInspection, SendResult } from './InspectionSender';

export async function replayOutbox(outbox: InspectionOutbox,
  endpoint: string): Promise<void> {
  const items = await outbox.read();
  for (const item of items) {
    if (item.blocked || Date.now() < item.nextAttemptAt) continue;
    const result: SendResult = await sendInspection(item, endpoint);
    if (result === 'conflict') {
      const latest = await outbox.read();
      await outbox.replace(latest.map((v: PendingCommit) =>
        v.requestId === item.requestId ? { ...v, blocked: true } : v));
      continue;
    }
    if (result === 'confirmed') {
      const latest = await outbox.read();
      await outbox.replace(latest.filter((v: PendingCommit) =>
        v.requestId !== item.requestId));
      continue;
    }
    const latest = await outbox.read();
    const updated = latest.map((v: PendingCommit) => {
      if (v.requestId !== item.requestId) return v;
      const retries = v.retryCount + 1;
      return { ...v, retryCount: retries,
        nextAttemptAt: Date.now() + Math.min(60000,
          1000 * Math.pow(2, retries)) };
    });
    await outbox.replace(updated);
  }
}

这里的 conflict 不会从队列删除,而是设置 blocked 并在下一轮同步时跳过,等待用户核对服务端最新数据。解锁后需要重新校验版本号与业务内容,而非简单清空标记。更重要的是,队列回放必须串行调用,同一对象不允许两处 UI 同时启动;可通过服务层 busy 标志与单实例管理器实现互斥。应用重新启动后也要先读取持久化队列,而不是只根据内存中的按钮状态判断是否存在待同步数据。

五、用户感知和验收应一致

建议把三个可视状态放在任务详情旁:灰色“未修改”、琥珀色“已保存,待同步”、绿色“服务端已确认”。发生冲突显示红色“需要核对”。用户在信号弱的位置按下保存后,最有价值的一句话不是“提交成功”,而是“本机已保存;联网后继续同步”。只有服务端返回确认并完成本地队列更新后,才显示最终成功。

手机巡检界面的待同步与失败提示设计

验收可以围绕一条记录 102 顺序展开:保持原来的 处理中 和 note 字段,编辑草稿后断网提交;确认等待本地队列落盘后才出现待同步提示;杀掉并重新打开应用后读取同一请求;恢复网络检查一次提交被确认;构造超时后重试仍使用同一请求 ID;构造 409 冲突时确认不会自动覆盖服务端状态。还应安排储存空间不足和写入权限错误,检查草稿没有因为 flush() 失败而消失。所有这些是明确的验证步骤,不应未经真实执行就填入耗时或成功率。

这一步之后,巡检工作台的保存链路才算拥有基本的失败语义:校验通过后先得到可靠的本地接收,再以幂等协议争取可确认的服务端结果。下一篇可在此基础上处理多设备并发、服务端版本冲突和真正的增量同步,而不是继续把按钮置灰当成数据一致性方案。

参考资料:

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐