整理中文文档结构与索引
This commit is contained in:
382
doc/experience/原生与H5桥接规范.md
Normal file
382
doc/experience/原生与H5桥接规范.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 原生与 H5 Bridge 协议草案
|
||||
|
||||
本文档定义当前项目中 **原生小程序** 与 **H5 定制内容页** 之间的基础通信协议。
|
||||
|
||||
目标：
|
||||
|
||||
- 让 H5 能获取当前游戏上下文
|
||||
- 让 H5 能请求原生能力
|
||||
- 让原生能接收 H5 的结果回传
|
||||
- 保持协议简单、稳定、可版本化
|
||||
- 为后续拍照、录音、小游戏、结果页等扩展留出空间
|
||||
|
||||
---
|
||||
|
||||
## 0. 当前适用前提
|
||||
|
||||
本规范当前属于：
|
||||
|
||||
- 协议与实现预留
|
||||
- 容器与回退机制先行
|
||||
|
||||
最近排查已经确认，当前最初使用的是**个人主体**小程序。
|
||||
在这个前提下，`web-view` 能力本身可能受限。
|
||||
|
||||
因此：
|
||||
|
||||
- Bridge 规范仍然应该先定义
|
||||
- 容器页与回退机制也应该先实现
|
||||
- 但在企业主体审核通过前，不应把 H5 接入是否成功完全归因于 bridge 代码本身
|
||||
|
||||
详细说明见：
|
||||
|
||||
- [platform-capability-notes.md](D:/dev/cmr-mini/doc/debug/平台能力说明.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 协议原则
|
||||
|
||||
### 原则 1：Bridge 要版本化
|
||||
|
||||
建议先固定：
|
||||
|
||||
- `content-v1`
|
||||
- `result-v1`
|
||||
|
||||
后续升级时：
|
||||
|
||||
- 新增 `content-v2`
|
||||
- 新增 `result-v2`
|
||||
|
||||
不要直接改旧协议。
|
||||
|
||||
### 原则 2：请求能力最小化
|
||||
|
||||
先只开放真正需要的能力，不要一开始做成“大而全总线”。
|
||||
|
||||
### 原则 3：原生控制核心状态
|
||||
|
||||
Bridge 只能做：
|
||||
|
||||
- 展示
|
||||
- 上报
|
||||
- 请求能力
|
||||
|
||||
不能让 H5 直接改比赛核心状态。
|
||||
|
||||
### 原则 4：消息必须可回执
|
||||
|
||||
每个请求都应有明确成功/失败返回，不允许 H5 靠超时猜测。
|
||||
|
||||
---
|
||||
|
||||
## 2. 通道模型
|
||||
|
||||
建议统一按“请求 / 响应 / 事件”三类消息组织：
|
||||
|
||||
- `request`
|
||||
H5 请求原生能力
|
||||
- `response`
|
||||
原生返回能力执行结果
|
||||
- `event`
|
||||
原生主动推送状态变化
|
||||
|
||||
推荐消息外壳：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "req-001",
|
||||
"channel": "request",
|
||||
"type": "getGameContext",
|
||||
"payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "req-001",
|
||||
"channel": "response",
|
||||
"type": "getGameContext",
|
||||
"ok": true,
|
||||
"payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 原生注入给 H5 的基础上下文
|
||||
|
||||
建议至少包含：
|
||||
|
||||
```json
|
||||
{
|
||||
"bridgeVersion": "content-v1",
|
||||
"eventId": "sample-score-o-001",
|
||||
"mode": "score-o",
|
||||
"sessionId": "session-001",
|
||||
"sessionStatus": "running",
|
||||
"controlId": "control-3",
|
||||
"controlKind": "control",
|
||||
"title": "湖边步道",
|
||||
"body": "这里适合短暂停留观察周边地形。",
|
||||
"theme": "default-race"
|
||||
}
|
||||
```
|
||||
|
||||
对于结果页，可扩展为：
|
||||
|
||||
```json
|
||||
{
|
||||
"bridgeVersion": "result-v1",
|
||||
"eventId": "sample-score-o-001",
|
||||
"mode": "score-o",
|
||||
"sessionId": "session-001",
|
||||
"summary": {
|
||||
"title": "比赛结束",
|
||||
"heroValue": "120",
|
||||
"rows": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. H5 -> 原生：第一阶段推荐动作
|
||||
|
||||
建议第一阶段只支持这几个：
|
||||
|
||||
### `close`
|
||||
|
||||
作用：
|
||||
|
||||
- 关闭当前 H5 页面
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "req-001",
|
||||
"channel": "request",
|
||||
"type": "close",
|
||||
"payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
### `getGameContext`
|
||||
|
||||
作用：
|
||||
|
||||
- 让 H5 主动获取最新上下文
|
||||
|
||||
### `takePhoto`
|
||||
|
||||
作用：
|
||||
|
||||
- 请求原生拍照
|
||||
|
||||
### `recordAudio`
|
||||
|
||||
作用：
|
||||
|
||||
- 请求原生录音
|
||||
|
||||
### `submitResult`
|
||||
|
||||
作用：
|
||||
|
||||
- 把 H5 内的任务结果、表单或作品结果提交回原生
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "req-002",
|
||||
"channel": "request",
|
||||
"type": "submitResult",
|
||||
"payload": {
|
||||
"taskId": "photo-task-1",
|
||||
"status": "completed",
|
||||
"assetId": "img-001"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议第二阶段可扩展动作
|
||||
|
||||
等第一阶段跑稳后，再逐步加入：
|
||||
|
||||
- `uploadImage`
|
||||
- `uploadAudio`
|
||||
- `getLocation`
|
||||
- `openMiniGame`
|
||||
- `submitForm`
|
||||
- `share`
|
||||
- `restartSession`
|
||||
|
||||
这些先不要第一阶段全开。
|
||||
|
||||
---
|
||||
|
||||
## 6. 原生 -> H5：统一返回结构
|
||||
|
||||
建议统一返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "req-002",
|
||||
"channel": "response",
|
||||
"type": "takePhoto",
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"assetId": "img-001",
|
||||
"url": "https://example.com/assets/img-001.jpg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
失败时：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "req-002",
|
||||
"channel": "response",
|
||||
"type": "takePhoto",
|
||||
"ok": false,
|
||||
"error": {
|
||||
"code": "USER_CANCELLED",
|
||||
"message": "用户取消拍照"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 原生 -> H5：推荐事件
|
||||
|
||||
原生可按需主动推送轻量事件：
|
||||
|
||||
- `contextUpdated`
|
||||
- `sessionFinished`
|
||||
- `sessionExited`
|
||||
- `networkChanged`
|
||||
|
||||
但第一阶段要克制，避免高频推送。
|
||||
|
||||
不建议第一阶段主动高频推：
|
||||
|
||||
- GPS 实时位置流
|
||||
- 指北针实时角度
|
||||
- HUD 高频数字
|
||||
|
||||
这些不适合让 H5 主导。
|
||||
|
||||
---
|
||||
|
||||
## 8. 错误码建议
|
||||
|
||||
建议第一阶段统一几类错误：
|
||||
|
||||
- `USER_CANCELLED`
|
||||
- `PERMISSION_DENIED`
|
||||
- `NETWORK_ERROR`
|
||||
- `UNSUPPORTED_ACTION`
|
||||
- `BRIDGE_NOT_READY`
|
||||
- `INTERNAL_ERROR`
|
||||
|
||||
这样 H5 侧更容易统一处理。
|
||||
|
||||
---
|
||||
|
||||
## 9. 安全与边界
|
||||
|
||||
### 9.1 H5 不直接改核心比赛状态
|
||||
|
||||
H5 不能直接决定：
|
||||
|
||||
- 是否打点成功
|
||||
- 是否跳点成功
|
||||
- 是否比赛结束
|
||||
|
||||
### 9.2 H5 只能请求能力
|
||||
|
||||
原生决定是否执行：
|
||||
|
||||
- 拍照
|
||||
- 录音
|
||||
- 上传
|
||||
- 页面关闭
|
||||
|
||||
### 9.3 Bridge 能力按页面类型开放
|
||||
|
||||
例如：
|
||||
|
||||
- 内容页开放 `takePhoto`
|
||||
- 结果页不一定开放
|
||||
|
||||
后续可做按 `bridgeVersion` 或 `pageType` 的能力白名单。
|
||||
|
||||
---
|
||||
|
||||
## 10. 第一阶段推荐支持范围
|
||||
|
||||
建议第一阶段只正式支持：
|
||||
|
||||
- `close`
|
||||
- `getGameContext`
|
||||
- `takePhoto`
|
||||
- `recordAudio`
|
||||
- `submitResult`
|
||||
|
||||
这样足够承接：
|
||||
|
||||
- 文创详情
|
||||
- 拍照任务
|
||||
- 语音留言
|
||||
- 结果页回传动作
|
||||
|
||||
---
|
||||
|
||||
## 11. 不建议第一阶段支持的内容
|
||||
|
||||
先不要一上来开放：
|
||||
|
||||
- 任意写比赛状态
|
||||
- 任意切换玩法
|
||||
- 任意修改地图行为
|
||||
- 任意控制打点
|
||||
- 高频实时 telemetry 推送
|
||||
|
||||
这些都属于核心状态，应该继续由原生掌控。
|
||||
|
||||
---
|
||||
|
||||
## 12. 当前建议实施顺序
|
||||
|
||||
1. 先实现一个通用 H5 容器页
|
||||
2. 先跑通 `content-v1`
|
||||
3. 先支持 5 个最小动作
|
||||
4. 再跑通一个简单结果页
|
||||
5. 最后再扩桥接能力
|
||||
|
||||
---
|
||||
|
||||
## 13. 当前建议结论
|
||||
|
||||
Bridge 的第一阶段目标，不是做成万能总线，而是：
|
||||
|
||||
**稳定承接定制内容页与结果页的最小需求。**
|
||||
|
||||
先把：
|
||||
|
||||
- 关闭
|
||||
- 获取上下文
|
||||
- 拍照
|
||||
- 录音
|
||||
- 结果提交
|
||||
|
||||
这 5 条做稳，就足够支撑第一波客户定制需求。
|
||||
|
||||
Reference in New Issue
Block a user