# 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 真机逐条核对"，防回归。
