# 期货 HarmonyOS 客户端稳定性治理需求开发文档 ## 1. 文档目的 本文将现有冻结（App Freeze）与内存溢出（OOM）整改记录整理为可研发落地、可测试验收的需求。目标是在不改变行情、交易、画线业务协议及用户可见规则的前提下，降低主线程阻塞、请求重复与对象滞留风险。 本文记录的是已验证改造的需求基线，不代表所有项均已随正式版本发布；版本接入与线上复采必须以各上游仓库和发布包为准。 ## 2. 范围与代码归属 | 域 | 主要归属 | 本次目标 | | ------ | ------------------------------------------------------------------- | --------------------- | | 应用业务 | `harmony-ths-futures` | 交易、行情与 WebView 生命周期治理 | | 通信 | `ohos_mobile_lib_communication` | 解码、曲线解析、请求队列与缓冲释放 | | 交易 SDK | `harmony_futures_trade_sdk` `futures_trade_sdk`（原生 `lib-weituosdk`） | Native 锁规避、成交推送、市价缓存 | | 画线 SDK | `hmdrawlinebasicsdk` | 绘制候选集去重 | 本仓库仅保存变更说明，不能直接构建或产出 HAP/HAR。 ## 3. 功能需求 ### FR-01 通信与解析异步化 1. XML 响应的字节解码和属性解析必须在 TaskPool 中完成；主线程仅消费解析结果。解析入口只允许携带可序列化数据，禁用 DOCTYPE，并保持登录会话、验证码、手机号查询的原有回调与失败语义。 2. `HXZip` 解压及曲线的 `points × fields` 解析必须在通信 HAR 的持久 Worker 中执行。响应须按请求顺序串行回调；Worker 异常须拒绝当前等待任务，但不得阻断后续消息。 3. `QueueManagement` 必须维护 `instanceId → client/companion` 索引，避免响应分发遍历全部客户端；跨 `frameId` 切换时，必须释放旧请求缓冲、主/伴随 client 映射。 ### FR-02 行情与绘制主线程削峰 1. 表格实时通知在同一事件循环内仅保留最新一份 `TableData`，已有定时器时不得继续创建闭包；切页或释放时必须取消定时器并清空待通知数据。 2. 画线候选集去重必须保持“同对象、本地 ID 相同或远端 ID 相同即重复”的既有语义与插入顺序，复杂度由 O(n²) 降为 O(n)。 ### FR-03 交易链路防重复与锁规避 1. 前台交易页的在线判断必须读取 `currentAccount.isOnline` 缓存，不得同步调用 Native 在线查询；断网、重登、切账号后的条件单补查行为保持不变。 2. 同一账号重登必须复用进行中的 Promise；无实际拦截效果的交易发送前 SDK 状态检查必须移除。 3. 挂单查询进行中再次触发时，只保留一次尾随刷新；列表构建中的套利灰度判断按账号缓存，并在设置更新、账号或灰度配置变化时失效。 4. 成交推送必须按唯一标识去重。首次加载可全量排序，后续记录必须以稳定二分插入，且不改变成交量、盈亏、账号过滤与展示顺序。 5. 市价缓存须按“合约 + 价格类型”更新同一节点；消费后必须用可修改数组操作删除节点，禁止重复累积。 ### FR-04 页面与请求资源释放 1. `TableRequestClient` 切页、取消订阅或释放时，必须幂等地移除旧队列映射、实时订阅、请求缓冲与待通知数据。 2. WebView 总览页销毁时，必须停止三个行情请求并清空 client 与 JS bridge 的双向引用。 ## 4. 影响面 | 需求域 | 用户/业务入口 | 受影响组件 | 保持不变 | 重点回归 | | --- | --- | --- | --- | --- | | 通信与解析 | 登录、验证码、行情包与 K 线加载 | XML Parser、通信 Worker、`QueueManagement` | 协议、回调结果、消息顺序 | 损坏 XML、大包、周期连续切换、跨 Frame 请求 | | 行情与画线 | 行情列表刷新、合约详情、K 线绘制 | `TableRequestClient`、画线 SDK | 行情数据、线条样式、命中与层级 | 高频推送、分组切换、滚动、跨周期线合并 | | 交易 | 前后台、账号切换、挂单/委托/成交页 | `TradePage`、`TradeApiManager`、交易 SDK | 下单/撤单、账户过滤、成交汇总与排序规则 | 断网重登、重复刷新、重复推送、真实账户切换 | | 页面生命周期 | WebView 行情总览页退出 | `OverViewEvent`、请求 client、JS bridge | 总览请求参数、前后台恢复行为 | 反复进入/退出总览页、页面销毁后回调 | ## 5. 非功能要求与边界 - 所有异步任务仅传递基础类型、`Uint8Array` 或其他可序列化数据；单个 Worker 消息受 16 MB 限制，接近上限时需分块设计。 - 不修改网络协议、公开接口、交易下单/撤单规则、行情数据模型或画线样式。 - 不将 SDK 对象迁移至 Worker；Native 锁的根治依赖交易 SDK 缩小锁粒度，应用侧仅减少进入锁域的次数。 - 临时 HAR 路径、压测代码、计数日志和 API SDK 替换不得进入正式提交。 ## 6. 验收标准 1. 在上游项目执行 `devecocli build --modules @default` 或对应 HAP 构建成功，且 `devecocli check lint` 无新增问题。 2. 覆盖登录/断网重登、前后台、账号切换、挂单/委托/成交刷新、行情分组切换、K 线周期切换及 WebView 总览销毁；无 JS Crash、CppCrash、OOM 或 `APPFREEZE`。 3. 成交去重、稳定排序、缓存删除和请求解绑须具备单元或白盒压力测试；测试后不存在旧订阅、旧缓冲、待通知数据或缓存节点残留。 4. 新包须在真机或模拟器重新采集冻屏采样。`QueueManagement`、`isArbitrageEnabled` 与 `TradeGuaDanListView.onForeground` 不应继续作为可归因的 TOP 耗时热点；分层采样不得重复相加作为性能收益。 ## 7. 交付与追溯 每个交付项需提供：所属仓库/分支/commit、HAR 或 HAP 版本与校验值、修改文件清单、构建日志、测试设备与场景、前后指标、未覆盖项及回滚包。详细历史证据见 `harmony-ths-futures-freeze/doc/change-notes/` 和 `harmony-ths-futures-apm-oom/doc/change-notes/`。 ## 8. Change-notes 追溯 | 需求域 | 改动仓库 | 原始功能改动记录（括号内为改动仓库） | | ------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 通信与解析 | `harmony-ths-futures`
`ohos_mobile_lib_communication` | | | 行情与画线 | `harmony-ths-futures`
`hmdrawlinebasicsdk` | | | 交易 | `harmony-ths-futures`
`futures_trade_sdk`（原生 `lib-weituosdk`）
`harmony_futures_trade_sdk` | | | 页面生命周期 | `harmony-ths-futures` | |