first commit

docs/设计文档/Plan/00_总体规划.md

@@ -0,0 +1,98 @@
+# 00 · 总体规划
+
+## 1. 里程碑总览
+
+| 里程碑 | 主题 | 出口判据（Exit Gate） | 估时 | 可并行 |
+|---|---|---|---|---|
+| **M0** | 工程脚手架 + 契约类型 | 多模块工程可编译、可签名、CI 跑通；`contracts` 全量类型就位 | 3–4 人日 | — |
+| **M1** | 桥引擎（最高优先） | 最小回显 H5 跑通；**`yy://` 拦截阻塞性验证通过**；桥引擎单测 ≥80% | 6–8 人日 | — |
+| **M2** | 容器 + 启动 + 资源 | 真机加载现有大厅 H5、能进子游戏；**`file://` 跨域阻塞性验证通过** | 8–10 人日 | 平台层/配置/资源三轨并行 |
+| **M3** | 本期能力（含占位桩） | 本期能力真机逐条对照契约通过；视频房/支付桩不报错不卡死 | 14–18 人日 | **各 Provider 高度并行** |
+| **M4** | 通用网页容器 | 活动页/收银台/客服打开、`settings` 6 法 + 3 直调 + 101 回传一致 | 3–4 人日 | 可与 M3 尾段并行 |
+| **M5** | 性能与加固 | 切换流畅、冷启动达标、安全审查通过、全链路可观测 | 6–8 人日 | 部分可贯穿 M3/M4 |
+| **M6** | 暂缓能力集成（按需） | 真实视频房/支付打通，H5 仍零改动 | 视集成而定 | 独立 |
+
+> 总估时（M0–M5，不含 M6）：约 **40–52 人日**。按 3 人并行、关键路径串行估算，日历周期约 **5–7 周**。
+
+## 2. 关键路径与依赖 DAG
+
+```
+M0 脚手架/契约类型
+   │
+   ▼
+M1 桥引擎 ──(⚠ yy:// 拦截验证 = 整体可行性闸门)
+   │
+   ▼
+M2 容器+启动+资源 ──(⚠ file:// 跨域验证 = 第二闸门)
+   │
+   ├──────────────┬───────────────┐
+   ▼              ▼               ▼
+M3 能力(并行)   M4 通用网页容器   M5 性能/加固(贯穿)
+   │              │               │
+   └──────────────┴───────────────┘
+                  │
+                  ▼
+            本期验收（H5 零改动）
+                  │
+                  ▼
+            M6 暂缓能力按需集成
+```
+
+**关键路径**：`M0 → M1 → M2 → M3 → 验收`。M1/M2 的两个阻塞性验证是**最高风险节点**，必须前置（见 §5）。
+
+## 3. 并行轨道（提升效率的关键）
+
+| 轨道 | 启动条件 | 内容 |
+|---|---|---|
+| **轨道 A：桥/容器** | 立即 | M1 桥引擎 → M2 容器 → M4 通用容器 |
+| **轨道 B：平台/领域** | M0 完成后即可（不必等 M1） | 平台层（Http/Download/Unzip/KvStore/Permission/TaskPool）、ConfigManager、VersionResolver、ResourceManager、StartupOrchestrator |
+| **轨道 C：能力 Provider** | M1+M2 出口后 | 14+ 个 Provider **彼此独立**，可多人同时领，互不阻塞（依赖 contracts + bridge 接口已稳定） |
+| **轨道 D：质量/工程** | 贯穿全程 | CI、单测、契约一致性回归、可观测、安全加固 |
+
+> **效率要点**：轨道 B 大量纯逻辑（VersionResolver/MessageCodec/ConfigManager）**不依赖真机**，可在 M1 进行时并行开发并单测；能力 Provider 在 M3 高度并行是压缩工期的核心。
+
+## 4. 角色分工建议（按能力域，非按人头）
+
+| 角色 | 职责 | 主要任务 |
+|---|---|---|
+| **桥/容器负责人** | feature_bridge、容器、ArkWeb | M1 全部、M2 容器、M4、M5 性能 |
+| **平台/领域负责人** | platform、domain_resource | M2 平台/配置/资源/启动 |
+| **能力工程师 ×N** | feature_capabilities | M3 各 Provider（按 SDK 熟悉度分配：分享/支付/定位/媒体…） |
+| **QA/测试** | 契约一致性、真机回归 | 测试计划、回显 H5、44 handler 逐条核对 |
+| **技术负责人** | 架构守门、阻塞性验证决策 | 评审两个阻塞验证结果、风险闸门 |
+
+## 5. 阻塞性验证（必须前置，决定整体技术路线）
+
+| 验证 | 里程碑 | 通过判据 | 不通过时的回退 |
+|---|---|---|---|
+| **V1：`yy://` iframe 导航被 `onLoadIntercept` 捕获** | M1（`T-M1-07`） | 最小 H5 用 `iframe.src='yy://...'`，原生 `onLoadIntercept` 能取到该 URL 并拦截 | ① `onInterceptRequest`+`WebSchemeHandler` 注册 `yy` scheme；② 改注入的桥 JS 走 `javaScriptProxy.postMessage`（对 H5 仍透明） |
+| **V2：`file://` 页面 XHR/fetch 取本地资源可用** | M2（`T-M2-08`） | 现有大厅 H5 以 `file://` 加载，其对本地 js/css/资源的请求正常 | 用自定义协议/`onInterceptRequest` 接管本地资源响应（§7.3 框架文档） |
+
+> **铁律**：V1 不过则 M1 不算完成，V2 不过则 M2 不算完成。两者越早证伪越好，避免后期返工。
+
+## 6. 环境与工程约定
+
+- **工具链**：DevEco Studio + `devecocli`（build/run/emulator/log/docs）。API ≥ 12（建议 17/23）。
+- **工程形态**：1 个 entry HAP + 7 个 HAR（`feature_bridge`/`feature_capabilities`/`domain_resource`/`platform`/`contracts`/`common`）。详见框架文档 §4。
+- **构建产物**：`build-profile.json5` 配 `debug`/`release` 两 product；`devecocli build --product <p> --build-mode <m>`。
+- **签名**：M0 配好调试签名；release 签名走密钥库（不入库）。
+- **分支策略**：`main`（可发布）/ `develop`（集成）/ `feat/M{n}-{task}`（按任务）。每任务一 PR，过 CI + 代码评审合入 develop。
+- **CI**：每 PR 跑 `devecocli build`（debug）+ 单测；develop 夜间跑真机冒烟（回显 H5 + 大厅加载）。
+- **代码规范**：ArkTS 严格模式（禁 `any`）、`contracts` 为唯一 handler 名/DTO 来源、模块边界只依赖接口（框架 §3 约束）。
+
+## 7. Definition of Done（任务级通用 DoD）
+
+一个任务"完成"须同时满足：
+1. 代码合入 develop，过 CI（编译 + lint + 单测）。
+2. 若涉及契约：handler 名/参数/数据结构/回传时机**逐条对照《契约规范》**无偏差。
+3. 涉及线程的出站消息：经 UI 线程守卫（框架 §5.5）；涉及 TaskPool：仅传 Sendable + emitter 回传（§9.1）。
+4. **遵循框架附录 A（ArkTS/ArkUI 实现适配清单）**：struct 持有/生命周期解绑、严格语法、系统能力对照。
+5. 有对应测试（纯逻辑→单测；能力→真机用例记录）。
+6. 受影响文档 / [01 覆盖矩阵](./01_任务分解WBS.md) / [02 契约核对清单](./02_测试与验收计划.md) 更新。
+
+## 8. 进度跟踪机制
+
+- **任务看板**：以 `01_任务分解WBS.md` 的任务 ID 为卡片，状态 `☐/◐/☑/⚠`。
+- **每日站会**：同步关键路径任务与阻塞项；`⚠` 受阻项当日进风险登记册。
+- **里程碑评审**：到达每个 Exit Gate 召开评审，未达判据不进入下一里程碑（M1/M2 闸门尤其严格）。
+- **契约回归**：M3 起，每周跑一次"44 handler 真机逐条核对"，防回归。

