AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/04-开发计划/企业微信注册指南.md

# 企业微信注册与配置指南

> **目标**：获取企业微信API凭证，用于IIT Manager Agent发送质控预警卡片  
> **预计时间**：20分钟

---

## 📋 步骤1：注册企业微信账号

### 1.1 访问企业微信官网

访问：https://work.weixin.qq.com/

### 1.2 注册企业

1. 点击"**立即注册**"
2. 选择"**企业**"类型
3. 填写企业信息：
   - 企业名称：`测试医院`（或您的实际机构名称）
   - 行业类型：`医疗健康`
   - 企业人数：`100人以下`
   - 管理员姓名：您的姓名
   - 管理员手机：您的手机号（接收验证码）
4. 完成验证，注册成功

---

## 📋 步骤2：创建自建应用

### 2.1 登录管理后台

1. 访问：https://work.weixin.qq.com/wework_admin/loginpage_wx
2. 使用企业微信APP扫码登录（需先在手机上下载企业微信APP）

### 2.2 创建应用

1. 进入**【应用管理】** → **【自建】** → **【创建应用】**

2. 填写应用信息：
   - **应用名称**：`IIT Manager Agent（测试）`
   - **应用Logo**：上传一个图标（可暂时使用默认）
   - **应用介绍**：`IIT研究智能质控助手 - 数据质量实时监控`
   - **可见范围**：选择"**所有人**"（测试阶段）

3. 点击"**创建应用**"

### 2.3 获取API凭证（重要！）

创建成功后，在应用详情页可以看到：

```
企业ID（CorpID）：  ww1234567890abcdef
AgentID：           1000002
Secret：            点击"查看"按钮查看
```

**⚠️ 重要提示**：
- **Secret** 只显示一次，请立即复制保存！
- 如果忘记Secret，需要重置（会导致旧Secret失效）

---

## 📋 步骤3：配置API权限

### 3.1 设置网页授权及JS-SDK

1. 在应用详情页，找到"**网页授权及JS-SDK**"
2. 设置**可信域名**：
   - 开发环境：`localhost`（如果支持）
   - 生产环境：您的实际域名（如 `iit.example.com`）

### 3.2 设置接收消息

1. 找到"**接收消息**"配置
2. 暂时不用配置（MVP阶段只需要推送消息，不需要接收）

### 3.3 设置权限范围

确保应用有以下权限：
- ✅ **发送消息到微信** - 核心功能
- ✅ **成员信息读取** - 用于获取用户OpenID
- ✅ **通讯录管理** - 用于用户映射

---

## 📋 步骤4：配置到项目中

### 4.1 复制凭证

将获取到的凭证记录下来：

```
CorpID:     ww1234567890abcdef
AgentID:    1000002
Secret:     abc123xyz789_your_secret_here
```

### 4.2 添加到 .env 文件

编辑 `AIclinicalresearch/backend/.env`，添加：

```bash
# ==================== 企业微信配置 ====================
WECHAT_CORP_ID=ww1234567890abcdef
WECHAT_CORP_SECRET=abc123xyz789_your_secret_here
WECHAT_AGENT_ID=1000002
```

**⚠️ 注意**：
- 不要提交 `.env` 文件到Git（已在 `.gitignore` 中）
- 生产环境使用独立的企业微信应用

---

## 📋 步骤5：测试企微API

### 5.1 重启后端服务

保存 `.env` 后，重启后端：

```bash
# 停止当前服务（Ctrl+C）
# 重新启动
cd D:\MyCursor\AIclinicalresearch\backend
npm run dev
```

### 5.2 手动测试（使用Postman或curl）

**测试端点**（后续Day 5会创建）：

```bash
POST http://localhost:3001/api/v1/iit/test/wechat-push
Content-Type: application/json

{
  "toUser": "YourUserID",
  "title": "测试通知",
  "description": "这是一条来自IIT Manager的测试消息",
  "url": "http://localhost:5173"
}
```

**预期结果**：
- ✅ 返回200状态码
- ✅ 企业微信APP收到卡片消息

---

## 📋 常见问题（FAQ）

### Q1：我没有企业，可以注册吗？

**A**：可以！选择"**个人**"或"**个体工商户**"类型注册，功能完全相同。

### Q2：Secret忘记了怎么办？

**A**：在应用详情页点击"**重置Secret**"，但会导致旧Secret失效。

### Q3：测试环境需要实名认证吗？

**A**：不需要。未认证企业也可以使用自建应用的全部功能，只是人数有限制（100人）。

### Q4：如何找到用户的 UserID？

**A**：
1. 方法1：登录管理后台 → 通讯录 → 点击成员 → 查看"账号"
2. 方法2：调用企业微信API获取：`GET /cgi-bin/user/getuserinfo`

### Q5：消息发送失败，返回40014错误？

**A**：`invalid access_token`，可能原因：
- Secret配置错误
- Access Token过期（需重新获取）
- CorpID或AgentID配置错误

---

## ✅ 验收标准

完成以下任务后，Day 1就完美收官了：

- [ ] 企业微信账号注册成功
- [ ] 自建应用创建成功
- [ ] 获取到CorpID、AgentID、Secret
- [ ] 配置到 `.env` 文件
- [ ] 后端服务能正常启动（无报错）

---

## 🎯 下一步

完成企业微信配置后，Day 2我们将开始：

1. **REDCap API Adapter开发**（核心功能）
2. **SyncManager开发**（混合同步模式）
3. 实现REDCap数据拉取和轮询

预计完成时间：8小时

---

**创建日期**：2025-12-31  
**维护者**：开发团队  
**参考文档**：
- 企业微信官方文档：https://developer.work.weixin.qq.com/document/
- 发送应用消息：https://developer.work.weixin.qq.com/document/path/90236