# 微信JS-SDK集成文档

## 🎯 项目概述

本文档介绍如何在智慧校园移动应用（mobile工程）中集成微信JS-SDK功能，实现微信浏览器内的原生功能调用。

## 📋 技术架构

- **技术栈**: uni-app 2.x + Vue 2.6.14 + TypeScript + uview-ui 2.0.38
- **微信JS-SDK版本**: 1.6.0
- **支持平台**: H5（微信浏览器环境）
- **集成方式**: 官方CDN + 本地工具类封装

## 🚀 快速开始

### 1. 前置条件

#### 1.1 微信公众平台配置
- 已认证的微信服务号
- 已配置JS接口安全域名
- 获取AppID和AppSecret

#### 1.2 后端接口支持
确保后端已实现以下接口：
```
POST /system/wechat/config      # 获取JS-SDK配置
POST /system/wechat/upload      # 上传微信媒体文件
GET  /system/wechat/download    # 下载微信媒体文件
GET  /system/wechat/userinfo    # 获取微信用户信息
```

### 2. 项目文件结构

```
mobile/
├── public/
│   └── index.html              # 已添加微信JS-SDK脚本引用
├── src/
│   ├── api/
│   │   └── wechat.ts          # 微信API接口定义
│   ├── utils/
│   │   └── wechat.js          # 微信JS-SDK工具类
│   └── components/
│       └── WeChatDemo.vue     # 功能演示组件
└── README-wechat-integration.md  # 本文档
```

### 3. 基础使用示例

#### 3.1 在页面中使用微信SDK

```vue
<template>
  <view>
    <button @click="initWeChatSDK">初始化微信SDK</button>
    <button @click="scanQRCode" :disabled="!isInitialized">扫一扫</button>
    <button @click="shareToFriends" :disabled="!isInitialized">分享给朋友</button>
  </view>
</template>

<script>
import weChatSDK from '@/utils/wechat.js';

export default {
  data() {
    return {
      isInitialized: false
    };
  },
  methods: {
    async initWeChatSDK() {
      try {
        await weChatSDK.init();
        this.isInitialized = true;
        console.log('微信SDK初始化成功');
      } catch (error) {
        console.error('初始化失败:', error);
      }
    },
    
    async scanQRCode() {
      try {
        const result = await weChatSDK.scanQRCode();
        console.log('扫码结果:', result.resultStr);
      } catch (error) {
        console.error('扫码失败:', error);
      }
    },
    
    async shareToFriends() {
      try {
        await weChatSDK.shareAppMessage({
          title: '智慧校园',
          desc: '校园管理系统',
          link: window.location.href,
          imgUrl: 'https://example.com/logo.png'
        });
        console.log('分享配置成功');
      } catch (error) {
        console.error('分享失败:', error);
      }
    }
  }
};
</script>
```

## 📚 API文档

### 微信工具类 (wechat.js)

#### 初始化方法

##### `init(options)`
初始化微信JS-SDK配置

**参数:**
- `options.url` (String, 可选): 当前页面URL，默认自动获取
- `options.jsApiList` (Array, 可选): 需要使用的API列表，默认使用全部
- `options.debug` (Boolean, 可选): 是否开启调试模式，默认根据环境

**返回:** Promise

```javascript
await weChatSDK.init({
  debug: false,
  jsApiList: ['chooseImage', 'scanQRCode']
});
```

#### 环境检测方法

##### `isWeChatBrowser()`
检查是否在微信浏览器中

**返回:** Boolean

##### `getCurrentUrl()`
获取当前页面URL（去除hash部分）

**返回:** String

#### 分享功能

##### `shareTimeline(shareData)`
分享到朋友圈

**参数:**
- `shareData.title` (String): 分享标题
- `shareData.link` (String): 分享链接
- `shareData.imgUrl` (String): 分享图标

##### `shareAppMessage(shareData)`
分享给朋友

**参数:**
- `shareData.title` (String): 分享标题
- `shareData.desc` (String): 分享描述
- `shareData.link` (String): 分享链接
- `shareData.imgUrl` (String): 分享图标

#### 扫码功能

##### `scanQRCode(options)`
微信扫一扫

**参数:**
- `options.needResult` (Number, 可选): 是否返回扫描结果，默认1
- `options.scanType` (Array, 可选): 扫码类型，默认['qrCode', 'barCode']

**返回:** Promise<{resultStr: string}>

#### 图片功能

##### `chooseImage(options)`
选择图片

**参数:**
- `options.count` (Number, 可选): 图片数量，默认1
- `options.sizeType` (Array, 可选): 图片尺寸，默认['original', 'compressed']
- `options.sourceType` (Array, 可选): 图片来源，默认['album', 'camera']

**返回:** Promise<{localIds: string[]}>

##### `previewImage(options)`
预览图片

**参数:**
- `options.current` (String): 当前显示图片的http链接
- `options.urls` (Array): 需要预览的图片http链接列表

#### 地理位置

##### `getLocation(options)`
获取地理位置

**参数:**
- `options.type` (String, 可选): 坐标类型，默认'gcj02'

**返回:** Promise<{latitude: number, longitude: number, accuracy: number}>

##### `openLocation(location)`
打开地图

**参数:**
- `location.latitude` (Number): 纬度
- `location.longitude` (Number): 经度
- `location.name` (String, 可选): 位置名称
- `location.address` (String, 可选): 地址详情
- `location.scale` (Number, 可选): 地图缩放级别，默认14

