# qywx

**Repository Path**: qcod/qywx

## Basic Information

- **Project Name**: qywx
- **Description**: 【进行中】
个人微信各种封禁，号都被封好几次永久降级了。之前用的itchat，后来用的win窗口监控，在微信客户端升级后都不能用了。
这是一个基于企业微信API的外部群（客户群）消息监控和自动回复应用。采用被动推送方式接收消息，支持指令识别和自动回复功能。
关于企业微信还有机器人方案，这里不做讨论和比较。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业微信外部群消息监控应用【此项目可行性由豆包论证，由千问智能体完成】

## 📋 项目简介【进行中】
个人微信各种封禁，号都被封好几次永久降级了。之前用的itchat，后来用的win窗口监控，在微信客户端升级后都不能用了。
这是一个基于企业微信API的外部群（客户群）消息监控和自动回复应用。采用被动推送方式接收消息，支持指令识别和自动回复功能。
关于企业微信还有机器人方案，这里不做讨论和比较。

> 🚀 **新手用户**：请先阅读 [QUICKSTART.md](QUICKSTART.md) 快速上手  
> 📊 **项目总结**：查看 [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) 了解项目详情  
> 🔧 **遇到问题**：查看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 故障排查指南  
> 🧪 **测试帮助**：查看 [TESTING_GUIDE.md](TESTING_GUIDE.md) 了解如何正确测试  
> ⚠️ **无法添加应用到群**：查看 [SOLUTION_ADD_APP_TO_GROUP.md](SOLUTION_ADD_APP_TO_GROUP.md) 完整解决方案  
> 📝 **命令说明**：查看 [COMMANDS_GUIDE.md](COMMANDS_GUIDE.md) 了解所有支持的命令
## 🌟 实现原理
```
关于企业微信，和普通 微信群的消息互通。
1.企业微信可以加普通微信好友，
2.企业微信可以自建应用，就是控制台普通应用一样。
3.企业微信，可以点“接收微信中的工作消息”可以去微信选择群。然后接收这个普通 群+做为群主。【群会显示为外部群】企业微信接管后原普通微信会退出群。
4.群里原普通用户，还可以去拉普通微信进群。
5.如何接收此群消息？
6.必须使用企业微信提供的会话内容存档（Session Archive）功能。这是企业微信为了合规监管专门开放的底层接口，能够拉取成员与客户（外部联系人）之间的单聊及群聊记录核心配置流程
你需要先在管理后台开启权限，配置加密公钥，再通过 API 主动拉取消息。
••后台开启存档：登录企业微信管理后台，进入【安全与管理】>【管理工具】>【会话内容存档】。开启该功能并设置需要存档的员工范围。
••配置加密公钥：在【数据与智能专区】>【企业会话内容】中，设置消息加密的公钥（Public Key）。企业微信会使用此公钥对消息进行加密，你必须在自己的服务端保留对应的私钥（Private Key）用于后续解密。
••API 拉取消息：服务端调用get_chat_data接口，传入成员 ID 和时间范围，拉取加密后的会话数据，再用私钥解密还原出具体的文本、图片或撤回消息等内容312。
外部群的特殊合规要求
在处理包含微信用户的外部群时，企业微信有严格的隐私保护限制
••必须获得同意：企业可以获取开启了存档功能的员工与已同意存档的外部联系人之间的会话内容。如果外部客户未在微信端点击同意，企业将无法通过 API 拉取到该客户的发言。
••成员范围限制：只能获取被纳入“会话内容存档”范围内的员工所产生的会话。未被授权的员工所在的群聊，即便群主是你，也无法通过此接口获取数据。
```
普通群与存档群的区别
|群类型|获取方式|适用场景|
|---|---|---|
|内部群|群机器人 Webhook|简单的群通知、报警，无法获取成员的历史聊天记录。|
|外部群与存档群|会话内容存档 API|合规审计、客诉追溯、销售质检，支持获取全量聊天记录。|
## ✨ 核心功能

- ✅ **被动推送**：通过回调接口实时接收群消息
- ✅ **指令识别**：支持天气、股票、时间、订单等多种指令
- ✅ **自动回复**：智能识别命令并自动回复
- ✅ **数据存储**：使用JSON文件存储群信息和消息历史
- ✅ **模块化设计**：清晰的代码结构，易于扩展
- ✅ **配置管理**：支持环境变量和配置文件

## 🏗️ 项目结构