docs/设计文档/Plan/01_任务分解WBS.md

@@ -0,0 +1,198 @@
+# 01 · 任务分解（WBS）
+
+> 全量任务清单。每个任务含：**目标 / 产出物 / 依赖 / 验收 / 估时 / 角色**。
+> 角色缩写：桥=桥/容器、台=平台/领域、能=能力工程师、Q=QA。估时单位：人日(pd)。
+> 验收一律以《契约规范》对应条目为准；通用 DoD 见 [00_总体规划 §7](./00_总体规划.md)。
+
+---
+
+## M0 · 工程脚手架 + 契约类型
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M0-01** | 创建多模块工程 | `devecocli create` 生成 entry + 6 HAR（`feature_bridge`/`feature_capabilities`/`domain_resource`/`platform`/`contracts`/`common`） | — | 工程可 `devecocli build`（debug）通过 | 1 | 桥 |
+| **T-M0-02** | 模块依赖与导出 | 各 `oh-package.json5` 依赖关系（单向向下）；`index.ets` 导出 | T-M0-01 | 跨模块 import 无环、可编译 | 0.5 | 桥 |
+| **T-M0-03** | 构建/签名/CI | `build-profile.json5`（debug/release product）；调试签名；CI 脚本（build+单测） | T-M0-01 | PR 触发 CI 通过 | 1 | 桥 |
+| **T-M0-04** | 契约类型（SSOT） | `contracts` HAR：`enum Handlers`（全部入站/出站 handler 名常量，含 `finsh`/`getcameraaAddress`/`backgameData-` 等原样拼写）；DTO interface（`sharetypeBean`/`MaplocationInfo`/`phoneInfoBean`/`savephotoURLBean`/`videoinfobean`/`Othervideoinfo`/`GamePay`/`sharelogin`/`sharesuccess`）；`Result<T>`/`Errors`；每 handler 的 `payloadType:'raw'|'json'` 标注 | T-M0-02 | 全量对照《契约规范》§8/§9/§12，零缺漏；编译通过 | 1.5 | 台 |
+| **T-M0-05** | 公共设施 | `common` HAR：`Logger`(分级)/`BridgeTracer`(traceId)/`EventBus`(emitter 封装)/`DIContainer`/**`ErrorCenter`(异常收敛+弹窗/静默/上报策略)**/`Result<T>` 配套 | T-M0-02 | 单测覆盖；可被各模块引用（框架 §10） | 1.5 | 台 |
+| **T-M0-06** | 引入桥 JS | 把 lzyzsd `WebViewJavascriptBridge.js` **原文件**放入 `feature_bridge/assets`，建读取/内联机制 | T-M0-01 | 文件就位、可被注入流程读取 | 0.5 | 桥 |
+| **T-M0-07** | App 入口与路由壳 | `EntryAbility`（Stage 模型生命周期，含 `onForeground/onBackground` 钩子接口）+ `Navigation`/路由骨架（Splash↔BridgeGameContainer↔GenericWebContainer 跳转与回传通道）+ `SplashPage` 壳（框架 §4） | T-M0-01 | 空壳可启动、可路由跳转；前后台钩子可触发 | 1 | 桥 |
+
+---
+
+## M1 · 桥引擎（最高优先 ⭐）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M1-01** | Web 控制器抽象 | `IWebController` 接口 + `WebviewControllerAdapter`（包 `webview.WebviewController`）+ `FakeWebController`（测试用） | T-M0-01 | 桥不直接依赖系统类；Fake 可记录脚本/模拟回执 | 1 | 桥 |
+| **T-M1-02** | 消息编解码 | `Message`（5 字段）+ `MessageCodec`：`toJson`/`toArray`/`escape`，**与 lzyzsd 完全一致的二次转义**（`\`、`"`） | T-M0-04 | 单测：与 Android 端样例字节级一致 | 1 | 桥 |
+| **T-M1-03** | Handler 注册表 | `HandlerRegistry`（put/get/default）+ `DefaultHandler`（空实现兜底） | T-M0-04 | 未注册名落默认 handler 不抛错（框架 §5.2/§6.5） | 0.5 | 桥 |
+| **T-M1-04** | 桥控制器 | `BridgeController`：`onLoadIntercept`/`callHandler`/`registerHandler`/`onPageEnd`/`flushMessageQueue`/`handleReturnData`/`dispatch`/`queue`；**`_fetchQueue` 走 `yy://return/` 回传**（非 runJavaScript 返回值）；**UI 线程守卫**（§5.5） | T-M1-01/02/03 | 单测（FakeWebController）：模拟 H5 callHandler→handler 分发、原生 callHandler→下发、回执路由、启动队列补发 | 2.5 | 桥 |
+| **T-M1-05** | 桥 JS 注入 | `onPageEnd` 中 `runJavaScript(BRIDGE_JS)` + 启动消息补发 | T-M1-04/T-M0-06 | 页面就绪后 `window.WebViewJavascriptBridge` 可用 | 0.5 | 桥 |
+| **T-M1-06** | 最小回显 H5 | 测试用 H5（`registerHandler('echo')`、`callHandler('getTime')`）+ 一个挂桥的最小测试页 | T-M1-04 | 真机：H5↔原生双向回显成功 | 1 | 桥/Q |
+| **T-M1-07 ⚠** | **阻塞性验证 V1** | 真机验证 `yy://` 的 iframe 导航被 `onLoadIntercept` 捕获；产出结论报告 | T-M1-06 | V1 通过；若不通过，按 [00 §5](./00_总体规划.md) 回退方案并更新设计 | 1 | 桥/技术负责人 |
+| **T-M1-08** | 桥引擎单测 | `BridgeController`/`MessageCodec`/`HandlerRegistry` 单测套件 | T-M1-04 | 覆盖率 ≥80%（框架 §13） | 1.5 | 桥/Q |
+
+> **M1 出口**：T-M1-06 跑通 + **T-M1-07（V1）通过** + T-M1-08 达标。
+
+---
+
+## M2 · 容器 + 启动 + 资源（轨道 A 容器 / 轨道 B 平台领域）
+
+### 平台层（轨道 B，可与 M1 并行起步）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M2-01** | 存储/文件 | `KvStore`(@ohos.data.preferences)、`FileSystem`(@ohos.file.fs) | T-M0-01 | 读写 `urlpath`/`upurlpath`；文件增删查 | 1 | 台 |
+| **T-M2-02** | 网络/下载 | `HttpClient`(@ohos.net.http 或 rcp)、`Downloader`（断点可选、进度回调） | T-M0-01 | GET 禁缓存；大文件下载带进度 | 1.5 | 台 |
+| **T-M2-03** | 解压/并发 | `Unzipper`(@ohos.zlib decompressFile)、`TaskScheduler`(TaskPool/Worker) **仅传 Sendable + emitter 进度**（§9.1） | T-M0-01 | zip 解压成功；解压在子线程、UI 不阻塞 | 1.5 | 台 |
+| **T-M2-04** | 权限/上传服务 | `PermissionGuard`（存储/电话/定位/相机/麦克风 用时申请）；`LocalUploadServer`（socket/NAPI 本机端口服务，截图上传用） | T-M0-01 | 权限流程合规；本机端口可访问 | 1.5 | 台 |
+
+### 配置/资源/启动（轨道 B）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M2-05** | 本地+远程配置 | `ConfigManager`：内置 `rawfile/app_config.json`（§4.2 全键）；远程配置请求（`http://gameconfig 去-换/ .txt?a=ts`，禁缓存）；`showmessage` 阻断、<30 错误文案 | T-M2-02 | 配置键齐全；远程 JSON 正确解析、阻断逻辑生效 | 2 | 台 |
+| **T-M2-06** | 分层覆盖 | `VersionResolver`：`agentlist`/`gamelist` 两棵树 + 二级 `url` 二次请求 + agent→channel→market→game **后层覆盖**（纯函数） | T-M2-05 | 单测：多层样例覆盖结果正确（《契约规范》§4.4） | 2 | 台 |
+| **T-M2-07** | 资源管理 | `ResourceManager`：路径规范、内置包拷贝+解压、`version.xml` 解析(@ohos.xml)、远程 zip 下载/删旧/解压、版本比较 | T-M2-03/06 | 首启拷贝、版本更新下载解压到正确目录（§5） | 2 | 台 |
+| **T-M2-08 ⚠** | **阻塞性验证 V2** | 真机验证 `file://` 大厅页 XHR/fetch 取本地资源；结论报告 | T-M2-07 + T-M2-10 | V2 通过；否则启用 §7.3 自定义协议方案并更新设计 | 1 | 台/桥 |
+| **T-M2-09** | app_data 注入 | `AppDataInjector`：加载前写 `<urlpath>/gamehall/app_data.js`（§6 全局变量同名同义） | T-M2-07 | H5 加载时能读到 `app_*` 变量；**时序在加载前**（§7.1 铁律） | 1 | 台 |
+| **T-M2-11** | 启动状态机 | `StartupOrchestrator`：INIT→…→ENTER_HALL；可重试/降级/阻断 | T-M2-05/07/09 | 真机按序走通；失败降级本地缓存 | 1.5 | 台 |
+
+### 容器（轨道 A）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M2-13** | **能力插件框架骨架** | `feature_capabilities`：`CapabilityProvider` 接口、`CapabilityContext`、注册表对接桥、组装根 `buildCapabilities()`/`AppModule`（DI 装配）、Provider 样板（框架 §6.1/§6.2） | T-M1-04、T-M0-05 | 一个示例 Provider 可注册并被桥分发；组装根可批量装配 | 1 | 桥 |
+| **T-M2-10** | 大厅/子游戏容器 | `BridgeGameContainer`：`Web` + 属性（JS/DOM/file/mixed/cache/geo/zoom）+ 生命周期接桥（`onControllerAttached` 注册能力、`onLoadIntercept` 接桥、`onPageEnd` 注桥）+ **首次进度 100% 推 `appservice`/`setPostUrl`** + `SwitchOverGameData` 同容器 `loadUrl` 切换 + `aboutToDisappear` 清理 | T-M1-08、T-M2-13、T-M0-07 | 入口 URL 规则正确（`weburl` 空→file://，非空→http://，带 `?Launchtype=0`） | 2 | 桥 |
+| **T-M2-12** | 集成联调 | 大厅 H5 真机加载 + 进子游戏 | T-M2-08/10/11 | 现有大厅 `index.html` 正常显示、可进子游戏 | 1 | 桥/Q |
+
+> **M2 出口**：T-M2-12 跑通 + **T-M2-08（V2）通过**。
+> **注**：`T-M2-13` 能力插件框架骨架是 **M3 全部 Provider 与 T-M2-10 容器注册能力的前置依赖**，须先于铺开能力完成。
+
+---
+
+## M3 · 本期能力（轨道 C，各 Provider 高度并行）
+
+> **前置依赖**：M3 全部 Provider 均依赖 `T-M2-13`（能力插件框架骨架）+ `T-M2-10`（容器可加载）+ `T-M0-04`（契约类型）。这三者就绪后，各 Provider 之间**互不依赖、可多人并行**。
+> 通用验收（每个 Provider）：入站 handler 名/参数解析、出站 handler 名/data 结构/时机**逐条对照《契约规范》§8/§9/§12**；异步回传经 UI 线程守卫；真机录用例。
+
+| ID | Provider | 入站 handler | 出站 handler | 关键实现/SDK | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M3-01** | `AppSystemProvider` | `orientation`、`browser`、`finsh`、`openApplyDownloadpath`、`notification`(空) | — | 屏幕方向、拉起浏览器、退出、按包名启动/下载兜底 | 1.5 | 能 |
+| **T-M3-02** | `DeviceProvider` | `getTime`、`getphonestate`、`getbattery`、`getwifiLevel`、`getcompareCode`、`getphoneInfo`、`getmarketname`、`getothername`、`getOther` | `getBattery`、`getwifiLevel`、`phonestate` | deviceInfo/telephony/batteryInfo/wifiManager；裸串 vs JSON 严格区分 | 2.5 | 能 |
+| **T-M3-03** | `NetworkProvider` | `getnetwork` | `getnetwork`(广播变化) | NetworkKit 监听 | 1 | 能 |
+| **T-M3-04** | `VibrateProvider` | `vibrator`、`repeatvibrator`、`canclevibrator` | — | @ohos.vibrator | 0.5 | 能 |
+| **T-M3-05** | `ClipboardProvider` | `gameCopytext`、`gamepastetext` | —（gamepastetext 同步返回串） | @ohos.pasteboard | 0.5 | 能 |
+| **T-M3-06** | `NavProvider` | `OpenurlTitleData`、`SwitchOverGameData`、`getGameinstall`(同步 0/1)、`backgameData` | `getWebdata` | 打开通用容器(M4)、同容器切换、目录判断 | 1.5 | 能/桥 |
+| **T-M3-07** | `PhotoProvider` | `getphoto` | `getphoto`(下载完成数组) | 批量下载图片到本地 + Downloader | 1.5 | 能 |
+| **T-M3-08** | `ShakeProvider` | `startshake`、`SwitchShake`、`stopshake` | `shakeEnd`(空串，触发后~1s) | @ohos.sensor 加速度 + 节流；声音可选 | 1.5 | 能 |
+| **T-M3-09** | `LocationProvider` | `startlocation`(1连续/否单次)、`getlocationinfo`(同步) | `getlocationinfo`(MaplocationInfo/错误码) | geoLocationManager；**隐私合规初始化**；错误码 0/-1/-2 | 2 | 能 |
+| **T-M3-10** | `AudioProvider` | `prepareaudio`(录音)、`mediaTypeAudio`、`srcIsloop`、`voicePlaying` | `getaudiourl`(`{audiourl,time}`)、`gameui_play_voice`、`gameui_stop_voice` | AVPlayer/SoundPool；录音上传(七牛等)；wav 路径拼接 | 3 | 能 |
+| **T-M3-11** | `ScanProvider` | `opensaoma` | `getsaomaData` | Scan Kit | 1 | 能 |
+| **T-M3-12** | `CameraProvider` | `opencamera` | `getcameraaAddress` | Camera Picker | 1 | 能 |
+| **T-M3-13** | `ShareProvider` | `friendsSharetypeUrlToptitleDescript` | `sharesuccess`(仅微信) | 微信分享 SDK；`type==2` 截图：`runJavaScript(canvas.toDataURL)` + LocalUploadServer | 2.5 | 能 |
+| **T-M3-14** | `LoginProvider` | `accreditlogin` | `sharelogin`(用户资料) | 微信登录；**建议 code 模式**（密钥下沉） | 2 | 能 |
+| **T-M3-15** | `RoomStubProvider`/`PayStubProvider` | `createRoom`/`exitRoom`/`getVideoinfo`/`DragViewvideoIsshow`；`paybrowser`/`getGameplay` | —（不触发） | **占位桩**：空实现 + 日志（§6.5） | 0.5 | 能 |
+| **T-M3-16** | 前后台联动 | — | `appservice`('1'/'2') | `UIAbility.onForeground/onBackground` → callHandler | 0.5 | 桥 |
+| **T-M3-17** | 契约一致性回归 | 全 44 入站 + 全出站真机逐条核对 | — | 对照《契约规范》§8/§9，出回归报告 | 2 | Q |
+
+> **M3 出口**：本期能力真机逐条通过；**视频房/支付桩被调用不报错不卡死**（T-M3-17 含此项）。
+
+---
+
+## M4 · 通用网页容器（轨道 A，可与 M3 尾段并行）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M4-01** | 通用容器 | `GenericWebContainer`：`Web` + cacheMode(有网 Default/无网 Only) + `javaScriptProxy` 注入 `settings` | T-M2-10 | 打开任意 url、属性正确 | 1.5 | 桥 |
+| **T-M4-02** | settings 注入 + 直调 | `SettingsProxy` 6 方法（`backgameData`/`loadurl`/`browser`/`finishweb`/`isexitdialogeshow`/`isbackfinishweb`）+ 3 个 `runJavaScript` 直调（`getWebdata`/`gamebackkeydown`/`backgameData`） | T-M4-01 | 逐一对照《契约规范》§11.3 | 1.5 | 桥 |
+| **T-M4-03** | 回传与返回键 | 101 结果经 router/emitter 回上层 → 上层 `callHandler('getWebdata')`；返回键逻辑（isbackfinishweb/isexitdialogeshow） | T-M4-02 | 活动页/收银台/客服打开、回传、返回正常 | 1 | 桥 |
+
+---
+
+## M5 · 性能与加固（轨道 D，部分贯穿 M3/M4）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M5-01** | Web 保活/预热 | `NodeController`+`BuilderNode` 离屏预创建/保活；启动期预热空 Web | T-M2-10 | 子游戏切换 <300ms、无白屏 | 2 | 桥 |
+| **T-M5-02** | 切换与桥重绑 | 子游戏切换走 `loadUrl` 复用；切换后桥/handler 重绑时序正确 | T-M5-01 | 切换后桥功能正常 | 1 | 桥 |
+| **T-M5-03** | 高频节流/批处理 | 定位/电量等高频 handler 节流；出站批处理 | T-M3-* | 跨引擎调用次数下降、无卡顿 | 1 | 桥 |
+| **T-M5-04** | 崩溃兜底/内存 | `onRenderExited` 重载；`aboutToDisappear` 彻底清理 | T-M2-10 | 渲染子进程崩溃可自恢复 | 1 | 桥 |
+| **T-M5-05** | 安全加固 | WebDebug 按 `isDebug` 守卫；密钥下沉服务端；明文 HTTP 域名白名单；file 跨域最小授权；自定义 scheme 注册(module.json5)；日志脱敏 | 各能力就绪 | 安全审查清单（附录 B）全过 | 2 | 桥/台 |
+| **T-M5-06** | 可观测 | `BridgeTracer` 全链路 traceId；接 APM/Crash | T-M0-05 | 能还原一条桥消息全链路 | 1 | 台 |
+| **T-M5-07** | 冷启动优化 | StartupOrchestrator 无依赖步骤并行化 | T-M2-11 | 冷启动到首帧达标（<2s 基线） | 1 | 台 |
+| **T-M5-08** | 包体/渠道裁剪（可选） | 能力 Provider 按渠道用 HSP 动态特性裁剪；包体瘦身（框架 §9 包体） | T-M3-* | 不同渠道包仅含所需能力，包体下降 | 1 | 桥/台 |
+
+---
+
+## M6 · 暂缓能力集成（按需，可延后）
+
+| ID | 目标 | 产出物 | 依赖 | 验收 | 估时 | 角色 |
+|---|---|---|---|---|---|---|
+| **T-M6-01** | 视频房真实 | `RoomProvider`（声网 RTC HarmonyOS SDK）替换桩 | M3 完成 | `createRoom/exitRoom/getVideoinfo/DragViewvideoIsshow` + 出站 `getVideoinfo` 真打通；H5 零改动 | 视 SDK | 能 |
+| **T-M6-02** | 支付真实 | `PayProvider`（浏览器收银台/或 App 内支付）替换桩；如启用 App 内支付则补 `PayuserPaytypePaystate` | M3 完成 | 支付闭环；H5 零改动 | 视 SDK | 能 |
+| **T-M6-03** | 补齐项（可选） | 抖音/快手登录(code)、主动截图 `getCanvasBase64`、QQ/抖音分享回传统一 | 按需 | 对照框架 §6.4 | 视需求 | 能 |
+
+---
+
+## 任务总数与估时汇总
+
+| 里程碑 | 任务数 | 估时(pd) |
+|---|---|---|
+| M0 | 7 | 7 |
+| M1 | 8 | 9 |
+| M2 | 13 | 19 |
+| M3 | 17 | 24.5 |
+| M4 | 3 | 4 |
+| M5 | 8 | 10 |
+| **合计(M0–M5)** | **56** | **≈73.5 pd（含测试/缓冲）** |
+| M6 | 3 | 视集成 |
+
+> 估时为"工作量"非"日历"。3 人并行、关键路径串行下，日历周期约 5–7 周（见 [00 §1](./00_总体规划.md)）。
+
+---
+
+## 附：框架设计 → 计划覆盖矩阵（完整性自检）
+
+> 逐条证明《框架设计与开发指南》每个章节都有计划任务承接，**无遗漏**。
+
+| 框架章节 | 计划任务 | 状态 |
+|---|---|---|
+| §1 设计原则 | 贯穿 DoD（[00 §7](./00_总体规划.md)）与代码规范（00 §6） | ✓ 原则类，非任务 |
+| §2 能力映射总表 | 各能力/桥任务的实现依据（引用表） | ✓ 参考 |
+| §3 分层架构 / §4 工程结构 | T-M0-01/02（建 entry+6 HAR）、**T-M0-07**（EntryAbility/路由/Splash） | ✓ |
+| §5.1–5.2 桥协议/控制器 | T-M1-02/03/04/05 | ✓ |
+| §5.3 同步/异步 | T-M1-04 + 各 Provider | ✓ |
+| §5.4 裸串vsJSON | T-M0-04（payloadType） | ✓ |
+| §5.5 线程模型 | T-M1-04（UI 守卫） | ✓ |
+| §5.6 IWebController | T-M1-01 | ✓ |
+| §6.1/6.2 插件框架/组装根/DI | **T-M2-13**（能力插件框架骨架） | ✓ 已补 |
+| §6.3 Provider 样板/截图分享 | T-M3-09(样板)、T-M3-13(分享截图) | ✓ |
+| §6.4 补齐项 | T-M6-03 | ✓ |
+| §6.5 占位桩 | T-M3-15 | ✓ |
+| §7.1 大厅/子游戏容器 | T-M2-10 | ✓ |
+| §7.2 通用网页容器 | T-M4-01/02/03 | ✓ |
+| §7.3 file:// 跨域 | T-M2-08（V2 阻塞验证） | ✓ |
+| §8.1 启动状态机 | T-M2-11 | ✓ |
+| §8.2 ConfigManager | T-M2-05 | ✓ |
+| §8.2 分层覆盖 | T-M2-06（VersionResolver） | ✓ |
+| §8.3 ResourceManager | T-M2-07 | ✓ |
+| §8.4 AppDataInjector | T-M2-09 | ✓ |
+| §9 性能（保活/并发/批处理/就绪渲染/内存/冷启动） | T-M5-01/02/03/04/07、T-M2-03 | ✓ |
+| §9 包体/HSP 裁剪 | **T-M5-08** | ✓ 已补 |
+| §9.1 TaskPool Sendable | T-M2-03 | ✓ |
+| §10 契约类型 SSOT | T-M0-04 | ✓ |
+| §10 日志/追踪 | T-M0-05（Tracer）、T-M5-06 | ✓ |
+| §10 ErrorCenter | **T-M0-05**（已含 ErrorCenter） | ✓ 已补 |
+| §10 事件总线/DI | T-M0-05 | ✓ |
+| §10 权限 | T-M2-04（PermissionGuard） | ✓ |
+| §10 安全 | T-M5-05 | ✓ |
+| §10 可测试 | T-M1-01/08 + 各单测 | ✓ |
+| §11 可追溯矩阵 | [02 测试与验收 §4](./02_测试与验收计划.md) 契约核对清单 + 本矩阵 | ✓ |
+| §12 路线图 M0–M6 | 本 WBS 全部里程碑 | ✓ |
+| §13 验收标准 | [02 测试与验收计划](./02_测试与验收计划.md) | ✓ |
+| 附录 A ArkTS/ArkUI 适配 | 贯穿 DoD（[00 §7](./00_总体规划.md) 已引用 §5.5/§9.1）+ T-M0-07/T-M2-10 落地 | ✓ |
+| 附录 B 生产加固合规 | T-M5-05（逐项）+ [02 §5 M5 Gate](./02_测试与验收计划.md) | ✓ |
+
+> **结论**：框架设计指南全部章节均有计划任务承接，覆盖完整。本次自检新增 `T-M0-07`、`T-M2-13`、`T-M5-08` 及 `T-M0-05` 的 ErrorCenter，补齐了能力插件框架骨架、入口/路由壳、ErrorCenter、包体裁剪四处缺口。

