624 lines
15 KiB
Markdown
624 lines
15 KiB
Markdown
# 羽声语音 H5 项目交接文档
|
||
|
||
## 📋 项目概述
|
||
|
||
**项目名称：** 羽声语音 H5 内嵌页面
|
||
**技术栈：** uni-app + Vue.js
|
||
**开发平台：** HBuilderX
|
||
**运行环境：** 微信公众号 H5、APP 内嵌 WebView
|
||
**API 地址：** https://yushengapi.qxyushen.top
|
||
|
||
---
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
羽声语音H5/
|
||
├── component/ # 公共组件
|
||
│ ├── nav.vue # 导航栏组件
|
||
│ ├── avatar.vue # 头像组件
|
||
│ ├── table.vue # 表格组件
|
||
│ ├── newTable.vue # 新版表格组件
|
||
│ ├── tab.vue # 标签页组件
|
||
│ ├── swiper.vue # 轮播图组件
|
||
│ ├── uploadImage.vue # 图片上传组件
|
||
│ ├── LevelProgress.vue # 等级进度条组件
|
||
│ ├── MiddlePopup.vue # 中间弹窗组件
|
||
│ └── headerHeight.vue # 头部高度组件
|
||
│
|
||
├── pages/ # 页面目录
|
||
│ ├── union/ # 公会相关页面
|
||
│ │ ├── index.vue # 公会首页
|
||
│ │ ├── list.vue # 公会列表（搜索加入）
|
||
│ │ ├── agreement.vue # 公会协议
|
||
│ │ ├── exitApplication.vue # 退出审核
|
||
│ │ ├── historyRecord.vue # 补贴历史记录
|
||
│ │ ├── setGroup.vue # 群聊设置
|
||
│ │ └── memberList.vue # 群聊成员
|
||
│ │
|
||
│ ├── other/ # 其他功能页面
|
||
│ │ ├── weChatPay.vue # 微信充值页面 ⭐
|
||
│ │ ├── taskDesc.vue # 规则说明
|
||
│ │ ├── grade.vue # 等级页面
|
||
│ │ ├── gradeRule.vue # 等级规则
|
||
│ │ ├── income.vue # 邀请收益
|
||
│ │ └── aboutUs.vue # 关于我们
|
||
│ │
|
||
│ ├── prop/ # 道具相关
|
||
│ │ └── propMall.vue # 道具商城
|
||
│ │
|
||
│ └── feedback/ # 反馈相关
|
||
│ ├── help.vue # 帮助与反馈
|
||
│ ├── customerService.vue # 在线客服
|
||
│ ├── feedback.vue # 反馈问题
|
||
│ ├── teenage.vue # 青少年模式
|
||
│ ├── teenageDetail.vue # 青少年详情
|
||
│ ├── problemDetail.vue # 问题详情
|
||
│ └── report.vue # 举报
|
||
│
|
||
├── until/ # 工具类
|
||
│ ├── config.js # 全局配置 ⭐
|
||
│ ├── http.js # HTTP 请求封装
|
||
│ ├── request.js # Axios 请求拦截器
|
||
│ └── wxpay.js # 微信支付工具 ⭐
|
||
│
|
||
├── static/ # 静态资源
|
||
│ ├── image/ # 图片资源
|
||
│ ├── customicons.css # 自定义图标
|
||
│ ├── customicons.ttf # 图标字体
|
||
│ ├── public.css # 公共样式
|
||
│ ├── youshe.ttf # 羽声字体
|
||
│ └── che.mp4 # 视频资源
|
||
│
|
||
├── uni_modules/ # uni-app 插件
|
||
│ ├── uni-ui/ # uni-ui 组件库
|
||
│ ├── simple-pdf-viewer/ # PDF 查看器
|
||
│ └── ... # 其他 uni-app 官方组件
|
||
│
|
||
├── App.vue # 应用入口
|
||
├── main.js # 主入口文件
|
||
├── pages.json # 页面配置
|
||
├── manifest.json # 应用配置
|
||
├── uni.scss # 全局样式变量
|
||
└── package.json # 依赖配置
|
||
```
|
||
|
||
---
|
||
|
||
## 🔑 核心功能模块
|
||
|
||
### 1. 公会系统 (pages/union/)
|
||
|
||
#### 1.1 公会列表与加入 (list.vue)
|
||
**功能描述：**
|
||
- 搜索公会（支持公会ID/昵称）
|
||
- 查看公会信息（头像、名称、简介、会长、在线人数）
|
||
- 申请加入公会
|
||
- 实名认证检查与跳转 ⭐
|
||
|
||
**关键逻辑：**
|
||
```javascript
|
||
// 实名认证流程
|
||
1. 用户点击"申请"按钮
|
||
2. 调用接口检查实名状态 (/api/User/get_user_info)
|
||
3. 已实名 → 显示加入确认弹窗
|
||
4. 未实名 → 提示跳转 APP 实名认证
|
||
5. 从 APP 返回时自动刷新实名状态（onShow 生命周期）
|
||
```
|
||
|
||
**重要更新：**
|
||
- ✅ 添加了实名状态缓存机制（user_auth_status）
|
||
- ✅ 添加了防抖机制（3秒内不重复请求）
|
||
- ✅ 解决了从 APP 返回后仍提示未实名的问题
|
||
|
||
**与 APP 交互：**
|
||
```javascript
|
||
// iOS
|
||
window.webkit.messageHandlers.nativeHandler.postMessage({
|
||
'action': 'enterAuthent'
|
||
});
|
||
|
||
// Android
|
||
window.Android.enterAuthent();
|
||
```
|
||
|
||
#### 1.2 公会首页 (index.vue)
|
||
- 公会信息展示
|
||
- 成员管理
|
||
- 公会设置
|
||
|
||
#### 1.3 其他公会功能
|
||
- 退出审核 (exitApplication.vue)
|
||
- 补贴历史记录 (historyRecord.vue)
|
||
- 群聊设置 (setGroup.vue)
|
||
- 群聊成员 (memberList.vue)
|
||
|
||
---
|
||
|
||
### 2. 微信充值系统 (pages/other/weChatPay.vue) 未完善⭐
|
||
|
||
**功能描述：**
|
||
- 用户输入羽声语音 ID
|
||
- 选择充值金额（300-10000 金币）
|
||
- 同意充值协议
|
||
- 调起微信公众号支付
|
||
|
||
**完整支付流程：**
|
||
```
|
||
1. 用户输入 ID
|
||
↓
|
||
2. 选择充值金额（卡片变绿表示选中）
|
||
↓
|
||
3. 勾选"我已阅读并同意《充值协议》"
|
||
↓
|
||
4. 点击"立即支付"按钮
|
||
↓
|
||
5. 验证：ID、金额、协议
|
||
↓
|
||
6. 生成订单号（YS + 时间戳 + 随机数）
|
||
↓
|
||
7. 调用后端接口创建支付订单
|
||
↓
|
||
8. 调起微信 JS-SDK 支付
|
||
↓
|
||
9. 用户完成支付
|
||
↓
|
||
10. 返回支付结果
|
||
```
|
||
|
||
**关键代码：**
|
||
```javascript
|
||
// 支付入口
|
||
handlePay() {
|
||
// 1. 验证用户ID
|
||
// 2. 验证充值金额
|
||
// 3. 验证协议同意
|
||
// 4. 调用微信支付
|
||
const result = await wxPay.pay(payAmount, orderNo, attach);
|
||
}
|
||
```
|
||
|
||
**支付工具类 (until/wxpay.js)：**
|
||
- 微信环境检测
|
||
- 微信授权获取 openid
|
||
- 初始化微信 JS-SDK
|
||
- 创建支付订单
|
||
- 发起微信支付
|
||
- 验证支付结果
|
||
|
||
**后端接口依赖：**
|
||
- `/api/wx/auth` - 获取 openid
|
||
- `/jssdk/config` - 获取 JS-SDK 配置
|
||
- `/api/wxpay/unifiedorder` - 创建支付订单
|
||
- `/api/wxpay/query` - 查询支付结果
|
||
|
||
---
|
||
|
||
### 3. 其他功能模块
|
||
|
||
#### 3.1 等级系统
|
||
- 等级展示 (grade.vue)
|
||
- 等级规则说明 (gradeRule.vue)
|
||
|
||
#### 3.2 邀请收益
|
||
- 邀请收益统计 (income.vue)
|
||
|
||
#### 3.3 道具商城
|
||
- 道具列表与购买 (propMall.vue)
|
||
|
||
#### 3.4 帮助与反馈
|
||
- 帮助中心 (help.vue)
|
||
- 在线客服 (customerService.vue)
|
||
- 问题反馈 (feedback.vue)
|
||
- 举报功能 (report.vue)
|
||
|
||
#### 3.5 青少年模式
|
||
- 青少年模式设置 (teenage.vue)
|
||
- 青少年详情 (teenageDetail.vue)
|
||
|
||
---
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### 1. 全局配置 (until/config.js)
|
||
|
||
```javascript
|
||
// API 基础地址
|
||
const BASE_URL = "https://yushengapi.qxyushen.top";
|
||
|
||
// 图片资源地址
|
||
const BASE_IMAGE_URL = "https://yushengapi.qxyushen.top/h5/image/";
|
||
|
||
// IM 配置
|
||
const IM_APP_TOKEN = "67962a777e2b13bc6a4bde3ccd389d1e";
|
||
|
||
// 主题色
|
||
const BASR_COLOR = '#3ABC6D';
|
||
|
||
// 项目名称
|
||
const BASE_NAME = '羽声语音';
|
||
```
|
||
|
||
**环境切换：**
|
||
```javascript
|
||
// 正式环境
|
||
const BASE_URL = "https://yushengapi.qxyushen.top";
|
||
|
||
// 测试环境
|
||
// const BASE_URL = "https://test.vespa.qxyushen.top";
|
||
```
|
||
|
||
### 2. 页面配置 (pages.json)
|
||
|
||
- 所有页面使用自定义导航栏 (`navigationStyle: "custom"`)
|
||
- 部分页面禁用 iOS 左滑返回 (`popGesture: "none"`)
|
||
|
||
### 3. 应用配置 (manifest.json)
|
||
|
||
- 配置应用名称、版本号
|
||
- 配置微信公众号 appid
|
||
- 配置权限申请
|
||
|
||
---
|
||
|
||
## 🔌 API 接口说明
|
||
|
||
### 基础配置
|
||
- **Base URL:** `https://yushengapi.qxyushen.top`
|
||
- **请求方式:** GET / POST / PUT / DELETE
|
||
- **认证方式:** Token（存储在 localStorage）
|
||
|
||
### 主要接口列表
|
||
|
||
#### 用户相关
|
||
```
|
||
GET /api/User/get_user_info # 获取用户信息（含实名状态）
|
||
```
|
||
|
||
#### 公会相关
|
||
```
|
||
GET /api/Guild/guild_list # 获取公会列表
|
||
POST /api/Guild/join_guild # 申请加入公会
|
||
```
|
||
|
||
#### 支付相关
|
||
```
|
||
GET /api/wx/auth # 微信授权获取 openid
|
||
GET /jssdk/config # 获取微信 JS-SDK 配置
|
||
POST /api/wxpay/unifiedorder # 创建支付订单
|
||
GET /api/wxpay/query # 查询支付结果
|
||
```
|
||
|
||
### 请求示例
|
||
|
||
```javascript
|
||
// GET 请求
|
||
http.get('/api/User/get_user_info', {
|
||
token: uni.getStorageSync('token')
|
||
})
|
||
|
||
// POST 请求
|
||
http.post('/api/Guild/join_guild', {
|
||
guild_id: 123,
|
||
token: uni.getStorageSync('token')
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 样式规范
|
||
|
||
### 1. 颜色变量
|
||
```scss
|
||
--primary-color: #3ABC6D; // 主题色（绿色）
|
||
--subss-color: #3ABC6D; // 辅助色
|
||
--font-button-color: #FFFFFF; // 按钮文字色
|
||
--font-button-size: 28rpx; // 按钮文字大小
|
||
```
|
||
|
||
### 2. 尺寸单位
|
||
- 使用 `rpx` 作为响应式单位（750rpx = 屏幕宽度）
|
||
- 字体大小：24rpx、28rpx、32rpx、44rpx
|
||
- 圆角：20rpx、44rpx、68rpx
|
||
|
||
### 3. 公共样式类
|
||
```scss
|
||
.flex-line // 横向弹性布局
|
||
.w-fill // 宽度 100%
|
||
.truncate // 单行文本省略
|
||
.color-3 // 文字颜色 #333
|
||
.font-24 // 字体大小 24rpx
|
||
.font-32 // 字体大小 32rpx
|
||
.ml-20 // 左边距 20rpx
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发环境配置
|
||
|
||
### 1. 环境要求
|
||
- **Node.js:** v14.0.0+
|
||
- **HBuilderX:** 最新版本
|
||
- **微信开发者工具:** 用于调试微信公众号功能
|
||
|
||
### 2. 安装依赖
|
||
```bash
|
||
npm install
|
||
# 或
|
||
pnpm install
|
||
```
|
||
|
||
### 3. 主要依赖
|
||
```json
|
||
{
|
||
"axios": "^1.9.0", // HTTP 请求库
|
||
"office-viewer": "^0.3.14", // Office 文档查看
|
||
"simple-pdf-viewer": "^2.0.3", // PDF 查看
|
||
"video-animation-player": "^1.0.5", // 视频播放
|
||
"vue-i18n": "^11.1.5" // 国际化
|
||
}
|
||
```
|
||
|
||
### 4. 运行项目
|
||
|
||
#### 方式一：HBuilderX
|
||
1. 使用 HBuilderX 打开项目
|
||
2. 选择运行 → 运行到浏览器 / 运行到手机或模拟器
|
||
3. 选择运行到微信开发者工具（需配置微信开发者工具路径）
|
||
|
||
#### 方式二：命令行
|
||
```bash
|
||
# 开发环境
|
||
npm run dev:h5
|
||
|
||
# 生产构建
|
||
npm run build:h5
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 与 APP 交互说明
|
||
|
||
### 1. 调用 APP 原生功能
|
||
|
||
#### iOS 交互
|
||
```javascript
|
||
// 调用 iOS 原生方法
|
||
window.webkit.messageHandlers.nativeHandler.postMessage({
|
||
'action': 'enterAuthent' // 跳转实名认证
|
||
});
|
||
```
|
||
|
||
#### Android 交互
|
||
```javascript
|
||
// 调用 Android 原生方法
|
||
window.Android.enterAuthent(); // 跳转实名认证
|
||
```
|
||
|
||
### 2. 接收 APP 传递的参数
|
||
|
||
```javascript
|
||
// 在 onLoad 或 onShow 中接收参数
|
||
onShow(options) {
|
||
if (options && options.guild_id) {
|
||
// 处理 APP 传递的公会 ID
|
||
this.searchValue = options.guild_id;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 页面生命周期注意事项
|
||
|
||
- **onShow:** 每次页面显示都会触发（包括从 APP 返回）
|
||
- **onLoad:** 只在页面首次加载时触发
|
||
- **从 APP 返回时：** 使用 onShow 刷新数据状态
|
||
|
||
---
|
||
|
||
## 🐛 常见问题与解决方案
|
||
|
||
### 1. 实名认证问题
|
||
|
||
**问题：** 从 APP 完成实名认证返回后，仍提示未实名
|
||
|
||
**原因：**
|
||
- 页面状态未刷新
|
||
- 接口缓存导致获取的是旧数据
|
||
|
||
**解决方案：**
|
||
```javascript
|
||
// 在 onShow 中刷新用户信息
|
||
onShow() {
|
||
this.refreshUserInfo(); // 获取最新实名状态
|
||
}
|
||
|
||
// 添加防抖机制避免频繁请求
|
||
async refreshUserInfo(force = false) {
|
||
const now = Date.now();
|
||
if (!force && now - this.lastRefreshTime < 3000) {
|
||
return; // 3秒内不重复请求
|
||
}
|
||
// ... 请求逻辑
|
||
}
|
||
```
|
||
|
||
### 2. 微信支付问题
|
||
|
||
**问题：** 微信支付调起失败
|
||
|
||
**可能原因：**
|
||
1. 未在微信环境中打开
|
||
2. 微信 JS-SDK 未正确初始化
|
||
3. 支付参数错误
|
||
4. 微信公众号配置问题
|
||
|
||
**排查步骤：**
|
||
```javascript
|
||
// 1. 检查是否在微信环境
|
||
const isWeixin = /micromessenger/i.test(navigator.userAgent);
|
||
|
||
// 2. 检查 JS-SDK 初始化
|
||
wx.ready(() => {
|
||
console.log('微信 JS-SDK 初始化成功');
|
||
});
|
||
|
||
wx.error((err) => {
|
||
console.error('微信 JS-SDK 初始化失败:', err);
|
||
});
|
||
|
||
// 3. 开启调试模式查看详细错误
|
||
wx.config({
|
||
debug: true, // 开启调试
|
||
// ...
|
||
});
|
||
```
|
||
|
||
### 3. 样式兼容问题
|
||
|
||
**问题：** iOS 和 Android 样式显示不一致
|
||
|
||
**解决方案：**
|
||
```javascript
|
||
// 获取平台信息
|
||
const platform = uni.getSystemInfoSync().platform;
|
||
|
||
// 根据平台设置不同样式
|
||
:style="{
|
||
marginTop: `${statusBarHeight}${platform === 'ios' ? 'px' : 'dp'}`
|
||
}"
|
||
```
|
||
|
||
### 4. 图片加载失败
|
||
|
||
**问题：** 图片显示不出来
|
||
|
||
**解决方案：**
|
||
```javascript
|
||
// 使用默认图片
|
||
<img :src="data.cover || defaultLogo" alt="" />
|
||
|
||
// 图片加载错误处理
|
||
<img :src="imageUrl" @error="handleImageError" />
|
||
|
||
handleImageError(e) {
|
||
e.target.src = this.defaultLogo;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 部署说明
|
||
|
||
### 1. 构建生产版本
|
||
|
||
```bash
|
||
# H5 构建
|
||
npm run build:h5
|
||
|
||
# 构建产物在 unpackage/dist/build/h5 目录
|
||
```
|
||
|
||
### 2. 部署到服务器
|
||
|
||
```bash
|
||
# 将构建产物上传到服务器
|
||
scp -r unpackage/dist/build/h5/* user@server:/var/www/html/
|
||
|
||
# 或使用 FTP 工具上传
|
||
```
|
||
|
||
### 3. Nginx 配置示例
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
root /var/www/html/h5;
|
||
index index.html;
|
||
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# 静态资源缓存
|
||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
|
||
expires 30d;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 微信公众号配置
|
||
|
||
1. 登录微信公众平台
|
||
2. 设置 → 公众号设置 → 功能设置
|
||
3. 配置 JS 接口安全域名
|
||
4. 配置网页授权域名
|
||
5. 配置支付授权目录
|
||
|
||
---
|
||
|
||
## 📝 开发注意事项
|
||
|
||
### 1. 代码规范
|
||
|
||
- 使用 ES6+ 语法
|
||
- 组件命名使用 PascalCase
|
||
- 方法命名使用 camelCase
|
||
- 常量命名使用 UPPER_CASE
|
||
- 添加必要的注释
|
||
|
||
### 2. 性能优化
|
||
|
||
- 图片使用 CDN 加载
|
||
- 列表使用虚拟滚动（长列表）
|
||
- 避免在 onShow 中频繁请求接口（添加防抖）
|
||
- 合理使用缓存（localStorage）
|
||
|
||
### 3. 安全注意事项
|
||
|
||
- Token 存储在 localStorage
|
||
- 敏感信息不要明文存储
|
||
- 接口请求添加 Token 验证
|
||
- 防止 XSS 攻击（用户输入过滤）
|
||
|
||
### 4. 测试要点
|
||
|
||
- 测试不同机型的兼容性（iOS / Android）
|
||
- 测试微信环境和 APP 内嵌环境
|
||
- 测试网络异常情况
|
||
- 测试支付流程完整性
|
||
- 测试实名认证流程
|
||
|
||
---
|
||
|
||
## 📞 联系方式与资源
|
||
|
||
### 技术文档
|
||
- [uni-app 官方文档](https://uniapp.dcloud.net.cn/)
|
||
- [微信 JS-SDK 文档](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html)
|
||
- [微信支付文档](https://pay.weixin.qq.com/wiki/doc/api/index.html)
|
||
|
||
### 相关账号
|
||
- **微信公众号:** 羽声语音
|
||
- **API 域名:** https://yushengapi.qxyushen.top
|
||
- **测试环境:** https://test.vespa.qxyushen.top
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 运行开发环境
|
||
npm run dev:h5
|
||
|
||
# 构建生产版本
|
||
npm run build:h5
|
||
|
||
# 清理缓存
|
||
npm run clean
|
||
```
|
||
|