# 企业微信 OAuth 2.0 集成指南

## 快速开始

### 前置条件

1. 已有企业微信账号
2. 在企业微信管理后台创建了应用
3. 获取了企业 ID（CorpID）和应用 Secret

### 配置步骤

#### 1. 配置企业微信应用

在 `src/js/wecom-config.js` 中填入你的企业信息：

```javascript
export const WECOM_CONFIG = {
    // 从企业微信管理后台获取
    corpId: 'ww1234567890abcdef',
    agentId: '1000001',
    redirectUri: 'https://your-domain.com/',
    apiBaseUrl: '/api'
};
```

#### 2. 在企业微信管理后台配置回调

1. 登录 [企业微信管理后台](https://work.weixin.qq.com/)
2. 点击 **应用管理** → 选择你的应用
3. 进入 **设置** 标签
4. 在 **OAuth 2.0 授权企业号管理员登录** 中：
   - 勾选 **启用**
   - 填入 **授权完成后的跳转链接**（必须是你的应用域名）
   - 填入 **可信域名**（用于 JSSDK 等功能）

#### 3. 配置后端服务

参考 `WECOM_OAUTH_GUIDE.md` 中的后端实现示例。

### 使用流程

#### 场景 1: 自动授权流程（推荐）

在企业微信中打开应用时自动进行授权：

```javascript
// src/main.js 会自动处理以下流程：
// 1. 检查是否有授权码
// 2. 如果有授权码，交换用户信息
// 3. 如果没有授权码，重定向到授权页面
// 4. 获取用户信息后显示
```

#### 场景 2: 手动授权链接

如果需要在页面中显示授权按钮：

```javascript
import WeChatOAuth from './js/wechat-oauth.js';
import { WECOM_CONFIG } from './js/wecom-config.js';

const oauth = new WeChatOAuth(WECOM_CONFIG);
const authUrl = oauth.getAuthUrl();

// 创建授权链接
const authLink = document.createElement('a');
authLink.href = authUrl;
authLink.textContent = '点击授权登录';
document.body.appendChild(authLink);
```

### 获取用户信息

授权成功后，可以通过以下方式获取用户信息：

```javascript
// 方式 1: 从全局变量访问
const user = window.currentUser;
console.log('用户ID:', user.userid);
console.log('用户名:', user.name);
console.log('手机号:', user.mobile);

// 方式 2: 从 OAuth 实例获取
import WeChatOAuth from './js/wechat-oauth.js';
const oauth = new WeChatOAuth(config);
const userInfo = oauth.getUserInfo();

// 方式 3: 从 sessionStorage 获取
const userInfo = JSON.parse(sessionStorage.getItem('wecom_user_info'));
```

### 用户信息说明

获取的用户信息包含以下字段：

| 字段 | 说明 | 示例 |
|------|------|------|
| userid | 企业微信用户ID | user123@company |
| name | 用户姓名 | 张三 |
| mobile | 用户手机号 | 13800138000 |
| email | 用户邮箱 | zhang@company.com |
| department | 用户部门 | 技术部 |
| position | 用户职位 | 工程师 |

## 安全说明

### 1. 防止 CSRF 攻击

系统会自动生成和验证 `state` 参数：

```javascript
// 前端会自动：
// 1. 生成随机 state
// 2. 保存到 sessionStorage
// 3. 在回调时验证 state

// 防止恶意网站冒充授权
```

### 2. 数据安全

- ✅ 使用 HTTPS 传输所有数据
- ✅ 授权码存储在 sessionStorage（浏览器关闭时清除）
- ✅ 用户信息存储在 sessionStorage（不持久化）
- ✅ 敏感信息不存储在 localStorage

### 3. API 安全

- ✅ 后端必须验证 access_token
- ✅ 实现速率限制防止 API 滥用
- ✅ 记录审计日志
- ✅ 定期更新 Secret

## 故障排查

### 问题 1: 重定向错误

**错误信息**: `redirect_uri mismatch`

**解决方案**:
1. 检查 `WECOM_CONFIG.redirectUri` 是否与企业微信后台配置一致
2. 确保协议、域名、路径都完全匹配（包括末尾 `/`）
3. 清除浏览器缓存重试

### 问题 2: 获取用户信息失败

**错误信息**: `获取用户信息失败`

**解决方案**:
1. 检查后端 `/api/wecom/getUserInfo` 端点是否正常
2. 验证后端是否获取到了正确的 access_token
3. 查看浏览器控制台的完整错误信息
4. 检查网络标签中的请求/响应

### 问题 3: 授权码过期

**错误信息**: `授权码已过期`

**解决方案**:
1. 授权码有效期为 10 分钟
2. 需要在授权后立即交换用户信息
3. 如果超时，需要重新授权

### 问题 4: Secret 不正确

**错误信息**: `invalid secret`

**解决方案**:
1. 确认 Secret 是从应用详情中复制的
2. 不要包含空格或特殊字符
3. 如果已泄露，应在企业微信后台重置

## 高级配置

### 1. 自定义错误处理

```javascript
// src/js/app.js 中修改 handleAuthCallback 函数
async function handleAuthCallback(code) {
    try {
        const userInfo = await oauth.exchangeCodeForUserInfo(code);
        // 自定义成功处理逻辑
    } catch (error) {
        if (error.message.includes('40014')) {
            // 处理无效的用户ID
        } else if (error.message.includes('40001')) {
            // 处理过期的 access_token
        }
    }
}
```

### 2. 集成业务系统

```javascript
// 获取用户信息后同步到业务系统
async function syncUserToBackend(userInfo) {
    const response = await apiClient.post('/user/sync', {
        userid: userInfo.userid,
        name: userInfo.name,
        mobile: userInfo.mobile
    });
    return response;
}
```

### 3. 实现权限控制

```javascript
// 检查用户是否有权限访问某功能
async function checkPermission(feature) {
    const user = window.currentUser;
    const response = await apiClient.get(`/permission/check/${feature}/${user.userid}`);
    return response.data.authorized;
}
```

## 性能优化

### 1. 缓存用户信息

用户信息已自动缓存到 sessionStorage，刷新页面时会自动恢复。

### 2. 延迟加载

对于不是立即需要的功能，可以使用延迟加载：

```javascript
// 只在需要时才加载历史记录
if (oauth.isAuthorized()) {
    loadHistory();
}
```

### 3. 减少 API 调用

```javascript
// 合并多个 API 请求
async function fetchUserData(userId) {
    return Promise.all([
        apiClient.get(`/user/${userId}`),
        apiClient.get(`/user/${userId}/permission`),
        apiClient.get(`/user/${userId}/settings`)
    ]);
}
```

## 部署指南

### 1. 生产环境构建

```bash
npm run build
```

生成的文件在 `dist/` 目录中。

### 2. 服务器配置

配置 Web 服务器处理 SPA 路由：

**Nginx**:
```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

**Apache**:
```apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
</IfModule>
```

### 3. HTTPS 配置

企业微信要求使用 HTTPS。使用 Let's Encrypt 配置 SSL：

```bash
certbot certonly --standalone -d your-domain.com
```

## 参考资源

- [企业微信开发文档](https://work.weixin.qq.com/api/doc)
- [OAuth 2.0 规范](https://tools.ietf.org/html/rfc6749)
- [OWASP 安全指南](https://owasp.org/www-project-oauth-2-0-security-best-current-practice/)

## 支持

如有问题，请：
1. 查看浏览器控制台错误日志
2. 参考企业微信官方文档
3. 检查网络请求（F12 → Network）
4. 查阅本指南的故障排查部分