# 88LIVE 客户端工程架构说明

> 文档用途：对内汇报 / 技术评审 / 新人 onboarding  
> 工程路径：`NewHKLive/88live`  
> 整理日期：2026-05-27  

---

## 一、项目概述（30 秒版）

88LIVE 是基于 **uni-app + Vue2** 的直播/短视频客户端，在旧版 88live 业务（只是业务流程，非原代码工程）基础上做了**目录重构与分层设计**。

核心思路：**页面（Vue）负责展示，JS 模块负责业务与基础设施**。

- **展示层**：`pages/`、`components/` — 布局、交互、样式         vue与nvue文件  
- **业务层**：`features/` — 各业务域的接口、规则、守卫            js文件
- **基础设施层**：`core/` — HTTP、导航、启动、网络守卫等公共能力   js文件
- **状态与配置**：`store/`、`locale/`、`common/config/`  

适用场景：直播 App 具备**多页面、多原生能力、跨生命周期逻辑**，不适合把所有代码堆进单个 `.vue` 文件。

---

## 二、技术栈

| 类别 | 选型 |
|------|------|
| 框架 | uni-app、Vue2、Vuex、vue-i18n |
| 构建 | HBuilderX |
| 端 | iOS / Android App、H5、微信小程序 |
| 特殊页面 | nvue（直播观看/开播、竖滑 Feed） |
| 网络 | `core/http` 统一请求、拦截、错误处理 |
| 配置 | `common/config/runtime-manifest.js` 运行时清单 |

---

## 三、目录分层

```
88live/
├── pages/              # 页面（按业务域分子目录）
├── components/         # 可复用 UI 组件
├── features/           # 业务逻辑（gateway、guard、bridge…）
├── core/               # 基础设施（与具体业务弱相关）
├── store/              # Vuex 全局状态
├── locale/             # 多语言文案
├── common/config/      # 环境、开关、API 根地址
├── static/             # 静态资源与全局样式
├── bootstrap/          # 应用启动辅助（i18n 等）
├── uni_modules/        # uni-app 插件
├── App.vue             # 应用生命周期入口
└── main.js             # Vue 实例与全局挂载
```

### 3.1 展示层

| 目录 | 职责 | 示例 |
|------|------|------|
| `pages/passport/` | 登录注册 | `signin.vue`、`enroll.vue` |
| `pages/dynamics/` | 动态社区 | `index.vue`、`publish.vue`、`detail.vue` |
| `pages/feed/` | 短视频 Feed | `index.nvue`、`reel.nvue` |
| `pages/live/` | 直播 | `hall.vue`、`watch.nvue`、`broadcast.nvue` |
| `pages/account/` | 账号中心 | `profile-edit.vue`、`security.vue` |
| `pages/user/settings/` | 通用设置 | `teen-mode.vue`、`general.vue` |
| `components/` | 可复用 UI | `passport-kit/`、`feed-reel/`、`live-room/` |

**原则**：页面尽量「薄」—— 组装组件、绑定数据、处理用户操作，复杂逻辑下沉到 `features/` 或 `core/`。

### 3.2 业务层 `features/`

按**业务域**划分，常见文件类型：

| 类型 | 命名习惯 | 职责 |
|------|----------|------|
| Gateway | `*-gateway.js` | 封装 API 请求、解析响应、兼容旧字段 |
| Guard | `*-guard.js` | 跨页面规则（权限、时长、发布校验） |
| Bridge | `*-bridge.js` | 连接 JS 与原生能力（推送、实名等） |
| 工具/规范化 | `*-normalize.js`、`*-cache.js` | 数据转换、本地缓存 |

**主要业务域：**

| 域 | 目录 | 典型文件 |
|----|------|----------|
| 登录注册 | `features/passport/` | `region-gateway.js`、`credential-bridge.js` |
| 动态 | `features/dynamics/` | `publish-gateway.js`、`media-picker-permission.js` |
| 短视频 | `features/feed/` | `feed-gateway.js`、`feed-list-cache.js` |
| 直播 | `features/live/` | `gateway.js`、`stream-picker.js`、`chat-lines.js` |
| 播放器接入 | `features/livestream/` | `external-player-detect.js`（IJK 等原生播放器） |
| 账号 | `features/account/` | `teen-mode-guard.js`、`teen-mode-settings.js` |
| 推送 | `features/push/` | `push-bridge.js`、`deep-link-router.js` |