#### 设备信息

##### `getNetworkType()`
获取网络状态

**返回:** Promise<{networkType: string}>

#### 支付功能

##### `chooseWXPay(payInfo)`
微信支付

**参数:**
- `payInfo.timestamp` (String): 时间戳
- `payInfo.nonceStr` (String): 随机字符串
- `payInfo.package` (String): 订单详情扩展字符串
- `payInfo.signType` (String, 可选): 签名方式，默认'MD5'
- `payInfo.paySign` (String): 签名

#### 其他功能

##### `checkJsApi(jsApiList)`
检查当前客户端版本是否支持指定JS接口

##### `closeWindow()`
关闭当前网页窗口

### API接口 (wechat.ts)

#### `getWeChatConfig(url: string)`
获取微信JS-SDK配置信息

#### `uploadWeChatMedia(mediaId: string, type: string)`
上传微信临时素材

#### `downloadWeChatMedia(mediaId: string)`
下载微信临时素材

#### `getWeChatUserInfo(code: string)`
获取微信用户信息

#### `createWeChatPay(orderData: any)`
生成微信支付订单

## 🔧 配置说明

### 1. 微信公众平台配置

1. 登录微信公众平台
2. 进入"设置" → "公众号设置" → "功能设置"
3. 配置"JS接口安全域名"
4. 填入你的网站域名（不需要协议头，不需要www）

### 2. 后端配置要求

后端需要实现微信JS-SDK配置接口，返回格式：

```json
{
  "code": 200,
  "data": {
    "appId": "wx1234567890abcdef",
    "timestamp": 1640995200,
    "nonceStr": "Wm3WZYTPz0wzccnW",
    "signature": "0f9de62fce790f9a083d5c99e95740ceb90c27ed"
  },
  "msg": "success"
}
```

### 3. 环境配置

确保项目配置文件中的API地址正确：

```javascript
// mobile/src/common/config.js
export const REQUEST_CONFIG = {
  baseURL: process.env.NODE_ENV === 'development' ? '/api' : '/prod-api'
};
```

## 🎨 功能演示组件

项目提供了完整的功能演示组件 `WeChatDemo.vue`，包含：

- ✅ 微信环境检测
- ✅ SDK初始化状态
- ✅ 分享功能（朋友圈/朋友）
- ✅ 扫码功能
- ✅ 图片选择和预览
- ✅ 地理位置获取
- ✅ 设备信息查询
- ✅ 接口支持检查

使用方法：

```vue
<template>
  <view>
    <WeChatDemo />
  </view>
</template>

<script>
import WeChatDemo from '@/components/WeChatDemo.vue';

export default {
  components: {
    WeChatDemo
  }
};
</script>
```

## 🚀 部署注意事项

### 1. 域名配置

- 确保生产环境域名已在微信公众平台配置
- 域名必须通过ICP备案
- 支持绑定最多5个域名

### 2. HTTPS要求

- 生产环境必须使用HTTPS协议
- 本地开发可以使用HTTP

### 3. 跨域处理

微信JS-SDK不存在跨域问题，但需要确保：
- 配置获取接口可以正常访问
- 分享的链接在安全域名内

## 🔍 调试指南

### 1. 开启调试模式

```javascript
await weChatSDK.init({
  debug: true  // 开启调试模式
});
```

### 2. 常见问题排查

#### 问题1: invalid signature 签名失败
**原因:** 签名验证失败
**解决:**
- 检查后端签名算法
- 确认URL参数正确（不包含#hash部分）
- 验证时间戳和随机字符串

#### 问题2: permission denied 权限拒绝
**原因:** 接口未授权或不在jsApiList中
**解决:**
- 确认服务号权限
- 检查jsApiList配置
- 验证config是否正确执行

#### 问题3: the permission value is offline verifying
**原因:** config配置有误
**解决:**
- 检查config参数完整性
- 确保在wx.ready回调中调用JSAPI
- 验证jsApiList包含所需接口

### 3. 调试工具

使用微信开发者工具进行调试：
1. 打开微信开发者工具
2. 新建项目，选择"网页"
3. 输入你的网站URL
4. 在控制台查看调试信息

## 📱 兼容性说明

### 支持的微信版本
- iOS: 6.0.2及以上
- Android: 6.0.2及以上

### 支持的功能
- ✅ 基础分享功能
- ✅ 图像处理
- ✅ 地理位置
- ✅ 设备信息
- ✅ 扫一扫
- ✅ 微信支付

### 平台限制
- 仅支持微信浏览器环境
- 部分接口需要服务号认证
- 支付功能需要开通微信支付

## 🔗 相关资源

### 官方文档
- [微信JS-SDK说明文档](https://developers.weixin.qq.com/doc/service/guide/h5/jssdk.html)
- [微信公众平台](https://mp.weixin.qq.com/)

### 项目文档
- [移动端开发规范](../.cursor/cursorrules-mobile.md)
- [API开发规范](../docs/开发文档/API/)
- [项目部署文档](../docs/部署文档/)

## 📝 更新日志

### v1.0.0 (2025-01-03)
- ✅ 完成微信JS-SDK基础集成
- ✅ 实现常用API功能封装
- ✅ 创建功能演示组件
- ✅ 编写完整使用文档

---

**维护者**: 开发团队  
**最后更新**: 2025-01-03  
**文档版本**: v1.0.0