```
qywx_analysis/
├── app.py                      # 主应用入口（Flask服务）
├── config.py                   # 配置管理模块
├── qywx_api.py                # 企业微信API封装
├── message_monitor.py         # 消息监控器
├── command_handler.py         # 命令处理器
├── data_storage.py            # JSON数据存储
├── utils.py                   # 工具函数
├── requirements.txt           # 依赖包列表
├── README.md                  # 本文档（技术参考）
├── QUICKSTART.md              # 快速开始指南
├── PROJECT_SUMMARY.md         # 项目总结
└── data/                      # 数据存储目录（自动生成）
    ├── groups.json            # 群信息
    ├── messages.json          # 消息历史
    └── storage_config.json    # 存储配置
```

## 🚀 快速开始

详细启动步骤请参考 **[QUICKSTART.md](QUICKSTART.md)**

简要步骤：
```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置应用（复制并编辑 config.json）
copy config.json.example config.json

# 3. 启动服务
python app.py
```

## ⚙️ 企业微信配置

详细配置步骤请参考 **[QUICKSTART.md](QUICKSTART.md)** 的"第三步：配置企业微信回调"

关键配置项：
- **回调URL**: `http://你的服务器IP:5000/api/qw/callback`
- **Token**: 与 config.json 中的 token 一致
- **EncodingAESKey**: 与 config.json 中的 encoding_aes_key 一致

所需权限：
- ✅ 客户联系权限
- ✅ 外部联系人管理
- ✅ 客户群管理
- ✅ 发送应用消息

### ⚠️ 重要：应用必须加入客户群才能接收消息

**这是最关键的一步！** URL验证成功仅代表回调配置正确，但要真正接收群消息，必须完成以下步骤：

#### ⚠️ 重要提示：仅支持客户群消息

**当前系统仅支持客户群（外部群）消息监控，不支持以下场景：**
- ❌ **单聊消息**：直接发送给应用的私聊消息会解析失败
- ❌ **内部群消息**：企业内部群的普通群消息
- ✅ **客户群消息**：应用在带外部联系人的客户群中收到的消息

**为什么单聊消息会"消息解析失败"？**
- 单聊消息的XML结构与群聊消息不同
- 单聊消息缺少 `ChatID` 字段
- 系统设计目标是监控客户群运营，而非处理私聊

**正确的测试方式：**
1. 将应用添加到客户群
2. **在群里**发送消息（不是直接发给应用）
3. 观察日志和应用回复

#### 方法1：通过企业微信客户端添加（推荐）

1. **打开目标客户群**
   - 在企业微信手机端或PC端，打开你要监控的客户群
   - ⚠️ 注意：必须是"客户群"（带外部联系人的外部群），普通内部群不支持

2. **添加应用到群**
   - 点击群右上角的【...】或【群详情】
   - 找到【群管理】→【添加群机器人】或【添加应用】
   - 选择你创建的应用（agentid对应的应用）
   - 确认添加

3. **验证是否成功**
   - 添加成功后，群成员列表中会显示该应用
   - 在群里发送一条测试消息
   - 查看应用日志，应该能看到收到消息的记录

#### 方法2：通过API获取群列表

如果不确定哪些群已添加应用，可以调用刷新接口：

```bash
# 刷新并获取所有可访问的客户群列表
curl -X POST http://localhost:5000/api/groups/refresh
```

返回的群列表即为应用已加入或有权限访问的群。

#### 常见问题

**Q: URL验证成功，但收不到消息？**
- A: 90%的情况是因为应用没有被添加到客户群中，请按上述步骤操作

**Q: 如何确认是"客户群"？**
- A: 客户群的标识是包含外部联系人（普通微信用户），在企业微信中会显示为"外部群"

**Q: 应用可以自动加入所有群吗？**
- A: 不可以，必须手动将应用添加到每个需要监控的群中

**Q: 添加应用后需要重启服务吗？**
- A: 不需要，添加后立即生效

## 📡 API接口文档

### 1. 健康检查

```
GET /api/health
```

**响应示例：**
```json
{
  "status": "healthy",
  "timestamp": 1635240000,
  "service": "qywx-group-monitor",
  "version": "1.0.0"
}
```

### 2. 获取监控群列表

```
GET /api/groups
```

**响应示例：**
```json
{
  "status": "success",
  "data": [
    {
      "chat_id": "wrOgQhDgAAeYbXlXrIvxxxxxx",
      "name": "技术交流群",
      "owner": "zhangsan",
      "member_count": 42
    }
  ],
  "total": 1
}
```

