yusheng-h5/交接文档.md

# 羽声语音 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
```