docs/设计文档/Plan/02_测试与验收计划.md

@@ -0,0 +1,88 @@
+# 02 · 测试与验收计划
+
+> 唯一判据：**现有 H5 零改动运行**，且行为与《契约规范》§8/§9/§11 完全一致。
+
+## 1. 测试层次
+
+| 层次 | 对象 | 手段 | 何时 |
+|---|---|---|---|
+| **单元测试** | 纯逻辑：`MessageCodec`、`HandlerRegistry`、`VersionResolver`、`ConfigManager` 解析、各 DTO 序列化 | ArkTS 单测 + `FakeWebController` | 随开发，CI 强制 |
+| **桥协议测试** | `BridgeController` 全路径 | FakeWebController 模拟 H5 收发 | M1 |
+| **集成测试** | 容器 + 启动 + 资源 + 配置 | 真机/模拟器 | M2 起 |
+| **契约一致性测试** | 全 44 入站 + 全出站 handler | 真机 + 测试 H5 探针 | M3 起每周回归 |
+| **端到端（E2E）** | 真实大厅 H5 + 子游戏 + 活动页 | 真机手测 + 录屏 | M3/M4 |
+| **性能测试** | 冷启动、子游戏切换、内存 | DevEco Profiler / hilog 打点 | M5 |
+| **安全测试** | 加固清单 | 人工审查 + 工具 | M5 |
+
+## 2. 关键测试资产
+
+### 2.1 最小回显 H5（M1 必备）
+一个独立测试页，仅用桥 API：
+- `registerHandler('echo', (d,cb)=>cb(d))`、`callHandler('getTime')`、`callHandler('echo','hi')`。
+- 验证：H5→原生→回执、原生→H5→回执、启动前积压消息补发、`yy://` 拦截（V1）。
+
+### 2.2 契约探针 H5（M3 回归）
+一个覆盖**全部 44 入站 handler**的探针页：逐个 `callHandler` 并记录回传，与《契约规范》期望值比对，输出"通过/差异"报告。出站 handler 用 `registerHandler` 全量挂载、记录原生推送。
+> 此页是"H5 零改动"的自动化守门员，纳入每周回归。
+
+## 3. 两个阻塞性验证（最高优先，决定技术路线）
+
+| 验证 | 用例 | 通过判据 | 不通过 → 动作 |
+|---|---|---|---|
+| **V1 `yy://` 拦截**（M1, T-M1-07） | 最小 H5 设 `iframe.src='yy://__queue__'`，原生 `onLoadIntercept` 取 URL | 能拿到 `yy://` URL 并拦截、`_fetchQueue` 回执经 `yy://return/` 到达 | 切 `onInterceptRequest`+`WebSchemeHandler`；或改桥 JS 走 `javaScriptProxy.postMessage`（[00 §5](./00_总体规划.md)） |
+| **V2 `file://` 跨域**（M2, T-M2-08） | 现有大厅 `index.html` 以 `file://` 加载，请求本地 js/css/图片/`app_data.js` | 资源全部正常加载、H5 正常运行 | 启用自定义协议/`onInterceptRequest` 接管本地资源（框架 §7.3） |
+
+> 这两项必须在对应里程碑**作为 Exit Gate 强制通过**。
+
+## 4. 契约一致性核对清单（H5 零改动判据）
+
+### 4.1 桥协议（§2）
+- [ ] `window.WebViewJavascriptBridge` 注入后 API 与事件 `WebViewJavascriptBridgeReady` 一致
+- [ ] `registerHandler`/`callHandler` 双向、回执、`callbackId`/`responseId` 路由正确
+- [ ] `_fetchQueue` 经 `yy://return/` 回传（非 runJavaScript 返回值）
+- [ ] 启动前积压消息在注桥后补发
+
+### 4.2 入站 44 handler（§8）—— 逐条核对名称/参数/同步返回
+- [ ] 账号社交：`accreditlogin`、`friendsSharetypeUrlToptitleDescript`、`getphoto`
+- [ ] 支付：`paybrowser`、`getGameplay`（**本期桩，验"不报错不卡死"**）
+- [ ] 设备信息：`getTime`、`getphonestate`、`getbattery`、`getwifiLevel`、`getnetwork`、`getcompareCode`、`getphoneInfo`、`getmarketname`、`getothername`、`getOther`
+- [ ] 交互：`orientation`、`vibrator`、`repeatvibrator`、`canclevibrator`、`gameCopytext`、`gamepastetext`、`notification`(空)
+- [ ] 摇一摇：`startshake`、`SwitchShake`、`stopshake`
+- [ ] 定位：`startlocation`、`getlocationinfo`
+- [ ] 音频：`prepareaudio`、`mediaTypeAudio`、`srcIsloop`、`voicePlaying`
+- [ ] 扫码/相机/浏览器/网页：`opensaoma`、`opencamera`、`browser`、`OpenurlTitleData`、`openApplyDownloadpath`
+- [ ] 子游戏/房间：`SwitchOverGameData`、`getGameinstall`、`createRoom`、`exitRoom`、`getVideoinfo`、`DragViewvideoIsshow`（**房间本期桩**）
+- [ ] 退出/返回：`finsh`、`backgameData`
+
+### 4.3 出站 handler（§9）—— 逐条核对名称/data 结构/时机
+- [ ] `appservice`(1/2)、`setPostUrl`、`getWebdata`、`getphoto`、`sharelogin`、`sharesuccess`、`shakeEnd`、`getBattery`、`getwifiLevel`、`getnetwork`、`getaudiourl`(+`filepath`)、`gameui_play_voice`、`gameui_stop_voice`、`getphoneinfo`、`getVideoinfo`(桩不推)、`PayuserPaytypePaystate`(桩不推)、`getlocationinfo`、`phonestate`、`getsaomaData`、`getcameraaAddress`
+- [ ] 名称陷阱：`backgameData-`（带连字符）≠ 入站 `backgameData`
+
+### 4.4 数据结构（§12）
+- [ ] `sharetypeBean`/`MaplocationInfo`/`phoneInfoBean`/`savephotoURLBean`/`videoinfobean`/`Othervideoinfo`/支付/`sharelogin`/`sharesuccess` 字段名同名同义
+
+### 4.5 启动/资源/容器（§3–§7、§11）
+- [ ] 配置键齐全、远程配置分层覆盖、`showmessage` 阻断
+- [ ] 资源路径、version.xml 版本比较、zip 下载解压
+- [ ] `app_data.js` 全局变量、**加载前注入**
+- [ ] 入口 URL（`weburl` 空/非空）、`?Launchtype=` 参数
+- [ ] 通用网页容器 `settings` 6 法 + 3 直调 + 101 回传
+
+## 5. 里程碑验收 Gate
+
+| 里程碑 | Gate |
+|---|---|
+| M0 | 工程编译/签名/CI 通过；`contracts` 全量类型对照契约零缺漏 |
+| **M1** | 回显 H5 双向通；**V1 通过**；桥单测 ≥80% |
+| **M2** | 真机加载大厅 H5、进子游戏；**V2 通过**；app_data.js 时序正确 |
+| M3 | §4.2/§4.3/§4.4 清单全过；**桩能力不报错不卡死** |
+| M4 | §11.3 通用容器一致；活动页/收银台/客服打开回传正常 |
+| M5 | 切换 <300ms、冷启动 <2s（基线）；安全清单（附录 B）全过；可观测可用 |
+| **本期总验收** | 现有大厅 + 全部子游戏 + 网页页面**零改动运行**；§4 全清单通过 |
+
+## 6. 缺陷分级与回归
+
+- **P0**：H5 无法运行/桥不通/崩溃 → 当日修复，阻塞合入。
+- **P1**：某 handler 行为不符契约 → 当迭代修复。
+- **P2**：性能/体验 → M5 收口。
+- 每次合入触发"契约探针 H5"回归，防止已通过的 handler 退化。

