离线模式
HAC 离线模式和离线存储命令的使用边界、流程和异常处理。
适用场景
离线模式用于在弱网或断网时控制页面行为，并用本地离线存储暂存必要数据。它适合盘点、巡检、收货、门店作业等现场流程。
离线能力只能解决“本机暂存”和“页面导航控制”，不能自动替代完整的数据同步、冲突处理和服务端校验。真正的离线业务仍需要设计补传、去重和冲突规则。
使用前提
- 应用运行在
HAC中； - 已安装并使用 PDA / Android 交互命令插件；
- 明确哪些数据可以离线暂存，哪些必须在线校验；
- 已定义键名、数据格式、清理时机和补传策略；
- 页面能区分“已暂存”和“已提交到服务端”。
命令速查
| 命令 | 用途 |
|---|---|
| 设置离线模式 | 开启或关闭离线模式；开启后页面导航会受限 |
| 从离线存储中读取值 | 按键读取本地缓存到变量 |
| 从离线存储中读取值到单元格 | 按键读取本地缓存到目标单元格 |
| 将键值存入离线存储 | 写入本地键值数据；对象会序列化为 JSON |
| 从离线存储中删除指定键值 | 删除指定本地缓存 |
未读取到数据时，读取命令通常返回：
DATA_NOT_FOUND推荐流程
进入离线作业：
进入离线业务页
-> 执行【设置离线模式：开启】
-> 读取本地任务包或缓存数据
-> 用户扫码、录入、拍照
-> 每完成一项就写入离线存储
-> 页面显示待提交数量恢复在线提交：
网络恢复或用户点击补传
-> 读取离线存储
-> 按业务主键去重
-> 调用服务端命令提交
-> 成功：删除对应本地键
-> 失败：保留本地数据并显示原因
-> 全部完成后关闭离线模式
设计要点
- 键名要稳定，建议包含业务类型、单据号、设备或用户信息；
- 每条离线记录应包含业务主键、操作人、设备、时间、状态和重试次数；
- 不要把大文件直接当作普通键值频繁写入；照片、视频应按文件流程处理；
- 页面要清楚显示“本地已保存”“待补传”“补传中”“补传失败”“已提交”；
- 删除本地缓存前，必须确认服务端已成功接收；
- 离线时限制容易造成冲突的操作，例如作废、审批、跨单据修改。
异常处理
| 异常 | 常见原因 | 推荐处理 |
|---|---|---|
读取返回 DATA_NOT_FOUND | 本地没有对应键或已被清理 | 初始化为空状态，并提示重新下载任务包 |
| 本地数据格式错误 | 版本升级、键名冲突、JSON 结构变化 | 保留原始值，提示清理或升级数据 |
| 补传失败 | 网络异常、服务端校验失败、重复提交 | 保留本地记录，显示失败原因和重试入口 |
| 同一业务重复提交 | 设备重试、多人多机操作 | 使用业务主键和提交批次做幂等校验 |
| 本地缓存过多 | 长期不清理或大数据暂存 | 显示待处理数量，提供管理员清理流程 |