### 3. 刷新群列表

```
POST /api/groups/refresh
```

从企业微信API同步最新的群列表。

**响应示例：**
```json
{
  "status": "success",
  "data": [...],
  "total": 5
}
```

### 4. 获取群消息历史

```
GET /api/groups/{chat_id}/messages?limit=50&hours=24
```

**参数：**
- `limit`: 返回消息数量（默认50）
- `hours`: 过去几小时的消息（可选）

**响应示例：**
```json
{
  "status": "success",
  "data": [
    {
      "chat_id": "wrOgQhDgA...",
      "sender": "zhangsan",
      "msg_type": "text",
      "content": "帮助",
      "send_time": 1635240000,
      "received_at": "2024-01-15T10:30:00"
    }
  ],
  "total": 10,
  "chat_id": "wrOgQhDgA..."
}
```

### 5. 获取统计信息

```
GET /api/stats
```

**响应示例：**
```json
{
  "status": "success",
  "data": {
    "total_messages": 1234,
    "command_messages": 567,
    "last_message_time": "2024-01-15T10:30:00",
    "groups_count": 5,
    "messages_count": 1234
  }
}
```

### 6. 测试发送消息

```
POST /api/test/send
Content-Type: application/json

{
  "chat_id": "wrOgQhDgA...",
  "content": "测试消息"
}
```

**用途**：仅用于调试，生产环境请禁用此接口。

## 💬 支持的指令

| 指令 | 说明 | 示例 |
|------|------|------|
| 帮助 / help | 显示帮助信息 | `帮助` |
| 天气 [城市] | 查询天气 | `天气 北京` |
| 股票 [代码] | 查询股票 | `股票 09988` |
| 时间 / time | 查询当前时间 | `时间` |
| 订单 [订单号] | 查询订单 | `订单 20240101001` |
| 价格 / price | 查询产品价格 | `价格` |

> 💡 当前为模拟数据，实际使用需接入相应的API服务

## 🔧 开发指南

### 添加新指令

在 [`command_handler.py`](command_handler.py) 中添加：

```python
def __init__(self):
    self.commands = {
        # ... 现有命令
        '新命令': self.handle_new_command,
    }

def handle_new_command(self, text):
    """处理新命令"""
    # 提取参数
    param = text.replace('新命令', '').strip()
    
    # 实现业务逻辑
    result = your_business_logic(param)
    
    return f"【新命令结果】\n{result}"
```

### 自定义消息处理

在 [`message_monitor.py`](message_monitor.py) 的 `handle_message` 方法中扩展逻辑：

```python
def handle_message(self, message_data):
    # ... 现有逻辑
    
    # 添加自定义处理
    if message_data.get('msg_type') == 'image':
        self.handle_image_message(message_data)
```

### 扩展数据存储

在 [`data_storage.py`](data_storage.py) 中添加新的数据管理方法：

```python
def save_custom_data(self, data_type, data):
    """保存自定义数据"""
    file_path = os.path.join(self.data_dir, f'{data_type}.json')
    # 实现保存逻辑
```

### 修改API行为

在 [`app.py`](app.py) 中添加新的路由：

```python
@app.route('/api/custom/endpoint', methods=['GET'])
def custom_endpoint():
    """自定义API端点"""
    return jsonify({'status': 'success'})
```

## 📊 数据管理

### 数据文件说明

所有数据存储在 `data/` 目录下：

- **groups.json** - 群信息列表
  ```json
  {
    "groups": [
      {
        "chat_id": "wrOgQhDgA...",
        "name": "技术交流群",
        "owner": "zhangsan",
        "member_count": 42
      }
    ],
    "last_update": "2024-01-15T10:30:00"
  }
  ```

- **messages.json** - 消息历史记录
  ```json
  {
    "messages": [...],
    "total_count": 1234
  }
  ```

- **storage_config.json** - 存储配置
  ```json
  {
    "max_message_history": 1000,
    "auto_cleanup": true,
    "cleanup_days": 30
  }
  ```

### 清理旧消息

```python
from data_storage import DataStorage

storage = DataStorage('./data')
storage.cleanup_old_messages(days=30)  # 清理30天前的消息
```

### 备份数据

定期备份 `data/` 目录：