### 3.3 基础设施层 `core/`

与具体业务页面无关、全 App 共用的能力：

| 目录 | 职责 |
|------|------|
| `core/http/` | HTTP 客户端、拦截器、响应解析、错误类型 |
| `core/bootstrap/` | 冷启动、前后台切换（`app-launch.js`） |
| `core/nav/` | 统一导航、Tab 跳转 |
| `core/network/` | 网络访问守卫、请求签名、客户端元信息 |
| `core/config/` | API 路径、应用设置入口 |
| `core/constants/` | 存储键名等常量 |
| `core/kit/` | 运行时工具集（`$appKit`） |
| `core/auth/` | 会话守卫 |
| `core/storage/` | 存储迁移、剪贴板等 |

### 3.4 状态与配置

| 目录 | 职责 |
|------|------|
| `store/modules/` | Vuex 模块：user、im、cart、shell… |
| `locale/` | 简中、繁中、英文、日文等文案 |
| `common/config/runtime-manifest.js` | 版本号、API 地址、功能开关（如 `nativePushEnabled`） |

---

## 四、运行时链路

```
用户打开 App
    │
    ▼
main.js ── 挂载 Vuex / i18n / $http / $api / $appKit
    │
    ▼
App.vue ── onLaunch / onShow / onHide
    │
    ▼
core/bootstrap/app-launch.js
    ├── 存储迁移、语言初始化
    ├── 网络守卫（App）
    ├── 青少年模式守卫
    └── 推送桥接（按开关，当前关闭）
    │
    ▼
pages/*.vue ── 调用 features/*-gateway.js 获取/提交数据
    │
    ▼
core/http ── 统一签名、Token、错误 Toast
    │
    ▼
后端 API
```

---

## 五、为什么不用「全写 Vue」，而要拆很多 JS？

### 5.1 背景说明

小型项目或简单 CRUD 页面，把逻辑写在 `.vue` 的 `<script>` 里完全可行。  
88LIVE 属于**中大型 App**：直播、短视频、社区、账号、多语言、App/H5/小程序多端，存在大量**跨页面、跨生命周期、可复用**的逻辑，因此采用「薄页面 + 厚模块」设计。

**结论：不是不用 Vue，而是 Vue 专注视图层，复杂逻辑由 JS 模块承载。**

### 5.2 拆 JS 的具体好处

| 好处 | 说明 | 本工程示例 |
|------|------|------------|
| **可复用** | 同一段逻辑被多个页面/入口使用 | `teen-mode-guard.js` 被 App 启动、锁屏页、设置页共用 |
| **页面更薄** | UI 改动不牵动接口与规则 | `publish.vue` + `publish-gateway.js` + `media-picker-permission.js` |
| **脱离 Vue 生命周期** | 无「当前页面」的全局能力 | `app-launch.js`、`network-access-guard.js` |
| **基础设施一处改、全局生效** | 减少重复与遗漏 | `core/http/interceptor-registry.js` 统一处理 Token/错误 |
| **API 变更可控** | Gateway 挡在后端与 UI 之间 | `features/*/gateway.js` 解析、兼容旧响应格式 |
| **多人协作清晰** | UI / 业务 / 基建可并行 | 改 `watch.nvue` 与改 `live/gateway.js` 互不干扰 |
| **多端差异集中处理** | 条件编译不散落各页面 | `media-picker-permission.js` 处理 App/小程序权限差异 |
| **更易测试** | 纯函数模块可单测 | gateway、guard 不依赖 Vue 实例 |

### 5.3 代码示例：青少年模式

```
features/account/
├── teen-mode-settings.js   # 本地开关、监护密码读写
└── teen-mode-guard.js      # 启动/前台计时、宵禁、40 分钟锁、原生遮罩

pages/user/settings/
├── teen-mode.vue           # 设置页 UI（开关、改密码）
└── teen-mode-lock.vue      # 锁屏页 UI（输入密码解锁）

core/bootstrap/app-launch.js  # 冷启动/前后台时调用 guard
```

