170 lines
10 KiB
Markdown
170 lines
10 KiB
Markdown
---
|
||
项目名称: 91pron H5 客户端 # 与 DMP 或内部命名一致时请自行替换
|
||
一级部门: 北斗 # 请填写一级部门名称
|
||
二级部门: 瑞升 # 请填写二级部门名称，无则留空
|
||
|
||
DMP编码: JHA-204 # 无则留空
|
||
|
||
项目类型: H5
|
||
# 可选值:
|
||
# H5 / APP / PC / 服务 / 组件 / 工具 / AI / 中间件
|
||
|
||
开发语言: Node
|
||
# 可选值:
|
||
# GO / Java / PHP / Node
|
||
|
||
项目负责人: DN4929,DN4868 # 员工编号，多个用逗号隔开，这里的负责是这套代码的负责人
|
||
|
||
运维负责人: DN9460,DN9651,DN4792 # 负责部署、监控、K8S、发布、证书等
|
||
|
||
产品负责人: YY1145,YY1208 # 项目产品经理
|
||
|
||
项目成员: DN4929,DN4868
|
||
|
||
项目状态: 开发中
|
||
# 可选值:
|
||
# 开发中 / 维护中 / 已停止 / 已归档
|
||
|
||
项目级别: 中
|
||
# 可选值:
|
||
# 高 / 中 / 低
|
||
|
||
核心分支: main
|
||
|
||
代码仓库:
|
||
- https://bd-git.jsyyds.com/ruisheng/jha-204-91pron/frontend/91porn-h5-client.git
|
||
|
||
最后审计人:
|
||
|
||
最后审计时间:
|
||
|
||
告警群:
|
||
|
||
备注:
|
||
- `package.json` 中 `name` 为 `redapricot`，仓库/目录名为 `91pron-h5-client`。
|
||
- 业务 API 根路径由 **选线得到的 `configStore.baseUrl`** + 环境变量 `VITE_APP_API_BASE_URL`（如 `/api/app`）拼接；选线候选域名见各环境 `.env.*` 中的 `VITE_BASE_URL`（JSON 数组），勿将含密钥、内网地址的未脱敏内容对外发布。
|
||
---
|
||
|
||
# 1. 项目说明
|
||
|
||
本仓库为面向 **移动端 H5 浏览器** 的 **Vue 3 + Vite + TypeScript** 单页应用，UI 基于 **Vant 4**，状态管理为 **Pinia**（`pinia-plugin-persistedstate` 持久化），路由为 **Vue Router 4**，模式为 **`createWebHistory`（HTML5 History）**（见 `src/router/index.ts`）。入口为 `src/main.ts`，挂载 Pinia、Router、埋点插件与 Vant `Lazyload` 等；全局路由前置逻辑见 `src/permission.ts`（含大量 `<keep-alive>` 与 Tab 缓存策略）。启动页 `Splash` 负责 **API 选线**（ping）、拉取应用配置并写入 `config`/`global` 等 store，再进入 `MainView` 主导航。
|
||
|
||
业务域在 `src/views/` 下按模块划分，主要包括：**首页与搜索/片库/长短视频播放详情**（`lldhome`、`shortVideo`）、**社区**（帖子、套图、排行、群聊等，`community`）、**直播**（`lldlive`）、**我的**（登录、钱包会员、充值提现、消息、AI 功能、历史收藏等，`lldmine`）、**ACG**（小说/漫画/动漫，`acgModule`）、**暗网**（`darkNet`）、**娱乐**（`entertainment`）、**联合游戏活动**（`jointGamingActivitie`）、**预售**（`lldpresale`）、**免费福利**（`lldfreeBenefits`）等；接口封装在 `src/service/`，按域拆分（如 `home.ts`、`user.ts`、`community.ts`）。
|
||
|
||
**技术栈要点：**
|
||
|
||
- 构建：**Vite 3**（`vite.config.ts`），生产使用 **Terser** 压缩，**vite-plugin-compression** 生成 **gzip** 产物；**unplugin-vue-components** + **VantResolver** 按需引入组件；**vite-plugin-svg-icons** 使用 `src/assets/icons`；可按环境开启 **vconsole**（`vite-plugin-vconsole`）。
|
||
- 样式：**Sass**，通过 `css.preprocessorOptions.scss.additionalData` 向各组件注入 `@/assets/styles/main.scss`；存在主题目录 `src/assets/theme/`。
|
||
- 适配：**postcss-px-to-viewport-8-plugin**（见 `postcss` 配置）。
|
||
- 网络：**axios** 封装于 `src/utils/request.ts`，`baseURL = configStore.baseUrl + VITE_APP_API_BASE_URL`；支持 **Authorization**、业务码非 200 时 `showToast`、可选 **请求体/查询参数加密**（`VITE_PARAMETER_ENCRYPTION`）、响应 `hash` 字段时的解密；GET 短缓存与请求去重等逻辑也在该文件中。
|
||
- 播放器与媒体：**xgplayer-hls.js**（HLS），业务中多处拼接 **`/api/app/vid/h5/m3u8/…`** 拉流地址（见 `VideoHls` 等组件）。
|
||
- 其他：**mitt** 事件总线、`moment`、**swiper**、**qrcode.vue**、**html5-qrcode**、**vuedraggable-es**、**devtools-detector**（生产环境非调试参数下启用检测）、`index.html` 引入 **web-sdk** 脚本供设备信息与部分请求头使用等。
|
||
|
||
**Node 版本：** 仓库 `README.md` 建议使用 **16.17.1**。
|
||
|
||
**常用脚本（`package.json`）：**
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `npm run dev` | 本地开发（`vite`，默认见 `vite.config.ts` 中 `server.port` 等） |
|
||
| `npm run build:prod` | 生产构建（`--mode production`） |
|
||
| `npm run build:test` | 测试环境构建（`--mode test`） |
|
||
| `npm run preview` | 预览构建产物（`vite preview`） |
|
||
| `npm run lint` | ESLint（`src` 下 `.js` / `.vue` / `.ts`，带 `--fix`） |
|
||
|
||
**开发环境代理（`vite.config.ts`）：** 本地将 **`/dcserv`** 代理到可配置的 `target`（用于部分接口调试，以文件内实际配置为准）。
|
||
|
||
**项目目录结构（核心）：**
|
||
|
||
```
|
||
91pron-h5-client/
|
||
├── public/
|
||
├── src/
|
||
│ ├── main.ts # 入口：Pinia、Router、Vant、埋点、devtools 等
|
||
│ ├── App.vue
|
||
│ ├── permission.ts # 路由守卫：keep-alive / Tab 缓存策略
|
||
│ ├── router/
|
||
│ │ └── index.ts # Router（History）、_SPLASH_ / 首页集合 / 业务子路由等
|
||
│ ├── stores/ # Pinia（user、config、global、app 等）
|
||
│ ├── views/ # 页面：lldhome / community / lldmine / acgModule 等
|
||
│ ├── service/ # 按域拆分的接口方法
|
||
│ ├── components/ # 通用与业务组件（含 VideoHls、瀑布流等）
|
||
│ ├── utils/ # request、埋点、加解密、本地存储等
|
||
│ ├── hooks/ # 组合式逻辑
|
||
│ ├── assets/ # 样式、图标、主题等
|
||
│ ├── plugins/ # 如 tracker 等
|
||
│ └── enums/、typings/ # 枚举与类型
|
||
├── vite.config.ts
|
||
├── index.html # 入口 HTML，含 web-sdk 脚本引用
|
||
├── .env.development / .env.test / .env.production # VITE_* 与选线域名等
|
||
├── prod_build.sh # 示例打包/发布脚本（环境差异大，使用前请内部确认）
|
||
└── project.md # 本文件
|
||
```
|
||
|
||
**接口基址与选线：**
|
||
|
||
- **`VITE_APP_API_BASE_URL`**：通常为 **`/api/app`**，作为 axios 路径前缀拼在选线成功的域名之后。
|
||
- **`VITE_BASE_URL`**：各环境文件中为 **JSON 数组字符串**，供启动阶段对多个候选域名做 **ping/选线**，选中的结果写入 **`configStore.baseUrl`**（详见 `Splash` 与 `src/utils/ping.ts` 等逻辑）。
|
||
- 生产部署若使用相对路径，需由 **网关 / Nginx** 将浏览器同源下的 **`/api`** 转发到实际业务后端。
|
||
|
||
---
|
||
|
||
# 2. 基础设施与中间件
|
||
|
||
本仓库为 **纯前端工程**，不内置后端；运行时依赖：
|
||
|
||
- **业务 API**：由选线结果 + `VITE_APP_API_BASE_URL` 决定；静态部署时需保证 **`/api/...` 反代** 与 HTTPS 证书策略一致。
|
||
- **静态资源托管**：`build:prod` / `build:test` 产物在 **`dist/`**，由 CDN 或 Web 服务器提供；**History 路由** 需在服务端配置 **单页回退**（如 `try_files` 到 `index.html`）。
|
||
- **媒体与图片域名**：全局配置、资源线与播放线路等由接口与 `config`/`global` store 中的 **`sourceInfo`**、**线路信息** 等共同决定（勿在文档中粘贴未脱敏的内网或密钥配置）。
|
||
|
||
---
|
||
|
||
# 3. 运维部署
|
||
|
||
**构建产物：** 执行 `npm run build:prod` 或 `npm run build:test` 后，在 **`dist/`** 生成静态资源；可能同时生成 **`.gz`**（依赖服务器是否启用 `gzip_static` 或等价能力）。
|
||
|
||
**推荐发布流程（示例）：**
|
||
|
||
1. 使用约定 **Node** 版本安装依赖：`npm ci` 或 `npm install`。
|
||
2. 确认各环境 **`.env.*`** 中 `VITE_BASE_URL`、`VITE_APP_API_BASE_URL`、加密开关等与当前发布目标一致。
|
||
3. 执行 `npm run build:prod` 或 `npm run build:test`。
|
||
4. 将 **`dist/`** 同步至静态服务器；确认 **History 路由回退** 与 **`/api` 反代**。
|
||
5. 仓库内 **`prod_build.sh`** 为示例流程，**主机与路径以实际运维规范为准**，避免泄露账号与内网信息。
|
||
|
||
**环境变量说明（摘录，完整以 `.env.*` 为准）：**
|
||
|
||
| 变量 | 作用 |
|
||
|------|------|
|
||
| `NODE_ENV` | 构建/运行环境标识 |
|
||
| `VITE_APP_API_BASE_URL` | 与选线域名拼接，作为 API 路径前缀 |
|
||
| `VITE_BASE_URL` | 选线候选 API 域名列表（JSON 数组字符串） |
|
||
| `VITE_BUILD_SOURCEMAP` | 是否生成 sourcemap |
|
||
| `VITE_BUILD_DROP_CONSOLE` | 生产是否剔除 `console` |
|
||
| `VITE_BUILD_VCONSOLE` | 是否打包进 vconsole |
|
||
| `VITE_PARAMETER_ENCRYPTION` | 是否开启请求参数加密 |
|
||
|
||
---
|
||
|
||
# 4. 风险说明
|
||
|
||
- **强依赖网关反代**：生产使用相对路径时，**`/api` 代理错误会导致整站接口不可用**；History 模式服务器配置错误会导致 **深链 404**。
|
||
- **选线失败**：启动阶段若所有候选域名不可用，用户可能停留在选线或错误态（见 `Splash` 与相关弹层逻辑）。
|
||
- **参数加密与后端约定**：`VITE_PARAMETER_ENCRYPTION` 与各环境必须 **与后端一致**，否则请求体解析失败。
|
||
- **安全与合规**：生产环境开启 **devtools 检测并跳转外部页**（见 `main.ts`），变更前需评估用户体验与合规要求。
|
||
- **配置敏感信息**：`.env`、选线域名、密钥类逻辑 **勿提交到公开仓库**；供应链上锁定 `package-lock.json` 并定期审计依赖。
|
||
|
||
---
|
||
|
||
# 5. 历史事故（可选）
|
||
|
||
- 暂无（请运维/研发后续补充）
|
||
|
||
---
|
||
|
||
# 6. 交接说明（可选）
|
||
|
||
- 路由与缓存策略集中在 **`src/permission.ts`**，新增常驻缓存页面时需同步维护 **keepAliveMap / mainViewKeep** 等映射。
|
||
- 用户信息、配置等与 **`src/stores/`** 及持久化插件相关；**请勿绕过 `src/utils/request.ts` 直接发起业务 axios**（与仓库 `.cursor` 前端规范一致）。
|
||
- 接口目录：**`src/service/`**；类型定义：**`src/typings/`**。
|
||
- **请勿将含密钥、生产内网地址的 `.env` 或未脱敏脚本提交至对外可见仓库**；YAML 头部元数据若与真实组织不一致，请在内部系统中核对后修改。
|