```bash
# Linux/Mac
tar -czf data_backup_$(date +%Y%m%d).tar.gz data/

# Windows
Compress-Archive -Path data -DestinationPath data_backup_20240115.zip
```

## 🔒 安全建议

### 1. 保护敏感信息

- ❌ 不要将 `config.json` 提交到版本控制（已在 .gitignore 中配置）
- ✅ 生产环境使用环境变量存储密钥
- ✅ 定期更换 Secret 和 Token

### 2. 网络访问控制

- 配置防火墙规则，仅开放必要端口
- 限制企业微信回调IP白名单
- 使用HTTPS加密传输

### 3. API安全

- 生产环境禁用 `/api/test/send` 接口
- 实现API认证机制
- 添加请求频率限制

### 4. 数据安全

- 定期备份数据文件
- 设置合理的消息保留期限
- 敏感数据加密存储

## 🐛 故障排除

### 问题1：回调验证失败

**症状**：企业微信后台提示"验证失败"

**可能原因：**
- Token 或 EncodingAESKey 配置错误
- 服务器无法被企业微信访问
- 签名验证逻辑有误

**解决方案：**
1. 检查 config.json 中的 token 和 encoding_aes_key
2. 确保服务器端口已开放且可从外网访问
3. 检查防火墙设置
4. 查看应用日志确认是否收到验证请求

### 问题2：无法发送消息

**症状**：指令识别成功但回复失败

**可能原因：**
- AccessToken 获取失败
- 应用权限不足
- 群ID不正确

**解决方案：**
1. 检查 corpid 和 corpsecret 是否正确
2. 确认应用有"客户群管理"和"发送应用消息"权限
3. 查看日志中的错误信息
4. 使用 `/api/test/send` 接口测试发送

### 问题3：消息未收到

**症状**：群里发送消息但应用无反应

**可能原因：**
- 回调URL配置错误
- 应用不在群中
- 网络不通

**解决方案：**
1. 检查企业微信后台的回调URL配置
2. 确认企业微信账号已在目标群中
3. 测试服务器连通性：`curl http://你的IP:5000/api/health`
4. 查看应用日志是否有收到请求

### 问题4：消息解密失败

**症状**：日志显示"解密失败"

**可能原因：**
- Token 或 EncodingAESKey 不匹配
- 加密算法版本不一致

**解决方案：**
1. 确认 config.json 中的配置与企业微信后台完全一致
2. 注意区分大小写
3. 检查是否有空格或特殊字符
4. 重新生成 EncodingAESKey

### 问题5：启动时连接失败

**症状**：启动时提示"企业微信连接失败"

**可能原因：**
- 网络问题
- 凭证错误
- 应用被禁用

**解决方案：**
1. 检查网络连接：`ping qyapi.weixin.qq.com`
2. 验证 corpid 和 corpsecret 是否正确
3. 确认应用未被禁用
4. 查看详细错误日志

## 📝 日志查看

应用运行时会输出详细日志：

```
2024-01-15 10:30:00 - message_monitor - INFO - 收到消息 - 群: wrOgQhDgA..., 发送者: zhangsan, 类型: text
2024-01-15 10:30:00 - message_monitor - INFO - 识别到命令，准备回复
2024-01-15 10:30:01 - message_monitor - INFO - 回复发送成功
```

**日志级别**：
- DEBUG：详细调试信息
- INFO：一般信息（推荐）
- WARNING：警告信息
- ERROR：错误信息

修改日志级别：在 config.json 中设置 `log_level`

## 🔍 模块说明

### config.py - 配置管理
- 支持JSON配置文件和环境变量
- 配置优先级：环境变量 > 配置文件 > 默认值
- 提供类型安全的配置访问

### qywx_api.py - 企业微信API
- AccessToken自动缓存和刷新
- 客户群列表获取
- 群详情查询
- 消息发送功能

### message_monitor.py - 消息监控
- 消息解析和路由
- 事件处理（客户添加、群变更等）
- 统计信息收集

### command_handler.py - 命令处理
- 灵活的命令匹配
- 易于扩展新指令
- 统一的响应格式

### data_storage.py - 数据存储
- JSON文件持久化
- 自动清理旧数据
- 配置管理

### utils.py - 工具函数
- AES加解密
- 签名验证
- XML解析
- 日志配置

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

**贡献流程**：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

MIT License

## 📧 联系方式

如有问题，请提交 Issue 或联系开发者。

---

**注意**：本项目仅供学习交流使用，请遵守企业微信使用条款和相关法规。