docs: 完善启动性能监控接入方案

- 对齐 StartupMonitor 实际采集和 ELK 上传链路
- 补充单次首帧、observer owner 与 APP_LAUNCH 去重约束
- 记录登录态、网络和隐私场景真机验收结果

HarmonyOS 启动性能监控接入方案_20260805.md

@@ -6,19 +6,36 @@
 
 ## 2. 总体链路
 
-`APP_LAUNCH` 系统事件提供启动类型和系统耗时；首页完成首次有效绘制后，通过 `reportDrawnCompleted` 标记首帧终点。客户端将两者组合为自定义启动指标，由 APM SDK 本地采样、聚合后上传；后台按模块配置阈值和采样策略，并在 ELK/Grafana 展示趋势与分位数。
+`APP_LAUNCH` 系统事件提供启动类型和系统耗时；首个有效入口页完成首次绘制后，通过 `reportDrawnCompleted` 标记终点。当前客户端使用 `ElkService` 异步上传结构化指标，后台再按模块配置阈值、聚合和看板。若后续具备 HarmonyOS 自定义 APM SDK，可替换上传层，但保留事件采集和去重逻辑。
 
 ## 3. 客户端接入
 
-在 `future_entry_demo/src/main/ets/monitor/APMHelper.ets` 中初始化与现有 `HXMonitor` 同体系的 HarmonyOS 自定义 APM 事件能力；不要直接复用 Android 文档中的 Java API。
+实现位于 `future_entry_demo/src/main/ets/monitor/StartupMonitor.ets`。`EntryAbility.onCreate` 必须尽早调用 `StartupMonitor.init()`，先注册 watcher，再允许入口页提交首帧完成事件。`init()` 本身应保持幂等，避免同一进程重复注册 watcher。
 
-在 `EntryAbility.ets` 中订阅 `APP_LAUNCH`，读取：
+监听 `APP_LAUNCH` 后读取：
 
 - `start_type`：启动类型；仅 `0` 纳入冷启动统计。
-- `extend_time`：从抬手到应用报告首帧完成的耗时。
-- `animation_finish_time`、`icon_input_time`、`bundle_version`：用于分析和问题追溯。
+- `extend_time`：从系统记录的 `icon_input_time` 到应用报告绘制完成的耗时。
+- `time`、`icon_input_time`、`process_name`：标识启动事件并用于去重。
+- `animation_finish_time`、`bundle_version`：用于分析和问题追溯。
 
-在首页根节点完成第一次有效绘制时仅上报一次 `reportDrawnCompleted`。隐私页、网络异常页等可能成为首次可见页面的入口也应覆盖，否则对应场景的首帧时间会失真。
+### 3.1 首帧单次提交
+
+`LauncherPage`、`NetworkAnomalyPage` 和 `Index` 都应尝试监听根节点首次 `draw`，以最先有效绘制的页面作为 `entry_page`。必须遵循以下约束：
+
+1. 在调用 `reportDrawnCompleted` **之前**设置进程级已提交状态；异步回调尚未执行时，其他页面也不得再次提交。
+2. observer 触发后立即注销，页面 `aboutToDisappear` 仅释放与自身 `pageName` 匹配的 observer，避免旧页面销毁新页面的监听。
+3. 仅同步调用异常表示任务未提交，此时恢复未提交状态，允许后续入口页重试；页面销毁不得重置已经提交的状态。
+
+### 3.2 事件过滤与去重
+
+仅处理 `start_type === 0` 且 `extend_time > 0` 的记录。上传前按以下键去重：
+
+```text
+time + icon_input_time + start_type + process_name
+```
+
+客户端保留最近 20 个事件键，兼容同一回调组内重复记录和系统重新投递，同时避免缓存无限增长。
 
 ## 4. 指标定义
 
@@ -28,6 +45,7 @@
 | 指标名 | `cold_start_time` |
 | 指标值 | 冷启动耗时，单位 ms |
 | 维度 | `start_type`、`entry_page`、`app_version` |
+| 追溯字段 | `event_time`、`icon_input_time`、`process_name`、`extend_time`、`animation_finish_time`、`bundle_version` |
 | 分桶 | `[500, 800, 1200, 2000, 3000]` |
 
 模块名使用小写字母和连字符；指标名不包含连字符。维度控制在必要范围内，避免将用户 ID、完整 URL 等高基数字段作为维度。
@@ -38,13 +56,19 @@
 
 ## 6. 兼容与兜底
 
-现有 `AppEvent.ets` 的 `ElkService` 可以上传结构化启动日志，但它不具备 PDF 所述的指标聚合语义。优先确认 HarmonyOS 是否提供与 Android 自定义 APM SDK 对应的包和 API；若暂未提供，则先通过 `ElkService` 上传 `cold_start_time`、维度和原始系统字段，并由后端补充索引、聚合规则和看板。
+当前通过 `ElkService` 上传 `cold_start_time`、维度和原始系统字段，但它不具备 PDF 所述的指标聚合语义，需要后端补充索引、聚合规则和看板。不要直接复用 Android 文档中的 Java API；后续接入 HarmonyOS 自定义 APM SDK 时，仅替换上传实现。
 
 `APP_LAUNCH` 的事件解析必须与崩溃事件分开处理：崩溃事件依赖异常和日志字段，启动事件不包含这些字段。上传应异步执行，不阻塞首页渲染；以 `time + icon_input_time + start_type + process_name` 去重，兼容系统重新投递。
 
 ## 7. 验收标准
 
-1. 每次冷启动只产生一条可查询记录，且 `extend_time` 大于 0。
-2. 本地日志/性能工具的耗时与后台数据量级一致。
-3. 看板可按版本和冷启动维度查询 P50、P95、超阈值占比及分桶分布。
-4. 断网、重复回调或上传失败不影响启动流程，网络恢复后按既有上传机制重试。
+1. 单次冷启动中，隐私页、网络页和首页连续跳转时，`reportDrawnCompleted` 仍只提交一次。
+2. 未登录启动以登录/启动页为入口；已登录启动以 `Index` 为入口，`entry_page` 不被后续页面覆盖。
+3. 每次冷启动只产生一条可查询记录，且 `extend_time > 0`；热启动、无效耗时和重复事件不上传。
+4. 页面在系统异步回调前销毁时，不影响已经提交的上报；旧页面不会释放新页面 observer。
+5. 本地日志与后台数据量级一致；看板可查询 P50、P95、超 2 秒占比及分桶分布。
+6. 断网或上传失败不影响启动流程，网络恢复后按既有上传机制重试。
+
+## 8. 已验证结果
+
+在 `CrashDiagnosticsDemo` 的 nova 14 Pro 真机回归中：未登录冷启动入口为 `StartupLogin`，`extend_time` 约 `158ms`；持久化登录后冷启动入口为 `Index`，`extend_time` 约 `155ms`。网络异常、网络恢复、隐私确认及页面返回场景均保持一次 draw 回调和一次系统提交，后续页面注册被全局保护拦截；`start_type=1` 的热启动事件被正确忽略。