81 lines
12 KiB
Markdown
81 lines
12 KiB
Markdown
# 期货 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 <module>@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`<br>`ohos_mobile_lib_communication` | <ul><li>[02-xml-taskpool-refactor.md](harmony-ths-futures-freeze/doc/change-notes/02-xml-taskpool-refactor.md)（`harmony-ths-futures`）</li><li>[03-communication-taskpool-decompression.md](harmony-ths-futures-freeze/doc/change-notes/03-communication-taskpool-decompression.md)（`ohos_mobile_lib_communication`、`harmony-ths-futures`）</li><li>[04-curve-parsing-taskpool.md](harmony-ths-futures-freeze/doc/change-notes/04-curve-parsing-taskpool.md)（`ohos_mobile_lib_communication`、`harmony-ths-futures`）</li><li>[14-communication-request-buffer-frame-cleanup.md](harmony-ths-futures-apm-oom/doc/change-notes/14-communication-request-buffer-frame-cleanup.md)（`ohos_mobile_lib_communication`、`harmony-ths-futures`）</li></ul> |
|
||
| 行情与画线 | `harmony-ths-futures`<br>`hmdrawlinebasicsdk` | <ul><li>[09-drawline-dedup-optimization.md](harmony-ths-futures-freeze/doc/change-notes/09-drawline-dedup-optimization.md)（`hmdrawlinebasicsdk`、`harmony-ths-futures`）</li><li>[10-table-request-client-subscription-cleanup.md](harmony-ths-futures-apm-oom/doc/change-notes/10-table-request-client-subscription-cleanup.md)（`harmony-ths-futures`）</li><li>[11-table-request-client-notification-coalescing.md](harmony-ths-futures-apm-oom/doc/change-notes/11-table-request-client-notification-coalescing.md)（`harmony-ths-futures`）</li></ul> |
|
||
| 交易 | `harmony-ths-futures`<br>`futures_trade_sdk`（原生 `lib-weituosdk`）<br>`harmony_futures_trade_sdk` | <ul><li>[05-trade-sdk-native-lock-app-mitigation.md](harmony-ths-futures-freeze/doc/change-notes/05-trade-sdk-native-lock-app-mitigation.md)（`harmony-ths-futures`、`futures_trade_sdk` 的原生 `lib-weituosdk`）</li><li>[07-trade-sdk-match-push-optimization.md](harmony-ths-futures-freeze/doc/change-notes/07-trade-sdk-match-push-optimization.md)（`harmony-ths-futures`、`harmony_futures_trade_sdk`）</li><li>[08-trade-page-online-status-cache.md](harmony-ths-futures-freeze/doc/change-notes/08-trade-page-online-status-cache.md)（`harmony-ths-futures`）</li><li>[11-top10-followup-fixes.md](harmony-ths-futures-freeze/doc/change-notes/11-top10-followup-fixes.md)（`harmony-ths-futures`）</li><li>[12-trade-sdk-market-price-cache-cleanup.md](harmony-ths-futures-apm-oom/doc/change-notes/12-trade-sdk-market-price-cache-cleanup.md)（`harmony_futures_trade_sdk`）</li></ul> |
|
||
| 页面生命周期 | `harmony-ths-futures` | <ul><li>[13-webview-overview-request-cleanup.md](harmony-ths-futures-apm-oom/doc/change-notes/13-webview-overview-request-cleanup.md)（`harmony-ths-futures`）</li></ul> |
|