若全部写在某个 `.vue` 里：守卫无法挂在 App 级生命周期，其他页面也无法复用，极易变成「上帝组件」。

### 5.4 与「全写 Vue」对比

| 维度 | 全写 .vue | 本工程分层 |
|------|-----------|------------|
| 上手速度 | 快 | 需熟悉目录规范 |
| 单文件体积 | 逻辑一多易上千行 | 页面偏 UI，逻辑外置 |
| 跨页面能力 | 易复制粘贴 | guard/bootstrap 一处接入 |
| 旧工程迁移 | 牵一发动全身 | gateway 可逐步替换 |
| 适用场景 | 简单页、活动页 | **直播 App、多模块、长生命周期** |

### 5.5 是否过度设计？

**不是为拆而拆。** 拆分粒度有明确边界：

- **留在 .vue**：模板、样式、页面级交互、组件组装  
- **抽到 features/**：接口封装、业务规则、跨页面守卫、原生桥接  
- **抽到 core/**：HTTP、导航、启动、与业务无关的工具  

只有「复用、跨页面、无 UI、全 App 级」的逻辑才独立成 JS 文件。

---

## 六、关键技术决策（汇报可提）

1. **旧工程迁移 + 新分层**：保留后端 API 路径，前端用 gateway 做适配，页面路由重新规划（如 `pages/find/user` → `pages/profile/show`）。  
2. **nvue + vue 叠层**：直播/Feed 用 nvue 保性能，互动按钮等用 vue 子组件 webview 叠层，兼顾性能与可维护性。  
3. **功能开关化**：推送（VoIP/FCM）、底部点赞数等通过 `runtime-manifest.js` 开关控制，便于分阶段上线。  
4. **国际化**：文案集中在 `locale/`，页面通过 `$t()` 引用，不写死中文。  
5. **原生插件隔离**：暂不需要的能力（如 `gzfuts-fcm`）移至 `_disabled_native/`，避免误打包进基座。

---

## 七、业务模块一览

| 模块 | 页面入口 | 主要 features |
|------|----------|---------------|
| 登录注册 | `pages/passport/*` | `features/passport/` |
| 首页 | `pages/index/` | `features/travel/` |
| 动态 | `pages/dynamics/` | `features/dynamics/` |
| 短视频 | `pages/feed/` | `features/feed/` |
| 直播 | `pages/live/` | `features/live/`、`features/livestream/` |
| 用户主页 | `pages/profile/` | `features/profile/` |
| 我的 / 设置 | `pages/mine/`、`pages/user/settings/` | `features/account/` |
| 搜索 | `pages/search/` | `features/search/` |
| IM | store `im` 模块 | `features/im/` |

---

## 八、新人快速上手

1. 从 `main.js` → `App.vue` → `core/bootstrap/app-launch.js` 了解启动流程。  
2. 找一个熟悉页面（如 `pages/dynamics/detail.vue`），顺藤摸瓜到对应 `features/dynamics/`。  
3. 发请求统一走 `core/http`，不要页面里直接拼 URL。  
4. 改文案去 `locale/zh-Hans.json`（及繁中/英文）。  
5. 改环境/开关看 `common/config/runtime-manifest.js`。

---

## 九、相关文档

- [工作周报-88live工程.md](./工作周报-88live工程.md) — 阶段功能交付与 Bug 修复记录  
- [features/livestream/README.md](../features/livestream/README.md) — 直播播放器接入说明  

---

## 十、附录：分层示意图

```
┌─────────────────────────────────────────────────────────┐
│  pages/ + components/          展示层（Vue / nvue）       │
├─────────────────────────────────────────────────────────┤
│  features/                     业务层（gateway/guard）   │
├─────────────────────────────────────────────────────────┤
│  core/                         基础设施（http/nav/…）    │
├─────────────────────────────────────────────────────────┤
│  store/ + locale/ + config/    状态 · 文案 · 配置        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
                     后端 API / 原生 SDK
```
