# 企业微信接入指南

本文档详细说明如何将保险智能客服系统接入企业微信，包括自建应用、机器人消息和 OAuth 登录。

---

## 目录

- [前置条件](#前置条件)
- [第一步：创建自建应用](#第一步创建自建应用)
- [第二步：配置机器人消息接收](#第二步配置机器人消息接收)
- [第三步：配置 OAuth 登录](#第三步配置-oauth-登录)
- [第四步：配置环境变量](#第四步配置环境变量)
- [第五步：验证接入](#第五步验证接入)
- [部署注意事项](#部署注意事项)
- [常见问题排查](#常见问题排查)

---

## 前置条件

- 已注册企业微信（[注册地址](https://work.weixin.qq.com/)）
- 拥有企业微信管理员权限
- 服务器已部署并配置 HTTPS（企微回调要求）
- 域名已备案（生产环境必须）

---

## 第一步：创建自建应用

### 1.1 登录管理后台

访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)，使用管理员账号登录。

### 1.2 创建应用

1. 左侧菜单 → **应用管理** → **自建**
2. 点击 **创建应用**
3. 填写应用信息：
   - **应用名称**: 保险智能客服
   - **应用 Logo**: 上传图标
   - **应用介绍**: 保险行业智能客服系统
   - **可见范围**: 选择需要使用的部门/成员

### 1.3 记录关键信息

创建完成后，进入应用详情页，记录以下信息：

| 配置项 | 位置 | 示例 |
|--------|------|------|
| **企业 ID** | 我的企业 → 企业信息 | `ww1234567890abcdef` |
| **AgentId** | 应用详情 → 基础信息 | `1000002` |
| **Secret** | 应用详情 → 基础信息 → Secret | `xxxxxxxxxxxxxxxxxxxxxxxx` |

> ⚠️ **Secret 点击查看后要立即保存**，关闭后无法再次查看。

---

## 第二步：配置机器人消息接收

### 2.1 启用机器人能力

1. 进入自建应用详情
2. 左侧菜单 → **机器人**
3. 点击 **启用** 按钮

### 2.2 配置消息接收 API

1. 进入应用详情 → **接收消息** → **设置 API 接收**
2. 填写以下信息：

| 配置项 | 值 | 说明 |
|--------|-----|------|
| **URL** | `https://your-domain.com/insurance/wecom/callback` | 企微回调地址 |
| **Token** | 自定义随机字符串 | 用于验证请求来源 |
| **EncodingAESKey** | 点击随机获取 | 43位加密密钥 |

3. 点击 **保存**，企微会向该 URL 发送验证请求

### 2.3 服务器验证要求

- 必须支持 HTTPS（443 端口）
- 必须在 **5 秒内** 响应验证请求
- 响应内容必须是明文的 `echostr`

### 2.4 记录配置信息

| 配置项 | 位置 | 长度 |
|--------|------|------|
| **Token** | 应用 → 接收消息 | 自定义，建议 32 位随机字符串 |
| **EncodingAESKey** | 应用 → 接收消息 | 43 位（自动生成） |

---

## 第三步：配置 OAuth 登录

### 3.1 开启授权登录

1. 进入自建应用详情
2. 左侧菜单 → **企业微信授权登录**
3. 点击 **设置授权回调域**

### 3.2 配置回调域名

根据部署环境配置：

| 环境 | 回调域名 | 说明 |
|------|----------|------|
| 开发环境 | `localhost` | 本地开发测试 |
| 测试环境 | `test.your-domain.com` | 测试服务器 |
| 生产环境 | `your-domain.com` | 正式环境 |

> ⚠️ 回调域名只填写域名，不要带 `https://` 和端口号。

### 3.3 权限配置

如需获取用户敏感信息（手机号等），需要在应用详情中申请相应权限：

- **基础信息**: 默认开启
- **通讯录权限**: 根据需要申请
- **成员信息**: 申请 `读取成员` 权限

---

## 第四步：配置环境变量

### 4.1 创建 .env 文件

在项目根目录（`baodan-main/`）创建 `.env` 文件：

```bash
# ===== 企业微信配置 =====

# 企业 ID（必填）
WECOM_CORP_ID=ww1234567890abcdef

# 自建应用 AgentId（必填）
WECOM_AGENT_ID=1000002

# 自建应用 Secret（必填）
WECOM_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 消息校验 Token（必填，与企微后台配置一致）
WECOM_TOKEN=your_random_token_32_chars

# 消息加密 Key（必填，43位，与企微后台配置一致）
WECOM_ENCODING_AES_KEY=your_43_char_encoding_aes_key
```

### 4.2 配置说明

| 环境变量 | 是否必填 | 说明 |
|----------|:--------:|------|
| `WECOM_CORP_ID` | ✅ | 企业唯一标识，从「我的企业」获取 |
| `WECOM_AGENT_ID` | ✅ | 自建应用 ID |
| `WECOM_SECRET` | ✅ | 应用密钥，点击查看后立即保存 |
| `WECOM_TOKEN` | ✅ | 消息校验 Token，需与后台一致 |
| `WECOM_ENCODING_AES_KEY` | ✅ | 43位加密密钥，需与后台一致 |

---

## 第五步：验证接入

### 5.1 启动服务

```bash
cd baodan-main

# 安装依赖
./dev/setup

# 启动后端
./dev/start-api
```

### 5.2 测试 OAuth 登录

浏览器访问：

```
http://localhost:5001/insurance/wecom/oauth
```

预期行为：
1. 重定向到企业微信授权页面
2. 扫码或确认登录后
3. 重定向回系统并携带用户信息

### 5.3 测试机器人消息

1. 在企业微信客户端，搜索「保险智能客服」应用
2. 向机器人发送消息
3. 检查服务器日志是否收到消息

### 5.4 API 健康检查

```bash
# 检查服务是否正常
curl http://localhost:5001/api/health

# 检查企微回调接口
curl http://localhost:5001/insurance/wecom/callback
```

---

## 部署注意事项

### 5.5 Nginx 配置

确保 Nginx 正确代理企微回调接口：

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    # SSL 证书配置
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # 企微回调接口
    location /insurance/wecom/ {
        proxy_pass http://127.0.0.1:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 其他接口...
}
```

### 5.6 防火墙配置

确保服务器开放以下端口：

| 端口 | 协议 | 用途 |
|------|------|------|
| 443 | TCP | HTTPS 访问（企微回调） |
| 80 | TCP | HTTP 访问（重定向到 HTTPS） |

### 5.7 域名要求

- 必须使用已备案域名（生产环境）
- 必须配置 SSL 证书（企微要求 HTTPS）
- 域名需加入企微后台的「可信域名」白名单

---

## 常见问题排查

### 问题 1: URL 验证失败

**现象**: 企微后台保存回调地址时提示「URL 验证失败」

**排查步骤**:
1. 检查服务器是否正常运行
2. 检查 Nginx 是否正确代理 `/insurance/wecom/callback`
3. 检查 SSL 证书是否有效
4. 检查 `Token` 和 `EncodingAESKey` 是否与代码一致

```bash
# 手动测试回调接口
curl -v "https://your-domain.com/insurance/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx"
```

### 问题 2: 消息接收不到

**现象**: 用户发送消息后，服务器没有收到回调

**排查步骤**:
1. 确认机器人能力已启用
2. 确认消息接收 API 已配置
3. 检查服务器日志是否有请求记录
4. 检查消息是否在 5 秒内处理（企微要求）

### 问题 3: OAuth 登录失败

**现象**: 点击登录后提示「授权失败」

**排查步骤**:
1. 确认「企业微信授权登录」已开启
2. 确认回调域名配置正确
3. 检查 `WECOM_CORP_ID` 环境变量是否正确
4. 检查应用可见范围是否包含测试用户

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

**现象**: 登录成功但无法获取用户详细信息

**排查步骤**:
1. 确认应用已申请「读取成员」权限
2. 确认用户在应用可见范围内
3. 检查 `WECOM_AGENT_ID` 和 `WECOM_SECRET` 是否正确

### 问题 5: 企微后台提示「回调地址不可达」

**现象**: 保存配置时提示网络不可达

**排查步骤**:
1. 确认域名已备案
2. 确认 SSL 证书有效（非自签名）
3. 确认防火墙已开放 443 端口
4. 使用在线工具检测 SSL：https://www.ssllabs.com/ssltest/

### 问题 6: 企微后台提示「回调地址请求不通过」

**现象**: 保存配置时提示 `openapi回调地址请求不通过`

**常见原因**:
1. AES 解密未正确实现 — 回调验证需要解密 echostr，代码只返回了原始密文
2. 环境变量未配置 — Docker 容器中缺少企微配置
3. Token/AES Key 不一致 — 企微后台配置与 `.env` 中的值不匹配
4. SSL 证书问题 — 自签名证书不被企微信任

**排查步骤**:
1. 手动测试回调接口：
   ```bash
   curl "https://your-domain.com/insurance/wecom/callback?msg_signature=test&timestamp=1234567890&nonce=test&echostr=test"
   # 应返回：Invalid signature（说明服务正常，只是参数不对）
   ```
2. 检查 Docker 日志：`docker compose logs baodanagent-api | grep -i wecom`
3. 确认 Token 和 AES Key 与企微后台完全一致
4. 确认 SSL 证书有效（非自签名）

### 问题 7: 5 秒内未返回 success

**现象**: 企微日志显示超时

**原因**: 服务器响应太慢

**解决**: 检查服务器性能、网络延迟，确保回调处理在 5 秒内完成

### 开发环境调试（内网穿透）

本地开发时，企微无法访问 localhost，需要使用内网穿透工具：

```bash
# 使用 ngrok
ngrok http 8080
# 获取公网地址，如：https://xxxx.ngrok.io

# 使用 frp（自建服务器）
# 配置 frpc.ini 指向本地 8080 端口
```

将获取到的公网地址配置到企微后台的回调 URL 中。

---

## 接口说明

### 6.1 OAuth 登录入口

```
GET /insurance/wecom/oauth
```

**说明**: 重定向到企微授权页面，用户确认后回调。

### 6.2 OAuth 回调

```
GET /insurance/wecom/oauth/callback?code=xxx&state=state
```

**说明**: 企微授权回调，自动完成登录并重定向到系统首页。

### 6.3 消息回调（URL 验证）

```
GET /insurance/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx
```

**说明**: 企微服务器验证回调地址有效性。

### 6.4 消息回调（消息接收）

```
POST /insurance/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx
```

**说明**: 接收用户发送给机器人的消息，5 秒内响应 `success`。

---

## 附录：配置清单

### 企业微信后台配置

- [ ] 创建自建应用
- [ ] 记录企业 ID、AgentId、Secret
- [ ] 启用机器人能力
- [ ] 配置消息接收 API（URL、Token、EncodingAESKey）
- [ ] 开启企业微信授权登录
- [ ] 配置授权回调域名
- [ ] 设置应用可见范围

### 服务器配置

- [ ] 配置 SSL 证书
- [ ] 配置 Nginx 代理
- [ ] 开放 443 端口
- [ ] 创建 `.env` 文件并填写配置
- [ ] 启动服务并测试

### 验证测试

- [ ] 测试 OAuth 登录流程
- [ ] 测试机器人消息接收
- [ ] 测试消息回复功能
- [ ] 检查服务器日志正常

---

## 参考链接

- [企业微信官方文档](https://developer.work.weixin.qq.com/document/path/90556)
- [自建应用开发指南](https://developer.work.weixin.qq.com/document/path/90537)
- [消息接收说明](https://developer.work.weixin.qq.com/document/path/90930)
- [OAuth 说明](https://developer.work.weixin.qq.com/document/path/91022)