统一 H5 宿主壳能力协议
新增 HostBridge 通用宿主能力服务与测试 迁移登录支付分享订阅入口到通用 HostBridge API 保留微信小程序旧接口兼容包装 补充宿主壳协议文档与项目记忆
This commit is contained in:
@@ -21,6 +21,8 @@
|
||||
|
||||
微信小程序虚拟支付接入、`wechat_mp_virtual` 渠道、`wx.requestVirtualPayment` 承接页和后端签名配置见 [【技术方案】微信虚拟支付接入-2026-05-26.md](./%E3%80%90%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88%E3%80%91%E5%BE%AE%E4%BF%A1%E8%99%9A%E6%8B%9F%E6%94%AF%E4%BB%98%E6%8E%A5%E5%85%A5-2026-05-26.md)。
|
||||
|
||||
微信小程序壳、未来原生 App 壳、固定内置玩法与 AI H5 沙箱之间的宿主能力边界见 [【前端架构】宿主壳能力统一协议-2026-06-17.md](./【前端架构】宿主壳能力统一协议-2026-06-17.md)。
|
||||
|
||||
本地通过 SSH alias 管理多台服务器、查看硬件 / systemd / HTTP 健康状态并执行受控服务启停的 egui 桌面工具见 [【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md](./technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md)。
|
||||
|
||||
生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
|
||||
|
||||
@@ -16,6 +16,14 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-17 H5 宿主壳能力统一走 HostBridge
|
||||
|
||||
- 背景：主站同时运行在普通浏览器、微信小程序 `web-view` 和未来可能出现的原生 App WebView 中；登录、支付、分享、订阅授权和运行态分享目标同步曾散落在业务组件与服务文件里，后续新增宿主壳会导致同一业务重复分叉。
|
||||
- 决策：前端宿主运行态识别、微信小程序 JS SDK 加载、原生页跳转、支付跳转、登录跳转、九宫切图和 `postMessage` 统一收口到 `src/services/host-bridge/hostBridge.ts`，业务层优先调用 `getHostRuntime`、`requestHostLogin`、`requestHostPayment`、`navigateHostNativePage`、`setHostShareTarget` 和 `openHostShareGrid`。`authService`、分享服务、订阅授权和个人中心充值可保留兼容导出或业务编排，但不再自行加载微信 JS SDK 或直接判断 `wx.miniProgram`。固定内置玩法不走代码包下载流程；AI 生成 H5 沙箱后续单独定义受限 `GameBridge`，不得直接暴露完整 `HostBridge`。
|
||||
- 影响范围：`src/services/host-bridge/`、`src/services/authService.ts`、`src/services/payment/paymentPlatform.ts`、`src/services/wechatMiniProgramShareGrid.ts`、`src/services/wechatMiniProgramShareTarget.ts`、`src/services/wechatMiniProgramSubscribe.ts`、`src/components/platform-entry/usePlatformProfileCenterController.ts`、微信小程序壳和未来原生 App 壳接入。
|
||||
- 验证方式：微信小程序首点登录仍打开原生登录页；小程序支付仍跳转 `/pages/wechat-pay/index` 并保留 hash 回灌确认；订阅授权仍跳转 `/pages/subscribe-message/index` 且返回不阻断生成；普通浏览器分享、H5 支付和 Native 二维码支付不受影响。前端验证运行 HostBridge、auth、payment、分享、订阅和个人中心充值相关定向测试，并执行 `npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`。
|
||||
|
||||
## 2026-06-15 SpacetimeDB 本地 skills 只保留 CLI / Concepts / Rust
|
||||
|
||||
- 背景：本仓库的 SpacetimeDB 接入已固定为 `server-rs + Axum + SpacetimeDB`，本地 skill 需要从上游 SpacetimeDB `skills/` 更新到 2.5 口径，同时避免继续维护当前项目不使用的 TypeScript server/client、C# 和 Unity 专用 skill。
|
||||
|
||||
68
docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
Normal file
68
docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# 宿主壳能力统一协议
|
||||
|
||||
更新时间：`2026-06-17`
|
||||
|
||||
## 背景
|
||||
|
||||
当前主站已经同时运行在普通浏览器、微信小程序 `web-view` 和后续可能出现的原生 App WebView 中。登录、支付、分享、订阅授权、运行态分享目标同步等能力散落在业务组件和服务文件里，后续如果新增原生 App 壳，容易出现同一业务按宿主重复分叉。
|
||||
|
||||
本方案先建立 `HostBridge` 宿主壳协议，把浏览器、微信小程序壳和未来原生 App 壳统一成能力 adapter。固定玩法运行态仍作为平台内置 runtime，AI 生成 H5 仍走独立 sandbox 和受限 GameBridge；二者都不能直接拿完整宿主壳能力。
|
||||
|
||||
## 目标
|
||||
|
||||
1. H5 业务层只判断宿主能力，不直接散落判断 `wx.miniProgram`、`MicroMessenger`、`clientRuntime`。
|
||||
2. 微信小程序壳先作为 `wechat_mini_program` adapter 接入，保留现有登录、支付、分享、订阅授权行为。
|
||||
3. 未来原生 App 壳只新增 `native_app` adapter，不重写 H5 业务。
|
||||
4. 固定玩法继续读取作品数据、素材、运行态 snapshot 和后端裁决结果，不走代码包下载流程。
|
||||
5. AI H5 sandbox 只能通过受限 GameBridge 请求资产、上报事件和提交候选结果，不暴露登录、支付、token、完整用户资料。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不重写 React 主站和现有玩法 runtime。
|
||||
- 不把固定玩法迁成远程代码包。
|
||||
- 不在本阶段实现 React Native / Expo 壳。
|
||||
- 不改变支付到账、任务、排行榜、发布、统计等后端裁决口径。
|
||||
|
||||
## 分层
|
||||
|
||||
```text
|
||||
H5 业务层
|
||||
-> HostBridge 能力接口
|
||||
-> browserHostBridge
|
||||
-> wechatMiniProgramHostBridge
|
||||
-> nativeAppHostBridge（预留）
|
||||
|
||||
AI H5 sandbox
|
||||
-> GameBridge 受限协议
|
||||
-> parent HostBridge adapter
|
||||
```
|
||||
|
||||
## 首批能力
|
||||
|
||||
- `getHostRuntime()`：识别 `browser`、`wechat_mini_program`、`native_app`。
|
||||
- `requestHostLogin()`：微信小程序跳转原生登录页；浏览器返回 `false`，由 H5 登录弹窗承接。
|
||||
- `requestHostPayment()`：微信小程序支付跳转原生支付页；其它渠道返回 `false`，继续走 H5 / Native 二维码。
|
||||
- `setHostShareTarget()`：把当前公开作品分享目标同步给宿主。
|
||||
- `openHostShareGrid()`：微信小程序九宫格切图页。
|
||||
- `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录等 adapter 复用。
|
||||
|
||||
## 迁移顺序
|
||||
|
||||
1. 新增 `src/services/host-bridge/`，沉淀宿主运行态识别和微信小程序 JS SDK 加载，并暴露通用 HostBridge 能力接口。
|
||||
2. `authService` 保留原导出，但内部委托 HostBridge，避免一次性改动 AuthGate。
|
||||
3. 分享弹窗、分享目标同步、九宫切图、微信小程序支付和订阅授权改用 HostBridge 通用接口；旧微信命名服务只作为兼容导出。
|
||||
4. 后续新增 `native_app` adapter 时只补桥接实现和测试，业务层不新增平台分叉。
|
||||
|
||||
## 验收
|
||||
|
||||
- 微信小程序首点登录仍能打开原生登录页。
|
||||
- 小程序分享链接仍生成 `/pages/web-view/index?targetPath=/works/detail&work=...`。
|
||||
- 小程序支付仍跳转 `/pages/wechat-pay/index` 并保留支付结果 hash 回灌确认。
|
||||
- 小程序订阅授权仍跳转 `/pages/subscribe-message/index`，且返回不阻断生成主链路。
|
||||
- 普通浏览器分享、H5 支付和 Native 二维码支付不受影响。
|
||||
|
||||
## 后续
|
||||
|
||||
- 设计 `native_app` 的 `postMessage` 消息格式和回包超时策略。
|
||||
- 为 AI H5 sandbox 单独定义 GameBridge，禁止直接依赖 HostBridge。
|
||||
- 将宿主能力、支付渠道和分享策略补充进移动端发布检查清单。
|
||||
Reference in New Issue
Block a user