127 lines
6.3 KiB
Markdown
127 lines
6.3 KiB
Markdown
# 会会数字分身 · uniapp + H5 混合架构
|
||
|
||
> 移动端采用 **uniapp 原生壳 + web-view 内嵌现有 H5** 的混合模式，与会会主 App 一致。
|
||
> 业务页面（数字分身管理 / 知识库 / 对话等）继续用 `digital-avatar-app`（Vue3 SPA）开发并构建为 H5，
|
||
> 由本工程的 uniapp 壳通过 `<web-view>` 加载，原生侧只负责登录、会会资料、导航壳。
|
||
|
||
---
|
||
|
||
## 1. 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 会会 App（uniapp 原生壳） uniapp-avatar/ │
|
||
│ ├─ 会会统一登录（token / userId / 资料） │
|
||
│ ├─ 原生导航壳（自定义导航栏 / 可选 tabBar） │
|
||
│ └─ <web-view :src="H5?token=...&userId=..."> │
|
||
└───────────────────────┬─────────────────────┘
|
||
│ web-view
|
||
▼
|
||
┌─────────────────────────────────────────────┐
|
||
│ 会会数字分身 H5 digital-avatar-app/ │
|
||
│ ├─ Vue3 + Vite SPA（构建产物即 H5） │
|
||
│ ├─ 从 URL / window.__uniBridgeHandle__ 取认证 │
|
||
│ └─ 通过 uni.webView.postMessage 回传原生事件 │
|
||
└─────────────────────────────────────────────┘
|
||
│ HTTPS /api
|
||
▼
|
||
FastAPI 后端（:8000）
|
||
```
|
||
|
||
**职责边界**
|
||
| 层 | 负责 |
|
||
|----|------|
|
||
| uniapp 壳 | 会会登录与会话、注入 token/用户、原生导航与返回、可承载原生能力（推送/分享/支付） |
|
||
| H5 业务 | 全部数字分身业务 UI 与交互、调用后端 API、知识库/问答/对话 |
|
||
| 后端 | 业务数据与 AI 能力（维持不变） |
|
||
|
||
---
|
||
|
||
## 2. 桥接协议（壳 ↔ H5）
|
||
|
||
### 2.1 握手（URL 注入，最可靠）
|
||
壳加载 web-view 时把认证与会会资料拼进 H5 地址的 query：
|
||
```
|
||
H5_BASE_URL/?token=<accessToken>&userId=<uid>&nickname=<urlencode>&avatar=<urlencode>&ts=<ms>
|
||
```
|
||
H5 在 `main.ts` 启动前用 `getLaunchParams()` 解析；`nickname` / `avatar` 需 `encodeURIComponent`。
|
||
|
||
### 2.2 H5 → 原生（`uni.webView.postMessage`）
|
||
H5 引入 uniapp web-view bridge 后调用：
|
||
| type | payload | 含义 |
|
||
|------|---------|------|
|
||
| `ready` | — | H5 已完成首屏渲染 |
|
||
| `needLogin` | — | token 失效，请求壳重新登录 |
|
||
| `setTitle` | `title` | 设置原生导航栏标题 |
|
||
| `navigate` | `path` | 请求原生跳转（打开原生页/新 web-view） |
|
||
| `back` | — | 请求原生返回 |
|
||
|
||
### 2.3 原生 → H5（壳主动推送）
|
||
壳通过 `web-view.evalJS` 调用 H5 全局函数 `window.__uniBridgeHandle__(message)`：
|
||
| type | payload | 含义 |
|
||
|------|---------|------|
|
||
| `context` | `platform, version` | 注入运行环境信息 |
|
||
| `tokenRefresh` | `token` | 登录刷新后下发新 token |
|
||
| `userUpdate` | `user` | 会会资料变更 |
|
||
|
||
> H5 侧用 `onNativeMessage(cb)` 注册 `window.__uniBridgeHandle__`，见 `digital-avatar-app/src/utils/uniapp-bridge.ts`。
|
||
|
||
---
|
||
|
||
## 3. 项目结构（uni CLI / src 布局，已验证可编译）
|
||
|
||
```
|
||
uniapp-avatar/
|
||
├── index.html # H5 入口模板（项目根，uni h5 在此找入口）
|
||
├── vite.config.js # 注册 @dcloudio/vite-plugin-uni（.vue 编译必须）
|
||
├── package.json
|
||
├── README.md
|
||
└── src/ # 源码根（uni CLI 要求 manifest/pages 在此）
|
||
├── manifest.json # 应用配置（名称/AppID/模块）
|
||
├── pages.json # 页面路由
|
||
├── uni.scss # 全局样式变量
|
||
├── App.vue # 启动即做会会登录（onLaunch → userStore.init）
|
||
├── main.js # createSSRApp + pinia
|
||
├── pages/index/index.vue # web-view 容器（内嵌 digital-avatar-app H5）
|
||
├── store/user.js # 会会会话（token/资料，本地缓存）
|
||
└── utils/
|
||
├── bridge.js # H5 URL 构造 + 原生→H5 推送
|
||
└── huihui.js # 会会登录（MOCK，留真实接入位）
|
||
```
|
||
> 构建产物：`npm run build:h5` → `dist/build/h5/`（含 index.html + assets）。
|
||
|
||
## 4. 运行与打包
|
||
|
||
### 方式一：HBuilderX（推荐，与生产一致）
|
||
1. HBuilderX → 导入 `uniapp-avatar/` 目录（已含 `manifest.json`/`pages.json`）。
|
||
2. 顶部菜单「运行」→ 运行到手机/模拟器/浏览器（H5）。
|
||
3. 修改 `src/pages/index/index.vue` 的 `H5_BASE_URL` 指向你的 H5 部署地址：
|
||
- 本地联调用的**局域网 IP + Vite 端口**（如 `http://192.168.1.100:5173`），不要用 `localhost`。
|
||
- 生产填 digital-avatar-app 构建后的 H5 线上域名。
|
||
4. 打包：发行 → 原生 App（云打包/本地打包）。
|
||
|
||
### 方式二：CLI（dev:h5 本地自测，已验证通过）
|
||
```bash
|
||
cd uniapp-avatar
|
||
npm install # 依赖版本已对齐本机 HBuilderX（3.0.0-4010520240507001）
|
||
npm run dev:h5 # 起 H5 版壳，web-view 会加载 H5_BASE_URL 指向的 H5
|
||
npm run build:h5 # 生产构建 → dist/build/h5/
|
||
```
|
||
> 若 npm 依赖版本与本地 HBuilderX 不一致，执行 `npx @dcloudio/uvm` 对齐。
|
||
|
||
### 会会登录接入
|
||
- 当前 `utils/huihui.js` 为 **MOCK**（`MOCK_AUTH = true`），便于联调。
|
||
- 生产接入：把 `MOCK_AUTH` 改为 `false`，在 `loginHuihui()` 接入会会开放平台授权，
|
||
换取 `access_token`、`userId`；`getUserInfo()` 请求会会 `usercenter` 真实资料接口
|
||
（接口基址见 `docs/production-interface-inventory.md`）。
|
||
|
||
---
|
||
|
||
## 4. H5 侧改动清单（digital-avatar-app）
|
||
- 新增 `src/utils/uniapp-bridge.ts`：环境探测、参数解析、双向消息。
|
||
- `src/api/index.ts`：`baseURL` 改为可配置（支持 web-view 内绝对地址）。
|
||
- `src/store/avatar.ts`：优先采用壳传入的会会资料；新增 `setNativeProfile`。
|
||
- `src/main.ts`：挂载前注入 token/用户，注册原生消息处理，渲染后发 `ready`。
|
||
- `src/router/index.ts`：改用 `createWebHashHistory()`（web-view 下返回键更稳）。
|
||
- `index.html`：引入 uniapp web-view bridge 脚本，注入 `apiBase` 配置。
|