Files

2026-01-29 18:26:32 +08:00

15 KiB

Raw Permalink Blame History

羽声语音 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/昵称）
查看公会信息（头像、名称、简介、会长、在线人数）
申请加入公会
实名认证检查与跳转 ⭐

关键逻辑：

// 实名认证流程
1. 用户点击"申请"按钮
2. 调用接口检查实名状态 (/api/User/get_user_info)
3. 已实名 → 显示加入确认弹窗
4. 未实名 → 提示跳转 APP 实名认证
5. 从 APP 返回时自动刷新实名状态（onShow 生命周期）

重要更新：

✅ 添加了实名状态缓存机制（user_auth_status）
✅ 添加了防抖机制（3秒内不重复请求）
✅ 解决了从 APP 返回后仍提示未实名的问题

与 APP 交互：

// 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. 返回支付结果

关键代码：

// 支付入口
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)

// 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 = '羽声语音';

环境切换：

// 正式环境
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               # 查询支付结果

请求示例

// 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. 颜色变量

--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. 公共样式类

.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. 安装依赖

npm install
# 或
pnpm install

3. 主要依赖

{
  "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

使用 HBuilderX 打开项目
选择运行 → 运行到浏览器 / 运行到手机或模拟器
选择运行到微信开发者工具（需配置微信开发者工具路径）

方式二：命令行

# 开发环境
npm run dev:h5

# 生产构建
npm run build:h5

📱 与 APP 交互说明

1. 调用 APP 原生功能

iOS 交互

// 调用 iOS 原生方法
window.webkit.messageHandlers.nativeHandler.postMessage({
  'action': 'enterAuthent'  // 跳转实名认证
});

Android 交互

// 调用 Android 原生方法
window.Android.enterAuthent();  // 跳转实名认证

2. 接收 APP 传递的参数

// 在 onLoad 或 onShow 中接收参数
onShow(options) {
  if (options && options.guild_id) {
    // 处理 APP 传递的公会 ID
    this.searchValue = options.guild_id;
  }
}

3. 页面生命周期注意事项

onShow: 每次页面显示都会触发（包括从 APP 返回）
onLoad: 只在页面首次加载时触发
从 APP 返回时： 使用 onShow 刷新数据状态

🐛 常见问题与解决方案

1. 实名认证问题

问题： 从 APP 完成实名认证返回后，仍提示未实名

原因：

页面状态未刷新
接口缓存导致获取的是旧数据

解决方案：

// 在 onShow 中刷新用户信息
onShow() {
  this.refreshUserInfo();  // 获取最新实名状态
}

// 添加防抖机制避免频繁请求
async refreshUserInfo(force = false) {
  const now = Date.now();
  if (!force && now - this.lastRefreshTime < 3000) {
    return;  // 3秒内不重复请求
  }
  // ... 请求逻辑
}

2. 微信支付问题

问题： 微信支付调起失败

可能原因：

未在微信环境中打开
微信 JS-SDK 未正确初始化
支付参数错误
微信公众号配置问题

排查步骤：

// 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 样式显示不一致

解决方案：

// 获取平台信息
const platform = uni.getSystemInfoSync().platform;

// 根据平台设置不同样式
:style="{
  marginTop: `${statusBarHeight}${platform === 'ios' ? 'px' : 'dp'}`
}"

4. 图片加载失败

问题： 图片显示不出来

解决方案：

// 使用默认图片
<img :src="data.cover || defaultLogo" alt="" />

// 图片加载错误处理
<img :src="imageUrl" @error="handleImageError" />

handleImageError(e) {
  e.target.src = this.defaultLogo;
}

🚀 部署说明

1. 构建生产版本

# H5 构建
npm run build:h5

# 构建产物在 unpackage/dist/build/h5 目录

2. 部署到服务器

# 将构建产物上传到服务器
scp -r unpackage/dist/build/h5/* user@server:/var/www/html/

# 或使用 FTP 工具上传

3. 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. 微信公众号配置

登录微信公众平台
设置 → 公众号设置 → 功能设置
配置 JS 接口安全域名
配置网页授权域名
配置支付授权目录

📝 开发注意事项

1. 代码规范

使用 ES6+ 语法
组件命名使用 PascalCase
方法命名使用 camelCase
常量命名使用 UPPER_CASE
添加必要的注释

2. 性能优化

图片使用 CDN 加载
列表使用虚拟滚动（长列表）
避免在 onShow 中频繁请求接口（添加防抖）
合理使用缓存（localStorage）

3. 安全注意事项

Token 存储在 localStorage
敏感信息不要明文存储
接口请求添加 Token 验证
防止 XSS 攻击（用户输入过滤）

4. 测试要点

测试不同机型的兼容性（iOS / Android）
测试微信环境和 APP 内嵌环境
测试网络异常情况
测试支付流程完整性
测试实名认证流程

📞 联系方式与资源

技术文档

常用命令

# 安装依赖
npm install

# 运行开发环境
npm run dev:h5

# 构建生产版本
npm run build:h5

# 清理缓存
npm run clean

15 KiB Raw Permalink Blame History Unescape Escape

羽声语音 H5 项目交接文档

📋 项目概述

🏗️ 项目结构

🔑 核心功能模块

1. 公会系统 (pages/union/)

1.1 公会列表与加入 (list.vue)

1.2 公会首页 (index.vue)

1.3 其他公会功能

2. 微信充值系统 (pages/other/weChatPay.vue) 未完善⭐

3. 其他功能模块

3.1 等级系统

3.2 邀请收益

3.3 道具商城

3.4 帮助与反馈

3.5 青少年模式

⚙️ 配置说明

1. 全局配置 (until/config.js)

2. 页面配置 (pages.json)

3. 应用配置 (manifest.json)

🔌 API 接口说明

基础配置

主要接口列表

用户相关

公会相关

支付相关

请求示例

🎨 样式规范

1. 颜色变量

2. 尺寸单位

3. 公共样式类

🔧 开发环境配置

1. 环境要求

2. 安装依赖

3. 主要依赖

4. 运行项目

方式一：HBuilderX

方式二：命令行

📱 与 APP 交互说明

1. 调用 APP 原生功能

iOS 交互

Android 交互

2. 接收 APP 传递的参数

3. 页面生命周期注意事项

🐛 常见问题与解决方案

1. 实名认证问题

2. 微信支付问题

3. 样式兼容问题

4. 图片加载失败

🚀 部署说明

1. 构建生产版本

2. 部署到服务器

3. Nginx 配置示例

4. 微信公众号配置

📝 开发注意事项

1. 代码规范

2. 性能优化

3. 安全注意事项

4. 测试要点

📞 联系方式与资源

技术文档

相关账号

常用命令

15 KiB

Raw Permalink Blame History