# 企业微信环境变量配置说明

## 📋 必需的环境变量

在 `backend/.env` 文件中添加以下配置：

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

# 企业微信基础配置（应用信息）
WECHAT_CORP_ID=ww6ab493470ab4f377
WECHAT_AGENT_ID=1000002
WECHAT_CORP_SECRET=AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU

# 企业微信回调配置（消息加解密）
WECHAT_TOKEN=oX1RBm1YnvMy2SbDLbvAdDd5Gq3oBGq
WECHAT_ENCODING_AES_KEY=zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO
```

## 📝 配置项说明

### 1. WECHAT_CORP_ID
- **说明**：企业微信的企业ID
- **获取方式**：企业微信管理后台 → 我的企业 → 企业信息 → 企业ID
- **当前值**：`ww6ab493470ab4f377`

### 2. WECHAT_AGENT_ID
- **说明**：应用的AgentID
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → AgentId
- **当前值**：`1000002`
- **应用名称**：`IIT Manager Agent`

### 3. WECHAT_CORP_SECRET
- **说明**：应用的Secret（用于获取access_token）
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → Secret
- **当前值**：`AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU`
- **⚠️ 安全提示**：Secret 非常重要，切勿泄露

### 4. WECHAT_TOKEN
- **说明**：消息回调的Token（用于验证签名）
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → 接收消息 → 点击"随机获取"
- **当前值**：`oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq`

### 5. WECHAT_ENCODING_AES_KEY
- **说明**：消息加解密密钥（43位字符）
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → 接收消息 → 点击"随机获取"
- **当前值**：`zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO`

## 🔧 企业微信回调URL配置

### 本地开发（natapp）

```
回调URL: https://iit.nat100.top/api/v1/iit/wechat/callback
Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
EncodingAESKey: zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO
```

### 生产环境（SAE）

```
回调URL: https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback
Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
EncodingAESKey: zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO
```

## ⚠️ 重要提示

1. **IP白名单**（生产环境必需）
   - SAE NAT网关EIP：`182.92.176.14`
   - 需要在企业微信后台配置为"企业可信IP"
   - 位置：企业微信管理后台 → 应用管理 → IIT Manager Agent → 企业可信IP

2. **natapp隧道**（本地开发）
   - 确保natapp隧道正常运行：`http://iit.nat100.top`
   - 后端服务监听：`http://localhost:3001`

3. **环境变量加载**
   - 修改 `.env` 文件后，需要**重启后端服务**
   - 验证方法：查看后端启动日志是否显示"✅ 企业微信服务初始化成功"

## 🚀 验证配置

### 步骤1：检查后端日志

启动后端服务后，应该看到：

```
✅ 企业微信服务初始化成功
✅ 企业微信回调控制器初始化成功
Registered route: GET /api/v1/iit/wechat/callback
Registered route: POST /api/v1/iit/wechat/callback
```

### 步骤2：访问健康检查

```bash
curl https://iit.nat100.top/api/v1/iit/health
```

预期返回：
```json
{
  "status": "ok",
  "module": "iit-manager",
  "version": "1.1.0",
  "timestamp": "2026-01-02T14:30:00.000Z"
}
```

### 步骤3：保存企业微信回调配置

在企业微信后台点击"保存"，如果配置正确：
- ✅ 企业微信会发送GET请求验证URL
- ✅ 后端会解密echostr并返回
- ✅ 显示"保存成功"

## 📞 常见问题

### Q1: 保存回调URL时提示"URL验证失败"

**可能原因**：
1. 后端服务未启动或无法访问
2. natapp隧道未运行
3. 环境变量配置错误（Token或EncodingAESKey不匹配）

**解决方法**：
1. 检查后端日志是否有错误
2. 确认natapp状态：`http://iit.nat100.top/api/v1/iit/health`
3. 检查 `.env` 文件中的Token和EncodingAESKey

### Q2: 收不到企业微信消息

**可能原因**：
1. 回调URL未保存成功
2. 消息类型未勾选（文本消息、支付且退款通知等）
3. 用户未关注应用

**解决方法**：
1. 确认回调URL已保存成功
2. 检查"选择需要接收的消息事件类型"是否勾选了对应类型
3. 用户在企业微信中打开应用

### Q3: 发送消息提示"invalid user"

**可能原因**：
1. 用户UserID不存在
2. 用户未在应用的可见范围内

**解决方法**：
1. 确认UserID正确（企业微信后台查看）
2. 检查应用的可见范围设置

## 📚 相关文档

- [企业微信API文档](https://developer.work.weixin.qq.com/document/path/90664)
- [企业微信消息加解密说明](https://developer.work.weixin.qq.com/document/path/90968)
- [最小MVP闭环开发计划](../docs/03-业务模块/IIT Manager Agent/04-开发计划/最小MVP闭环开发计划.md)