docs/设计文档/Plan/03_风险登记册.md

@@ -0,0 +1,47 @@
+# 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 |
+
+## 4. 受阻任务记录（动态更新）
+
+| 日期 | 受阻任务 | 关联风险 | 描述 | 处置 | 状态 |
+|---|---|---|---|---|---|
+| — | — | — | （执行期间填写） | — | — |
+
+## 5. 风险闸门（与里程碑绑定）
+
+- **M1 闸门**：R-01 必须收敛（V1 通过或回退方案落地）方可进入 M2。
+- **M2 闸门**：R-02 必须收敛（V2 通过或回退方案落地）方可大规模铺 M3 能力。
+- **M5 闸门**：R-04/R-07 收敛 + 安全清单（框架附录 B）通过方可发布。

docs/设计文档/Plan/README.md

@@ -0,0 +1,32 @@
+# TSGame HarmonyOS 开发计划（Plan）
+
+> 本目录是《[TSGame_HarmonyOS框架设计与开发指南](../TSGame_HarmonyOS框架设计与开发指南.md)》的**落地实施计划**，把"设计"拆解为"可执行、可验收、可追踪"的任务。
+>
+> 上游依据（单一事实来源 SSOT）：
+> - 《[TSGame_原生与H5接口契约总规范](../TSGame_原生与H5接口契约总规范.md)》—— 对外不可变契约（H5 零改动的判据）
+> - 《[TSGame_HarmonyOS框架设计与开发指南](../TSGame_HarmonyOS框架设计与开发指南.md)》—— HarmonyOS 侧如何实现
+
+## 文档导航
+
+| 文件 | 内容 | 读者 |
+|---|---|---|
+| [00_总体规划.md](./00_总体规划.md) | 里程碑、关键路径、依赖 DAG、并行轨道、角色分工、环境/分支、DoD、进度机制 | 全员 / PM |
+| [01_任务分解WBS.md](./01_任务分解WBS.md) | **核心**：按里程碑的全量任务（ID/目标/产出/依赖/验收/估时/角色） | 开发 |
+| [02_测试与验收计划.md](./02_测试与验收计划.md) | 测试策略、回显 H5、两个阻塞性验证、契约一致性回归、里程碑验收 Gate | 开发 / QA |
+| [03_风险登记册.md](./03_风险登记册.md) | 风险、概率/影响、缓解、触发条件、负责人 | PM / 技术负责人 |
+
+## 一页速览（TL;DR）
+
+- **目标**：在 HarmonyOS 上实现原生外壳，使现有 H5（大厅 + 全部子游戏 + 活动/收银台等网页）**一行不改**即可运行。
+- **本期范围**：桥引擎、双容器、启动/配置/资源、本期全部设备能力。**视频房、支付用占位桩**（不报错/不卡死），**闲聊不涉及**。真实视频房/支付列入 M6 按需集成。
+- **最高优先 & 最大风险**：M1 桥引擎，以及两个"阻塞性验证"——`yy://` 拦截（M1）、`file://` 跨域（M2）。这两点必须**最先证伪**，决定整体可行性。
+- **关键路径**：M0 → M1 → M2 →（M3 能力并行）→ M4 → M5。M6 可延后。
+- **判据**：以《契约规范》§8/§9/§11 的 handler 名、参数、数据结构、调用时机为唯一验收标准。
+
+## 任务 ID 规范
+
+`T-M{里程碑}-{序号}`，例：`T-M1-04` = 里程碑 M1 的第 4 个任务。跨文档引用任务用此 ID。
+
+## 状态约定
+
+`☐ 未开始` · `◐ 进行中` · `☑ 完成` · `⚠ 受阻`（受阻须在 [03_风险登记册](./03_风险登记册.md) 记录）。