# 会会数字分身 · 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` 配置。