# 03 · 风险登记册

> 概率/影响：高/中/低。状态：开放/缓解中/关闭。受阻任务（`⚠`）须在此登记。

## 1. 技术风险（最高优先）

| ID | 风险 | 概率 | 影响 | 触发信号 | 缓解 / 应对 | 负责人 |
|---|---|---|---|---|---|---|
| **R-01** | **`yy://` 自定义 scheme 的 iframe 导航不被 `onLoadIntercept` 捕获**（桥不通） | 中 | 高（阻断全局） | T-M1-07 验证失败 | 前置到 M1 最先验证；回退：`onInterceptRequest`+`WebSchemeHandler` 注册 `yy` scheme；或改桥 JS 走 `javaScriptProxy.postMessage`（对 H5 透明）。三方案均零改 H5 | 桥/技术负责人 |
| **R-02** | **`file://` 页面跨域受限**，H5 的 XHR/fetch 取本地资源失败 | 中 | 高（大厅/子游戏白屏） | T-M2-08 验证失败 | 前置到 M2；回退：自定义协议/`onInterceptRequest` 接管本地资源（框架 §7.3）。必要时把首页改用自定义 scheme 加载 | 台/桥 |
| **R-03** | `MessageCodec` 转义与 lzyzsd 不一致，含特殊字符的 data 解析错位 | 中 | 中 | 含引号/反斜杠/中文的分享文案、JSON data 解析异常 | 单测以 Android 端样例做字节级对照；复用库 JS 原文件 | 桥 |
| **R-04** | **线程问题**：能力回调在非 UI 线程调 `runJavaScript` 崩溃/丢消息 | 中 | 高 | 定位/支付/传感器回调偶发崩溃 | 强制 UI 线程守卫（框架 §5.5）；能力回传统一经桥（emitter/UIContext） | 桥 |
| **R-05** | **TaskPool Sendable 约束**导致下载/解压回调传参编译/运行失败 | 中 | 中 | `@Concurrent` 报 Sendable 错 | 仅传 Sendable + emitter 回传（§9.1）；路径在 UI 线程取好传字符串 | 台 |
| **R-06** | 远程配置二级 `url`/分层覆盖逻辑与 Android 不一致，选错下载地址/版本 | 中 | 中 | 资源版本判断错误、下错包 | `VersionResolver` 纯函数 + 多层样例单测，对照《契约规范》§4.4 | 台 |
| **R-07** | Web 保活（NodeController/BuilderNode）生命周期/内存复杂，切换异常或泄漏 | 中 | 中 | 切换白屏/内存涨 | M5 才上；先用 `loadUrl` 切换保底；保活作为优化项可回退 | 桥 |
| **R-08** | `app_data.js` 注入时序错误（加载后才写），H5 读不到配置 | 低 | 高 | 大厅读 `app_*` 为 undefined | 铁律：`INJECT_APP_DATA` 早于进入容器（框架 §7.1/§8.4）；测试覆盖 | 台 |

## 2. 第三方 SDK / 平台风险

| ID | 风险 | 概率 | 影响 | 缓解 / 应对 | 负责人 |
|---|---|---|---|---|---|
| **R-09** | 微信/分享/定位等厂商 **HarmonyOS SDK 缺失或能力不全** | 中 | 中 | 早期做 SDK 可用性盘点；缺失则系统能力替代（如系统分享/系统定位）或服务端代理；登录/支付走 code/服务端 | 能 |
| **R-10** | 声网/支付 SDK 集成成本高 | 中 | 低（本期桩规避） | 本期占位桩，M6 按需集成；不阻塞主线 | 能 |
| **R-11** | 高德等定位 SDK **隐私合规**未先行，定位失败/审核不过 | 中 | 中 | 使用前 `updatePrivacyShow/Agree`；权限用时申请 + 文案；优先系统定位 | 能 |
| **R-12** | 本机 HTTP 上传服务（截图）实现复杂（无内置 server） | 中 | 低 | `@ohos.net.socket` 自建轻量服务或 NAPI；截图分享非核心可后置 | 台 |
| **R-13** | ArkWeb 版本差异导致 API 行为变化 | 低 | 中 | 锁定目标 API 版本；编码前 `devecocli docs` 核对签名；CI 固定 SDK | 桥 |

## 3. 工程 / 进度风险

| ID | 风险 | 概率 | 影响 | 缓解 / 应对 | 负责人 |
|---|---|---|---|---|---|
| **R-14** | 团队 ArkTS/ArkUI 经验不足，前期效率低 | 中 | 中 | M0/M1 配对开发；沉淀附录 A 适配清单；统一脚手架样板 | 技术负责人 |
| **R-15** | 契约理解偏差导致 handler 行为不符，后期返工 | 中 | 中 | `contracts` HAR 固化为 SSOT；契约探针 H5 每周回归；评审对照 | Q |
| **R-16** | 能力并行开发接口/风格不统一 | 低 | 低 | `CapabilityProvider` 统一接口 + Provider 样板；代码评审 | 桥 |
| **R-17** | 真机/设备不足影响联调与回归 | 低 | 中 | 早期备真机 + 模拟器；CI 夜间冒烟 | PM |
| **R-18** | **单测运行工具链缺口**：`devecocli` 无 `test` 子命令，本地单测（src/test/hypium）的 hvigor task 未常规暴露，CLI 难跑覆盖率 | 中 | 中 | 单测代码已就位；运行候选：① DevEco IDE 跑 Local Test；② 确认 hvigorw 本地单测 task 并纳入 CI；③ 以真机契约探针 H5 为主回归。待定方案 | 桥/技术负责人 |

## 4. 受阻任务记录（动态更新）

| 日期 | 受阻任务 | 关联风险 | 描述 | 处置 | 状态 |
|---|---|---|---|---|---|
| 2026-06-25 | T-M1-08 桥引擎单测 | R-18 | 13 用例代码已就位，但 devecocli 无 test 命令、本地单测 hvigor task 未常规暴露，无法 CLI 跑覆盖率 | 代码入库；运行方式待用户定夺（IDE/CI/hvigorw 例外） | 开放 |

## 5. 风险闸门（与里程碑绑定）

- **M1 闸门**：R-01 必须收敛（V1 通过或回退方案落地）方可进入 M2。
- **M2 闸门**：R-02 必须收敛（V2 通过或回退方案落地）方可大规模铺 M3 能力。
- **M5 闸门**：R-04/R-07 收敛 + 安全清单（框架附录 B）通过方可发布。